[PATCH 2/8] rtems: Add files to Doxygen groups
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Jul 25 08:49:20 UTC 2023
Provide basic Doxygen comments.
Update #3706.
Update #3707.
---
bsps/shared/rtems-version.c | 9 +++
cpukit/include/rtems/linkersets.h | 50 ++++++++++++---
cpukit/include/rtems/sysinit.h | 91 ++++++++++++++++++++-------
cpukit/include/rtems/thread.h | 21 +++++++
cpukit/sapi/src/cpucounterconverter.c | 9 +++
cpukit/sapi/src/version.c | 2 +-
6 files changed, 150 insertions(+), 32 deletions(-)
diff --git a/bsps/shared/rtems-version.c b/bsps/shared/rtems-version.c
index b12504a1c9..aaac5a07f3 100644
--- a/bsps/shared/rtems-version.c
+++ b/bsps/shared/rtems-version.c
@@ -1,3 +1,12 @@
+/**
+ * @file
+ *
+ * @ingroup RTEMSImplClassic
+ *
+ * @brief This source file contains the implementation of
+ * rtems_board_support_package() and the definition of ::_RTEMS_version.
+ */
+
/*
* COPYRIGHT (c) 2003, Ralf Corsepius, Ulm, Germany.
* COPYRIGHT (c) 2003, On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/include/rtems/linkersets.h b/cpukit/include/rtems/linkersets.h
index ef1b0d38d4..a5d7b1b037 100644
--- a/cpukit/include/rtems/linkersets.h
+++ b/cpukit/include/rtems/linkersets.h
@@ -1,5 +1,13 @@
/* SPDX-License-Identifier: BSD-2-Clause */
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPILinkerSets
+ *
+ * @brief This header file provides the linker sets API.
+ */
+
/*
* Copyright (C) 2015, 2020 embedded brains GmbH & Co. KG
*
@@ -34,6 +42,36 @@
extern "C" {
#endif /* __cplusplus */
+/**
+ * @ingroup RTEMSImpl
+ *
+ * @brief Obfuscates a pointer to prevent compiler optimizations.
+ *
+ * @param ptr is the pointer to obfuscate.
+ *
+ * @return Returns the unsigned integer representation of the obfuscated
+ * pointer.
+ */
+static inline uintptr_t _Linker_set_Obfuscate( const void *ptr )
+{
+ uintptr_t addr;
+
+ addr = (uintptr_t) ptr;
+ RTEMS_OBFUSCATE_VARIABLE( addr );
+
+ return addr;
+}
+
+/**
+ * @defgroup RTEMSAPILinkerSets Linker Sets
+ *
+ * @ingroup RTEMSAPI
+ *
+ * @brief This group contains the linker sets API.
+ *
+ * @{
+ */
+
#define RTEMS_LINKER_SET_BEGIN( set ) \
_Linker_set_##set##_begin
@@ -129,16 +167,6 @@ extern "C" {
decl \
RTEMS_SECTION( ".rtemsrwset." #set ".content" )
-static inline uintptr_t _Linker_set_Obfuscate( const void *ptr )
-{
- uintptr_t addr;
-
- addr = (uintptr_t) ptr;
- RTEMS_OBFUSCATE_VARIABLE( addr );
-
- return addr;
-}
-
#define RTEMS_LINKER_SET_SIZE( set ) \
( _Linker_set_Obfuscate( RTEMS_LINKER_SET_END( set ) ) \
- _Linker_set_Obfuscate( RTEMS_LINKER_SET_BEGIN( set ) ) )
@@ -157,6 +185,8 @@ static inline uintptr_t _Linker_set_Obfuscate( const void *ptr )
++item \
)
+/** @} */
+
#ifdef __cplusplus
}
#endif /* __cplusplus */
diff --git a/cpukit/include/rtems/sysinit.h b/cpukit/include/rtems/sysinit.h
index b973ecfc91..3e6f4d9933 100644
--- a/cpukit/include/rtems/sysinit.h
+++ b/cpukit/include/rtems/sysinit.h
@@ -1,7 +1,15 @@
/* SPDX-License-Identifier: BSD-2-Clause */
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPISystemInit
+ *
+ * @brief This header file provides the API of the @ref RTEMSAPISystemInit.
+ */
+
/*
- * Copyright (C) 2015, 2020 embedded brains GmbH & Co. KG
+ * Copyright (C) 2015, 2023 embedded brains GmbH & Co. KG
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
@@ -34,6 +42,54 @@
extern "C" {
#endif /* __cplusplus */
+/**
+ * @ingroup RTEMSImpl
+ *
+ * @brief Enables a verbose system initialization.
+ */
+void _Sysinit_Verbose( void );
+
+/**
+ * @ingroup RTEMSImpl
+ *
+ * @brief Creates the system initialization item associated with the handler
+ * and index.
+ *
+ * The enum helps to detect typos in the module and order parameters of
+ * RTEMS_SYSINIT_ITEM().
+ */
+#define _RTEMS_SYSINIT_INDEX_ITEM( handler, index ) \
+ enum { _Sysinit_##handler = index }; \
+ RTEMS_LINKER_ROSET_ITEM_ORDERED( \
+ _Sysinit, \
+ rtems_sysinit_item, \
+ handler, \
+ index \
+ ) = { handler }
+
+/**
+ * @ingroup RTEMSImpl
+ *
+ * @brief Creates the system initialization item associated with the handler,
+ * module, and order.
+ *
+ * This helper macro is used to perform parameter expansion in
+ * RTEMS_SYSINIT_ITEM().
+ */
+#define _RTEMS_SYSINIT_ITEM( handler, module, order ) \
+ _RTEMS_SYSINIT_INDEX_ITEM( handler, 0x##module##order )
+
+/**
+ * @defgroup RTEMSAPISystemInit System Initialization Support
+ *
+ * @ingroup RTEMSAPI
+ *
+ * @brief The system initialization support provides an ordered invocation of
+ * system initialization handlers registered in a linker set.
+ *
+ * @{
+ */
+
/*
* The value of each module define must consist of exactly six hexadecimal
* digits without a 0x-prefix. A 0x-prefix is concatenated with the module and
@@ -133,29 +189,22 @@ typedef struct {
rtems_sysinit_handler handler;
} rtems_sysinit_item;
-/* The enum helps to detect typos in the module and order parameters */
-#define _RTEMS_SYSINIT_INDEX_ITEM( handler, index ) \
- enum { _Sysinit_##handler = index }; \
- RTEMS_LINKER_ROSET_ITEM_ORDERED( \
- _Sysinit, \
- rtems_sysinit_item, \
- handler, \
- index \
- ) = { handler }
-
-/* Create index from module and order */
-#define _RTEMS_SYSINIT_ITEM( handler, module, order ) \
- _RTEMS_SYSINIT_INDEX_ITEM( handler, 0x##module##order )
-
-/* Perform parameter expansion */
+/**
+ * @brief Creates the system initialization item associated with the handler,
+ * module, and order.
+ *
+ * @param handler is the system initialization handler.
+ *
+ * @param module is the system initialization module. It shall be a 6-digit
+ * hex number without a 0x-prefix.
+ *
+ * @param order is the system initialization order with respect to the module.
+ * It shall be a 2-digit hex number without a 0x-prefix.
+ */
#define RTEMS_SYSINIT_ITEM( handler, module, order ) \
_RTEMS_SYSINIT_ITEM( handler, module, order )
-/**
- * @brief System initialization handler to enable a verbose system
- * initialization.
- */
-void _Sysinit_Verbose( void );
+/** @} */
#ifdef __cplusplus
}
diff --git a/cpukit/include/rtems/thread.h b/cpukit/include/rtems/thread.h
index 739744b4e0..c3d7de67f4 100644
--- a/cpukit/include/rtems/thread.h
+++ b/cpukit/include/rtems/thread.h
@@ -1,5 +1,14 @@
/* SPDX-License-Identifier: BSD-2-Clause */
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPISelfContainedObjects
+ *
+ * @brief This header file provides the API of
+ * @ref RTEMSAPISelfContainedObjects.
+ */
+
/*
* Copyright (c) 2017 embedded brains GmbH & Co. KG
*
@@ -45,6 +54,16 @@ void _Semaphore_Post_binary(struct _Semaphore_Control *);
typedef struct _Mutex_Control rtems_mutex;
+/**
+ * @defgroup RTEMSAPISelfContainedObjects Self-Contained Objects
+ *
+ * @ingroup RTEMSAPI
+ *
+ * @brief This group contains the self-contained objects API.
+ *
+ * @{
+ */
+
#define RTEMS_MUTEX_INITIALIZER( name ) _MUTEX_NAMED_INITIALIZER( name )
static __inline void rtems_mutex_init( rtems_mutex *mutex, const char *name )
@@ -309,6 +328,8 @@ static __inline void rtems_binary_semaphore_destroy(
_Semaphore_Destroy( &binary_semaphore->Semaphore );
}
+/** @} */
+
__END_DECLS
#endif /* _RTEMS_THREAD_H */
diff --git a/cpukit/sapi/src/cpucounterconverter.c b/cpukit/sapi/src/cpucounterconverter.c
index 4cabdc5e4a..587fe460df 100644
--- a/cpukit/sapi/src/cpucounterconverter.c
+++ b/cpukit/sapi/src/cpucounterconverter.c
@@ -1,5 +1,14 @@
/* SPDX-License-Identifier: BSD-2-Clause */
+/**
+ * @file
+ *
+ * @ingroup RTEMSImpl
+ *
+ * @brief This source file contains a implementation of the counter value
+ * conversion functions.
+ */
+
/*
* Copyright (C) 2014, 2018 embedded brains GmbH & Co. KG
*
diff --git a/cpukit/sapi/src/version.c b/cpukit/sapi/src/version.c
index 385cf83f2a..ea07683876 100644
--- a/cpukit/sapi/src/version.c
+++ b/cpukit/sapi/src/version.c
@@ -3,7 +3,7 @@
/**
* @file
*
- * @ingroup RTEMSAPIClassicVersion
+ * @ingroup RTEMSImplClassic
*
* @brief This source file contains the implementation of rtems_version(),
* rtems_version_control_key(), rtems_version_major(), rtems_version_minor(),
--
2.35.3
More information about the devel
mailing list