score misc: Clean up Doxygen #14 (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/8025204
This commit is contained in:
Mathew Kallada
2012-12-02 16:59:17 -06:00
committed by Joel Sherrill
parent 43e0599151
commit c05d75020d
31 changed files with 230 additions and 287 deletions

View File

@@ -104,7 +104,7 @@ rtems_status_code rtems_barrier_create(
);
/**
* @brief rtems_barrier_ident
* @brief RTEMS Barrier name to Id
*
* This routine implements the rtems_barrier_ident directive.
* This directive returns the barrier ID associated with name.
@@ -139,7 +139,7 @@ rtems_status_code rtems_barrier_delete(
);
/**
* @brief rtems_barrier_wait
* @brief RTEMS Barrier Wait
*
* This routine implements the rtems_barrier_wait directive. It
* attempts to wait at the barrier associated with @a id. The calling task

View File

@@ -228,7 +228,7 @@ rtems_status_code rtems_clock_get_uptime(
);
/**
* @brief Gets the system uptime in the struct timeval format.
* @brief Gets the System Uptime in the Struct Timeval Format
*
* @param[out] Returns the system uptime. Pointer must not be NULL.
*/

View File

@@ -98,7 +98,7 @@ extern "C" {
*/
/**
* @brief Sends an event set to the target task.
* @brief Sends an Event Set to the Target Task
*
* This directive sends an event set @a event_in to the task specified by
* @a id.
@@ -453,6 +453,14 @@ void _Event_Seize(
States_Control wait_state
);
/**
* @brief Surrender Event
*
* - INTERRUPT LATENCY:
* + before flash
* + after flash
* + check sync
*/
void _Event_Surrender(
Thread_Control *the_thread,
rtems_event_set event_in,

View File

@@ -122,7 +122,7 @@ rtems_status_code rtems_message_queue_create(
);
/**
* @brief rtems_message_queue_ident
* @brief RTEMS Message Queue Name to Id
*
* This routine implements the rtems_message_queue_ident directive.
* This directive returns the message queue ID associated with NAME.
@@ -131,6 +131,13 @@ rtems_status_code rtems_message_queue_create(
* extent of the search for the ID of the message queue named name.
* The search can be limited to a particular node or allowed to
* encompass all nodes.
*
* @param[in] name is the user defined message queue name
* @param[in] node is the node(s) to be searched
* @param[in] id is the pointer to message queue id
*
* @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
* *id filled with the message queue id
*/
rtems_status_code rtems_message_queue_ident(
rtems_name name,
@@ -139,10 +146,14 @@ rtems_status_code rtems_message_queue_ident(
);
/**
* @brief rtems_message_queue_delete
* @brief RTEMS Delete Message Queue
*
* This routine implements the rtems_message_queue_delete directive. The
* message queue indicated by ID is deleted.
*
* @param[in] id is the queue id
*
* @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
*/
rtems_status_code rtems_message_queue_delete(
rtems_id id

View File

@@ -297,11 +297,17 @@ rtems_status_code rtems_rate_monotonic_ident(
);
/**
* @brief rtems_rate_monotonic_cancel
* @brief RTEMS Rate Monotonic Cancel
*
* This routine implements the rtems_rate_monotonic_cancel directive. This
* directive stops the period associated with ID from continuing to
* run.
*
* @param[in] id is the rate monotonic id
*
* @return RTEMS_SUCCESSFUL if successful and caller is not the owning thread
* or error code if unsuccessful
*
*/
rtems_status_code rtems_rate_monotonic_cancel(
rtems_id id
@@ -318,7 +324,7 @@ rtems_status_code rtems_rate_monotonic_delete(
);
/**
* @brief rtems_rate_monotonic_get_status
* @brief RTEMS Rate Monotonic Get Status
*
* This routine implements the rtems_rate_monotonic_get_status directive.
* Information about the period indicated by ID is returned.
@@ -330,10 +336,15 @@ rtems_status_code rtems_rate_monotonic_get_status(
);
/**
* @brief rtems_rate_monotonic_get_statistics
* @brief RTEMS Rate Monotonic Get Statistics
*
* This routine implements the rtems_rate_monotonic_get_statistics directive.
* Statistics gathered from the use of this period are returned.
*
* @param[in] id is the rate monotonic id
* @param[in] statistics is the pointer to statistics control block
*
* @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
*/
rtems_status_code rtems_rate_monotonic_get_statistics(
rtems_id id,
@@ -378,12 +389,17 @@ void rtems_rate_monotonic_report_statistics_with_plugin(
void rtems_rate_monotonic_report_statistics( void );
/**
* @brief rtems_rate_monotonic_period
* @brief RTEMS Rate Monotonic Period
*
* This routine implements the rtems_rate_monotonic_period directive. When
* length is non-zero, this directive initiates the period associated with
* ID from continuing for a period of length. If length is zero, then
* result is set to indicate the current state of the period.
*
* @param[in] id is the rate monotonic id
* @param[in] lenght is the length of period (in ticks)
*
* @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
*/
rtems_status_code rtems_rate_monotonic_period(
rtems_id id,
@@ -429,7 +445,7 @@ bool _Rate_monotonic_Get_status(
);
/**
* @brief _Rate_monotonic_Initiate_statistics(
* @brief Initiate Rate Monotonic Statistics
*
* This routine is invoked when a period is initiated via an explicit
* call to rtems_rate_monotonic_period for the period's first iteration

View File

@@ -136,11 +136,17 @@ rtems_status_code rtems_region_ident(
);
/**
* @brief rtems_region_get_information
* @brief RTEMS Get Region Information
*
* This routine implements the rtems_region_get_information directive.
* This directive returns information about the heap associated with
* this region.
*
* @param[in] id is the region id
* @param[in] the_info is the pointer to region information block
*
* @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
* *id filled with the region information block
*/
rtems_status_code rtems_region_get_information(
rtems_id id,
@@ -249,11 +255,13 @@ rtems_status_code rtems_region_resize_segment(
#ifndef __RTEMS_APPLICATION__
#include <rtems/rtems/region.inl>
/**
* @brief Region_Process_queue
* @brief Process Region Queue
*
* This is a helper routine which is invoked any time memory is
* freed. It looks at the set of waiting tasks and attempts to
* satisfy all outstanding requests.
*
* @param[in] the_region is the the region
*/
extern void _Region_Process_queue(Region_Control *the_region);

View File

@@ -128,7 +128,7 @@ rtems_status_code rtems_semaphore_create(
);
/**
* @brief rtems_semaphore_ident
* @brief RTEMS Semaphore Name to Id
*
* This routine implements the rtems_semaphore_ident directive.
* This directive returns the semaphore ID associated with name.
@@ -137,6 +137,13 @@ rtems_status_code rtems_semaphore_create(
* extent of the search for the ID of the semaphore named name.
* The search can be limited to a particular node or allowed to
* encompass all nodes.
*
* @param[in] name is the user defined semaphore name
* @param[in] node is(are) the node(s) to be searched
* @param[in] id is the pointer to semaphore id
*
* @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
* *id filled in with the semaphore id
*/
rtems_status_code rtems_semaphore_ident(
rtems_name name,

View File

@@ -61,10 +61,15 @@ rtems_status_code rtems_signal_catch(
);
/**
* @brief rtems_signal_send
* @brief RTEMS Send Signal
*
* This routine implements the rtems_signal_send directive. This directive
* sends the signal_set to the task specified by ID.
*
* @param[in] id is the thread thread id
* @param[in] signal_set is the signal set
*
* @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
*/
rtems_status_code rtems_signal_send(
rtems_id id,

View File

@@ -100,13 +100,13 @@ bool rtems_workspace_free(
);
/**
* @brief Greedy allocate that empties the workspace.
* @brief Greedy Allocate that Empties the Workspace
*
* Afterward the heap has at most @a block_count allocateable blocks of sizes
* specified by @a block_sizes. The @a block_sizes must point to an array with
* @a block_count members. All other blocks are used.
* Afterward the heap has at most @a block_count allocateable blocks of sizes
* specified by @a block_sizes. The @a block_sizes must point to an array with
* @a block_count members. All other blocks are used.
*
* @see rtems_workspace_greedy_free().
* @see rtems_workspace_greedy_free().
*/
void *rtems_workspace_greedy_allocate(
const uintptr_t *block_sizes,

View File

@@ -375,12 +375,19 @@ rtems_status_code rtems_task_resume(
);
/**
* @brief rtems_task_set_priority
* @brief RTEMS Set Task Priority
*
* This routine implements the rtems_task_set_priority directive. The
* current priority of the task associated with ID is set to
* new_priority. The former priority of that task is returned
* in old_priority.
*
* @param[in] id is the thread to extract
* @param[in] new_priority is the thread to extract
* @param[in] old_priority is the thread to extract
*
* @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
* and *old_priority filled in with the previous previous priority
*/
rtems_status_code rtems_task_set_priority(
rtems_id id,

View File

@@ -239,12 +239,18 @@ rtems_status_code rtems_timer_create(
);
/**
* @brief rtems_timer_ident
* @brief RTEMS Timer Name to Id
*
* This routine implements the rtems_timer_ident directive.
* This directive returns the timer ID associated with name.
* If more than one timer is named name, then the timer
* to which the ID belongs is arbitrary.
*
* @param[in] name is the user defined message queue name
* @param[in] id is the pointer to timer id
*
* @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
* id filled with the message queue id
*/
rtems_status_code rtems_timer_ident(
rtems_name name,

View File

@@ -1,6 +1,11 @@
/*
* Barrier Manager Name to ID
/**
* @file
*
* @brief RTEMS Barrier name to Id
* @ingroup ClassicBarrier
*/
/*
* COPYRIGHT (c) 1989-2006.
* On-Line Applications Research Corporation (OAR).
*
@@ -20,22 +25,6 @@
#include <rtems/rtems/options.h>
#include <rtems/rtems/barrier.h>
/*
* rtems_barrier_ident
*
* This directive returns the system ID associated with
* the barrier name.
*
* Input parameters:
* name - user defined barrier name
* id - pointer to barrier id
*
* Output parameters:
* *id - barrier id
* RTEMS_SUCCESSFUL - if successful
* error code - if unsuccessful
*/
rtems_status_code rtems_barrier_ident(
rtems_name name,
rtems_id *id

View File

@@ -1,6 +1,11 @@
/*
* Barrier Manager -- Wait at a Barrier
/**
* @file
*
* @brief RTEMS Barrier Wait
* @ingroup ClassicBarrier
*/
/*
* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*
@@ -20,20 +25,6 @@
#include <rtems/score/thread.h>
#include <rtems/score/threadq.h>
/*
* rtems_barrier_wait
*
* This directive allows a thread to wait at a barrier.
*
* Input parameters:
* id - barrier id
* timeout - number of ticks to wait (0 means wait forever)
*
* Output parameters:
* RTEMS_SUCCESSFUL - if successful
* error code - if unsuccessful
*/
rtems_status_code rtems_barrier_wait(
rtems_id id,
rtems_interval timeout

View File

@@ -1,3 +1,10 @@
/**
* @file
*
* @brief Gets the System Uptime in the Struct Timeval Format
* @ingroup ClassicClock
*/
/*
* Copyright (c) 2012 embedded brains GmbH. All rights reserved.
*

View File

@@ -1,6 +1,11 @@
/*
* Event Manager -- Instantiate Data
/**
* @file
*
* @brief Instantiate RTEMS Event Data
* @ingroup ClassicEvent
*/
/*
* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*
@@ -13,7 +18,6 @@
#include "config.h"
#endif
/* instantiate RTEMS event data */
#define RTEMS_EVENT_EXTERN
#include <rtems/system.h>

View File

@@ -1,6 +1,11 @@
/*
* Event Manager
/**
* @file
*
* @brief Sends an Event Set to the Target Task
* @ingroup ClassicEvent
*/
/*
* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*

View File

@@ -1,6 +1,11 @@
/*
* Event Manager
/**
* @file
*
* @brief Surrender Event
* @ingroup ClassicEvent
*/
/*
* COPYRIGHT (c) 1989-2008.
* On-Line Applications Research Corporation (OAR).
*
@@ -15,13 +20,6 @@
#include <rtems/rtems/event.h>
/*
* INTERRUPT LATENCY:
* before flash
* after flash
* check sync
*/
void _Event_Surrender(
Thread_Control *the_thread,
rtems_event_set event_in,

View File

@@ -1,6 +1,11 @@
/*
* Barrier Manager -- Instantiate Data
/**
* @file
*
* @brief Instantiate the Message Queue Data
* @ingroup ClassicMessageQueue
*/
/*
* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*
@@ -13,7 +18,6 @@
#include "config.h"
#endif
/* instantiate message queue data */
#define RTEMS_MESSAGE_EXTERN
#include <rtems/system.h>

View File

@@ -1,7 +1,11 @@
/**
* @file
*
* @brief RTEMS Delete Message Queue
* @ingroup ClassicMessageQueue
*/
/*
* Message Queue Manager
*
*
* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*
@@ -32,20 +36,6 @@
#include <rtems/rtems/options.h>
#include <rtems/rtems/support.h>
/*
* rtems_message_queue_delete
*
* This directive allows a thread to delete the message queue specified
* by the given queue identifier.
*
* Input parameters:
* id - queue id
*
* Output parameters:
* RTEMS_SUCCESSFUL - if successful
* error code - if unsuccessful
*/
rtems_status_code rtems_message_queue_delete(
rtems_id id
)

View File

@@ -1,7 +1,11 @@
/**
* @file
*
* @brief RTEMS Message Queue Name to Id
* @ingroup ClassicMessageQueue
*/
/*
* Message Queue Manager
*
*
* COPYRIGHT (c) 1989-1999.
* On-Line Applications Research Corporation (OAR).
*
@@ -32,23 +36,6 @@
#include <rtems/rtems/options.h>
#include <rtems/rtems/support.h>
/*
* rtems_message_queue_ident
*
* This directive returns the system ID associated with
* the message queue name.
*
* Input parameters:
* name - user defined message queue name
* node - node(s) to be searched
* id - pointer to message queue id
*
* Output parameters:
* *id - message queue id
* RTEMS_SUCCESSFUL - if successful
* error code - if unsuccessful
*/
rtems_status_code rtems_message_queue_ident(
rtems_name name,
uint32_t node,

View File

@@ -1,6 +1,11 @@
/*
* Rate Monotonic Manager -- Cancel a Period
/**
* @file
*
* @brief RTEMS Rate Monotonic Cancel
* @ingroup ClassicRateMon
*/
/*
* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*
@@ -21,19 +26,6 @@
#include <rtems/rtems/ratemon.h>
#include <rtems/score/thread.h>
/*
* rtems_rate_monotonic_cancel
*
* This directive allows a thread to cancel a rate monotonic timer.
*
* Input parameters:
* id - rate monotonic id
*
* Output parameters:
* RTEMS_SUCCESSFUL - if successful and caller is not the owning thread
* error code - if unsuccessful
*/
rtems_status_code rtems_rate_monotonic_cancel(
rtems_id id
)

View File

@@ -1,6 +1,11 @@
/*
* Rate Monotonic Manager -- Get Statistics
/**
* @file
*
* @brief RTEMS Rate Monotonic Get Statistics
* @ingroup ClassicRateMon
*/
/*
* COPYRIGHT (c) 1989-2009.
* On-Line Applications Research Corporation (OAR).
*
@@ -21,22 +26,6 @@
#include <rtems/rtems/ratemon.h>
#include <rtems/score/thread.h>
/*
* rtems_rate_monotonic_get_statistics
*
* This directive allows a thread to obtain statistics information on a
* period.
*
* Input parameters:
* id - rate monotonic id
* statistics - pointer to statistics control block
*
* Output parameters:
* RTEMS_SUCCESSFUL - if successful
* error code - if unsuccessful
*
*/
rtems_status_code rtems_rate_monotonic_get_statistics(
rtems_id id,
rtems_rate_monotonic_period_statistics *statistics

View File

@@ -1,6 +1,11 @@
/*
* Rate Monotonic Manager - Period Blocking and Status
/**
* @file
*
* @brief Rate Monotonic Support
* @ingroup ClassicRateMon
*/
/*
* COPYRIGHT (c) 1989-2010.
* On-Line Applications Research Corporation (OAR).
*
@@ -224,21 +229,6 @@ static void _Rate_monotonic_Update_statistics(
#endif
}
/*
* rtems_rate_monotonic_period
*
* This directive allows a thread to manipulate a rate monotonic timer.
*
* Input parameters:
* id - rate monotonic id
* length - length of period (in ticks)
*
* Output parameters:
* RTEMS_SUCCESSFUL - if successful
* error code - if unsuccessful
*/
rtems_status_code rtems_rate_monotonic_period(
rtems_id id,
rtems_interval length

View File

@@ -1,7 +1,11 @@
/**
* @file
*
* @brief RTEMS Get Region Information
* @ingroup ClassicRegion
*/
/*
* Region Manager
*
*
* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*
@@ -24,21 +28,6 @@
#include <rtems/score/apimutex.h>
#include <rtems/score/thread.h>
/*
* rtems_region_get_information
*
* This directive will return information about the region specified.
*
* Input parameters:
* id - region id
* the_info - pointer to region information block
*
* Output parameters:
* *the_info - region information block filled in
* RTEMS_SUCCESSFUL - if successful
* error code - if unsuccessful
*/
rtems_status_code rtems_region_get_information(
rtems_id id,
Heap_Information_block *the_info

View File

@@ -1,7 +1,11 @@
/**
* @file
*
* @brief Process Region Queue
* @ingroup ClassicRegion
*/
/*
* Region Manager
*
*
* COPYRIGHT (c) 1989-1999.
* On-Line Applications Research Corporation (OAR).
*
@@ -24,20 +28,6 @@
#include <rtems/score/thread.h>
#include <rtems/score/apimutex.h>
/*
* _Region_Process_queue
*
* If enough memory is available to satisfy the rtems_region_get_segment of
* the first blocked task, then that task and as many subsequent tasks as
* possible will be unblocked with their requests satisfied.
*
* Input parameters:
* the_region - the region
*
* Output parameters:
* none
*/
void _Region_Process_queue(
Region_Control *the_region
)

View File

@@ -1,6 +1,11 @@
/*
* RTEMS Object Helper -- Extract Index From Id
/**
* @file
*
* @brief Get Index Portion of Object Id
* @ingroup ClassicClassInfo
*/
/*
* COPYRIGHT (c) 1989-2008.
* On-Line Applications Research Corporation (OAR).
*

View File

@@ -1,20 +1,11 @@
/**
* @file
*
* @brief RTEMS Semaphore Name to Id
* @ingroup ClassicSem
*/
/*
* Semaphore Manager
*
* DESCRIPTION:
*
* This package is the implementation of the Semaphore Manager.
* This manager utilizes standard Dijkstra counting semaphores to provide
* synchronization and mutual exclusion capabilities.
*
* Directives provided are:
*
* + create a semaphore
* + get an ID of a semaphore
* + delete a semaphore
* + acquire a semaphore
* + release a semaphore
*
* COPYRIGHT (c) 1989-1999.
* On-Line Applications Research Corporation (OAR).
*
@@ -47,23 +38,6 @@
#include <rtems/score/interr.h>
/*
* rtems_semaphore_ident
*
* This directive returns the system ID associated with
* the semaphore name.
*
* Input parameters:
* name - user defined semaphore name
* node - node(s) to be searched
* id - pointer to semaphore id
*
* Output parameters:
* *id - semaphore id
* RTEMS_SUCCESSFUL - if successful
* error code - if unsuccessful
*/
rtems_status_code rtems_semaphore_ident(
rtems_name name,
uint32_t node,

View File

@@ -1,7 +1,11 @@
/**
* @file
*
* @brief RTEMS Send Signal
* @ingroup ClassicSignal
*/
/*
* Signal Manager
*
*
* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*
@@ -23,20 +27,6 @@
#include <rtems/score/thread.h>
#include <rtems/rtems/tasks.h>
/*
* rtems_signal_send
*
* This directive allows a thread to send signals to a thread.
*
* Input parameters:
* id - thread id
* signal_set - signal set
*
* Output parameters:
* RTEMS_SUCCESSFUL - if successful
* error code - if unsuccessful
*/
rtems_status_code rtems_signal_send(
rtems_id id,
rtems_signal_set signal_set

View File

@@ -1,7 +1,11 @@
/**
* @file
*
* @brief RTEMS Set Task Priority
* @ingroup ClassicTasks
*/
/*
* RTEMS Task Manager
*
*
* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*
@@ -29,24 +33,6 @@
#include <rtems/score/apiext.h>
#include <rtems/score/sysstate.h>
/*
* rtems_task_set_priority
*
* This directive changes the priority of the specified thread.
* The specified thread can be any thread in the system including
* the requesting thread.
*
* Input parameters:
* id - thread id (0 indicates requesting thread)
* new_priority - thread priority (0 indicates current priority)
* old_priority - pointer to previous priority
*
* Output parameters:
* old_priority - previous priority
* RTEMS_SUCCESSFUL - if successful
* error code - if unsuccessful
*/
rtems_status_code rtems_task_set_priority(
rtems_id id,
rtems_task_priority new_priority,

View File

@@ -1,7 +1,11 @@
/**
* @file
*
* @brief RTEMS Timer Name to Id
* @ingroup ClassicTimer
*/
/*
* Timer Manager - rtems_timer_ident directive
*
*
* COPYRIGHT (c) 1989-2002.
* On-Line Applications Research Corporation (OAR).
*
@@ -23,22 +27,6 @@
#include <rtems/score/tod.h>
#include <rtems/score/watchdog.h>
/*
* rtems_timer_ident
*
* This directive returns the system ID associated with
* the timer name.
*
* Input parameters:
* name - user defined message queue name
* id - pointer to timer id
*
* Output parameters:
* *id - message queue id
* RTEMS_SUCCESSFUL - if successful
* error code - if unsuccessful
*/
rtems_status_code rtems_timer_ident(
rtems_name name,
rtems_id *id

View File

@@ -1,3 +1,10 @@
/**
* @file
*
* @brief Greedy Allocate that Empties the Workspace and Free
* @ingroup ClassicRTEMS
*/
/*
* Copyright (c) 2012 embedded brains GmbH. All rights reserved.
*