From a96ec9f30d0d2193cb1127f52555226a614b2606 Mon Sep 17 00:00:00 2001 From: Ryan Hartlage Date: Sun, 15 Dec 2024 16:49:57 -0500 Subject: [PATCH] Add notes on interrupt safety --- src/tiny_gea2_interface.c | 38 ++++++++++++++++++++++++++++++++++++++ src/tiny_gea3_interface.c | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+) diff --git a/src/tiny_gea2_interface.c b/src/tiny_gea2_interface.c index 4a486ce..aafb2ad 100644 --- a/src/tiny_gea2_interface.c +++ b/src/tiny_gea2_interface.c @@ -1,6 +1,44 @@ /*! * @file * @brief + * + * # Notes on Interrupt Safety + * + * Sending is interrupt-safe because the interrupt context only peeks from + * the first element of the queue and makes no changes to the queue. While + * sending, the non-interrupt context is free to add elements to the queue + * as long as it does not remove any elements from the queue or otherwise + * modify the first element in the queue. Only when the interrupt context + * is done sending a packet is an element removed from the queue and while + * this operation is pending the interrupt context is not free to begin + * sending any additional packets. + * + * The non-interrupt context sets the send.in_progress flag and clears + * the send.completed flag. While send.completed remains false, the first + * element of the queue is not modified. + * + * The interrupt context sets the send.completed flag to indicate that it + * is no longer reading from the queue. Until send.completed is false, it + * does not read from the queue. + * + * [Non-interrupt] [Interrupt] + * | | + * queue packet | + * | | + * |--- | + * | | send.in_progress == true | + * |<-- | + * | | + * |--- send.in_progress = true ---->| + * | | + * | send packet + * | | + * |<------ send.completed = true ---| + * | | + * |--- send.completed = false ----->| + * |--- send.in_progress = false --->| + * | | + * ... ... */ #include diff --git a/src/tiny_gea3_interface.c b/src/tiny_gea3_interface.c index 9eb8ca6..2a726a2 100644 --- a/src/tiny_gea3_interface.c +++ b/src/tiny_gea3_interface.c @@ -1,6 +1,44 @@ /*! * @file * @brief + * + * # Notes on Interrupt Safety + * + * Sending is interrupt-safe because the interrupt context only peeks from + * the first element of the queue and makes no changes to the queue. While + * sending, the non-interrupt context is free to add elements to the queue + * as long as it does not remove any elements from the queue or otherwise + * modify the first element in the queue. Only when the interrupt context + * is done sending a packet is an element removed from the queue and while + * this operation is pending the interrupt context is not free to begin + * sending any additional packets. + * + * The non-interrupt context sets the send.in_progress flag and clears + * the send.completed flag. While send.completed remains false, the first + * element of the queue is not modified. + * + * The interrupt context sets the send.completed flag to indicate that it + * is no longer reading from the queue. Until send.completed is false, it + * does not read from the queue. + * + * [Non-interrupt] [Interrupt] + * | | + * queue packet | + * | | + * |--- | + * | | send.in_progress == true | + * |<-- | + * | | + * |--- send.in_progress = true ---->| + * | | + * | send packet + * | | + * |<------ send.completed = true ---| + * | | + * |--- send.completed = false ----->| + * |--- send.in_progress = false --->| + * | | + * ... ... */ #include