Changeset 11e7893 in rtems


Ignore:
Timestamp:
Apr 12, 2019, 9:55:49 AM (6 months ago)
Author:
Andreas Dachsberger <andreas.dachsberger@…>
Branches:
master
Children:
d5548b65
Parents:
e2d575c2
git-author:
Andreas Dachsberger <andreas.dachsberger@…> (04/12/19 09:55:49)
git-committer:
Sebastian Huber <sebastian.huber@…> (05/13/19 05:42:04)
Message:

doxygen: score: adjust doc in schedulerimpl.h to doxygen guidelines

Update #3706.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • cpukit/include/rtems/score/schedulerimpl.h

    re2d575c2 r11e7893  
    11/**
    22 * @file
     3 *
     4 * @ingroup RTEMSScoreScheduler
    35 *
    46 * @brief Inlined Routines Associated with the Manipulation of the Scheduler
     
    3436/**
    3537 * @addtogroup RTEMSScoreScheduler
    36  */
    37 /**@{**/
     38 *
     39 * @{
     40 */
    3841
    3942/**
     
    6871
    6972/**
    70  *  @brief Initializes the scheduler to the policy chosen by the user.
    71  *
    72  *  This routine initializes the scheduler to the policy chosen by the user
    73  *  through confdefs, or to the priority scheduler with ready chains by
    74  *  default.
     73 * @brief Initializes the scheduler to the policy chosen by the user.
     74 *
     75 * This routine initializes the scheduler to the policy chosen by the user
     76 * through confdefs, or to the priority scheduler with ready chains by
     77 * default.
    7578 */
    7679void _Scheduler_Handler_initialization( void );
    7780
     81/**
     82 * @brief Gets the context of the scheduler.
     83 *
     84 * @param scheduler The scheduler to get the context of.
     85 *
     86 * @return The context of @a scheduler.
     87 */
    7888RTEMS_INLINE_ROUTINE Scheduler_Context *_Scheduler_Get_context(
    7989  const Scheduler_Control *scheduler
     
    8393}
    8494
     95/**
     96 * @brief Gets the scheduler for the cpu.
     97 *
     98 * @param cpu The cpu control to get the scheduler of.
     99 *
     100 * @return The scheduler for the cpu.
     101 */
    85102RTEMS_INLINE_ROUTINE const Scheduler_Control *_Scheduler_Get_by_CPU(
    86103  const Per_CPU_Control *cpu
     
    99116 * disabled).
    100117 *
    101  * @param[in] scheduler The scheduler instance.
    102  * @param[in] lock_context The lock context to use for
     118 * @param scheduler The scheduler instance.
     119 * @param lock_context The lock context to use for
    103120 *   _Scheduler_Release_critical().
    104121 */
     
    123140 * disabled).
    124141 *
    125  * @param[in] scheduler The scheduler instance.
    126  * @param[in] lock_context The lock context used for
     142 * @param scheduler The scheduler instance.
     143 * @param lock_context The lock context used for
    127144 *   _Scheduler_Acquire_critical().
    128145 */
     
    155172 * other scheduler instances.
    156173 *
    157  * @param[in] the_thread The thread in need for help.
     174 * @param the_thread The thread in need for help.
    158175 */
    159176RTEMS_INLINE_ROUTINE void _Scheduler_Ask_for_help( Thread_Control *the_thread )
     
    188205 * the scheduler. It does NOT dispatch.
    189206 *
    190  * @param[in] the_thread The thread which state changed previously.
     207 * @param the_thread The thread which state changed previously.
    191208 */
    192209RTEMS_INLINE_ROUTINE void _Scheduler_Schedule( Thread_Control *the_thread )
     
    209226 * of the processor to another thread.
    210227 *
    211  * @param[in] the_thread The yielding thread.
     228 * @param the_thread The yielding thread.
    212229 */
    213230RTEMS_INLINE_ROUTINE void _Scheduler_Yield( Thread_Control *the_thread )
     
    231248 * This routine removes @a the_thread from the scheduling decision for
    232249 * the scheduler. The primary task is to remove the thread from the
    233  * ready queue.  It performs any necessary schedulering operations
     250 * ready queue.  It performs any necessary scheduling operations
    234251 * including the selection of a new heir thread.
    235252 *
    236  * @param[in] the_thread The thread.
     253 * @param the_thread The thread.
    237254 */
    238255RTEMS_INLINE_ROUTINE void _Scheduler_Block( Thread_Control *the_thread )
     
    294311 * scheduler instance and update its internal state if necessary.
    295312 *
    296  * @param[in] the_thread The thread.
     313 * @param the_thread The thread.
    297314 *
    298315 * @see _Scheduler_Node_get_priority().
     
    329346 * in case the set of scheduled threads changes.
    330347 *
    331  * @param[in] the_thread The thread changing its priority.
     348 * @param the_thread The thread changing its priority.
    332349 *
    333350 * @see _Scheduler_Node_get_priority().
     
    379396 * priority change of a thread to the scheduler.
    380397 *
    381  * @param[in] the_thread The thread changing its priority or sticky level.
     398 * @param the_thread The thread changing its priority or sticky level.
    382399 *
    383400 * @see _Scheduler_Update_priority().
     
    441458 * other values the mapping is undefined.
    442459 *
    443  * @param[in] scheduler The scheduler instance.
    444  * @param[in] priority The user domain thread priority.
     460 * @param scheduler The scheduler instance.
     461 * @param priority The user domain thread priority.
    445462 *
    446463 * @return The corresponding thread priority of the scheduler domain is returned.
     
    457474 * @brief Unmaps a thread priority from the scheduler domain to the user domain.
    458475 *
    459  * @param[in] scheduler The scheduler instance.
    460  * @param[in] priority The scheduler domain thread priority.
     476 * @param scheduler The scheduler instance.
     477 * @param priority The scheduler domain thread priority.
    461478 *
    462479 * @return The corresponding thread priority of the user domain is returned.
     
    478495 * destroyed.
    479496 *
    480  * @param[in] scheduler The scheduler instance.
    481  * @param[in] node The scheduler node to initialize.
    482  * @param[in] the_thread The thread of the scheduler node to initialize.
    483  * @param[in] priority The thread priority.
     497 * @param scheduler The scheduler instance.
     498 * @param[out] node The scheduler node to initialize.
     499 * @param the_thread The thread of the scheduler node to initialize.
     500 * @param priority The thread priority.
    484501 */
    485502RTEMS_INLINE_ROUTINE void _Scheduler_Node_initialize(
     
    504521 * after a corresponding _Scheduler_Node_initialize().
    505522 *
    506  * @param[in] scheduler The scheduler instance.
    507  * @param[in] node The scheduler node to destroy.
     523 * @param scheduler The scheduler instance.
     524 * @param[out] node The scheduler node to destroy.
    508525 */
    509526RTEMS_INLINE_ROUTINE void _Scheduler_Node_destroy(
     
    518535 * @brief Releases a job of a thread with respect to the scheduler.
    519536 *
    520  * @param[in] the_thread The thread.
    521  * @param[in] priority_node The priority node of the job.
    522  * @param[in] deadline The deadline in watchdog ticks since boot.
    523  * @param[in] queue_context The thread queue context to provide the set of
     537 * @param the_thread The thread.
     538 * @param priority_node The priority node of the job.
     539 * @param deadline The deadline in watchdog ticks since boot.
     540 * @param queue_context The thread queue context to provide the set of
    524541 *   threads for _Thread_Priority_update().
    525542 */
     
    546563 * @brief Cancels a job of a thread with respect to the scheduler.
    547564 *
    548  * @param[in] the_thread The thread.
    549  * @param[in] priority_node The priority node of the job.
    550  * @param[in] queue_context The thread queue context to provide the set of
     565 * @param the_thread The thread.
     566 * @param priority_node The priority node of the job.
     567 * @param queue_context The thread queue context to provide the set of
    551568 *   threads for _Thread_Priority_update().
    552569 */
     
    575592 * scheduler which support standard RTEMS features, this includes
    576593 * time-slicing management.
     594 *
     595 * @param cpu The cpu control for the operation.
    577596 */
    578597RTEMS_INLINE_ROUTINE void _Scheduler_Tick( const Per_CPU_Control *cpu )
     
    589608 * @brief Starts the idle thread for a particular processor.
    590609 *
    591  * @param[in] scheduler The scheduler instance.
     610 * @param scheduler The scheduler instance.
    592611 * @param[in,out] the_thread The idle thread for the processor.
    593612 * @param[in,out] cpu The processor for the idle thread.
     
    604623}
    605624
     625/**
     626 * @brief Checks if the scheduler of the cpu with the given index is equal
     627 *      to the given scheduler.
     628 *
     629 * @param scheduler The scheduler for the comparison.
     630 * @param cpu_index The index of the cpu for the comparison.
     631 *
     632 * @retval true The scheduler of the cpu is the given @a scheduler.
     633 * @retval false The scheduler of the cpu is not the given @a scheduler.
     634 */
    606635RTEMS_INLINE_ROUTINE bool _Scheduler_Has_processor_ownership(
    607636  const Scheduler_Control *scheduler,
     
    625654}
    626655
     656/**
     657 * @brief Gets the processors of the scheduler
     658 *
     659 * @param scheduler The scheduler to get the processors of.
     660 *
     661 * @return The processors of the context of the given scheduler.
     662 */
    627663RTEMS_INLINE_ROUTINE const Processor_mask *_Scheduler_Get_processors(
    628664  const Scheduler_Control *scheduler
     
    636672}
    637673
     674/**
     675 * @brief Copies the thread's scheduler's affinity to the given cpuset.
     676 *
     677 * @param the_thread The thread to get the affinity of its scheduler.
     678 * @param cpusetsize The size of @a cpuset.
     679 * @param[out] cpuset The cpuset that serves as destination for the copy operation
     680 *
     681 * @retval true The copy operation was lossless.
     682 * @retval false The copy operation was not lossless
     683 */
    638684bool _Scheduler_Get_affinity(
    639685  Thread_Control *the_thread,
     
    642688);
    643689
     690/**
     691 * @brief Checks if the affinity is a subset of the online processors.
     692 *
     693 * @param scheduler This parameter is unused.
     694 * @param the_thread This parameter is unused.
     695 * @param node This parameter is unused.
     696 * @param affinity The processor mask to check.
     697 *
     698 * @retval true @a affinity is a subset of the online processors.
     699 * @retval false @a affinity is not a subset of the online processors.
     700 */
    644701RTEMS_INLINE_ROUTINE bool _Scheduler_default_Set_affinity_body(
    645702  const Scheduler_Control *scheduler,
     
    655712}
    656713
     714/**
     715 * @brief Sets the thread's scheduler's affinity.
     716 *
     717 * @param[in, out] the_thread The thread to set the affinity of.
     718 * @param cpusetsize The size of @a cpuset.
     719 * @param cpuset The cpuset to set the affinity.
     720 *
     721 * @retval true The operation succeeded.
     722 * @retval false The operation did not succeed.
     723 */
    657724bool _Scheduler_Set_affinity(
    658725  Thread_Control  *the_thread,
     
    661728);
    662729
     730/**
     731 * @brief Blocks the thread.
     732 *
     733 * @param scheduler The scheduler instance.
     734 * @param the_thread The thread to block.
     735 * @param node The corresponding scheduler node.
     736 * @param extract Method to extract the thread.
     737 * @param schedule Method for scheduling threads.
     738 */
    663739RTEMS_INLINE_ROUTINE void _Scheduler_Generic_block(
    664740  const Scheduler_Control *scheduler,
     
    686762}
    687763
     764/**
     765 * @brief Gets the number of processors of the scheduler.
     766 *
     767 * @param scheduler The scheduler instance to get the number of processors of.
     768 *
     769 * @return The number of processors.
     770 */
    688771RTEMS_INLINE_ROUTINE uint32_t _Scheduler_Get_processor_count(
    689772  const Scheduler_Control *scheduler
     
    701784}
    702785
     786/**
     787 * @brief Builds an object build id.
     788 *
     789 * @param scheduler_index The index to build the build id out of.
     790 *
     791 * @return The build id.
     792 */
    703793RTEMS_INLINE_ROUTINE Objects_Id _Scheduler_Build_id( uint32_t scheduler_index )
    704794{
     
    711801}
    712802
     803/**
     804 * @brief Gets the scheduler index from the given object build id.
     805 *
     806 * @param id The object build id.
     807 *
     808 * @return The scheduler index.
     809 */
    713810RTEMS_INLINE_ROUTINE uint32_t _Scheduler_Get_index_by_id( Objects_Id id )
    714811{
     
    718815}
    719816
     817/**
     818 * @brief Gets the scheduler from the given object build id.
     819 *
     820 * @param id The object build id.
     821 *
     822 * @return The scheduler to the object id.
     823 */
    720824RTEMS_INLINE_ROUTINE const Scheduler_Control *_Scheduler_Get_by_id(
    721825  Objects_Id id
     
    733837}
    734838
     839/**
     840 * @brief Gets the index of the scheduler
     841 *
     842 * @param scheduler The scheduler to get the index of.
     843 *
     844 * @return The index of the given scheduler.
     845 */
    735846RTEMS_INLINE_ROUTINE uint32_t _Scheduler_Get_index(
    736847  const Scheduler_Control *scheduler
     
    744855 * @brief Gets an idle thread from the scheduler instance.
    745856 *
    746  * @param[in] context The scheduler instance context.
    747  *
    748  * @retval idle An idle thread for use.  This function must always return an
     857 * @param context The scheduler instance context.
     858 *
     859 * @return idle An idle thread for use.  This function must always return an
    749860 * idle thread.  If none is available, then this is a fatal error.
    750861 */
     
    756867 * @brief Releases an idle thread to the scheduler instance for reuse.
    757868 *
    758  * @param[in] context The scheduler instance context.
    759  * @param[in] idle The idle thread to release
     869 * @param context The scheduler instance context.
     870 * @param idle The idle thread to release.
    760871 */
    761872typedef void ( *Scheduler_Release_idle_thread )(
     
    764875);
    765876
     877/**
     878 * @brief Changes the threads state to the given new state.
     879 *
     880 * @param[out] the_thread The thread to change the state of.
     881 * @param new_state The new state for @a the_thread.
     882 */
    766883RTEMS_INLINE_ROUTINE void _Scheduler_Thread_change_state(
    767884  Thread_Control         *the_thread,
     
    778895}
    779896
     897/**
     898 * @brief Sets the scheduler node's idle thread.
     899 *
     900 * @param[in, out] node The node to receive an idle thread.
     901 * @param idle The idle thread control for the operation.
     902 */
    780903RTEMS_INLINE_ROUTINE void _Scheduler_Set_idle_thread(
    781904  Scheduler_Node *node,
     
    793916
    794917/**
    795  * @brief Use an idle thread for this scheduler node.
    796  *
    797  * A thread those home scheduler node has a sticky level greater than zero may
    798  * use an idle thread in the home scheduler instance in case it executes
    799  * currently in another scheduler instance or in case it is in a blocking
     918 * @brief Uses an idle thread for this scheduler node.
     919 *
     920 * A thread whose home scheduler node has a sticky level greater than zero may
     921 * use an idle thread in the home scheduler instance in the case it executes
     922 * currently in another scheduler instance or in the case it is in a blocking
    800923 * state.
    801924 *
    802  * @param[in] context The scheduler instance context.
    803  * @param[in] node The node which wants to use the idle thread.
    804  * @param[in] cpu The processor for the idle thread.
    805  * @param[in] get_idle_thread Function to get an idle thread.
     925 * @param context The scheduler instance context.
     926 * @param[in, out] node The node which wants to use the idle thread.
     927 * @param cpu The processor for the idle thread.
     928 * @param get_idle_thread Function to get an idle thread.
    806929 */
    807930RTEMS_INLINE_ROUTINE Thread_Control *_Scheduler_Use_idle_thread(
     
    826949
    827950/**
    828  * @brief Try to schedule this scheduler node.
    829  *
    830  * @param[in] context The scheduler instance context.
    831  * @param[in] node The node which wants to get scheduled.
    832  * @param[in] idle A potential idle thread used by a potential victim node.
    833  * @param[in] get_idle_thread Function to get an idle thread.
     951 * @brief Tries to schedule this scheduler node.
     952 *
     953 * @param context The scheduler instance context.
     954 * @param[in, out] node The node which wants to get scheduled.
     955 * @param idle A potential idle thread used by a potential victim node.
     956 * @param get_idle_thread Function to get an idle thread.
    834957 *
    835958 * @retval true This node can be scheduled.
    836  * @retval false Otherwise.
     959 * @retval false This node cannot be scheduled.
    837960 */
    838961RTEMS_INLINE_ROUTINE Scheduler_Try_to_schedule_action
     
    8811004
    8821005/**
    883  * @brief Release an idle thread using this scheduler node.
    884  *
    885  * @param[in] context The scheduler instance context.
    886  * @param[in] node The node which may have an idle thread as user.
    887  * @param[in] release_idle_thread Function to release an idle thread.
     1006 * @brief Releases an idle thread using this scheduler node.
     1007 *
     1008 * @param context The scheduler instance context.
     1009 * @param[in, out] node The node which may have an idle thread as user.
     1010 * @param release_idle_thread Function to release an idle thread.
    8881011 *
    8891012 * @retval idle The idle thread which used this node.
     
    9091032}
    9101033
     1034/**
     1035 * @brief Exchanges an idle thread from the scheduler node that uses it
     1036 *      right now to another scheduler node.
     1037 *
     1038 * @param needs_idle The scheduler node that needs an idle thread.
     1039 * @param uses_idle The scheduler node that used the idle thread.
     1040 * @param idle The idle thread that is exchanged.
     1041 */
    9111042RTEMS_INLINE_ROUTINE void _Scheduler_Exchange_idle_thread(
    9121043  Scheduler_Node *needs_idle,
     
    9241055
    9251056/**
    926  * @brief Block this scheduler node.
    927  *
    928  * @param[in] context The scheduler instance context.
    929  * @param[in] thread The thread which wants to get blocked referencing this
     1057 * @brief Blocks this scheduler node.
     1058 *
     1059 * @param context The scheduler instance context.
     1060 * @param[in, out] thread The thread which wants to get blocked referencing this
    9301061 *   node.  This is not necessarily the user of this node in case the node
    9311062 *   participates in the scheduler helping protocol.
    932  * @param[in] node The node which wants to get blocked.
    933  * @param[in] is_scheduled This node is scheduled.
    934  * @param[in] get_idle_thread Function to get an idle thread.
     1063 * @param[in, out] node The node which wants to get blocked.
     1064 * @param is_scheduled This node is scheduled.
     1065 * @param get_idle_thread Function to get an idle thread.
    9351066 *
    9361067 * @retval thread_cpu The processor of the thread.  Indicates to continue with
     
    9811112}
    9821113
     1114/**
     1115 * @brief Discard the idle thread from the scheduler node.
     1116 *
     1117 * @param context The scheduler context.
     1118 * @param[in, out] the_thread The thread for the operation.
     1119 * @param[in, out] node The scheduler node to discard the idle thread from.
     1120 * @param release_idle_thread Method to release the idle thread from the context.
     1121 */
    9831122RTEMS_INLINE_ROUTINE void _Scheduler_Discard_idle_thread(
    9841123  Scheduler_Context             *context,
     
    10061145
    10071146/**
    1008  * @brief Unblock this scheduler node.
    1009  *
    1010  * @param[in] context The scheduler instance context.
    1011  * @param[in] the_thread The thread which wants to get unblocked.
    1012  * @param[in] node The node which wants to get unblocked.
    1013  * @param[in] is_scheduled This node is scheduled.
    1014  * @param[in] release_idle_thread Function to release an idle thread.
     1147 * @brief Unblocks this scheduler node.
     1148 *
     1149 * @param context The scheduler instance context.
     1150 * @param[in, out] the_thread The thread which wants to get unblocked.
     1151 * @param[in, out] node The node which wants to get unblocked.
     1152 * @param is_scheduled This node is scheduled.
     1153 * @param release_idle_thread Function to release an idle thread.
    10151154 *
    10161155 * @retval true Continue with the unblocking operation.
    1017  * @retval false Otherwise.
     1156 * @retval false Do not continue with the unblocking operation.
    10181157 */
    10191158RTEMS_INLINE_ROUTINE bool _Scheduler_Unblock_node(
     
    10481187#endif
    10491188
     1189/**
     1190 * @brief Updates the heir.
     1191 *
     1192 * @param[in, out] new_heir The new heir.
     1193 * @param force_dispatch Indicates whether the dispatch happens also if the
     1194 *      currently running thread is set as not preemptible.
     1195 */
    10501196RTEMS_INLINE_ROUTINE void _Scheduler_Update_heir(
    10511197  Thread_Control *new_heir,
     
    10721218}
    10731219
     1220/**
     1221 * @brief Sets a new scheduler.
     1222 *
     1223 * @param new_scheduler The new scheduler to set.
     1224 * @param[in, out] the_thread The thread for the operations.
     1225 * @param priority The initial priority for the thread with the new scheduler.
     1226 *
     1227 * @retval STATUS_SUCCESSFUL The operation succeeded.
     1228 * @retval STATUS_RESOURCE_IN_USE The thread's wait queue is not empty.
     1229 * @retval STATUS_UNSATISFIED The new scheduler has no processors.
     1230 */
    10741231RTEMS_INLINE_ROUTINE Status_Control _Scheduler_Set(
    10751232  const Scheduler_Control *new_scheduler,
Note: See TracChangeset for help on using the changeset viewer.