RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

score misc: Clean up Doxygen (GCI 2012)

Browse Source 
This patch is a task from GCI 2012 which improves the Doxygen
comments in the RTEMS source.
https://google-melange.appspot.com/gci/task/view/google/gci2012/7978208
This commit is contained in:
Alex Ivanov
2012-11-28 08:11:31 -06:00
committed by Joel Sherrill
parent 815994fd17
commit f7f1d776de
28 changed files with 199 additions and 220 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
cpukit/score/include/rtems/score/coremsg.h
View File

@@ -436,6 +436,8 @@ void _CORE_message_queue_Seize(
);
/**
* @brief Insert a Message into the Message Queue
*
* This kernel routine inserts the specified message into the
* message queue. It is assumed that the message has been filled
* in before this routine is called.
@@ -444,6 +446,9 @@ void _CORE_message_queue_Seize(
* @param[in] the_message is the message to enqueue
* @param[in] submit_type determines whether the message is prepended,
* appended, or enqueued in priority order.
*
* - INTERRUPT LATENCY:
* + insert
*/
void _CORE_message_queue_Insert_message(
CORE_message_queue_Control *the_message_queue,

2
cpukit/score/include/rtems/score/corerwlock.h
View File

@@ -157,6 +157,8 @@ void _CORE_RWLock_Obtain_for_reading(
);
/**
* @brief RWLock Obtain for Writing
*
* This routine attempts to obtain the RWLock for write exclusive access.
*
* @param[in] the_rwlock is the RWLock to wait for

2
cpukit/score/include/rtems/score/corespinlock.h
View File

@@ -140,6 +140,8 @@ CORE_spinlock_Status _CORE_spinlock_Wait(
);
/**
* @brief Manually release Spinlock
*
* This routine manually releases the spinlock. All of the threads waiting
* for the spinlock will be readied.
*

8
cpukit/score/include/rtems/score/object.h
View File

@@ -49,6 +49,12 @@ extern "C" {
* @brief Provides CPU architecture dependent services.
*/
/**
* @defgroup ScoreObject Object Handler
*
* @ingroup Score
*/
/**
* The following type defines the control block used to manage
* object names.
@@ -450,6 +456,8 @@ void _Objects_Shrink_information(
);
/**
* @brief Initialize object Information
*
* This function initializes an object class information record.
* SUPPORTS_GLOBAL is true if the object class supports global
* objects, and false otherwise. Maximum indicates the number

9
cpukit/score/include/rtems/score/rbtree.h
View File

@@ -223,6 +223,15 @@ RBTree_Node *_RBTree_Get(
* This function returns a pointer to the node with key equal to a key
* of @a the_node if it exists in the Red-Black Tree @a the_rbtree,
* and NULL if not.
*
* @param[in] the_rbtree pointer to rbtree control
* @param[in] the_node node with the key to search for
* @return This method returns pointer to control header of rbtree. *
* If there is no control header available (the node is not part
* of a tree), then NULL is returned. *
*
* - INTERRUPT LATENCY:
* + single case
*/
RBTree_Node *_RBTree_Find(
RBTree_Control *the_rbtree,

3
cpukit/score/include/rtems/score/schedulerpriority.h
View File

@@ -69,6 +69,8 @@ typedef struct {
void _Scheduler_priority_Initialize(void);
/**
* @brief Scheduler priority Block
*
* This routine removes @a the_thread from the scheduling decision,
* that is, removes it from the ready queue. It performs
* any necessary scheduling operations including the selection of
@@ -107,6 +109,7 @@ void _Scheduler_priority_Free(
);
/**
* @brief Update Scheduler priority
* This routine updates @a the_thread->scheduler based on @a the_scheduler
* structures and thread state.
*

1
cpukit/score/include/rtems/score/thread.h
View File

@@ -592,6 +592,7 @@ bool _Thread_Start(
);
/**
* @brief Restart Thread
* This support routine restarts the specified task in a way that the
* next time this thread executes, it will begin execution at its
* original starting point.

62
cpukit/score/include/rtems/score/threadq.h
View File

@@ -51,9 +51,8 @@ typedef void ( *Thread_queue_Flush_callout )(
);
/**
*
* The following type defines the callout used for timeout processing
* methods.
* The following type defines the callout used for timeout processing
* methods.
*/
typedef void ( *Thread_queue_Timeout_callout )(
Objects_Id,
@@ -61,7 +60,7 @@ typedef void ( *Thread_queue_Timeout_callout )(
);
/**
* @brief Thread queue Dequeue
* @brief Thread Queue Dequeue
*
* This function returns a pointer to a thread waiting on
* the_thread_queue. The selection of this thread is based on
@@ -73,7 +72,7 @@ Thread_Control *_Thread_queue_Dequeue(
);
/**
* @brief Thread queue Enqueue Wrapper
* @brief Thread Queue Enqueue Wrapper
*
* This routine enqueues the currently executing thread on
* the_thread_queue with an optional timeout.
@@ -84,12 +83,17 @@ Thread_Control *_Thread_queue_Dequeue(
_timeout, \
_Thread_queue_Timeout )
/**
* @brief Thread queue Enqueue
* @brief Thread Queue Enqueue
*
* This routine enqueues the currently executing thread on
* the_thread_queue with an optional timeout.
* This routine blocks a thread, places it on a thread, and optionally
* starts a timeout timer.
*
* @param[in] the_thread_queue pointer to threadq
* @param[in] timeout interval to wait
*
* - INTERRUPT LATENCY:
* + single case
*/
void _Thread_queue_Enqueue_with_handler(
Thread_queue_Control* the_thread_queue,
@@ -98,7 +102,7 @@ void _Thread_queue_Enqueue_with_handler(
);
/**
* @brief Thread queue Requeue
* @brief Thread Queue Requeue
*
* This routine is invoked when a thread changes priority and is
* blocked on a thread queue. If the queue is priority ordered,
@@ -112,7 +116,7 @@ void _Thread_queue_Requeue(
);
/**
* @brief Thread queue Extract
* @brief Thread Queue Extract
*
* This routine removes the_thread from the_thread_queue
* and cancels any timeouts associated with this blocking.
@@ -123,7 +127,7 @@ void _Thread_queue_Extract(
);
/**
* @brief Thread queue Extract with proxy
* @brief Thread Queue Extract with proxy
*
* This routine extracts the_thread from the_thread_queue
* and ensures that if there is a proxy for this task on
@@ -134,7 +138,7 @@ bool _Thread_queue_Extract_with_proxy(
);
/**
* @brief Thread queue First
* @brief Thread Queue First
*
* This function returns a pointer to the "first" thread
* on the_thread_queue. The "first" thread is selected
@@ -145,7 +149,7 @@ Thread_Control *_Thread_queue_First(
);
/**
* @brief Thread queue Flush
* @brief Thread Queue Flush
*
* This routine unblocks all threads blocked on the_thread_queue
* and cancels any associated timeouts.
@@ -157,7 +161,7 @@ void _Thread_queue_Flush(
);
/**
* @brief Thread queue Initialize
* @brief Thread Queue Initialize
*
* This routine initializes the_thread_queue based on the
* discipline indicated in attribute_set. The state set on
@@ -171,7 +175,7 @@ void _Thread_queue_Initialize(
);
/**
* @brief Thread queue Dequeue priority
* @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
@@ -182,7 +186,7 @@ Thread_Control *_Thread_queue_Dequeue_priority(
);
/**
* @brief Thread queue Enqueue priority
* @brief Thread Queue Enqueue priority
*
* This routine enqueues the currently executing thread on
* the_thread_queue with an optional timeout using the
@@ -195,10 +199,16 @@ Thread_blocking_operation_States _Thread_queue_Enqueue_priority (
);
/**
* @brief Thread queue Extract priority Helper
* @brief Thread Queue Extract priority Helper
*
* This routine removes the_thread from the_thread_queue
* and cancels any timeouts associated with this blocking.
* @param[in] the_thread_queue pointer to a threadq header
* @param[in] the_thread pointer to a thread control block
* @param[in] requeuing true if requeuing and should not alter
* timeout or state
* - INTERRUPT LATENCY:
* + EXTRACT_PRIORITY
*/
void _Thread_queue_Extract_priority_helper(
Thread_queue_Control *the_thread_queue,
@@ -207,7 +217,7 @@ void _Thread_queue_Extract_priority_helper(
);
/**
* @brief Thread queue Extract priority
* @brief Thread Queue Extract priority
*
* This macro wraps the underlying call and hides the requeuing argument.
*/
@@ -217,7 +227,7 @@ void _Thread_queue_Extract_priority_helper(
/**
* @brief Thread queue First priority
* @brief Thread Queue First priority
*
* This function returns a pointer to the "first" thread
* on the_thread_queue. The "first" thread is the highest
@@ -228,7 +238,7 @@ Thread_Control *_Thread_queue_First_priority(
);
/**
* @brief Thread queue Dequeue FIFO
* @brief Thread Queue Dequeue FIFO
*
* This function returns a pointer to the thread which has
* been waiting the longest on the_thread_queue. If no
@@ -239,7 +249,7 @@ Thread_Control *_Thread_queue_Dequeue_fifo(
);
/**
* @brief Thread queue Enqueue FIFO
* @brief Thread Queue Enqueue FIFO
*
* This routine enqueues the currently executing thread on
* the_thread_queue with an optional timeout using the
@@ -252,7 +262,7 @@ Thread_blocking_operation_States _Thread_queue_Enqueue_fifo (
);
/**
* @brief Thread queue Extract FIFO
* @brief Thread Queue Extract FIFO
*
* This routine removes the_thread from the_thread_queue
* and cancels any timeouts associated with this blocking.
@@ -263,7 +273,7 @@ void _Thread_queue_Extract_fifo(
);
/**
* @brief Thread queue First FIFO
* @brief Thread Queue First FIFO
*
* This function returns a pointer to the "first" thread
* on the_thread_queue. The first thread is the thread
@@ -274,7 +284,7 @@ Thread_Control *_Thread_queue_First_fifo(
);
/**
* @brief Thread queue timeout
* @brief Thread Queue timeout
*
* This routine is invoked when a task's request has not
* been satisfied after the timeout interval specified to
@@ -288,7 +298,7 @@ void _Thread_queue_Timeout (
);
/**
* @brief Process Thread Queue Timeout
* @brief Process Thread Queue Timeout
*
* This is a shared helper routine which makes it easier to have multiple
* object class specific timeout routines.

33
cpukit/score/src/coremsginsert.c
View File

@@ -1,12 +1,11 @@
/**
* @file
*
* @brief Insert a Message into the Message Queue
* @ingroup ScoreMessageQueue
*/
/*
* CORE Message Queue Handler
*
* DESCRIPTION:
*
* This package is the implementation of the CORE Message Queue Handler.
* This core object provides task synchronization and communication functions
* via messages passed to queue objects.
*
* COPYRIGHT (c) 1989-2005.
* On-Line Applications Research Corporation (OAR).
*
@@ -28,24 +27,6 @@
#include <rtems/score/thread.h>
#include <rtems/score/wkspace.h>
/*
* _CORE_message_queue_Insert_message
*
* This kernel routine inserts the specified message into the
* message queue. It is assumed that the message has been filled
* in before this routine is called.
*
* Input parameters:
* the_message_queue - pointer to message queue
* the_message - message to insert
* priority - insert indication
*
* Output parameters: NONE
*
* INTERRUPT LATENCY:
* insert
*/
void _CORE_message_queue_Insert_message(
CORE_message_queue_Control *the_message_queue,
CORE_message_queue_Buffer_control *the_message,

23
cpukit/score/src/corerwlockobtainwrite.c
View File

@@ -1,6 +1,11 @@
/*
* SuperCore RWLock Handler -- Obtain RWLock for writing
/**
* @file
*
* @brief RWLock Obtain for Writing
* @ingroup ScoreRWLock
*/
/*
* COPYRIGHT (c) 1989-2006.
* On-Line Applications Research Corporation (OAR).
*
@@ -19,20 +24,6 @@
#include <rtems/score/thread.h>
#include <rtems/score/watchdog.h>
/*
* _CORE_rwlock_Obtain_for_writing
*
* This function waits for the rwlock to become available. Optionally,
* a limit may be placed on the duration of the spin.
*
* Input parameters:
* the_rwlock - the rwlock control block to initialize
* timeout_allowed - true if timeout allowed
* timeout - the maximum number of ticks to spin
*
* Output parameters: NONE
*/
void _CORE_RWLock_Obtain_for_writing(
CORE_RWLock_Control *the_rwlock,
Objects_Id id,

22
cpukit/score/src/corerwlocktimeout.c
View File

@@ -1,7 +1,11 @@
/**
* @file
*
* @brief RWLock Specific Thread Queue Timeout
* @ingroup ScoreRWLock
*/
/*
* Thread Queue Handler
*
*
* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*
@@ -18,18 +22,6 @@
#include <rtems/score/corerwlock.h>
#include <rtems/score/corerwlock.h>
/*
* _CORE_RWLock_Timeout
*
* This routine processes a thread which timeouts while waiting on
* a thread queue. It is called by the watchdog handler.
*
* Input parameters:
* id - thread id
*
* Output parameters: NONE
*/
void _CORE_RWLock_Timeout(
Objects_Id id,
void *ignored

23
cpukit/score/src/corespinlockrelease.c
View File

@@ -1,6 +1,11 @@
/*
* SuperCore Spinlock Handler -- Release a Spinlock
/**
* @file
*
* @brief Release a Spinlock
* @ingroup ScoreSpinlock
*/
/*
* COPYRIGHT (c) 1989-2006.
* On-Line Applications Research Corporation (OAR).
*
@@ -19,20 +24,6 @@
#include <rtems/score/thread.h>
#include <rtems/score/watchdog.h>
/*
* _CORE_spinlock_Release
*
* This function releases the spinlock.
*
* Input parameters:
* the_spinlock - the spinlock control block to initialize
*
* Output parameters:
* CORE_SPINLOCK_SUCCESSFUL - if successful
* error code - if unsuccessful
*
*/
CORE_spinlock_Status _CORE_spinlock_Release(
CORE_spinlock_Control *the_spinlock
)

21
cpukit/score/src/coretodgetuptimetimespec.c
View File

@@ -1,8 +1,12 @@
/*
* Time of Day (TOD) Handler - get uptime
/**
* @file
*
* @brief Get Uptime as struct timespec
* @ingroup ScoreTODConstants
*/
/* COPYRIGHT (c) 1989-2008.
/*
* COPYRIGHT (c) 1989-2008.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -19,17 +23,6 @@
#include <rtems/score/timestamp.h>
#include <rtems/score/tod.h>
/*
* _TOD_Get_uptime_as_timespec
*
* This routine is used to obtain the system uptime
*
* Input parameters:
* time - pointer to the timestamp structure
*
* Output parameters: NONE
*/
void _TOD_Get_uptime_as_timespec(
struct timespec *uptime
)

27
cpukit/score/src/objectinitializeinformation.c
View File

@@ -1,6 +1,11 @@
/*
* Object Handler Initialization per Object Class
/**
* @file
*
* @brief Initialize Object Information
* @ingroup ScoreObject
*/
/*
* COPYRIGHT (c) 1989-2011.
* On-Line Applications Research Corporation (OAR).
*
@@ -25,24 +30,6 @@
#include <rtems/score/sysstate.h>
#include <rtems/score/isr.h>
/*
* _Objects_Initialize_information
*
* This routine initializes all object information related data structures.
*
* Input parameters:
* information - object information table
* maximum - maximum objects of this class
* size - size of this object's control block
* is_string - true if names for this object are strings
* maximum_name_length - maximum length of each object's name
* When multiprocessing is configured,
* supports_global - true if this is a global object class
* extract_callout - pointer to threadq extract callout
*
* Output parameters: NONE
*/
void _Objects_Initialize_information(
Objects_Information *information,
Objects_APIs the_api,

7
cpukit/score/src/percpu.c
View File

@@ -1,3 +1,10 @@
/**
* @file
*
* @brief Allocate and Initialize Per CPU Structures
* @ingroup PerCPU
*/
/*
* COPYRIGHT (c) 1989-2011.
* On-Line Applications Research Corporation (OAR).

26
cpukit/score/src/rbtreefind.c
View File

@@ -1,3 +1,10 @@
/**
* @file
*
* @brief Find the control structure of the tree containing the given node
* @ingroup ScoreRBTree
*/
/*
* Copyright (c) 2010 Gedare Bloom.
*
@@ -15,25 +22,6 @@
#include <rtems/score/rbtree.h>
#include <rtems/score/isr.h>
/*
* _RBTree_Find
*
* This kernel routine returns a pointer to the rbtree node containing the
* given key within the given tree, if it exists, or NULL otherwise.
*
* Input parameters:
* the_rbtree - pointer to rbtree control
* search_node - node with the key to search for
*
* Output parameters:
* return_node - pointer to control header of rbtree
* NULL - if there is no control header available (the node is not part
* of a tree)
*
* INTERRUPT LATENCY:
* only case
*/
RBTree_Node *_RBTree_Find(
RBTree_Control *the_rbtree,
RBTree_Node *search_node

7
cpukit/score/src/schedulercbsgetparameters.c
View File

@@ -1,3 +1,10 @@
/**
* @file
*
* @brief _Scheduler_CBS_Get_parameters
* @ingroup ScoreScheduler
*/
/*
* Copyright (C) 2011 Petr Benes.
* Copyright (C) 2011 On-Line Applications Research Corporation (OAR).

7
cpukit/score/src/scheduleredfenqueue.c
View File

@@ -1,3 +1,10 @@
/**
* @file
*
* @brief Scheduler EDF Enqueue
* @ingroup ScoreScheduler
*/
/*
* Copyright (C) 2011 Petr Benes.
* Copyright (C) 2011 On-Line Applications Research Corporation (OAR).

7
cpukit/score/src/schedulerpriorityblock.c
View File

@@ -1,3 +1,10 @@
/**
* @file
*
* @brief Scheduler Priority Block
* @ingroup ScoreScheduler
*/
/*
* Scheduler Handler
*

9
cpukit/score/src/schedulerpriorityupdate.c
View File

@@ -1,6 +1,11 @@
/*
* Scheduler Handler
/**
* @file
*
* @brief Update Scheduler Priority
* @ingroup ScoreScheduler
*/
/*
* Copyright (C) 2010 Gedare Bloom.
* Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
*

8
cpukit/score/src/threaddisabledispatch.c
View File

@@ -1,5 +1,11 @@
/**
* @file
*
* @brief Disaable Thread Dispatching
* @ingroup ScoreThread
*/
/*
* _Thread_Disable_dispatch
*
*
* COPYRIGHT (c) 1989-2011.

23
cpukit/score/src/threadqenqueue.c
View File

@@ -1,3 +1,10 @@
/**
* @file
*
* @brief Thread Queue Enqueue
* @ingroup ScoreThreadQ
*/
/*
* Thread Queue Handler
*
@@ -23,22 +30,6 @@
#include <rtems/score/threadq.h>
#include <rtems/score/tqdata.h>
/*
* _Thread_queue_Enqueue_with_handler
*
* This routine blocks a thread, places it on a thread, and optionally
* starts a timeout timer.
*
* Input parameters:
* the_thread_queue - pointer to threadq
* timeout - interval to wait
*
* Output parameters: NONE
*
* INTERRUPT LATENCY:
* only case
*/
void _Thread_queue_Enqueue_with_handler(
Thread_queue_Control *the_thread_queue,
Watchdog_Interval timeout,

27
cpukit/score/src/threadqextractpriority.c
View File

@@ -1,7 +1,11 @@
/**
* @file
*
* @brief Thread queue Extract priority Helper
* @ingroup ScoreThreadQ
*/
/*
* Thread Queue Handler
*
*
* COPYRIGHT (c) 1989-2008.
* On-Line Applications Research Corporation (OAR).
*
@@ -23,23 +27,6 @@
#include <rtems/score/threadq.h>
#include <rtems/score/tqdata.h>
/*
* _Thread_queue_Extract_priority
*
* This routine removes a specific thread from the specified threadq,
* deletes any timeout, and unblocks the thread.
*
* Input parameters:
* the_thread_queue - pointer to a threadq header
* the_thread - pointer to a thread control block
* requeuing - true if requeuing and should not alter timeout or state
*
* Output parameters: NONE
*
* INTERRUPT LATENCY:
* EXTRACT_PRIORITY
*/
void _Thread_queue_Extract_priority_helper(
Thread_queue_Control *the_thread_queue __attribute__((unused)),
Thread_Control *the_thread,

20
cpukit/score/src/threadrestart.c
View File

@@ -1,7 +1,11 @@
/**
* @file
*
* @brief Restart Thread
* @ingroup ScoreThread
*/
/*
* Thread Handler
*
*
* COPYRIGHT (c) 1989-1999.
* On-Line Applications Research Corporation (OAR).
*
@@ -28,16 +32,6 @@
#include <rtems/score/userextimpl.h>
#include <rtems/score/wkspace.h>
/*
* _Thread_Restart
*
* DESCRIPTION:
*
* This support routine restarts the specified task in a way that the
* next time this thread executes, it will begin execution at its
* original starting point.
*/
bool _Thread_Restart(
Thread_Control *the_thread,
void *pointer_argument,

5
cpukit/score/src/timespecdivide.c
View File

@@ -1,5 +1,8 @@
/**
* @file score/src/timespecdivide.c
* @file
*
* @brief Divide Timespec By Integer
* @ingroup Timespec
*/
/*

7
cpukit/score/src/ts64getseconds.c
View File

@@ -1,6 +1,9 @@
/**
* @file score/src/ts64getseconds.c
*/
* @file
*
* @brief Get Seconds Portion of Timestamp
* @ingroup SuperCore
*/
/*
* COPYRIGHT (c) 1989-2008.

8
cpukit/score/src/ts64subtract.c
View File

@@ -1,7 +1,9 @@
/**
* @file score/src/ts64subtract.c
*/
* @file
*
* @brief Subtract Two Timestamps
* @ingroup Timestamp
*/
/*
* COPYRIGHT (c) 1989-2008.
* On-Line Applications Research Corporation (OAR).

17
cpukit/score/src/watchdogremove.c
View File

@@ -1,7 +1,11 @@
/**
* @file
*
* @brief Remove Watchdog from List
* @ingroup ScoreWatchdog
*/
/*
* Watchdog Handler
*
*
* COPYRIGHT (c) 1989-1999.
* On-Line Applications Research Corporation (OAR).
*
@@ -18,13 +22,6 @@
#include <rtems/score/isr.h>
#include <rtems/score/watchdog.h>
/*
* _Watchdog_Remove
*
* The routine removes a watchdog from a delta chain and updates
* the delta counters of the remaining watchdogs.
*/
Watchdog_States _Watchdog_Remove(
Watchdog_Control *the_watchdog
)