RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

api: Remove deprecated Notepads

Browse Source 
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.
This commit is contained in:
Aun-Ali Zaidi
2015-12-23 14:44:02 -06:00
committed by Joel Sherrill
parent a48b7c442d
commit d5154d0f6a
128 changed files with 119 additions and 2595 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
doc/user/conf.t
View File

@@ -594,75 +594,6 @@ the assumption that all tasks have floating point enabled. This would
require the addition of a new configuration parameter to specify the
number of tasks which enable floating point support.
@c
@c === CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS ===
@c
@subsection Enable Classic API Notepads
@findex CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS
@table @b
@item CONSTANT:
@code{CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS}
@item DATA TYPE:
Boolean feature macro.
@item RANGE:
Defined or undefined.
@item DEFAULT VALUE:
This is not defined by default, and Classic API Notepads are not supported.
@end table
@subheading DESCRIPTION:
@code{CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS} should be defined if the
user wants to have support for Classic API Notepads in their application.
@subheading NOTES:
Disabling Classic API Notepads saves the allocation of sixteen (16)
thirty-two bit integers. This saves sixty-four bytes per task/thread
plus the allocation overhead. Notepads are rarely used in applications
and this can save significant memory in a low RAM system. Classic API
Notepads are deprecated, and this option is expected to be obsolete in
the near future.
@c
@c === CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS ===
@c
@subsection Disable Classic API Notepads
@findex CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS
@table @b
@item CONSTANT:
@code{CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS}
@item DATA TYPE:
Boolean feature macro.
@item RANGE:
Defined or undefined.
@item DEFAULT VALUE:
This is not defined by default, and Classic API Notepads are not supported.
@end table
@subheading DESCRIPTION:
@code{CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS} is deprecated. If users
want to have support for Classic API Notepads, they should use
@code{CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS}.
@subheading NOTES:
Disabling Classic API Notepads saves the allocation of sixteen (16)
thirty-two bit integers. This saves sixty-four bytes per task/thread
plus the allocation overhead. Notepads are rarely used in applications
and this can save significant memory in a low RAM system. Classic API
Notepads are deprecated, and this option is expected to be obsolete in
the near future.
@c
@c === CONFIGURE_MAXIMUM_TIMERS ===
@c

2
doc/user/intr.t
View File

@@ -189,8 +189,6 @@ to the interrupted task. Most of the time, it is an application
implementation error to use RTEMS_SELF from an ISR.
@itemize
@item rtems_task_get_note
@item rtems_task_set_note
@item rtems_task_suspend
@item rtems_task_resume
@end itemize

141
doc/user/task.t
View File

