From 604fb54c2ebeb718adf919a22ead32435b732674 Mon Sep 17 00:00:00 2001 From: Boris Zbarsky Date: Thu, 23 Feb 2023 11:01:15 -0500 Subject: [PATCH] Improve documentation about our event buffer size configuration. (#25255) --- src/app/EventManagement.h | 56 ++++++++++++++++++------- src/include/platform/CHIPDeviceConfig.h | 29 +++++++++---- 2 files changed, 61 insertions(+), 24 deletions(-) diff --git a/src/app/EventManagement.h b/src/app/EventManagement.h index f4d575464df611..55209418d7e71e 100644 --- a/src/app/EventManagement.h +++ b/src/app/EventManagement.h @@ -37,6 +37,33 @@ #include #include +/** + * Events are stored in the LogStorageResources provided to + * EventManagement::Init. + * + * A newly generated event will be placed in the lowest-priority (in practice + * DEBUG) buffer, the one associated with the first LogStorageResource. If + * there is no space in that buffer, space will be created by evicting the + * oldest event currently in that buffer, until enough space is available. + * + * When an event is evicted from a buffer, there are two possibilities: + * + * 1) If the next LogStorageResource has a priority that is no higher than the + * event's priority, the event will be moved to that LogStorageResource's + * buffer. This may in turn require events to be evicted from that buffer. + * 2) If the next LogStorageResource has a priority that is higher than the + * event's priority, then the event is just dropped. + * + * This means that LogStorageResources at a given priority level are reserved + * for events of that priority level or higher priority. + * + * As a simple example, assume there are only two priority levels, DEBUG and + * CRITICAL, and two LogStorageResources with those priorities. In that case, + * old CRITICAL events will not start getting dropped until both buffers are + * full, while old DEBUG events will start getting dropped once the DEBUG + * LogStorageResource buffer is full. + */ + #define CHIP_CONFIG_EVENT_GLOBAL_PRIORITY PriorityLevel::Debug namespace chip { @@ -162,31 +189,28 @@ struct LogStorageResources /** * @brief - * A class for managing the in memory event logs. - * Assume we have two importance levels. DEBUG and CRITICAL, for simplicity, - * A new incoming event will always get logged in buffer with debug buffer no matter it is Debug or CRITICAL event. - * In order for it to get logged, we need to free up space. So we look at the tail of the buffer. - * If the tail of the buffer contains a DEBUG event, that will be dropped. If the tail of the buffer contains - * a CRITICAL event, that event will be 'promoted' to the next level of buffers, where it will undergo the same procedure - * The outcome of this management policy is that the critical buffer is dedicated to the critical events, and the - * debug buffer is shared between critical and debug events. + * A class for managing the in memory event logs. See documentation at the + * top of the file describing the eviction policy for events when there is no + * more space for new events. */ class EventManagement { public: /** - * @brief - * Initialize the EventManagement with an array of LogStorageResources. The - * array must provide a resource for each valid priority level, the elements - * of the array must be in increasing numerical value of priority (and in - * increasing priority); the first element in the array corresponds to the - * resources allocated for least important events, and the last element - * corresponds to the most critical events. + * Initialize the EventManagement with an array of LogStorageResources and + * an equal-length array of CircularEventBuffers that correspond to those + * LogStorageResources. The array of LogStorageResources must provide a + * resource for each valid priority level, the elements of the array must be + * in increasing numerical value of priority (and in increasing priority); + * the first element in the array corresponds to the resources allocated for + * least important events, and the last element corresponds to the most + * critical events. * * @param[in] apExchangeManager ExchangeManager to be used with this logging subsystem * - * @param[in] aNumBuffers Number of elements in inLogStorageResources array + * @param[in] aNumBuffers Number of elements in the apLogStorageResources + * and apCircularEventBuffer arrays. * * @param[in] apCircularEventBuffer An array of CircularEventBuffer for each priority level. * diff --git a/src/include/platform/CHIPDeviceConfig.h b/src/include/platform/CHIPDeviceConfig.h index 7e87ee7615c360..45db2624e773e7 100644 --- a/src/include/platform/CHIPDeviceConfig.h +++ b/src/include/platform/CHIPDeviceConfig.h @@ -952,8 +952,12 @@ * @def CHIP_DEVICE_CONFIG_EVENT_LOGGING_CRIT_BUFFER_SIZE * * @brief - * A size, in bytes, of the individual critical event logging buffer. - * Note: the critical event buffer must exist. + * A size, in bytes, of the buffer reserved for storing CRITICAL events and no + * other events. CRITICAL events will never be evicted until this buffer is + * full, so its size and the sizes of events determine how many of the last N + * CRITICAL events are guaranteed to be available. + * + * Note: this number must be nonzero. */ #ifndef CHIP_DEVICE_CONFIG_EVENT_LOGGING_CRIT_BUFFER_SIZE #define CHIP_DEVICE_CONFIG_EVENT_LOGGING_CRIT_BUFFER_SIZE (1024) @@ -967,9 +971,13 @@ * @def CHIP_DEVICE_CONFIG_EVENT_LOGGING_INFO_BUFFER_SIZE * * @brief - * A size, in bytes, of the individual info event logging buffer. - * Note: set to 0 to disable info event buffer and all support - * for the info level events. + * A size, in bytes, of the buffer reserved for storing events at INFO + * priority and higher. INFO-priority events will not be evicted until this + * buffer is full (with INFO and CRITICAL events in it) and the oldest event + * in the buffer is an INFO-priority event (which cannot be evicted into the + * CRITICAL event buffer). + * + * Note: set to 0 to treat INFO events as effectively equivalent to DEBUG events. */ #ifndef CHIP_DEVICE_CONFIG_EVENT_LOGGING_INFO_BUFFER_SIZE #define CHIP_DEVICE_CONFIG_EVENT_LOGGING_INFO_BUFFER_SIZE (512) @@ -979,9 +987,14 @@ * @def CHIP_DEVICE_CONFIG_EVENT_LOGGING_DEBUG_BUFFER_SIZE * * @brief - * A size, in bytes, of the individual debug event logging buffer. - * Note: set to 0 to disable debug event buffer and all support - * for the debug level events. + * A size, in bytes, of the buffer used for storing newly generated events, + * and the only buffer in which DEBUG-priority events are allowed. + * DEBUG-priority events will start getting evicted when this buffer is full + * (with DEBUG, INFO, and CRITICAL events in it) and the oldest event in the + * buffer is a DEBUG-priority event, which cannot be evicted into the INFO + * event buffer. + * + * Note: set to 0 to disable storing DEBUG events. */ #ifndef CHIP_DEVICE_CONFIG_EVENT_LOGGING_DEBUG_BUFFER_SIZE #define CHIP_DEVICE_CONFIG_EVENT_LOGGING_DEBUG_BUFFER_SIZE (512)