2008-04-28 Joel Sherrill <joel.sherrill@oarcorp.com>

* rtems/include/rtems.h, rtems/include/rtems/rtems/ratemon.h, rtems/include/rtems/rtems/status.h, rtems/include/rtems/rtems/tasks.h, rtems/include/rtems/rtems/timer.h, rtems/inline/rtems/rtems/sem.inl: More Doxygen warnings removed.
2026-11-09 08:37:58 +08:00 · 2008-04-28 18:21:01 +00:00
1 parent 86101e3cca
commit 2ad3d02459
@@ -1,3 +1,10 @@
+2008-04-28	Joel Sherrill <joel.sherrill@oarcorp.com>
+
+	* rtems/include/rtems.h, rtems/include/rtems/rtems/ratemon.h,
+	rtems/include/rtems/rtems/status.h,
+	rtems/include/rtems/rtems/tasks.h, rtems/include/rtems/rtems/timer.h,
+	rtems/inline/rtems/rtems/sem.inl: More Doxygen warnings removed.
+
 2008-04-28	Daron Chabot <daron.chabot@usask.ca>

 	* posix/src/keycreate.c, posix/src/pthreadequal.c,
@@ -31,7 +31,11 @@
 extern "C" {
 #endif

-/*
+#if (!defined(__RTEMS_VIOLATE_KERNEL_VISIBILITY__)) && \
+    (!defined(__RTEMS_INSIDE__))
+/**
+ *  @brief Compiling RTEMS Application Macro
+ *
 *  Unless told otherwise, the RTEMS include files will hide some stuff
 *  from normal application code.  Defining this crosses a boundary which
 *  is undesirable since it means your application is using RTEMS features
@@ -39,7 +43,6 @@ extern "C" {
 *  Define this at your own risk.
 */

-#if (!defined(__RTEMS_VIOLATE_KERNEL_VISIBILITY__)) && (!defined(__RTEMS_INSIDE__))
 #define __RTEMS_APPLICATION__
 #endif

@@ -76,23 +79,72 @@ extern "C" {
 #include <rtems/rtems/support.h>
 #include <rtems/score/sysstate.h>

+/**
+ *  This constant indicates whether this processor variant has
+ *  hardware floating point support.
+ */
 #define RTEMS_HAS_HARDWARE_FP CPU_HARDWARE_FP

-/**
+/*
 *  The following define the constants which may be used in name searches.
 */
-#define RTEMS_SEARCH_ALL_NODES   OBJECTS_SEARCH_ALL_NODES
-#define RTEMS_SEARCH_OTHER_NODES OBJECTS_SEARCH_OTHER_NODES
-#define RTEMS_SEARCH_LOCAL_NODE  OBJECTS_SEARCH_LOCAL_NODE
-#define RTEMS_WHO_AM_I           OBJECTS_WHO_AM_I

 /**
+ * This constant indicates that the search is across all nodes.
+ */
+#define RTEMS_SEARCH_ALL_NODES   OBJECTS_SEARCH_ALL_NODES
+
+/**
+ *  This constant indicates that the search is across all nodes
+ *  except the one the call is made from.
+ */
+#define RTEMS_SEARCH_OTHER_NODES OBJECTS_SEARCH_OTHER_NODES
+
+/**
+ *  This constant indicates that the search is to be restricted
+ *  to the local node.
+ */
+#define RTEMS_SEARCH_LOCAL_NODE  OBJECTS_SEARCH_LOCAL_NODE
+
+/**
+ *  This constant indicates that the caller wants to obtain the
+ *  name of the currently executing thread.
+ *
+ *  @note This constant is only meaningful when obtaining the name
+ *        of a task.
+ */
+#define RTEMS_WHO_AM_I           OBJECTS_WHO_AM_I
+
+/*
 * Parameters and return id's for _Objects_Get_next
 */
-#define RTEMS_OBJECT_ID_INITIAL_INDEX        OBJECTS_ID_INITIAL_INDEX
-#define RTEMS_OBJECT_ID_FINAL_INDEX          OBJECTS_ID_FINAL_INDEX
-#define RTEMS_OBJECT_ID_INITIAL(api, class, node) OBJECTS_ID_INITIAL(api, class, node)

+/**
+ *  This constant is the lowest valid valid for the index portion
+ *  of an object Id.
+ */
+#define RTEMS_OBJECT_ID_INITIAL_INDEX        OBJECTS_ID_INITIAL_INDEX
+
+/**
+ *  This constant is the maximum valid valid for the index portion
+ *  of an object Id.
+ */
+#define RTEMS_OBJECT_ID_FINAL_INDEX          OBJECTS_ID_FINAL_INDEX
+
+/**
+ *  This method returns the Id of the object with the lowest
+ *  valid index valud.
+ *
+ *  @param[in] _api is the API of the object
+ *  @param[in] _class is the Object Class of the object
+ *  @param[in] _node is the node where the object resides
+ */
+#define RTEMS_OBJECT_ID_INITIAL(_api, _class, _node) \
+   OBJECTS_ID_INITIAL(_api, _class, _node)
+
+/**
+ *  This constant is the maximum valid object Id.
+ */
 #define RTEMS_OBJECT_ID_FINAL                OBJECTS_ID_FINAL

 /**
@@ -158,7 +158,13 @@ typedef struct {
  Thread_Control                         *owner;
  rtems_rate_monotonic_period_statistics  Statistics;
 }   Rate_monotonic_Control;
-
+ 
+/**
+ *  @brief Rate Monotonic Period Class Management Structure
+ *
+ *  This instance of Objects_Information is used to manage the
+ *  set of rate monotonic period instances.
+ */
 RTEMS_RATEMON_EXTERN Objects_Information _Rate_monotonic_Information;

 /**
@@ -320,6 +326,11 @@ void _Rate_monotonic_Timeout(
  #define _Rate_monotonic_Reset_wall_time_statistics( _the_period )
 #endif

+/**
+ *  @brief Rate_monotonic_Reset_cpu_use_statistics
+ *
+ *  This helper method resets the period CPU usage statistics structure.
+ */
 #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS
  #define _Rate_monotonic_Reset_cpu_use_statistics( _the_period ) \
     do { \
@@ -331,6 +342,11 @@ void _Rate_monotonic_Timeout(
  #define _Rate_monotonic_Reset_cpu_use_statistics( _the_period )
 #endif

+/**
+ *  @brief Rate_monotonic_Reset_statistics
+ *
+ *  This helper method resets the period wall time statistics structure.
+ */
 #define _Rate_monotonic_Reset_statistics( _the_period ) \
  do { \
    memset( \
@@ -81,9 +81,30 @@ extern "C" {
 */
 typedef Priority_Control rtems_task_priority;

+/**
+ *  This is the constant used with the rtems_task_set_priority
+ *  directive to indicate that the caller wants to obtain its
+ *  current priority rather than set it as the name of the
+ *  directive indicates.
+ */
 #define RTEMS_NO_PRIORITY           RTEMS_CURRENT_PRIORITY

+/**
+ *  This constant is the least valid value for a Classic API
+ *  task priority.
+ */
 #define RTEMS_MINIMUM_PRIORITY      (PRIORITY_MINIMUM + 1)
+
+/**
+ *  This constant is the maximum valid value for a Classic API
+ *  task priority.
+ *
+ *  @note This is actually the priority of the IDLE thread so
+ *        using this priority will result in having a task
+ *        which never executes.  This could be useful if you
+ *        want to ensure that a task does not executes during
+ *        certain operations such as a system mode change.
+ */
 #define RTEMS_MAXIMUM_PRIORITY      PRIORITY_MAXIMUM

 /**
@@ -129,6 +150,7 @@ typedef Priority_Control rtems_task_priority;
 /** This is used to indicate the highest numbered notepad. */
 #define RTEMS_NOTEPAD_LAST RTEMS_NOTEPAD_15

+/** This is used to indicate the number of notepads available. */
 #define RTEMS_NUMBER_NOTEPADS  (RTEMS_NOTEPAD_LAST+1)

 /**
@@ -180,8 +202,8 @@ typedef struct {
  ASR_Information          Signal;
 }  RTEMS_API_Control;

-/*
- *  The following defines the information control block used to
+/**
+ *  The following instantiates the information control block used to
 *  manage this class of objects.
 */
 RTEMS_TASKS_EXTERN Objects_Information _RTEMS_tasks_Information;
@@ -312,6 +312,8 @@ rtems_status_code rtems_timer_get_information(
 */
 extern Watchdog_Control _Timer_Seconds_timer;

+/**
+ *  This method is used to temporaril
 #define _Timer_Server_stop_ticks_timer() \
      _Watchdog_Remove( &_Timer_Server->Timer )

@@ -67,6 +67,17 @@ RTEMS_INLINE_ROUTINE Semaphore_Control *_Semaphore_Get (
    _Objects_Get( &_Semaphore_Information, id, location );
 }

+/**
+ *  @brief Semaphore_Get (Interrupts disabled)
+ *
+ *  This function maps semaphore IDs to semaphore control blocks.
+ *  If ID corresponds to a local semaphore, then it returns
+ *  the_semaphore control pointer which maps to ID and location
+ *  is set to OBJECTS_LOCAL.  if the semaphore ID is global and
+ *  resides on a remote node, then location is set to OBJECTS_REMOTE,
+ *  and the_semaphore is undefined.  Otherwise, location is set
+ *  to OBJECTS_ERROR and the_semaphore is undefined.
+ */
 RTEMS_INLINE_ROUTINE Semaphore_Control *_Semaphore_Get_interrupt_disable (
  Objects_Id         id,
  Objects_Locations *location,