Changeset a238912 in rtems-docs


Ignore:
Timestamp:
Feb 1, 2017, 12:07:25 PM (3 years ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
a6a1f72
Parents:
3966353
Message:

c-user: Move some task directives

Location:
c-user
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • c-user/symmetric_multiprocessing_services.rst

    r3966353 ra238912  
    4848
    4949- rtems_scheduler_remove_processor_ - Remove processor from a scheduler
    50 
    51 - rtems_task_get_scheduler_ - Get scheduler of a task
    52 
    53 - rtems_task_set_scheduler_ - Set scheduler of a task
    54 
    55 - rtems_task_get_affinity_ - Get task processor affinity
    56 
    57 - rtems_task_set_affinity_ - Set task processor affinity
    5850
    5951Background
     
    584576prologue before the stack is switched to the interrupt stack.
    585577
    586 Operations
    587 ==========
    588 
    589 Setting Affinity to a Single Processor
    590 --------------------------------------
    591 
    592 On some embedded applications targeting SMP systems, it may be beneficial to
    593 lock individual tasks to specific processors.  In this way, one can designate a
    594 processor for I/O tasks, another for computation, etc..  The following
    595 illustrates the code sequence necessary to assign a task an affinity for
    596 processor with index ``processor_index``.
    597 
    598 .. code-block:: c
    599 
    600     #include <rtems.h>
    601     #include <assert.h>
    602 
    603     void pin_to_processor(rtems_id task_id, int processor_index)
    604     {
    605         rtems_status_code sc;
    606         cpu_set_t         cpuset;
    607         CPU_ZERO(&cpuset);
    608         CPU_SET(processor_index, &cpuset);
    609         sc = rtems_task_set_affinity(task_id, sizeof(cpuset), &cpuset);
    610         assert(sc == RTEMS_SUCCESSFUL);
    611     }
    612 
    613 It is important to note that the ``cpuset`` is not validated until the
    614 ``rtems_task_set_affinity`` call is made. At that point, it is validated
    615 against the current system configuration.
    616 
    617578Directives
    618579==========
     
    841802    objects allocator lock.  Removing a processor from a scheduler is a complex
    842803    operation that involves all tasks of the system.
    843 
    844 .. raw:: latex
    845 
    846    \clearpage
    847 
    848 .. _rtems_task_get_scheduler:
    849 
    850 TASK_GET_SCHEDULER - Get scheduler of a task
    851 --------------------------------------------
    852 
    853 CALLING SEQUENCE:
    854     .. code-block:: c
    855 
    856         rtems_status_code rtems_task_get_scheduler(
    857             rtems_id  task_id,
    858             rtems_id *scheduler_id
    859         );
    860 
    861 DIRECTIVE STATUS CODES:
    862     .. list-table::
    863      :class: rtems-table
    864 
    865      * - ``RTEMS_SUCCESSFUL``
    866        - successful operation
    867      * - ``RTEMS_INVALID_ADDRESS``
    868        - ``scheduler_id`` is NULL
    869      * - ``RTEMS_INVALID_ID``
    870        - invalid task id
    871 
    872 DESCRIPTION:
    873     Returns the scheduler identifier of a task identified by ``task_id`` in
    874     ``scheduler_id``.
    875 
    876 NOTES:
    877     None.
    878 
    879 .. raw:: latex
    880 
    881    \clearpage
    882 
    883 .. _rtems_task_set_scheduler:
    884 .. _TASK_SET_SCHEDULER - Set scheduler of a task:
    885 
    886 TASK_SET_SCHEDULER - Set scheduler of a task
    887 --------------------------------------------
    888 
    889 CALLING SEQUENCE:
    890     .. code-block:: c
    891 
    892         rtems_status_code rtems_task_set_scheduler(
    893             rtems_id task_id,
    894             rtems_id scheduler_id
    895         );
    896 
    897 DIRECTIVE STATUS CODES:
    898     .. list-table::
    899      :class: rtems-table
    900 
    901      * - ``RTEMS_SUCCESSFUL``
    902        - successful operation
    903      * - ``RTEMS_INVALID_ID``
    904        - invalid task or scheduler id
    905      * - ``RTEMS_INCORRECT_STATE``
    906        - the task is in the wrong state to perform a scheduler change
    907 
    908 DESCRIPTION:
    909     Sets the scheduler of a task identified by ``task_id`` to the scheduler
    910     identified by ``scheduler_id``.  The scheduler of a task is initialized to
    911     the scheduler of the task that created it.
    912 
    913 NOTES:
    914     None.
    915 
    916 EXAMPLE:
    917     .. code-block:: c
    918         :linenos:
    919 
    920         #include <rtems.h>
    921         #include <assert.h>
    922 
    923         void task(rtems_task_argument arg);
    924 
    925         void example(void)
    926         {
    927             rtems_status_code sc;
    928             rtems_id          task_id;
    929             rtems_id          scheduler_id;
    930             rtems_name        scheduler_name;
    931 
    932             scheduler_name = rtems_build_name('W', 'O', 'R', 'K');
    933 
    934             sc = rtems_scheduler_ident(scheduler_name, &scheduler_id);
    935             assert(sc == RTEMS_SUCCESSFUL);
    936 
    937             sc = rtems_task_create(
    938                     rtems_build_name('T', 'A', 'S', 'K'),
    939                     1,
    940                     RTEMS_MINIMUM_STACK_SIZE,
    941                     RTEMS_DEFAULT_MODES,
    942                     RTEMS_DEFAULT_ATTRIBUTES,
    943                     &task_id
    944                  );
    945             assert(sc == RTEMS_SUCCESSFUL);
    946 
    947             sc = rtems_task_set_scheduler(task_id, scheduler_id);
    948             assert(sc == RTEMS_SUCCESSFUL);
    949 
    950             sc = rtems_task_start(task_id, task, 0);
    951             assert(sc == RTEMS_SUCCESSFUL);
    952         }
    953 
    954 .. raw:: latex
    955 
    956    \clearpage
    957 
    958 .. _rtems_task_get_affinity:
    959 
    960 TASK_GET_AFFINITY - Get task processor affinity
    961 -----------------------------------------------
    962 
    963 CALLING SEQUENCE:
    964     .. code-block:: c
    965 
    966         rtems_status_code rtems_task_get_affinity(
    967             rtems_id   id,
    968             size_t     cpusetsize,
    969             cpu_set_t *cpuset
    970         );
    971 
    972 DIRECTIVE STATUS CODES:
    973     .. list-table::
    974      :class: rtems-table
    975 
    976      * - ``RTEMS_SUCCESSFUL``
    977        - successful operation
    978      * - ``RTEMS_INVALID_ADDRESS``
    979        - ``cpuset`` is NULL
    980      * - ``RTEMS_INVALID_ID``
    981        - invalid task id
    982      * - ``RTEMS_INVALID_NUMBER``
    983        - the affinity set buffer is too small for the current processor affinity
    984          set of the task
    985 
    986 DESCRIPTION:
    987     Returns the current processor affinity set of the task in ``cpuset``.  A
    988     set bit in the affinity set means that the task can execute on this
    989     processor and a cleared bit means the opposite.
    990 
    991 NOTES:
    992     None.
    993 
    994 .. raw:: latex
    995 
    996    \clearpage
    997 
    998 .. _rtems_task_set_affinity:
    999 
    1000 TASK_SET_AFFINITY - Set task processor affinity
    1001 -----------------------------------------------
    1002 
    1003 CALLING SEQUENCE:
    1004     .. code-block:: c
    1005 
    1006         rtems_status_code rtems_task_set_affinity(
    1007             rtems_id         id,
    1008             size_t           cpusetsize,
    1009             const cpu_set_t *cpuset
    1010         );
    1011 
    1012 DIRECTIVE STATUS CODES:
    1013     .. list-table::
    1014      :class: rtems-table
    1015 
    1016      * - ``RTEMS_SUCCESSFUL``
    1017        - successful operation
    1018      * - ``RTEMS_INVALID_ADDRESS``
    1019        - ``cpuset`` is NULL
    1020      * - ``RTEMS_INVALID_ID``
    1021        - invalid task id
    1022      * - ``RTEMS_INVALID_NUMBER``
    1023        - invalid processor affinity set
    1024 
    1025 DESCRIPTION:
    1026     Sets the processor affinity set for the task specified by ``cpuset``.  A
    1027     set bit in the affinity set means that the task can execute on this
    1028     processor and a cleared bit means the opposite.
    1029 
    1030 NOTES:
    1031     This function will not change the scheduler of the task.  The intersection
    1032     of the processor affinity set and the set of processors owned by the
    1033     scheduler of the task must be non-empty.  It is not an error if the
    1034     processor affinity set contains processors that are not part of the set of
    1035     processors owned by the scheduler instance of the task.  A task will simply
    1036     not run under normal circumstances on these processors since the scheduler
    1037     ignores them.  Some locking protocols may temporarily use processors that
    1038     are not included in the processor affinity set of the task.  It is also not
    1039     an error if the processor affinity set contains processors that are not
    1040     part of the system.
  • c-user/task_manager.rst

    r3966353 ra238912  
    4343
    4444- rtems_task_wake_when_ - Wake up when specified
     45
     46- rtems_task_get_scheduler_ - Get scheduler of a task
     47
     48- rtems_task_set_scheduler_ - Set scheduler of a task
     49
     50- rtems_task_get_affinity_ - Get task processor affinity
     51
     52- rtems_task_set_affinity_ - Set task processor affinity
    4553
    4654- rtems_task_iterate_ - Iterate Over Tasks
     
    512520itself.
    513521
     522Setting Affinity to a Single Processor
     523--------------------------------------
     524
     525On some embedded applications targeting SMP systems, it may be beneficial to
     526lock individual tasks to specific processors.  In this way, one can designate a
     527processor for I/O tasks, another for computation, etc..  The following
     528illustrates the code sequence necessary to assign a task an affinity for
     529processor with index ``processor_index``.
     530
     531.. code-block:: c
     532
     533    #include <rtems.h>
     534    #include <assert.h>
     535
     536    void pin_to_processor(rtems_id task_id, int processor_index)
     537    {
     538        rtems_status_code sc;
     539        cpu_set_t         cpuset;
     540        CPU_ZERO(&cpuset);
     541        CPU_SET(processor_index, &cpuset);
     542        sc = rtems_task_set_affinity(task_id, sizeof(cpuset), &cpuset);
     543        assert(sc == RTEMS_SUCCESSFUL);
     544    }
     545
     546It is important to note that the ``cpuset`` is not validated until the
     547``rtems_task_set_affinity`` call is made. At that point, it is validated
     548against the current system configuration.
     549
    514550Transition Advice for Obsolete Notepads
    515551---------------------------------------
     
    13551391   \clearpage
    13561392
     1393.. _rtems_task_get_scheduler:
     1394
     1395TASK_GET_SCHEDULER - Get scheduler of a task
     1396--------------------------------------------
     1397
     1398CALLING SEQUENCE:
     1399    .. code-block:: c
     1400
     1401        rtems_status_code rtems_task_get_scheduler(
     1402            rtems_id  task_id,
     1403            rtems_id *scheduler_id
     1404        );
     1405
     1406DIRECTIVE STATUS CODES:
     1407    .. list-table::
     1408     :class: rtems-table
     1409
     1410     * - ``RTEMS_SUCCESSFUL``
     1411       - successful operation
     1412     * - ``RTEMS_INVALID_ADDRESS``
     1413       - ``scheduler_id`` is NULL
     1414     * - ``RTEMS_INVALID_ID``
     1415       - invalid task id
     1416
     1417DESCRIPTION:
     1418    Returns the scheduler identifier of a task identified by ``task_id`` in
     1419    ``scheduler_id``.
     1420
     1421NOTES:
     1422    None.
     1423
     1424.. raw:: latex
     1425
     1426   \clearpage
     1427
     1428.. _rtems_task_set_scheduler:
     1429.. _TASK_SET_SCHEDULER - Set scheduler of a task:
     1430
     1431TASK_SET_SCHEDULER - Set scheduler of a task
     1432--------------------------------------------
     1433
     1434CALLING SEQUENCE:
     1435    .. code-block:: c
     1436
     1437        rtems_status_code rtems_task_set_scheduler(
     1438            rtems_id task_id,
     1439            rtems_id scheduler_id
     1440        );
     1441
     1442DIRECTIVE STATUS CODES:
     1443    .. list-table::
     1444     :class: rtems-table
     1445
     1446     * - ``RTEMS_SUCCESSFUL``
     1447       - successful operation
     1448     * - ``RTEMS_INVALID_ID``
     1449       - invalid task or scheduler id
     1450     * - ``RTEMS_INCORRECT_STATE``
     1451       - the task is in the wrong state to perform a scheduler change
     1452
     1453DESCRIPTION:
     1454    Sets the scheduler of a task identified by ``task_id`` to the scheduler
     1455    identified by ``scheduler_id``.  The scheduler of a task is initialized to
     1456    the scheduler of the task that created it.
     1457
     1458NOTES:
     1459    None.
     1460
     1461EXAMPLE:
     1462    .. code-block:: c
     1463        :linenos:
     1464
     1465        #include <rtems.h>
     1466        #include <assert.h>
     1467
     1468        void task(rtems_task_argument arg);
     1469
     1470        void example(void)
     1471        {
     1472            rtems_status_code sc;
     1473            rtems_id          task_id;
     1474            rtems_id          scheduler_id;
     1475            rtems_name        scheduler_name;
     1476
     1477            scheduler_name = rtems_build_name('W', 'O', 'R', 'K');
     1478
     1479            sc = rtems_scheduler_ident(scheduler_name, &scheduler_id);
     1480            assert(sc == RTEMS_SUCCESSFUL);
     1481
     1482            sc = rtems_task_create(
     1483                    rtems_build_name('T', 'A', 'S', 'K'),
     1484                    1,
     1485                    RTEMS_MINIMUM_STACK_SIZE,
     1486                    RTEMS_DEFAULT_MODES,
     1487                    RTEMS_DEFAULT_ATTRIBUTES,
     1488                    &task_id
     1489                 );
     1490            assert(sc == RTEMS_SUCCESSFUL);
     1491
     1492            sc = rtems_task_set_scheduler(task_id, scheduler_id);
     1493            assert(sc == RTEMS_SUCCESSFUL);
     1494
     1495            sc = rtems_task_start(task_id, task, 0);
     1496            assert(sc == RTEMS_SUCCESSFUL);
     1497        }
     1498
     1499.. raw:: latex
     1500
     1501   \clearpage
     1502
     1503.. _rtems_task_get_affinity:
     1504
     1505TASK_GET_AFFINITY - Get task processor affinity
     1506-----------------------------------------------
     1507
     1508CALLING SEQUENCE:
     1509    .. code-block:: c
     1510
     1511        rtems_status_code rtems_task_get_affinity(
     1512            rtems_id   id,
     1513            size_t     cpusetsize,
     1514            cpu_set_t *cpuset
     1515        );
     1516
     1517DIRECTIVE STATUS CODES:
     1518    .. list-table::
     1519     :class: rtems-table
     1520
     1521     * - ``RTEMS_SUCCESSFUL``
     1522       - successful operation
     1523     * - ``RTEMS_INVALID_ADDRESS``
     1524       - ``cpuset`` is NULL
     1525     * - ``RTEMS_INVALID_ID``
     1526       - invalid task id
     1527     * - ``RTEMS_INVALID_NUMBER``
     1528       - the affinity set buffer is too small for the current processor affinity
     1529         set of the task
     1530
     1531DESCRIPTION:
     1532    Returns the current processor affinity set of the task in ``cpuset``.  A
     1533    set bit in the affinity set means that the task can execute on this
     1534    processor and a cleared bit means the opposite.
     1535
     1536NOTES:
     1537    None.
     1538
     1539.. raw:: latex
     1540
     1541   \clearpage
     1542
     1543.. _rtems_task_set_affinity:
     1544
     1545TASK_SET_AFFINITY - Set task processor affinity
     1546-----------------------------------------------
     1547
     1548CALLING SEQUENCE:
     1549    .. code-block:: c
     1550
     1551        rtems_status_code rtems_task_set_affinity(
     1552            rtems_id         id,
     1553            size_t           cpusetsize,
     1554            const cpu_set_t *cpuset
     1555        );
     1556
     1557DIRECTIVE STATUS CODES:
     1558    .. list-table::
     1559     :class: rtems-table
     1560
     1561     * - ``RTEMS_SUCCESSFUL``
     1562       - successful operation
     1563     * - ``RTEMS_INVALID_ADDRESS``
     1564       - ``cpuset`` is NULL
     1565     * - ``RTEMS_INVALID_ID``
     1566       - invalid task id
     1567     * - ``RTEMS_INVALID_NUMBER``
     1568       - invalid processor affinity set
     1569
     1570DESCRIPTION:
     1571    Sets the processor affinity set for the task specified by ``cpuset``.  A
     1572    set bit in the affinity set means that the task can execute on this
     1573    processor and a cleared bit means the opposite.
     1574
     1575NOTES:
     1576    This function will not change the scheduler of the task.  The intersection
     1577    of the processor affinity set and the set of processors owned by the
     1578    scheduler of the task must be non-empty.  It is not an error if the
     1579    processor affinity set contains processors that are not part of the set of
     1580    processors owned by the scheduler instance of the task.  A task will simply
     1581    not run under normal circumstances on these processors since the scheduler
     1582    ignores them.  Some locking protocols may temporarily use processors that
     1583    are not included in the processor affinity set of the task.  It is also not
     1584    an error if the processor affinity set contains processors that are not
     1585    part of the system.
     1586
     1587.. raw:: latex
     1588
     1589   \clearpage
     1590
    13571591.. _rtems_task_iterate:
    13581592
Note: See TracChangeset for help on using the changeset viewer.