@@ -25,8 +25,6 @@ by the task manager are:
@item @code{@value{DIRPREFIX}task_is_suspended} - Determine if a task is suspended
@item @code{@value{DIRPREFIX}task_set_priority} - Set task priority
@item @code{@value{DIRPREFIX}task_mode} - Change current task's mode
@item @code{@value{DIRPREFIX}task_get_note} - Get task notepad entry
@item @code{@value{DIRPREFIX}task_set_note} - Set task notepad entry
@item @code{@value{DIRPREFIX}task_wake_after} - Wake up after interval
@item @code{@value{DIRPREFIX}task_wake_when} - Wake up when specified
@item @code{@value{DIRPREFIX}iterate_over_all_threads} - Iterate Over Tasks
@@ -81,9 +79,9 @@ by the application in response to external and internal stimuli.
TCBs are the only RTEMS internal data structure that can be
accessed by an application via user extension routines. The TCB
contains a task's name, ID, current priority, current and
starting states, execution mode, set of notepad locations, TCB
user extension pointer, scheduling control structures, as well
as data required by a blocked task.
starting states, execution mode, TCB user extension pointer,
scheduling control structures, as well as data required by a
blocked task.
A task's context is stored in the TCB when a task switch occurs.
When the task regains control of the processor, its context is
@@ -636,22 +634,6 @@ The @code{@value{DIRPREFIX}task_restart}
directive resets the mode of a task to its
original value.
@subsection Notepad Locations
RTEMS provides sixteen notepad locations for each task. Each
notepad location may contain a note consisting of four bytes of
information. RTEMS provides two directives,
@code{@value{DIRPREFIX}task_set_note} and
@code{@value{DIRPREFIX}task_get_note}, that enable a user
to access and change the
notepad locations. The @code{@value{DIRPREFIX}task_set_note}
directive enables the user
to set a task's notepad entry to a specified note. The
@code{@value{DIRPREFIX}task_get_note}
directive allows the user to obtain the note
contained in any one of the sixteen notepads of a specified task.
Notepads are deprecated and will be removed.
@subsection Task Deletion
RTEMS provides the @code{@value{DIRPREFIX}task_delete}
@@ -1482,123 +1464,6 @@ mask constant is provided in the following table:
@page
@subsection TASK_GET_NOTE - Get task notepad entry
@cindex get task notepad entry
@subheading CALLING SEQUENCE:
@ifset is-C
@findex rtems_task_get_note
@example
rtems_status_code rtems_task_get_note(
rtems_id id,
uint32_t notepad,
uint32_t *note
);
@end example
@end ifset
@ifset is-Ada
@example
procedure Task_Get_Note (
ID : in RTEMS.ID;
Notepad : in RTEMS.Notepad_Index;
Note : out RTEMS.Unsigned32;
Result : out RTEMS.Status_Codes
);
@end example
@end ifset
@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - note obtained successfully@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{note} is NULL@*
@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
@code{@value{RPREFIX}INVALID_NUMBER} - invalid notepad location
@subheading DESCRIPTION:
This directive returns the note contained in the notepad
location of the task specified by id.
@subheading NOTES:
This directive is deprecated and will be removed.
This directive will not cause the running task to be preempted.
If id is set to @code{@value{RPREFIX}SELF},
the calling task accesses its own notepad.
@c This version of the paragraph avoids the overfull hbox error.
@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the
@c sixteen notepad locations.
The sixteen notepad locations can be accessed using the constants
@code{@value{RPREFIX}NOTEPAD_0} through @code{@value{RPREFIX}NOTEPAD_15}.
Getting a note of a global task which does not reside on the
local node will generate a request to the remote node to obtain
the notepad entry of the specified task.
@page
@subsection TASK_SET_NOTE - Set task notepad entry
@cindex set task notepad entry
@subheading CALLING SEQUENCE:
@ifset is-C
@findex rtems_task_set_note
@example
rtems_status_code rtems_task_set_note(
rtems_id id,
uint32_t notepad,
uint32_t note
);
@end example
@end ifset
@ifset is-Ada
@example
procedure Task_Set_Note (
ID : in RTEMS.ID;
Notepad : in RTEMS.Notepad_Index;
Note : in RTEMS.Unsigned32;
Result : out RTEMS.Status_Codes
);
@end example
@end ifset
@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - task's note set successfully@*
@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
@code{@value{RPREFIX}INVALID_NUMBER} - invalid notepad location
@subheading DESCRIPTION:
This directive is deprecated and will be removed.
This directive sets the notepad entry for the task specified by
id to the value note.
@subheading NOTES:
If id is set to @code{@value{RPREFIX}SELF}, the calling
task accesses its own notepad locations.
This directive will not cause the running task to be preempted.
@c This version of the paragraph avoids the overfull hbox error.
@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the
@c sixteen notepad locations.
The sixteen notepad locations can be accessed using the constants
@code{@value{RPREFIX}NOTEPAD_0} through @code{@value{RPREFIX}NOTEPAD_15}.
Setting a notepad location of a global task which does not
reside on the local node will generate a request to the remote
node to set the specified notepad entry.
@page
@subsection TASK_WAKE_AFTER - Wake up after interval
@cindex delay a task for an interval

6
doc/user/userext.t
View File

@@ -134,11 +134,7 @@ RTEMS provides for a pointer to a user-defined data
area for each extension set to be linked to each task's control
block. This set of pointers is an extension of the TCB and can
be used to store additional data required by the user's
extension functions. It is also possible for a user extension
to utilize the notepad locations associated with each task
although this may conflict with application usage of those
particular notepads. However, notepads are deprecated and will
be removed.
extension functions.
The TCB extension is an array of pointers in the TCB. The
index into the table can be obtained from the extension id