From 8d72288675536cc40b032435686ec70289bdf8fa Mon Sep 17 00:00:00 2001 From: bit-cyber-fh <3120225656@bit.edu.cn> Date: Thu, 28 Mar 2024 15:58:15 +0800 Subject: [PATCH] Better struct comment --- df_datalink_sp/src/include/circ_queue.h | 11 +- df_datalink_sp/src/include/clist.h | 150 +++++++++--------- .../networking/link_layer/geometry/coord.h | 2 +- .../link_layer/geometry/eulerangles.h | 2 +- .../link_layer/geometry/quaternion.h | 2 +- .../src/networking/link_layer/link_layer.h | 6 +- .../networking/link_layer/link_layer_types.h | 36 +++-- .../src/networking/link_layer/node_list.h | 5 +- .../src/networking/link_layer/schdevent.h | 6 +- .../src/networking/phy_layer/phy_layer.h | 25 +-- df_datalink_sp/src/system_monitor.c | 4 +- df_datalink_sp/src/system_monitor.h | 13 +- df_datalink_sp/src/systembus/systembus.h | 4 +- df_datalink_sp/src/systembus/systembus_uart.h | 12 ++ df_datalink_sp/src/time_ctrl/time_ctrl.h | 7 +- 15 files changed, 154 insertions(+), 131 deletions(-) diff --git a/df_datalink_sp/src/include/circ_queue.h b/df_datalink_sp/src/include/circ_queue.h index 0d5245a..d4e7308 100644 --- a/df_datalink_sp/src/include/circ_queue.h +++ b/df_datalink_sp/src/include/circ_queue.h @@ -29,15 +29,16 @@ #include /** - * @struct CircularQueueInst + * @struct CIRC_QUEUE + * @brief Circular queue Instance */ typedef struct { void **data; - volatile uint32_t nelts; /**< # elements */ - uint32_t in; /**< next empty location */ - uint32_t out; /**< next filled location */ - uint32_t bounds; /**< max size of queue */ + volatile uint32_t nelts; ///< number of elements + uint32_t in; ///< next empty location + uint32_t out; ///< next filled location + uint32_t bounds; ///< max size of queue } CIRC_QUEUE; /** diff --git a/df_datalink_sp/src/include/clist.h b/df_datalink_sp/src/include/clist.h index d82da88..84e944b 100644 --- a/df_datalink_sp/src/include/clist.h +++ b/df_datalink_sp/src/include/clist.h @@ -32,104 +32,100 @@ extern "C" #include #include - /** - * @enum cListDirection - * @brief clist_t iterator direction. - */ + /** + * @enum clist_direction_t + * @brief clist_t iterator direction. + */ + typedef enum + { + LIST_HEAD, + LIST_TAIL + } clist_direction_t; - typedef enum - { - LIST_HEAD, - LIST_TAIL - } clist_direction_t; + /** + * @struct clist_node_t + * @brief clist_t node struct. + */ + typedef struct + { + struct clist_node *prev; ///< previous node + struct clist_node *next; ///< next node + void *val; + } clist_node_t; - /** - * @struct cListNode - * @brief clist_t node struct. - */ + /** + * @struct clist_t + * @brief clist_t struct. + */ + typedef struct + { + clist_node_t *head; ///< first node + clist_node_t *tail; ///< last node + uint32_t len; ///< list length + void (*free)(void *val); ///< node free function handle + int8_t (*compare)(void *a, void *b); ///< node compare function handle + } clist_t; - typedef struct clist_node - { - struct clist_node *prev; - struct clist_node *next; - void *val; - } clist_node_t; + /** + * @struct clist_iterator_t + * @brief clist_t iterator struct. + */ + typedef struct + { + clist_node_t *next; ///< next element + clist_direction_t direction; ///< iter direction + } clist_iterator_t; - /** - * @struct cListInst - * @brief clist_t struct. - */ + // Node prototypes. - typedef struct - { - clist_node_t *head; - clist_node_t *tail; - uint32_t len; - void (*free)(void *val); - int8_t (*compare)(void *a, void *b); - } clist_t; + clist_node_t * + clist_node_new(void *val); - /** - * @struct cListIter - * @brief clist_t iterator struct. - */ + // clist_t prototypes. - typedef struct - { - clist_node_t *next; - clist_direction_t direction; - } clist_iterator_t; + clist_t * + clist_new(void); - // Node prototypes. + clist_node_t * + clist_rpush(clist_t *self, clist_node_t *node); - clist_node_t * - clist_node_new(void *val); + clist_node_t * + clist_lpush(clist_t *self, clist_node_t *node); - // clist_t prototypes. + clist_node_t * + clist_find(clist_t *self, void *val); - clist_t * - clist_new(void); + clist_node_t * + clist_at(clist_t *self, int index); - clist_node_t * - clist_rpush(clist_t *self, clist_node_t *node); + clist_node_t * + clist_rpop(clist_t *self); - clist_node_t * - clist_lpush(clist_t *self, clist_node_t *node); + clist_node_t * + clist_lpop(clist_t *self); - clist_node_t * - clist_find(clist_t *self, void *val); + void + clist_remove(clist_t *self, clist_node_t *node); - clist_node_t * - clist_at(clist_t *self, int index); + void + clist_clear(clist_t *self); - clist_node_t * - clist_rpop(clist_t *self); + void + clist_destroy(clist_t *self); - clist_node_t * - clist_lpop(clist_t *self); + // clist_t iterator prototypes. - void - clist_remove(clist_t *self, clist_node_t *node); + clist_iterator_t * + clist_iterator_new(clist_t *list, clist_direction_t direction); - void - clist_clear(clist_t *self); + clist_iterator_t * + clist_iterator_new_from_node(clist_node_t *node, clist_direction_t direction); - void - clist_destroy(clist_t *self); + clist_node_t * + clist_iterator_next(clist_iterator_t *self); - // clist_t iterator prototypes. - - clist_iterator_t * - clist_iterator_new(clist_t *list, clist_direction_t direction); - - clist_iterator_t * - clist_iterator_new_from_node(clist_node_t *node, clist_direction_t direction); - - clist_node_t * - clist_iterator_next(clist_iterator_t *self); - - void - clist_iterator_destroy(clist_iterator_t *self); + void + clist_iterator_destroy(clist_iterator_t *self); #ifdef __cplusplus } diff --git a/df_datalink_sp/src/networking/link_layer/geometry/coord.h b/df_datalink_sp/src/networking/link_layer/geometry/coord.h index 533f69c..0d3a79c 100644 --- a/df_datalink_sp/src/networking/link_layer/geometry/coord.h +++ b/df_datalink_sp/src/networking/link_layer/geometry/coord.h @@ -28,7 +28,7 @@ */ /** - * @struct Coordinate + * @struct COORD * @brief Structure for storing 3D coordinates. */ typedef struct diff --git a/df_datalink_sp/src/networking/link_layer/geometry/eulerangles.h b/df_datalink_sp/src/networking/link_layer/geometry/eulerangles.h index 8296b65..bf790fa 100644 --- a/df_datalink_sp/src/networking/link_layer/geometry/eulerangles.h +++ b/df_datalink_sp/src/networking/link_layer/geometry/eulerangles.h @@ -45,7 +45,7 @@ */ /** - * @struct EulerAngles + * @struct EULERANGLES * @brief Structure for standard quaternion */ typedef struct diff --git a/df_datalink_sp/src/networking/link_layer/geometry/quaternion.h b/df_datalink_sp/src/networking/link_layer/geometry/quaternion.h index c91ae92..79241b4 100644 --- a/df_datalink_sp/src/networking/link_layer/geometry/quaternion.h +++ b/df_datalink_sp/src/networking/link_layer/geometry/quaternion.h @@ -32,7 +32,7 @@ #include "eulerangles.h" /** - * @struct Quaternion + * @struct QUATERNION * @brief Structure for standard quaternion */ typedef struct diff --git a/df_datalink_sp/src/networking/link_layer/link_layer.h b/df_datalink_sp/src/networking/link_layer/link_layer.h index 8d3610f..7df9fcc 100644 --- a/df_datalink_sp/src/networking/link_layer/link_layer.h +++ b/df_datalink_sp/src/networking/link_layer/link_layer.h @@ -33,7 +33,7 @@ /**************************** Type Definitions *******************************/ /** - * @struct LinklayerConfig + * @struct L2_CONFIG * @brief A struct holds all linklayer initialization parameters */ typedef struct @@ -50,7 +50,7 @@ typedef struct } L2_CONFIG; /** - * @struct LinklayerLogLocal + * @struct L2_LOG * @brief A struct holds linklayer operating log */ typedef struct @@ -84,7 +84,7 @@ typedef struct } L2_LOG; /** - * @struct LinklayerInst + * @struct L2_INST * @brief A linklayer instance */ typedef struct diff --git a/df_datalink_sp/src/networking/link_layer/link_layer_types.h b/df_datalink_sp/src/networking/link_layer/link_layer_types.h index 938427e..108fe0d 100644 --- a/df_datalink_sp/src/networking/link_layer/link_layer_types.h +++ b/df_datalink_sp/src/networking/link_layer/link_layer_types.h @@ -59,7 +59,8 @@ /**************************** Type Definitions *******************************/ /** - * @struct LinklayerRecord + * @struct L2_RCD + * @brief Linklayer recode buffer */ typedef struct { @@ -69,7 +70,7 @@ typedef struct } L2_RCD; /** - * @enum LinklayerTorType + * @enum L2_TOR_TYPE */ typedef enum { @@ -79,7 +80,7 @@ typedef enum } L2_TOR_TYPE; /** - * @enum LinkLayerNodeType + * @enum L2_NODE_TYPE */ typedef enum { @@ -90,7 +91,7 @@ typedef enum } L2_NODE_TYPE; /** - * @enum LinklayerNodeState + * @enum L2_NODE_STATE */ typedef enum { @@ -103,7 +104,7 @@ typedef enum } L2_NODE_STATE; /** - * @struct LinklayerNodeInfo + * @struct L2_NODE_INFO * @brief Node information struct contains the detail node info which needed by the link layer. */ typedef struct @@ -119,7 +120,7 @@ typedef struct } L2_NODE_INFO; /** - * @enum LinklayerEvent + * @enum L2_EVENT_TYPE */ typedef enum { @@ -138,7 +139,8 @@ typedef enum } L2_EVENT_TYPE; /** - * @struct LinklayerEvent + * @struct L2_EVENT + * @brief Linklayer event instance */ typedef struct { @@ -147,7 +149,7 @@ typedef struct } L2_EVENT; /** - * @enum LinklayerSlotType + * @enum L2_SLOT_TYPE */ typedef enum { @@ -160,7 +162,7 @@ typedef enum } L2_SLOT_TYPE; /** - * @enum LinklayerFrameType + * @enum L2_FRAME_TYPE */ typedef enum { @@ -172,7 +174,7 @@ typedef enum } L2_FRAME_TYPE; /** - * @enum LinklayerCRCType + * @enum L2_CRC_TYPE */ typedef enum { @@ -183,7 +185,8 @@ typedef enum } L2_CRC_TYPE; /** - * @struct LinklayerRoutineTableEntry + * @struct L2_RTNE_TABLE_ENTRY + * @brief Linklayer routine table entry */ typedef struct { @@ -194,7 +197,7 @@ typedef struct } L2_RTNE_TABLE_ENTRY; /** - * @enum LinklayerScanStage + * @enum SCAN_STAGE */ typedef enum { @@ -205,7 +208,8 @@ typedef enum } SCAN_STAGE; /** - * @struct LinklayerScanFSM + * @struct L2_SCAN_FSM + * @brief Linklayer scan process FSM instance */ typedef struct { @@ -222,7 +226,8 @@ typedef struct } L2_SCAN_FSM; /** - * @struct LinklayerServiceFSM + * @struct L2_SVC_FSM + * @brief Linklayer service process FSM */ typedef struct { @@ -238,7 +243,8 @@ typedef struct } L2_SVC_FSM; /** - * @struct LinklayerRoutineConfig + * @struct L2_RTNE_CONFIG + * @brief Linklayer routine table configuration */ typedef struct { diff --git a/df_datalink_sp/src/networking/link_layer/node_list.h b/df_datalink_sp/src/networking/link_layer/node_list.h index 8f6bfbf..7bb54b8 100644 --- a/df_datalink_sp/src/networking/link_layer/node_list.h +++ b/df_datalink_sp/src/networking/link_layer/node_list.h @@ -38,9 +38,10 @@ /***************** Macros (Inline Functions) Definitions *********************/ /**************************** Type Definitions *******************************/ /** - * @struct NodeList_Entry + * @struct NODE_ENTRY + * @brief Linklayer discovered node list node entry */ -typedef struct NODE_LIST_ENTRY +typedef struct { L2_NODE_INFO nodeInfo; uint32_t ttlCnt; diff --git a/df_datalink_sp/src/networking/link_layer/schdevent.h b/df_datalink_sp/src/networking/link_layer/schdevent.h index 259ecda..6999c4a 100644 --- a/df_datalink_sp/src/networking/link_layer/schdevent.h +++ b/df_datalink_sp/src/networking/link_layer/schdevent.h @@ -31,7 +31,8 @@ /***************** Macros (Inline Functions) Definitions *********************/ /**************************** Type Definitions *******************************/ /** - * @struct LinklayerEvent + * @struct L2_SCHD_EVENT + * @brief Linklayer scheduled event descriptor */ typedef struct { @@ -45,7 +46,8 @@ typedef struct } L2_SCHD_EVENT; /** - * @struct L2 event + * @struct L2_SCHD_POOL + * @brief Linklayer schedule event pool instance */ typedef struct { diff --git a/df_datalink_sp/src/networking/phy_layer/phy_layer.h b/df_datalink_sp/src/networking/phy_layer/phy_layer.h index a6e5e79..0a25c6d 100644 --- a/df_datalink_sp/src/networking/phy_layer/phy_layer.h +++ b/df_datalink_sp/src/networking/phy_layer/phy_layer.h @@ -56,7 +56,7 @@ /***************** Macros (Inline Functions) Definitions *********************/ /**************************** Type Definitions *******************************/ /** - * @enum PhysicalLayerFrameType + * @enum L1_FRAME_TYPE */ typedef enum { @@ -72,7 +72,8 @@ typedef enum } L1_FRAME_TYPE; /** - * @struct PhysicalLayerAntennaConfig + * @struct PHY_ANT_CONFIG + * @brief PhysicalLayer antenna config */ typedef struct { @@ -113,7 +114,8 @@ typedef struct } PHY_ANT_CONFIG; /** - * @struct PhysicalLayerAntennaAngle + * @struct PHY_ANT_ANGLE + * @brief Describe the PhysicalLayer antenna angle */ typedef struct { @@ -124,7 +126,7 @@ typedef struct } PHY_ANT_ANGLE; /** - * @enum PhysicalLayerTimeWordType + * @enum PHY_TIME_WORD_TYPE */ typedef enum { @@ -134,7 +136,7 @@ typedef enum } PHY_TIME_WORD_TYPE; /** - * @enum PhysicalLayerAntennaBeamWidth + * @enum PHY_ANT_BEAM_WIDTH */ typedef enum { @@ -146,7 +148,7 @@ typedef enum } PHY_ANT_BEAM_WIDTH; /** - * @enum PhysicalLayerTorState + * @enum PHY_TOR_TYPE */ typedef enum { @@ -156,7 +158,7 @@ typedef enum } PHY_TOR_TYPE; /** - * @enum PhysicalLayerWorkMode + * @enum PHY_MODE */ typedef enum { @@ -167,7 +169,7 @@ typedef enum } PHY_MODE; /** - * @enum PhysicalLayerAntennaMode + * @enum PHY_ANT_MODE */ typedef enum { @@ -178,7 +180,8 @@ typedef enum } PHY_ANT_MODE; /** - * @struct PhysicalLayerRecord + * @struct PHY_RCD + * @brief Physical Layer recode buffer */ typedef struct { @@ -188,7 +191,7 @@ typedef struct } PHY_RCD; /** - * @struct PhysicalLayerConfig + * @struct PHY_CONFIG * @brief struct holds all physical layer initialization parameters */ typedef struct @@ -209,7 +212,7 @@ typedef struct } PHY_CONFIG; /** - * @struct PhysicalLayerInst + * @struct PHY_INST * @brief Physical Layer operating instance */ typedef struct diff --git a/df_datalink_sp/src/system_monitor.c b/df_datalink_sp/src/system_monitor.c index acd945f..d50c20d 100644 --- a/df_datalink_sp/src/system_monitor.c +++ b/df_datalink_sp/src/system_monitor.c @@ -26,7 +26,7 @@ /** @} SystemMonitor_Private_Constants*/ /************************** Data Type Definitions ****************************/ /** - * @struct PingPong + * @struct PINGPONG * @brief PingPing Control */ typedef struct @@ -37,7 +37,7 @@ typedef struct } PINGPONG; /** - * @struct System_Monitor_Inst + * @struct SYSMONITOR * @brief System Monitor struct holds all the system log info */ typedef struct diff --git a/df_datalink_sp/src/system_monitor.h b/df_datalink_sp/src/system_monitor.h index 6b6a6bc..bf3b3f7 100644 --- a/df_datalink_sp/src/system_monitor.h +++ b/df_datalink_sp/src/system_monitor.h @@ -81,7 +81,8 @@ /************************* Data Type Definitions ****************************/ /** - * @struct System_Info + * @struct SYSINFO + * @brief System Infomation log */ typedef struct __attribute__((packed)) { @@ -112,7 +113,7 @@ typedef struct __attribute__((packed)) } SYSINFO; /** - * @struct System_Bus_Log + * @struct SYSBUSLOG * @brief System Info holds the system bus log */ typedef struct __attribute__((packed)) @@ -128,7 +129,7 @@ typedef struct __attribute__((packed)) } SYSBUSLOG; /** - * @struct Linklayer_Log + * @struct LINKLOG * @brief Linklayer Log struct holds the Linklayer log */ typedef struct __attribute__((packed)) @@ -160,7 +161,7 @@ typedef struct __attribute__((packed)) } LINKLOG; /** - * @struct Physical_Layer_Log + * @struct PHYLOG * @brief Physical Layer Log struct holds the Linklayer log */ typedef struct __attribute__((packed)) @@ -182,7 +183,7 @@ typedef struct __attribute__((packed)) } PHYLOG; /** - * @struct Hardware_Status_Log + * @struct HWSTATE * @brief Hardware Status Log struct holds all hardware status */ typedef struct __attribute__((packed)) @@ -206,7 +207,7 @@ typedef struct __attribute__((packed)) } HWSTATE; /** - * @struct Payload + * @struct PAYLOAD * @brief Payload struct holds the service payload */ typedef struct diff --git a/df_datalink_sp/src/systembus/systembus.h b/df_datalink_sp/src/systembus/systembus.h index 4c0549d..76c0b81 100644 --- a/df_datalink_sp/src/systembus/systembus.h +++ b/df_datalink_sp/src/systembus/systembus.h @@ -29,7 +29,7 @@ /************************** Data Type Definitions ****************************/ /** - * @struct SystemBus Config + * @struct SYSBUS_CONFIG * @brief SystemBus Config struct holds SystemBus initialization parameters */ typedef struct @@ -40,7 +40,7 @@ typedef struct } SYSBUS_CONFIG; /** - * @struct SystemBus Instance + * @struct SYSBUS * @brief SystemBus Instance struct */ typedef struct diff --git a/df_datalink_sp/src/systembus/systembus_uart.h b/df_datalink_sp/src/systembus/systembus_uart.h index 38a8017..a86c290 100644 --- a/df_datalink_sp/src/systembus/systembus_uart.h +++ b/df_datalink_sp/src/systembus/systembus_uart.h @@ -69,16 +69,28 @@ IO_In32((baseAddr) + (offset)) /************************** Data Type Definitions ****************************/ +/** + * @struct SYSBUS_UART_CONFIG + * @brief SystemBus UART driver initialization parameters + */ typedef struct { uintptr_t baseAddr; } SYSBUS_UART_CONFIG; +/** + * @struct SYSBUS_UART + * @brief SystemBus UART driver instance + */ typedef struct { SYSBUS_UART_CONFIG config; } SYSBUS_UART; +/** + * @struct SYSBUS_UART_FRAME + * @brief SystemBus UART frame definition + */ typedef struct { uint16_t len; diff --git a/df_datalink_sp/src/time_ctrl/time_ctrl.h b/df_datalink_sp/src/time_ctrl/time_ctrl.h index e22daf2..80e9257 100644 --- a/df_datalink_sp/src/time_ctrl/time_ctrl.h +++ b/df_datalink_sp/src/time_ctrl/time_ctrl.h @@ -39,7 +39,8 @@ typedef uint32_t TIME_FRAC; typedef uint32_t TIME_INT; /** - * @struct TimeWord + * @struct TIME_WORD + * @brief Time controller time word */ typedef struct { @@ -48,7 +49,7 @@ typedef struct } TIME_WORD; /** - * @struct TmcConfig. + * @struct TMC_CONFIG * @brief TmcConfig holds the initialization parameters of time controller */ typedef struct @@ -58,7 +59,7 @@ typedef struct } TMC_CONFIG; /** - * @struct TmcInst. + * @struct TMC_INST * @brief An instance struct of time controller */ typedef struct