Changeset 6a1734a3 in rtems


Ignore:
Timestamp:
Apr 15, 2019, 8:17:38 AM (7 months ago)
Author:
Andreas Dachsberger <andreas.dachsberger@…>
Branches:
master
Children:
ee3351c
Parents:
ceff06f
git-author:
Andreas Dachsberger <andreas.dachsberger@…> (04/15/19 08:17:38)
git-committer:
Sebastian Huber <sebastian.huber@…> (05/13/19 05:42:04)
Message:

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

Update #3706.

File:
1 edited

Legend:

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

    rceff06f r6a1734a3  
    343343);
    344344
     345/**
     346 * @brief Does nothing.
     347 *
     348 * @param context This parameter is unused.
     349 * @param idle This parameter is unused.
     350 * @param cpu This parameter is unused.
     351 */
    345352static inline void _Scheduler_SMP_Do_nothing_register_idle(
    346353  Scheduler_Context *context,
     
    354361}
    355362
     363/**
     364 * @brief Checks if @a to_insert is less or equal than the priority of the chain node.
     365 *
     366 * @param to_insert The priority to compare.
     367 * @param next The chain node to compare the priority of.
     368 *
     369 * @retval true @a to_insert is less or equal than the priority of @a next.
     370 * @retval false @a to_insert is greater than the priority of @a next.
     371 */
    356372static inline bool _Scheduler_SMP_Priority_less_equal(
    357373  const void       *to_insert,
     
    368384}
    369385
     386/**
     387 * @brief Gets the scheduler smp context.
     388 *
     389 * @param context The context to cast to Scheduler_SMP_Context *.
     390 *
     391 * @return @a context cast to Scheduler_SMP_Context *.
     392 */
    370393static inline Scheduler_SMP_Context *_Scheduler_SMP_Get_self(
    371394  Scheduler_Context *context
     
    375398}
    376399
     400/**
     401 * @brief Initializes the scheduler smp context.
     402 *
     403 * @param[out] self The context to initialize.
     404 */
    377405static inline void _Scheduler_SMP_Initialize(
    378406  Scheduler_SMP_Context *self
     
    383411}
    384412
     413/**
     414 * @brief Gets the scheduler smp node of the thread.
     415 *
     416 * @param thread The thread to get the smp node of.
     417 *
     418 * @return The scheduler smp node of @a thread.
     419 */
    385420static inline Scheduler_SMP_Node *_Scheduler_SMP_Thread_get_node(
    386421  Thread_Control *thread
     
    390425}
    391426
     427/**
     428 * @brief Gets the scheduler smp node of the thread.
     429 *
     430 * @param thread The thread to get the smp node of.
     431 *
     432 * @return The scheduler smp node of @a thread.
     433 */
    392434static inline Scheduler_SMP_Node *_Scheduler_SMP_Thread_get_own_node(
    393435  Thread_Control *thread
     
    397439}
    398440
     441/**
     442 * @brief Gets the scheduler smp node.
     443 *
     444 * @param node The node to cast to Scheduler_SMP_Node *.
     445 *
     446 * @return @a node cast to Scheduler_SMP_Node *.
     447 */
    399448static inline Scheduler_SMP_Node *_Scheduler_SMP_Node_downcast(
    400449  Scheduler_Node *node
     
    404453}
    405454
     455/**
     456 * @brief Gets the state of the node.
     457 *
     458 * @param node The node to get the state of.
     459 *
     460 * @return The state of @a node.
     461 */
    406462static inline Scheduler_SMP_Node_state _Scheduler_SMP_Node_state(
    407463  const Scheduler_Node *node
     
    411467}
    412468
     469/**
     470 * @brief Gets the priority of the node.
     471 *
     472 * @param node The node to get the priority of.
     473 *
     474 * @return The priority of @a node.
     475 */
    413476static inline Priority_Control _Scheduler_SMP_Node_priority(
    414477  const Scheduler_Node *node
     
    418481}
    419482
     483/**
     484 * @brief Initializes the scheduler smp node.
     485 *
     486 * @param scheduler The scheduler instance.
     487 * @param[out] node The node to initialize.
     488 * @param thread The thread of the scheduler smp node.
     489 * @param priority The priority to initialize @a node with.
     490 */
    420491static inline void _Scheduler_SMP_Node_initialize(
    421492  const Scheduler_Control *scheduler,
     
    430501}
    431502
     503/**
     504 * @brief Updates the priority of the node to the new priority.
     505 *
     506 * @param[out] node The node to update the priority of.
     507 * @param new_priority The new priority for @a node.
     508 */
    432509static inline void _Scheduler_SMP_Node_update_priority(
    433510  Scheduler_SMP_Node *node,
     
    438515}
    439516
     517/**
     518 * @brief Changes the state of the node to the given state.
     519 *
     520 * @param[out] node the node to change the state of.
     521 * @param new_state The new state for @a node.
     522 */
    440523static inline void _Scheduler_SMP_Node_change_state(
    441524  Scheduler_Node           *node,
     
    449532}
    450533
     534/**
     535 * @brief Checks if the processor is owned by the given context.
     536 *
     537 * @param context The context to check whether @a cpu is owned by it.
     538 * @param cpu The cpu to check whether it is owned by @a context.
     539 *
     540 * @retval true @a cpu is owned by @a context.
     541 * @retval false @a cpu is not owned by @a context.
     542 */
    451543static inline bool _Scheduler_SMP_Is_processor_owned_by_us(
    452544  const Scheduler_Context *context,
     
    457549}
    458550
     551/**
     552 * @brief Gets The first idle thread of the given context.
     553 *
     554 * @param context The scheduler context to get the first idle thread from.
     555 *
     556 * @return The first idle thread of @a context.
     557 */
    459558static inline Thread_Control *_Scheduler_SMP_Get_idle_thread(
    460559  Scheduler_Context *context
     
    470569}
    471570
     571/**
     572 * @brief Releases the thread and adds it to the idle threads.
     573 *
     574 * @param[in, out] context The scheduler context instance.
     575 * @param idle The thread to add to the idle threads.
     576 */
    472577static inline void _Scheduler_SMP_Release_idle_thread(
    473578  Scheduler_Context *context,
     
    480585}
    481586
     587/**
     588 * @brief Extracts the node of the idle thread.
     589 *
     590 * @param[in, out] idle The thread to extract the node of.
     591 */
    482592static inline void _Scheduler_SMP_Exctract_idle_thread(
    483593  Thread_Control *idle
     
    487597}
    488598
     599/**
     600 * @brief Allocates the cpu for the scheduled thread.
     601 *
     602 * Attempts to prevent migrations but does not take into account affinity.
     603 *
     604 * @param context The scheduler context instance.
     605 * @param scheduled The scheduled node that should be executed next.
     606 * @param victim If the heir is this node's thread, no processor is allocated.
     607 * @param[in, out] victim_cpu The cpu to allocate.
     608 */
    489609static inline void _Scheduler_SMP_Allocate_processor_lazy(
    490610  Scheduler_Context *context,
     
    524644}
    525645
    526 /*
     646/**
     647 * @brief Allocates the cpu for the scheduled thread.
     648 *
    527649 * This method is slightly different from
    528650 * _Scheduler_SMP_Allocate_processor_lazy() in that it does what it is asked to
    529651 * do.  _Scheduler_SMP_Allocate_processor_lazy() attempts to prevent migrations
    530652 * but does not take into account affinity.
     653 *
     654 * @param context This parameter is unused.
     655 * @param scheduled The scheduled node whose thread should be executed next.
     656 * @param victim This parameter is unused.
     657 * @param[in, out] victim_cpu The cpu to allocate.
    531658 */
    532659static inline void _Scheduler_SMP_Allocate_processor_exact(
     
    547674}
    548675
     676/**
     677 * @brief Allocates the cpu for the scheduled thread using the given allocation function.
     678 *
     679 * @param context The scheduler context instance.
     680 * @param scheduled The scheduled node that should be executed next.
     681 * @param victim If the heir is this node's thread, no processor is allocated.
     682 * @param[in, out] victim_cpu The cpu to allocate.
     683 * @param allocate_processor The function to use for the allocation of @a victim_cpu.
     684 */
    549685static inline void _Scheduler_SMP_Allocate_processor(
    550686  Scheduler_Context                *context,
     
    559695}
    560696
     697/**
     698 * @brief Preempts the victim's thread and allocates a cpu for the scheduled thread.
     699 *
     700 * @param context The scheduler context instance.
     701 * @param scheduled Node of the scheduled thread that is about to be executed.
     702 * @param[in, out] victim Node of the thread to preempt.
     703 * @param allocate_processor The function for allocation of a processor for the new thread.
     704 *
     705 * @return The preempted thread.
     706 */
    561707static inline Thread_Control *_Scheduler_SMP_Preempt(
    562708  Scheduler_Context                *context,
     
    605751}
    606752
     753/**
     754 * @brief Returns the lowest member of the scheduled nodes.
     755 *
     756 * @param context The scheduler context instance.
     757 * @param filter This parameter is unused.
     758 *
     759 * @return The lowest scheduled node.
     760 */
    607761static inline Scheduler_Node *_Scheduler_SMP_Get_lowest_scheduled(
    608762  Scheduler_Context *context,
     
    625779}
    626780
     781/**
     782 * @brief Tries to schedule the given node.
     783 *
     784 * Schedules the node, or blocks if that is necessary.
     785 *
     786 * @param context The scheduler context instance.
     787 * @param[in, out] node The node to insert into the scheduled nodes.
     788 * @param priority The priority of @a node.
     789 * @param[in, out] lowest_scheduled The lowest member of the scheduled nodes.
     790 * @param insert_scheduled Function to insert a node into the set of
     791 *   scheduled nodes.
     792 * @param move_from_scheduled_to_ready Function to move a node from the set
     793 *   of scheduled nodes to the set of ready nodes.
     794 * @param allocate_processor Function to allocate a processor to a node
     795 *   based on the rules of the scheduler.
     796 */
    627797static inline void _Scheduler_SMP_Enqueue_to_scheduled(
    628798  Scheduler_Context                *context,
     
    686856 * The node must not be in the scheduled state.
    687857 *
    688  * @param[in] context The scheduler instance context.
    689  * @param[in] node The node to enqueue.
    690  * @param[in] priority The node insert priority.
    691  * @param[in] order The order function.
    692  * @param[in] insert_ready Function to insert a node into the set of ready
     858 * @param context The scheduler instance context.
     859 * @param[in, out] node The node to enqueue.
     860 * @param priority The node insert priority.
     861 * @param order The order function.
     862 * @param insert_ready Function to insert a node into the set of ready
    693863 *   nodes.
    694  * @param[in] insert_scheduled Function to insert a node into the set of
     864 * @param insert_scheduled Function to insert a node into the set of
    695865 *   scheduled nodes.
    696  * @param[in] move_from_scheduled_to_ready Function to move a node from the set
     866 * @param move_from_scheduled_to_ready Function to move a node from the set
    697867 *   of scheduled nodes to the set of ready nodes.
    698  * @param[in] get_lowest_scheduled Function to select the node from the
     868 * @param get_lowest_scheduled Function to select the node from the
    699869 *   scheduled nodes to replace.  It may not be possible to find one, in this
    700870 *   case a pointer must be returned so that the order functions returns false
    701871 *   if this pointer is passed as the second argument to the order function.
    702  * @param[in] allocate_processor Function to allocate a processor to a node
     872 * @param allocate_processor Function to allocate a processor to a node
    703873 *   based on the rules of the scheduler.
    704874 */
     
    743913 * function.
    744914 *
    745  * @param[in] context The scheduler instance context.
    746  * @param[in] node The node to enqueue.
    747  * @param[in] order The order function.
    748  * @param[in] extract_from_ready Function to extract a node from the set of
     915 * @param context The scheduler instance context.
     916 * @param[in, out] node The node to enqueue.
     917 * @param order The order function.
     918 * @param extract_from_ready Function to extract a node from the set of
    749919 *   ready nodes.
    750  * @param[in] get_highest_ready Function to get the highest ready node.
    751  * @param[in] insert_ready Function to insert a node into the set of ready
     920 * @param get_highest_ready Function to get the highest ready node.
     921 * @param insert_ready Function to insert a node into the set of ready
    752922 *   nodes.
    753  * @param[in] insert_scheduled Function to insert a node into the set of
     923 * @param insert_scheduled Function to insert a node into the set of
    754924 *   scheduled nodes.
    755  * @param[in] move_from_ready_to_scheduled Function to move a node from the set
     925 * @param move_from_ready_to_scheduled Function to move a node from the set
    756926 *   of ready nodes to the set of scheduled nodes.
    757  * @param[in] allocate_processor Function to allocate a processor to a node
     927 * @param allocate_processor Function to allocate a processor to a node
    758928 *   based on the rules of the scheduler.
    759929 */
     
    8691039}
    8701040
     1041/**
     1042 * @brief Extracts a scheduled node from the scheduled nodes.
     1043 *
     1044 * @param context This parameter is unused.
     1045 * @param node The node to extract from the chain it belongs to.
     1046 */
    8711047static inline void _Scheduler_SMP_Extract_from_scheduled(
    8721048  Scheduler_Context *context,
     
    8781054}
    8791055
     1056/**
     1057 * @brief Schedules the highest ready node.
     1058 *
     1059 * @param context The scheduler context instance.
     1060 * @param victim The node of the thread that is repressed by the newly scheduled thread.
     1061 * @param victim_cpu The cpu to allocate.
     1062 * @param extract_from_ready Function to extract a node from the set of
     1063 *      ready nodes.
     1064 * @param get_highest_ready Function to get the highest ready node.
     1065 * @param move_from_ready_to_scheduled Function to move a node from the set
     1066 *      of ready nodes to the set of scheduled nodes.
     1067 * @param allocate_processor Function to allocate a processor to a node
     1068 *      based on the rules of the scheduler.
     1069 */
    8801070static inline void _Scheduler_SMP_Schedule_highest_ready(
    8811071  Scheduler_Context                *context,
     
    9231113}
    9241114
     1115/**
     1116 * @brief Schedules the highest ready node and preempts a currently executing one.
     1117 *
     1118 * @param context The scheduler context instance.
     1119 * @param victim The node of the thread that is repressed by the newly scheduled thread.
     1120 * @param victim_cpu The cpu to allocate.
     1121 * @param extract_from_ready Function to extract a node from the set of
     1122 *      ready nodes.
     1123 * @param get_highest_ready Function to get the highest ready node.
     1124 * @param move_from_ready_to_scheduled Function to move a node from the set
     1125 *      of ready nodes to the set of scheduled nodes.
     1126 * @param allocate_processor Function to allocate a processor to a node
     1127 *      based on the rules of the scheduler.
     1128 */
    9251129static inline void _Scheduler_SMP_Preempt_and_schedule_highest_ready(
    9261130  Scheduler_Context                *context,
     
    9681172
    9691173/**
    970  * @brief Blocks a thread.
    971  *
    972  * @param[in] context The scheduler instance context.
    973  * @param[in] thread The thread of the scheduling operation.
    974  * @param[in] node The scheduler node of the thread to block.
    975  * @param[in] extract_from_scheduled Function to extract a node from the set of
    976  *   scheduled nodes.
    977  * @param[in] extract_from_ready Function to extract a node from the set of
    978  *   ready nodes.
    979  * @param[in] get_highest_ready Function to get the highest ready node.
    980  * @param[in] move_from_ready_to_scheduled Function to move a node from the set
    981  *   of ready nodes to the set of scheduled nodes.
     1174 * @brief Blocks the thread.
     1175 *
     1176 * @param context The scheduler instance context.
     1177 * @param[in, out] thread The thread of the scheduling operation.
     1178 * @param[in, out] node The scheduler node of the thread to block.
     1179 * @param extract_from_scheduled Function to extract a node from the set of
     1180 *      scheduled nodes.
     1181 * @param extract_from_ready Function to extract a node from the set of
     1182 *      ready nodes.
     1183 * @param get_highest_ready Function to get the highest ready node.
     1184 * @param move_from_ready_to_scheduled Function to move a node from the set
     1185 *      of ready nodes to the set of scheduled nodes.
     1186 * @param allocate_processor Function to allocate a processor to a node
     1187 *      based on the rules of the scheduler.
    9821188 */
    9831189static inline void _Scheduler_SMP_Block(
     
    10251231}
    10261232
     1233/**
     1234 * @brief Unblocks the thread.
     1235 *
     1236 * @param context The scheduler instance context.
     1237 * @param[in, out] thread The thread of the scheduling operation.
     1238 * @param[in, out] node The scheduler node of the thread to block.
     1239 * @param update Function to update the node's priority to the new value.
     1240 * @param enqueue Function to insert a node with a priority in the ready queue
     1241 *      of a context.
     1242 */
    10271243static inline void _Scheduler_SMP_Unblock(
    10281244  Scheduler_Context     *context,
     
    10751291}
    10761292
     1293/**
     1294 * @brief Updates the priority of the node and the position in the queues it
     1295 * is in.
     1296 *
     1297 * This function firstly updates the priority of the node and then extracts
     1298 * and reinserts it into the queue the node is part of using the given
     1299 * functions.
     1300 *
     1301 * @param context The scheduler instance context.
     1302 * @param thread The thread for the operation.
     1303 * @param[in, out] node The node to update the priority of.
     1304 * @param extract_from_ready Function to extract a node from the ready
     1305 *      queue of the scheduler context.
     1306 * @param update Function to update the priority of a node in the scheduler
     1307 *      context.
     1308 * @param enqueue Function to enqueue a node with a given priority.
     1309 * @param enqueue_scheduled Function to enqueue a scheduled node.
     1310 * @param ask_for_help Function to perform a help request.
     1311 */
    10771312static inline void _Scheduler_SMP_Update_priority(
    10781313  Scheduler_Context          *context,
     
    11201355}
    11211356
     1357/**
     1358 * @brief Performs a yield and asks for help if necessary.
     1359 *
     1360 * @param context The scheduler instance context.
     1361 * @param thread The thread for the operation.
     1362 * @param node The node of the thread that yields.
     1363 * @param extract_from_ready Function to extract a node from the ready
     1364 *      queue of the scheduler context.
     1365 * @param enqueue Function to enqueue a node with a given priority.
     1366 * @param enqueue_scheduled Function to enqueue a scheduled node.
     1367 */
    11221368static inline void _Scheduler_SMP_Yield(
    11231369  Scheduler_Context     *context,
     
    11541400}
    11551401
     1402/**
     1403 * @brief Inserts the node with the given priority into the scheduled nodes.
     1404 *
     1405 * @param context The scheduler instance context.
     1406 * @param node_to_insert The scheduled node to insert.
     1407 * @param priority_to_insert The priority with which to insert the node.
     1408 */
    11561409static inline void _Scheduler_SMP_Insert_scheduled(
    11571410  Scheduler_Context *context,
     
    11721425}
    11731426
     1427/**
     1428 * @brief Asks for help.
     1429 *
     1430 * @param context The scheduler instance context.
     1431 * @param thread The thread that asks for help.
     1432 * @param[in, out] node The node of the thread that performs the ask for help
     1433 *      operation.
     1434 * @param order The order function.
     1435 * @param insert_ready Function to insert a node into the set of ready
     1436 *      nodes.
     1437 * @param insert_scheduled Function to insert a node into the set of
     1438 *      scheduled nodes.
     1439 * @param move_from_scheduled_to_ready Function to move a node from the set
     1440 *      of scheduled nodes to the set of ready nodes.
     1441 * @param get_lowest_scheduled Function to select the node from the
     1442 *      scheduled nodes to replace.
     1443 * @param allocate_processor Function to allocate a processor to a node
     1444 *      based on the rules of the scheduler.
     1445 *
     1446 * @retval true The ask for help operation was successful.
     1447 * @retval false The ask for help operation was not successful.
     1448 */
    11741449static inline bool _Scheduler_SMP_Ask_for_help(
    11751450  Scheduler_Context                  *context,
     
    12661541}
    12671542
     1543/**
     1544 * @brief Reconsiders help request.
     1545 *
     1546 * @param context The scheduler context instance.
     1547 * @param thread The thread to reconsider the help request of.
     1548 * @param[in, out] node The scheduler node of @a thread.
     1549 * @param extract_from_ready Function to extract a node from the ready queue
     1550 *      of the scheduler context.
     1551 */
    12681552static inline void _Scheduler_SMP_Reconsider_help_request(
    12691553  Scheduler_Context     *context,
     
    12891573}
    12901574
     1575/**
     1576 * @brief Withdraws the node.
     1577 *
     1578 * @param context The scheduler context instance.
     1579 * @param[in, out] thread The thread to change to @a next_state.
     1580 * @param[in, out] node The node to withdraw.
     1581 * @param next_state The new state for @a thread.
     1582 * @param extract_from_ready Function to extract a node from the ready queue
     1583 *      of the scheduler context.
     1584 * @param get_highest_ready Function to get the highest ready node.
     1585 * @param move_from_ready_to_scheduled Function to move a node from the set
     1586 *      of ready nodes to the set of scheduled nodes.
     1587 * @param allocate_processor Function to allocate a processor to a node
     1588 *      based on the rules of the scheduler.
     1589 */
    12911590static inline void _Scheduler_SMP_Withdraw_node(
    12921591  Scheduler_Context                *context,
     
    13341633}
    13351634
     1635/**
     1636 * @brief Starts the idle thread on the given processor.
     1637 *
     1638 * @param context The scheduler context instance.
     1639 * @param[in, out] idle The idle thread to schedule.
     1640 * @param cpu The processor for the idle thread.
     1641 * @param register_idle Function to register the idle thread for a cpu.
     1642 */
    13361643static inline void _Scheduler_SMP_Do_start_idle(
    13371644  Scheduler_Context           *context,
     
    13561663}
    13571664
     1665/**
     1666 * @brief Adds the idle thread to the processor.
     1667 *
     1668 * @param context The scheduler context instance.
     1669 * @param[in, out] idle The idle thread to add to the processor.
     1670 * @param has_ready Function that checks if a given context has ready threads.
     1671 * @param enqueue_scheduled Function to enqueue a scheduled node.
     1672 * @param register_idle Function to register the idle thread for a cpu.
     1673 */
    13581674static inline void _Scheduler_SMP_Add_processor(
    13591675  Scheduler_Context           *context,
     
    13851701}
    13861702
     1703/**
     1704 * @brief Removes an idle thread from the processor.
     1705 *
     1706 * @param context The scheduler context instance.
     1707 * @param cpu The processor to remove from.
     1708 * @param extract_from_ready Function to extract a node from the ready queue
     1709 *      of the scheduler context.
     1710 * @param enqueue Function to enqueue a node with a given priority.
     1711 *
     1712 * @return The idle thread of @a cpu.
     1713 */
    13871714static inline Thread_Control *_Scheduler_SMP_Remove_processor(
    13881715  Scheduler_Context     *context,
     
    14471774}
    14481775
     1776/**
     1777 * @brief Sets the affinity of the node.
     1778 *
     1779 * Also performs a reinsert into the queue the node is currently in.
     1780 *
     1781 * @param context The scheduler context instance.
     1782 * @param thread The thread for the operation.
     1783 * @param[in, out] node The node to set the affinity of.
     1784 * @param arg The affinity for @a node.
     1785 * @param set_affinity Function to set the affinity of a node.
     1786 * @param extract_from_ready Function to extract a node from the ready queue
     1787 *      of the scheduler context.
     1788 * @param get_highest_ready Function to get the highest ready node.
     1789 * @param move_from_ready_to_scheduled Function to move a node from the set
     1790 *      of ready nodes to the set of scheduled nodes.
     1791 * @param enqueue Function to enqueue a node with a given priority.
     1792 * @param allocate_processor Function to allocate a processor to a node
     1793 *      based on the rules of the scheduler.
     1794 */
    14491795static inline void _Scheduler_SMP_Set_affinity(
    14501796  Scheduler_Context               *context,
Note: See TracChangeset for help on using the changeset viewer.