From c29f5bcbcfa9ddec26af60a8d1b65af3076d9366 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 1 Nov 2016 16:05:08 -0500 Subject: [PATCH] c_user: Re-add task notepads for 4.11. Remove this patch after branching. --- c_user/configuring_a_system.rst | 32 +++++++++ c_user/task_manager.rst | 114 ++++++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+) diff --git a/c_user/configuring_a_system.rst b/c_user/configuring_a_system.rst index 9c36b2d..e993877 100644 --- a/c_user/configuring_a_system.rst +++ b/c_user/configuring_a_system.rst @@ -565,6 +565,38 @@ 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. +.. COMMENT: === CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS === + +.. _Specify Maximum Classic API Timers: + +Specify Maximum Classic API Timers +---------------------------------- +.. index:: CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS + +*CONSTANT:* + ``CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS`` + +*DATA TYPE:* + Boolean feature macro. + +*RANGE:* + Defined or undefined. + +*DEFAULT VALUE:* + This is not defined by default, and Classic API Notepads are not supported. + +**DESCRIPTION:** + ``CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS`` should be defined if the + user wants to have support for Classic API Notepads in their application. + +**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 has been removed from + post 4.11 versions of RTEMS. + .. COMMENT: === CONFIGURE_MAXIMUM_TIMERS === .. _Specify Maximum Classic API Timers: diff --git a/c_user/task_manager.rst b/c_user/task_manager.rst index 9756e00..449ca3c 100644 --- a/c_user/task_manager.rst +++ b/c_user/task_manager.rst @@ -37,6 +37,10 @@ and administer tasks. The directives provided by the task manager are: - rtems_task_mode_ - Change current task's mode +- rtems_task_get_note_ - Get task notepad entry + +- rtems_task_set_note_ - Set task notepad entry + - rtems_task_wake_after_ - Wake up after interval - rtems_task_wake_when_ - Wake up when specified @@ -526,6 +530,18 @@ preemption, timeslicing, ASR processing, and to set the task's interrupt level. The ``rtems_task_restart`` directive resets the mode of a task to its original value. +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, ``rtems_task_set_note`` and +``rtems_task_get_note``, that enable a user to access and change +the notepad locations. The ``rtems_task_set_note`` directive +enables the user to set a task's notepad entry to a specified note. +The ``rtems_task_get_note`` directive allows the user to obtain the note +contained in any one of the sixteen notepads of a specified task. + Task Deletion ------------- @@ -1241,6 +1257,104 @@ provided in the following table: * - ``RTEMS_INTERRUPT_LEVEL(n)`` - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n +.. _rtems_task_get_note: + +TASK_GET_NOTE - Get task notepad entry +-------------------------------------- +.. index:: get task notepad entry + +**CALLING SEQUENCE:** + +.. index:: rtems_task_get_note + +.. code-block:: c + + rtems_status_code rtems_task_get_note( + rtems_id id, + uint32_t notepad, + uint32_t *note + ); + +**DIRECTIVE STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - note value obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``note`` parameter is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_NUMBER`` + - invalid notepad location + +**DESCRIPTION:** + +This directive returns the note contained in the notepad location of +the task specified by id. + +**NOTES:** + +This directive will not cause the running task to be preempted. + +If id is set to ``RTEMS_SELF``, the calling task accesses its own notepad. + +The sixteen notepad locations can be accessed using the constants +``RTEMS_NOTEPAD_0`` through ``RTEMS_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. + +.. _rtems_task_set_note: + +TASK_SET_NOTE - Set task notepad entry +-------------------------------------- +.. index:: set task notepad entry + +**CALLING SEQUENCE:** + +.. index:: rtems_task_set_note + +.. code-block:: c + + rtems_status_code rtems_task_set_note( + rtems_id id, + uint32_t notepad, + uint32_t note + ); + +**DIRECTIVE STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - note set successfully + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_NUMBER`` + - invalid notepad location + +**DESCRIPTION:** + +This directive sets the notepad entry for the task specified by +id to the value note. + +**NOTES:** + +If ``id`` is set to ``RTEMS_SELF``, the calling task accesses its own notepad. + +This directive will not cause the running task to be preempted. + +The sixteen notepad locations can be accessed using the constants +``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``. + +Setting a note of a global task which does not reside on the +local node will generate a request to the remote node to set +the notepad entry of the specified task. + .. _rtems_task_wake_after: TASK_WAKE_AFTER - Wake up after interval