diff options
author | Alexandre Devienne <deviennealexandre@gmail.com> | 2012-11-28 14:14:50 -0600 |
---|---|---|
committer | Joel Sherrill <joel.sherrill@oarcorp.com> | 2012-11-28 14:14:50 -0600 |
commit | bf54252a053b6bdedb01ca71bacba5a661ea6215 (patch) | |
tree | e7c08891d1204507c7aa2f6df58add7e0390b9ac /cpukit/score/include/rtems | |
parent | score misc: Clean up Doxygen #3 (GCI 2012) (diff) | |
download | rtems-bf54252a053b6bdedb01ca71bacba5a661ea6215.tar.bz2 |
Score misc: Clean up Doxygen #4 (GCI 2012)
This patch is a task from GCI 2012 which improves the Doxygen
comments in the RTEMS source.
http://www.google-melange.com/gci/task/view/google/gci2012/7985215
Diffstat (limited to '')
-rw-r--r-- | cpukit/score/include/rtems/score/corerwlock.h | 2 | ||||
-rw-r--r-- | cpukit/score/include/rtems/score/interr.h | 13 | ||||
-rw-r--r-- | cpukit/score/include/rtems/score/isr.h | 4 | ||||
-rw-r--r-- | cpukit/score/include/rtems/score/mpci.h | 30 | ||||
-rw-r--r-- | cpukit/score/include/rtems/score/object.h | 7 | ||||
-rw-r--r-- | cpukit/score/include/rtems/score/schedulerpriority.h | 2 | ||||
-rw-r--r-- | cpukit/score/include/rtems/score/thread.h | 41 | ||||
-rw-r--r-- | cpukit/score/include/rtems/score/threadq.h | 13 | ||||
-rw-r--r-- | cpukit/score/include/rtems/score/watchdog.h | 2 |
9 files changed, 100 insertions, 14 deletions
diff --git a/cpukit/score/include/rtems/score/corerwlock.h b/cpukit/score/include/rtems/score/corerwlock.h index 1bc5301946..f0d3477b22 100644 --- a/cpukit/score/include/rtems/score/corerwlock.h +++ b/cpukit/score/include/rtems/score/corerwlock.h @@ -125,6 +125,8 @@ typedef struct { } CORE_RWLock_Control; /** + * @brief Initialize a RWlock + * * This routine initializes the RWLock based on the parameters passed. * * @param[in] the_rwlock is the RWLock to initialize diff --git a/cpukit/score/include/rtems/score/interr.h b/cpukit/score/include/rtems/score/interr.h index e325e68d3b..6198dbd94a 100644 --- a/cpukit/score/include/rtems/score/interr.h +++ b/cpukit/score/include/rtems/score/interr.h @@ -172,6 +172,13 @@ extern Internal_errors_Information _Internal_errors_What_happened; * determines that a fatal error has occurred or a final system state is * reached (for example after exit()). * + * This routine will invoke the fatal error handler supplied by the user + * followed by the the default one provided by the executive. The default + * error handler assumes no hardware is present to help inform the user + * of the problem. Halt stores the error code in a known register, + * disables interrupts, and halts the CPU. If the CPU does not have a + * halt instruction, it will loop to itself. + * * The first action of this function is to call the fatal handler of the user * extensions. For the initial extensions the following conditions are * required @@ -191,6 +198,12 @@ extern Internal_errors_Information _Internal_errors_What_happened; * * The final step is to call the CPU specific _CPU_Fatal_halt(). * + * @param[in] the_source is what subsystem the error originated in + * @param[in] is_internal is if the error was internally generated + * @param[in] the_error is the fatal error status code + * + * @note The the_error is not necessarily a directive status code. + * * @see rtems_fatal_error_occurred() and rtems_fatal(). */ void _Internal_error_Occurred( diff --git a/cpukit/score/include/rtems/score/isr.h b/cpukit/score/include/rtems/score/isr.h index 531b872256..8a0574951b 100644 --- a/cpukit/score/include/rtems/score/isr.h +++ b/cpukit/score/include/rtems/score/isr.h @@ -87,7 +87,9 @@ SCORE_EXTERN ISR_Handler_entry *_ISR_Vector_table; #endif /** - * This routine performs the initialization necessary for this handler. + * @brief Initialize the ISR handler + * + * This routine performs the initialization necessary for the ISR handler. */ void _ISR_Handler_initialization ( void ); diff --git a/cpukit/score/include/rtems/score/mpci.h b/cpukit/score/include/rtems/score/mpci.h index 59e60f10fe..5fce6a274f 100644 --- a/cpukit/score/include/rtems/score/mpci.h +++ b/cpukit/score/include/rtems/score/mpci.h @@ -196,6 +196,8 @@ SCORE_EXTERN MPCI_Packet_processor _MPCI_Packet_processors[MP_PACKET_CLASSES_LAST+1]; /** + * @brief Initialization of the MPCI Handler + * * This routine performs the initialization necessary for this handler. * * @param[in] timeout_status is the value which should be returned to @@ -206,11 +208,15 @@ void _MPCI_Handler_initialization( ); /** + * @brief Create the MPCI Server Thread + * * This routine creates the packet receive server used in MP systems. */ void _MPCI_Create_server( void ); /** + * @brief Initialize the MPCI driver + * * This routine initializes the MPCI driver by * invoking the user provided MPCI initialization callout. */ @@ -242,6 +248,8 @@ void _MPCI_Register_packet_processor( MP_packet_Prefix *_MPCI_Get_packet ( void ); /** + * @brief Deallocate a packet + * * This routine deallocates a packet by invoking the user provided * MPCI return packet callout. * @@ -252,6 +260,8 @@ void _MPCI_Return_packet ( ); /** + * @brief Send a process packet + * * This routine sends a process packet by invoking the user provided * MPCI send callout. * @@ -264,6 +274,8 @@ void _MPCI_Send_process_packet ( ); /** + * @brief Send a request packet + * * This routine sends a request packet by invoking the user provided * MPCI send callout. * @@ -283,6 +295,8 @@ uint32_t _MPCI_Send_request_packet ( ); /** + * @brief Send a response packet + * * This routine sends a response packet by invoking the user provided * MPCI send callout. * @@ -295,6 +309,8 @@ void _MPCI_Send_response_packet ( ); /** + * @brief Receive a packet + * * This routine receives a packet by invoking the user provided * MPCI receive callout. * @@ -303,6 +319,8 @@ void _MPCI_Send_response_packet ( MP_packet_Prefix *_MPCI_Receive_packet ( void ); /** + * @brief Pass a packet to the thread + * * This routine is responsible for passing @a the_packet to the thread * waiting on the remote operation to complete. The unblocked thread is * responsible for eventually freeing @a the_packet. @@ -317,6 +335,8 @@ Thread_Control *_MPCI_Process_response ( ); /** + * @brief Receive and process all packets + * * This is the server thread which receives and processes all MCPI packets. * * @param[in] ignored is the thread argument. It is not used. @@ -326,11 +346,15 @@ Thread _MPCI_Receive_server( ); /** + * @brief Announce the availability of a packet + * * This routine informs RTEMS of the availability of an MPCI packet. */ void _MPCI_Announce ( void ); /** + * @brief Perform a process on another node + * * This routine performs a remote procedure call so that a * process operation can be performed on another node. * @@ -361,6 +385,8 @@ void _MPCI_Internal_packets_Send_process_packet ( */ /** + * @brief Perform requested action from another node + * * This routine performs the actions specific to this package for * the request from another node. */ @@ -391,7 +417,9 @@ void _MPCI_Internal_packets_Process_packet ( */ /** - * This routine is used to obtain a internal threads mp packet. + * @brief Obtain an internal thread + * + * This routine is used to obtain an internal threads MP packet. */ MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void ); diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h index c9176e7e5b..1dec9930d1 100644 --- a/cpukit/score/include/rtems/score/object.h +++ b/cpukit/score/include/rtems/score/object.h @@ -447,8 +447,13 @@ void _Objects_Extend_information( ); /** + * @brief Shrink an object class information record + * * This function shrink an object class information record. - * + * The object's name and object space are released. The local_table + * etc block does not shrink. The InActive list needs to be scanned + * to find the objects are remove them. + * * @param[in] information points to an object class information block. */ void _Objects_Shrink_information( diff --git a/cpukit/score/include/rtems/score/schedulerpriority.h b/cpukit/score/include/rtems/score/schedulerpriority.h index 63e36696cd..844d043eb4 100644 --- a/cpukit/score/include/rtems/score/schedulerpriority.h +++ b/cpukit/score/include/rtems/score/schedulerpriority.h @@ -83,6 +83,8 @@ void _Scheduler_priority_Block( ); /** + * @brief schedule entry point + * * This kernel routine sets the heir thread to be the next ready thread * by invoking the_scheduler->ready_queue->operations->first(). */ diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h index fd49b8c340..1c8723f70a 100644 --- a/cpukit/score/include/rtems/score/thread.h +++ b/cpukit/score/include/rtems/score/thread.h @@ -524,23 +524,36 @@ void _Thread_Create_idle(void); void _Thread_Start_multitasking( void ); /** + * @brief Dispatch Thread + * * This routine is responsible for transferring control of the - * processor from the executing thread to the heir thread. As part - * of this process, it is responsible for the following actions: - * + * processor from the executing thread to the heir thread. Once the + * heir is running an attempt is made to dispatch any ASRs. + * As part of this process, it is responsible for the following actions: * + saving the context of the executing thread * + restoring the context of the heir thread * + dispatching any signals for the resulting executing thread + + * ALTERNATE ENTRY POINTS: + * void _Thread_Enable_dispatch(); + * + * INTERRUPT LATENCY: + * dispatch thread + * no dispatch thread */ void _Thread_Dispatch( void ); /** + * @brief Stack Allocate Helper + * * Allocate the requested stack space for the thread. - * return the actual size allocated after any adjustment - * or return zero if the allocation failed. - * Set the Start.stack field to the address of the stack + * Set the Start.stack field to the address of the stack. + * + * @param[in] the_thread is the thread where the stack space is requested + * + * @retval actual size allocated after any adjustment + * @retval zero if the allocation failed */ - size_t _Thread_Stack_Allocate( Thread_Control *the_thread, size_t stack_size @@ -606,8 +619,15 @@ bool _Thread_Restart( ); /** + * @brief Resets a thread to its initial state + * * This routine resets a thread to its initial state but does - * not restart it. + * not restart it. Some APIs do this in separate + * operations and this division helps support this. + * + * @param[in] the_thread is the thread to resets + * @param[in] pointer_argument + * @param[in] numeric_argument */ void _Thread_Reset( Thread_Control *the_thread, @@ -688,8 +708,13 @@ void _Thread_Load_environment( void _Thread_Handler( void ); /** + * @brief Ended the delay of a Thread + * * This routine is invoked when a thread must be unblocked at the * end of a time based delay (i.e. wake after or wake when). + * It is called by the watchdog handler. + * + * @param[in] id is the thread id */ void _Thread_Delay_ended( Objects_Id id, diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h index 1999ea14ff..5a6e710a8b 100644 --- a/cpukit/score/include/rtems/score/threadq.h +++ b/cpukit/score/include/rtems/score/threadq.h @@ -180,9 +180,16 @@ void _Thread_queue_Initialize( /** * @brief Thread Queue Dequeue priority * - * This function returns a pointer to the highest priority - * thread waiting on the_thread_queue. If no threads are waiting - * on the_thread_queue, then NULL is returned. + * This routine removes a thread from the specified PRIORITY based + * threadq, unblocks it, and cancels its timeout timer. + * + * - INTERRUPT LATENCY: + * + single case + * + * @param[in] the_thread_queue is a pointer to a thread queue + * + * @retval thread dequeued + * @retval NULL if no thread are waiting on the_thread_queue */ Thread_Control *_Thread_queue_Dequeue_priority( Thread_queue_Control *the_thread_queue diff --git a/cpukit/score/include/rtems/score/watchdog.h b/cpukit/score/include/rtems/score/watchdog.h index 01b36b3be7..a3b033666e 100644 --- a/cpukit/score/include/rtems/score/watchdog.h +++ b/cpukit/score/include/rtems/score/watchdog.h @@ -263,6 +263,7 @@ void _Watchdog_Adjust_to_chain( * * This routine inserts @a the_watchdog into the @a header watchdog chain * for a time of @a units. + * Update the delta interval counters. * * @param[in] header is @a the_watchdog list to insert @a the_watchdog on * @param[in] the_watchdog is the watchdog to insert @@ -277,6 +278,7 @@ void _Watchdog_Insert ( * * This routine is invoked at appropriate intervals to update * the @a header watchdog chain. + * This routine decrements the delta counter in response to a tick. * * @param[in] header is the watchdog chain to tickle */ |