patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 7 Packages Projects Releases Wiki Activity

doc: Edit the Event Logger APIs

Browse source 
Edit public API details for clarity, grammar, punctuation found
on file event_logger.h

Includes the event logger information in the ReST documentation.
Modifies doxygen.config to include the event logger.

Made consistent use of @retval to document return values.

Used imperative verbs for all @brief descriptions.

Change-Id: I88b8672a527138e2b4f7df4b4b0495a0d871cad3
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero 2016-02-07 12:00:52 -06:00 committed by Gerrit Code Review
parent e893869435
commit a3edcaa816
4 changed files with 75 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/api/api.rst
View file

@ -20,3 +20,4 @@ The use of the Zephyr APIs is the same for all platforms and boards.
nanokernel_api.rst
microkernel_api.rst
io_interfaces.rst
event_logger.rst

16
doc/api/event_logger.rst Normal file
View file

@ -0,0 +1,16 @@
.. _event_logger:
Event Logger APIs
#################
.. contents::
:depth: 1
:local:
:backlinks: top
Event Logger
************
.. doxygengroup:: event_logger
:project: Zephyr
:content-only:

1
doc/doxygen.config
View file

@ -99,6 +99,7 @@ WARN_LOGFILE =
#---------------------------------------------------------------------------
INPUT = \
include/ \
include/misc/ \
lib/libc/minimal/include/
INPUT_ENCODING = UTF-8
FILE_PATTERNS = "*.c" "*.h" "*.S"

98
include/misc/event_logger.h
View file

