summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJoel Sherrill <joel@rtems.org>2016-11-01 16:05:08 -0500
committerJoel Sherrill <joel@rtems.org>2016-11-01 16:05:54 -0500
commitc29f5bcbcfa9ddec26af60a8d1b65af3076d9366 (patch)
treea200597ae23054ba61182823b53b9ea789cbefdf
parent4ace089bde87fa3a10fcd43d1291187406fcd23f (diff)
downloadrtems-docs-c29f5bcbcfa9ddec26af60a8d1b65af3076d9366.tar.bz2
c_user: Re-add task notepads for 4.11. Remove this patch after branching.
-rw-r--r--c_user/configuring_a_system.rst32
-rw-r--r--c_user/task_manager.rst114
2 files changed, 146 insertions, 0 deletions
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