[rtems-docs commit] c_user: Re-add task notepads for 4.11. Remove this patch after branching.

Joel Sherrill joel at rtems.org
Tue Nov 1 21:06:01 UTC 2016


Module:    rtems-docs
Branch:    master
Commit:    c29f5bcbcfa9ddec26af60a8d1b65af3076d9366
Changeset: http://git.rtems.org/rtems-docs/commit/?id=c29f5bcbcfa9ddec26af60a8d1b65af3076d9366

Author:    Joel Sherrill <joel at rtems.org>
Date:      Tue Nov  1 16:05:08 2016 -0500

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



More information about the vc mailing list