michaelh/zephyr
1
0
Fork 0
Code Releases Activity

debug: coredump: Doxygen cleanup

Browse source 
Ensure coredump.h is properly documented, in particular add missing docs
for coredump_query_id and coredump_cmd_id enums that are part of the
API.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This commit is contained in:
Benjamin Cabé 2023-08-21 14:36:08 +02:00 • committed by Carles Cufí
commit b4fe506779
1 changed files with 58 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

102
include/zephyr/debug/coredump.h
View file

@ -11,94 +11,115 @@
#include <stdint.h>
#include <sys/types.h>
/* Query ID */
/**
* @file
*
* @defgroup coredump_apis Coredump APIs
* @ingroup os_services
* @brief Coredump APIs
* @{
*/
/** Query ID */
enum coredump_query_id {
/*
/**
* Returns error code from backend.
*/
COREDUMP_QUERY_GET_ERROR,
/*
/**
* Check if there is a stored coredump from backend.
*
* Returns 1 if there is a stored coredump.
* 0 if none.
* -ENOTSUP if this query is not supported.
* Otherwise, error code from backend.
* Returns:
* - 1 if there is a stored coredump, 0 if none.
* - -ENOTSUP if this query is not supported.
* - Otherwise, error code from backend.
*/
COREDUMP_QUERY_HAS_STORED_DUMP,
/*
* Returns coredump raw size from backend.
* 0 if none.
* -ENOTSUP if this query is not supported.
* Otherwise, error code from backend.
/**
* Returns:
* - coredump raw size from backend, 0 if none.
* - -ENOTSUP if this query is not supported.
* - Otherwise, error code from backend.
*/
COREDUMP_QUERY_GET_STORED_DUMP_SIZE,
/**
* Max value for query ID.
*/
COREDUMP_QUERY_MAX
};
/* Command ID */
/** Command ID */
enum coredump_cmd_id {
/*
/**
* Clear error code from backend.
*
* Returns 0 if successful, failed otherwise.
*/
COREDUMP_CMD_CLEAR_ERROR,
/*
/**
* Verify that the stored coredump is valid.
*
* Returns 1 if valid.
* 0 if not valid or no stored coredump.
* -ENOTSUP if this command is not supported.
* Otherwise, error code from backend.
* Returns:
* - 1 if valid.
* - 0 if not valid or no stored coredump.
* - -ENOTSUP if this command is not supported.
* - Otherwise, error code from backend.
*/
COREDUMP_CMD_VERIFY_STORED_DUMP,
/*
/**
* Erase the stored coredump.
*
* Returns 0 if successful.
* -ENOTSUP if this command is not supported.
* Otherwise, error code from backend.
* Returns:
* - 0 if successful.
* - -ENOTSUP if this command is not supported.
* - Otherwise, error code from backend.
*/
COREDUMP_CMD_ERASE_STORED_DUMP,
/*
/**
* Copy the raw stored coredump.
*
* Returns copied size if successful
* 0 if stored coredump is not found
* -ENOTSUP if this command is not supported.
* Otherwise, error code from backend.
* Returns:
* - copied size if successful
* - 0 if stored coredump is not found
* - -ENOTSUP if this command is not supported.
* - Otherwise, error code from backend.
*/
COREDUMP_CMD_COPY_STORED_DUMP,
/*
/**
* Invalidate the stored coredump. This is faster than
* erasing the whole partition.
*
* Returns 0 if successful.
* -ENOTSUP if this command is not supported.
* Otherwise, error code from backend.
* Returns:
* - 0 if successful.
* - -ENOTSUP if this command is not supported.
* - Otherwise, error code from backend.
*/
COREDUMP_CMD_INVALIDATE_STORED_DUMP,
/**
* Max value for command ID.
*/
COREDUMP_CMD_MAX
};
/* Coredump copy command argument definition */
/** Coredump copy command (@ref COREDUMP_CMD_COPY_STORED_DUMP) argument definition */
struct coredump_cmd_copy_arg {
/* Copy offset */
/** Copy offset */
off_t offset;
/* Copy destination buffer */
/** Copy destination buffer */
uint8_t *buffer;
/* Copy length */
/** Copy length */
size_t length;
};
@ -244,13 +265,6 @@ int coredump_cmd(enum coredump_cmd_id query_id, void *arg)
#endif /* CONFIG_DEBUG_COREDUMP */
/**
* @defgroup coredump_apis Coredump APIs
* @ingroup os_services
* @brief Coredump APIs
* @{
*/
/**
* @fn void coredump(unsigned int reason, const z_arch_esf_t *esf, struct k_thread *thread);
* @brief Perform coredump.
@ -300,7 +314,7 @@ int coredump_cmd(enum coredump_cmd_id query_id, void *arg)
* @fn int coredump_cmd(enum coredump_cmd_id cmd_id, void *arg);
* @brief Perform command on coredump subsystem.
*
* Perform certain on coredump subsystem, for example, output the stored
* Perform command on coredump subsystem, for example, output the stored
* coredump via logging.
*
* @param[in] cmd_id Command ID