@ -39,17 +39,22 @@ struct event_logger {
struct ring_buf ring_buf;
};
/**
* @brief Event Logger
* @defgroup event_logger Event Logger
* @{
*/
/**
* @brief Initialize the event logger.
*
* @details Initialize the ring buffer.
* @details This routine initializes the ring buffer.
*
* @param logger Logger to be initialized.
* @param logger_buffer Pointer to the buffer to be used by the logger.
* @param buffer_size Size of the buffer in 32-bit words.
*
* @return No return value.
* @return N/A
*/
void sys_event_logger_init(struct event_logger *logger,
uint32_t *logger_buffer, uint32_t buffer_size);
@ -58,15 +63,15 @@ void sys_event_logger_init(struct event_logger *logger,
/**
* @brief Send an event message to the logger.
*
* @details Add an event message to the ring buffer and signal the sync
* semaphore to inform that there are event messages available.
* @details This routine adds an event message to the ring buffer and signals
* the sync semaphore to indicate that event messages are available.
*
* @param logger Pointer to the event logger used.
* @param event_id The identification of the profiler event.
* @param event_id The profiler event's ID.
* @param event_data Pointer to the data of the message.
* @param data_size Size of the buffer in 32-bit words.
*
* @return No return value.
* @return N/A
*/
void sys_event_logger_put(struct event_logger *logger, uint16_t event_id,
uint32_t *event_data, uint8_t data_size);
@ -75,23 +80,23 @@ void sys_event_logger_put(struct event_logger *logger, uint16_t event_id,
/**
* @brief Retrieve an event message from the logger.
*
* @details Retrieve an event message from the ring buffer and copy it to the
* provided buffer. If the provided buffer is smaller than the message
* size the function returns -EMSGSIZE. Otherwise return the number of 32-bit
* words copied. The function retrieves messages in FIFO order. If there is no
* message in the buffer the function returns immediately. It can only be called
* from a fiber.
* @details This routine retrieves an event message from the ring buffer and
* copies it to the provided buffer. If the provided buffer is smaller
* than the message size the function returns -EMSGSIZE. Otherwise, it returns
* the number of 32-bit words copied. The function retrieves messages in
* FIFO order. If there is no message in the buffer the function returns
* immediately. It can only be called from a fiber.
*
* @param logger Pointer to the event logger used.
* @param event_id Pointer to the id of the event fetched
* @param dropped_event_count Pointer to how many events were dropped
* @param buffer Pointer to the buffer where the message will be copied.
* @param event_id Pointer to the id of the fetched event.
* @param dropped_event_count Pointer to the number of events dropped.
* @param buffer Pointer to the buffer for the copied message.
* @param buffer_size Size of the buffer in 32-bit words. Updated with the
* actual message size.
* actual message's size.
*
* @return -EMSGSIZE if the buffer size is smaller than the message size, or
* the amount of 32-bit words copied. 0 (zero) if there was no message already
* available.
* @retval EMSGSIZE If the buffer size is smaller than the message size.
* @retval Number of 32-bit words copied.
* @retval 0 If no message was already available.
*/
int sys_event_logger_get(struct event_logger *logger, uint16_t *event_id,
uint8_t *dropped_event_count, uint32_t *buffer,
@ -100,22 +105,23 @@ int sys_event_logger_get(struct event_logger *logger, uint16_t *event_id,
/**
* @brief Retrieve an event message from the logger, wait if empty.
*
* @details Retrieve an event message from the ring buffer and copy it to the
* provided buffer. If the provided buffer is smaller than the message
* size the function returns -EMSGSIZE. Otherwise return the number of 32-bit
* words copied. The function retrieves messages in FIFO order. The caller pends
* if there is no message available in the buffer. It can only be called from a
* fiber.
* @details This routine retrieves an event message from the ring buffer
* and copies it to the provided buffer. If the provided buffer is smaller
* than the message size the function returns -EMSGSIZE. Otherwise, it
* returns the number of 32-bit words copied.
*
* The function retrieves messages in FIFO order. The caller pends if there is
* no message available in the buffer. It can only be called from a fiber.
*
* @param logger Pointer to the event logger used.
* @param event_id Pointer to the id of the event fetched
* @param dropped_event_count Pointer to how many events were dropped
* @param buffer Pointer to the buffer where the message will be copied.
* @param event_id Pointer to the ID of the fetched event.
* @param dropped_event_count Pointer to the number of dropped events.
* @param buffer Pointer to the buffer for the copied messages.
* @param buffer_size Size of the buffer in 32-bit words. Updated with the
* actual message size.
* actual message's size.
*
* @return -EMSGSIZE if the buffer size is smaller than the message size. Or
* the amount of DWORDs copied.
* @retval EMSGSIZE If the buffer size is smaller than the message size.
* @retval Number of DWORDs copied, otherwise.
*/
int sys_event_logger_get_wait(struct event_logger *logger, uint16_t *event_id,
uint8_t *dropped_event_count, uint32_t *buffer,
@ -126,30 +132,36 @@ int sys_event_logger_get_wait(struct event_logger *logger, uint16_t *event_id,
* @brief Retrieve an event message from the logger, wait with a timeout if
* empty.
*
* @details Retrieve an event message from the ring buffer and copy it to the
* provided buffer. If the provided buffer is smaller than the message
* size the function returns -EMSGSIZE. Otherwise return the number of dwords
* copied. The function retrieves messages in FIFO order. The caller pends if
* there is no message available in the buffer until a new message is added or
* the timeout expires. It can only be called from a fiber.
* @details This routine retrieves an event message from the ring buffer and
* copies it to the provided buffer. If the provided buffer is smaller than
* the message size the routine returns -EMSGSIZE. Otherwise, it returns the
* number of dwords copied. The function retrieves messages in FIFO order.
* If no message is available in the buffer, the caller pends until a
* new message is added or the timeout expires. This routine can only be
* called from a fiber.
*
* @param logger Pointer to the event logger used.
* @param event_id Pointer to the id of the event fetched
* @param dropped_event_count Pointer to how many events were dropped
* @param buffer Pointer to the buffer where the message will be copied.
* @param event_id Pointer to the ID of the event fetched.
* @param dropped_event_count Pointer to the number of dropped events.
* @param buffer Pointer to the buffer for the copied message.
* @param buffer_size Size of the buffer in 32-bit words. Updated with the
* actual message size.
* @param timeout Timeout in ticks.
*
* @return -EMSGSIZE if the buffer size is smaller than the message size. Or
* the amount of 32-bit words copied. 0 (zero) if the timeout expired and there
* was no message already available.
* @retval EMSGSIZE if the buffer size is smaller than the message size.
* @retval Number of 32-bit words copied.
* @retval 0 If the timeout expired and there was no message already
* available.
*/
int sys_event_logger_get_wait_timeout(struct event_logger *logger,
uint16_t *event_id,
uint8_t *dropped_event_count,
uint32_t *buffer, uint8_t *buffer_size,
uint32_t timeout);
/**
* @}
*/
#endif /* CONFIG_NANO_TIMEOUTS */
#endif /* _ASMLANGUAGE */