Changeset d5154d0f in rtems for doc


Ignore:
Timestamp:
Dec 23, 2015, 8:44:02 PM (4 years ago)
Author:
Aun-Ali Zaidi <admin@…>
Branches:
master
Children:
2268ee6
Parents:
a48b7c44
git-author:
Aun-Ali Zaidi <admin@…> (12/23/15 20:44:02)
git-committer:
Joel Sherrill <joel.sherrill@…> (12/24/15 22:52:34)
Message:

api: Remove deprecated Notepads

Notepads where a feature of RTEMS' tasks that simply functioned in
the same way as POSIX keys or threaded local storage (TLS). They were
introduced well before per task variables, which are also deprecated,
and were barely used in favor of their POSIX alternatives.

In addition to their scarce usage, Notepads took up unnecessary memory.
For each task:

  • 16 32-bit integers were allocated.
  • A total of 64 bytes per task per thread.

This is especially critical in low memory and safety-critical applications.

They are also defined as uint32_t, and therefore are not guaranteed to
hold a pointer.

Lastly, they are not portable solutions for SMP and uniprocessor systems,
like POSIX keys and TLS.

updates #2493.

Location:
doc/user
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • doc/user/conf.t

    ra48b7c44 rd5154d0f  
    594594require the addition of a new configuration parameter to specify the
    595595number of tasks which enable floating point support.
    596 
    597 @c
    598 @c === CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS ===
    599 @c
    600 @subsection Enable Classic API Notepads
    601 
    602 @findex CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS
    603 
    604 @table @b
    605 @item CONSTANT:
    606 @code{CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS}
    607 
    608 @item DATA TYPE:
    609 Boolean feature macro.
    610 
    611 @item RANGE:
    612 Defined or undefined.
    613 
    614 @item DEFAULT VALUE:
    615 This is not defined by default, and Classic API Notepads are not supported.
    616 
    617 @end table
    618 
    619 @subheading DESCRIPTION:
    620 @code{CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS} should be defined if the
    621 user wants to have support for Classic API Notepads in their application.
    622 
    623 @subheading NOTES:
    624 Disabling Classic API Notepads saves the allocation of sixteen (16)
    625 thirty-two bit integers. This saves sixty-four bytes per task/thread
    626 plus the allocation overhead. Notepads are rarely used in applications
    627 and this can save significant memory in a low RAM system. Classic API
    628 Notepads are deprecated, and this option is expected to be obsolete in
    629 the near future.
    630 
    631 @c
    632 @c === CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS ===
    633 @c
    634 @subsection Disable Classic API Notepads
    635 
    636 @findex CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS
    637 
    638 @table @b
    639 @item CONSTANT:
    640 @code{CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS}
    641 
    642 @item DATA TYPE:
    643 Boolean feature macro.
    644 
    645 @item RANGE:
    646 Defined or undefined.
    647 
    648 @item DEFAULT VALUE:
    649 This is not defined by default, and Classic API Notepads are not supported.
    650 
    651 @end table
    652 
    653 @subheading DESCRIPTION:
    654 @code{CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS} is deprecated. If users
    655 want to have support for Classic API Notepads, they should use
    656 @code{CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS}.
    657 
    658 @subheading NOTES:
    659 Disabling Classic API Notepads saves the allocation of sixteen (16)
    660 thirty-two bit integers. This saves sixty-four bytes per task/thread
    661 plus the allocation overhead. Notepads are rarely used in applications
    662 and this can save significant memory in a low RAM system. Classic API
    663 Notepads are deprecated, and this option is expected to be obsolete in
    664 the near future.
    665596
    666597@c
  • doc/user/intr.t

    ra48b7c44 rd5154d0f  
    190190
    191191@itemize
    192 @item rtems_task_get_note
    193 @item rtems_task_set_note
    194192@item rtems_task_suspend
    195193@item rtems_task_resume
  • doc/user/task.t

    ra48b7c44 rd5154d0f  
    2626@item @code{@value{DIRPREFIX}task_set_priority} - Set task priority
    2727@item @code{@value{DIRPREFIX}task_mode} - Change current task's mode
    28 @item @code{@value{DIRPREFIX}task_get_note} - Get task notepad entry
    29 @item @code{@value{DIRPREFIX}task_set_note} - Set task notepad entry
    3028@item @code{@value{DIRPREFIX}task_wake_after} - Wake up after interval
    3129@item @code{@value{DIRPREFIX}task_wake_when} - Wake up when specified 
     
    8280accessed by an application via user extension routines.  The TCB
    8381contains a task's name, ID, current priority, current and
    84 starting states, execution mode, set of notepad locations, TCB
    85 user extension pointer, scheduling control structures, as well
    86 as data required by a blocked task.
     82starting states, execution mode, TCB user extension pointer,
     83scheduling control structures, as well as data required by a
     84blocked task.
    8785
    8886A task's context is stored in the TCB when a task switch occurs.
     
    636634directive resets the mode of a task to its
    637635original value.
    638 
    639 @subsection Notepad Locations
    640 
    641 RTEMS provides sixteen notepad locations for each task.  Each
    642 notepad location may contain a note consisting of four bytes of
    643 information.  RTEMS provides two directives,
    644 @code{@value{DIRPREFIX}task_set_note} and
    645 @code{@value{DIRPREFIX}task_get_note}, that enable a user
    646 to access and change the
    647 notepad locations.  The @code{@value{DIRPREFIX}task_set_note}
    648 directive enables the user
    649 to set a task's notepad entry to a specified note.  The
    650 @code{@value{DIRPREFIX}task_get_note}
    651 directive allows the user to obtain the note
    652 contained in any one of the sixteen notepads of a specified task.
    653 Notepads are deprecated and will be removed.
    654636
    655637@subsection Task Deletion
     
    14831465@page
    14841466
    1485 @subsection TASK_GET_NOTE - Get task notepad entry
    1486 
    1487 @cindex get task notepad entry
    1488 
    1489 @subheading CALLING SEQUENCE:
    1490 
    1491 @ifset is-C
    1492 @findex rtems_task_get_note
    1493 @example
    1494 rtems_status_code rtems_task_get_note(
    1495   rtems_id  id,
    1496   uint32_t  notepad,
    1497   uint32_t *note
    1498 );
    1499 @end example
    1500 @end ifset
    1501 
    1502 @ifset is-Ada
    1503 @example
    1504 procedure Task_Get_Note (
    1505    ID      : in     RTEMS.ID;
    1506    Notepad : in     RTEMS.Notepad_Index;
    1507    Note    :    out RTEMS.Unsigned32;
    1508    Result  :    out RTEMS.Status_Codes
    1509 );
    1510 @end example
    1511 @end ifset
    1512 
    1513 @subheading DIRECTIVE STATUS CODES:
    1514 @code{@value{RPREFIX}SUCCESSFUL} - note obtained successfully@*
    1515 @code{@value{RPREFIX}INVALID_ADDRESS} - @code{note} is NULL@*
    1516 @code{@value{RPREFIX}INVALID_ID} - invalid task id@*
    1517 @code{@value{RPREFIX}INVALID_NUMBER} - invalid notepad location
    1518 
    1519 @subheading DESCRIPTION:
    1520 This directive returns the note contained in the notepad
    1521 location of the task specified by id.
    1522 
    1523 @subheading NOTES:
    1524 This directive is deprecated and will be removed.
    1525 
    1526 This directive will not cause the running task to be preempted.
    1527 
    1528 If id is set to @code{@value{RPREFIX}SELF},
    1529 the calling task accesses its own notepad.
    1530 
    1531 @c This version of the paragraph avoids the overfull hbox error.
    1532 @c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the
    1533 @c sixteen notepad locations.
    1534 
    1535 The sixteen notepad locations can be accessed using the constants
    1536 @code{@value{RPREFIX}NOTEPAD_0} through @code{@value{RPREFIX}NOTEPAD_15}.
    1537 
    1538 Getting a note of a global task which does not reside on the
    1539 local node will generate a request to the remote node to obtain
    1540 the notepad entry of the specified task.
    1541 
    1542 @page
    1543 
    1544 @subsection TASK_SET_NOTE - Set task notepad entry
    1545 
    1546 @cindex set task notepad entry
    1547 
    1548 @subheading CALLING SEQUENCE:
    1549 
    1550 @ifset is-C
    1551 @findex rtems_task_set_note
    1552 @example
    1553 rtems_status_code rtems_task_set_note(
    1554   rtems_id  id,
    1555   uint32_t  notepad,
    1556   uint32_t  note
    1557 );
    1558 @end example
    1559 @end ifset
    1560 
    1561 @ifset is-Ada
    1562 @example
    1563 procedure Task_Set_Note (
    1564    ID      : in     RTEMS.ID;
    1565    Notepad : in     RTEMS.Notepad_Index;
    1566    Note    : in     RTEMS.Unsigned32;
    1567    Result  :    out RTEMS.Status_Codes
    1568 );
    1569 @end example
    1570 @end ifset
    1571 
    1572 @subheading DIRECTIVE STATUS CODES:
    1573 @code{@value{RPREFIX}SUCCESSFUL} - task's note set successfully@*
    1574 @code{@value{RPREFIX}INVALID_ID} - invalid task id@*
    1575 @code{@value{RPREFIX}INVALID_NUMBER} - invalid notepad location
    1576 
    1577 @subheading DESCRIPTION:
    1578 This directive is deprecated and will be removed.
    1579 
    1580 This directive sets the notepad entry for the task specified by
    1581 id to the value note.
    1582 
    1583 @subheading NOTES:
    1584 If id is set to @code{@value{RPREFIX}SELF}, the calling
    1585 task accesses its own notepad locations.
    1586 
    1587 This directive will not cause the running task to be preempted.
    1588 
    1589 @c This version of the paragraph avoids the overfull hbox error.
    1590 @c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the
    1591 @c sixteen notepad locations.
    1592 
    1593 The sixteen notepad locations can be accessed using the constants
    1594 @code{@value{RPREFIX}NOTEPAD_0} through @code{@value{RPREFIX}NOTEPAD_15}.
    1595 
    1596 Setting a notepad location of a global task which does not
    1597 reside on the local node will generate a request to the remote
    1598 node to set the specified notepad entry.
    1599 
    1600 @page
    1601 
    16021467@subsection TASK_WAKE_AFTER - Wake up after interval
    16031468
  • doc/user/userext.t

    ra48b7c44 rd5154d0f  
    135135block.  This set of pointers is an extension of the TCB and can
    136136be used to store additional data required by the user's
    137 extension functions.  It is also possible for a user extension
    138 to utilize the notepad locations associated with each task
    139 although this may conflict with application usage of those
    140 particular notepads. However, notepads are deprecated and will
    141 be removed.
     137extension functions.
    142138
    143139The TCB extension is an array of pointers in the TCB. The
Note: See TracChangeset for help on using the changeset viewer.