From 3ac681191ec76f7c0a876f2f2cc33adad9a99cc0 Mon Sep 17 00:00:00 2001 From: Gedare Bloom Date: Fri, 6 Mar 2015 12:41:49 -0500 Subject: cpukit: deprecate notepads Deprecate Classic API Notepads. Mark task_set/get_note() with the deprecated attribute, and also mark the notepads field. Replace disable with enable option for notepads in confdefs.h, and make notepads disabled by default. The previous option CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS is now unused and will emit a compile-time warning. A new option CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS is available to turn on notepads, but it also will emit a compile-time warning to indicate that notepads are deprecated. Closes #2265 --- c/src/librtems++/include/rtems++/rtemsTask.h | 4 +-- cpukit/libmisc/monitor/monitor.h | 3 +- cpukit/rtems/include/rtems/rtems/tasks.h | 12 ++++++-- cpukit/sapi/include/confdefs.h | 10 ++++-- doc/user/conf.t | 46 +++++++++++++++++++++++++--- doc/user/task.t | 5 +++ doc/user/userext.t | 3 +- testsuites/libtests/rtems++/System.h | 1 + testsuites/mptests/mp02/system.h | 2 ++ testsuites/sptests/sp07/system.h | 2 ++ testsuites/sptests/spnotepad01/init.c | 1 - testsuites/sptests/sptask_err04/system.h | 2 ++ testsuites/tmtests/tm08/system.h | 2 ++ 13 files changed, 77 insertions(+), 16 deletions(-) diff --git a/c/src/librtems++/include/rtems++/rtemsTask.h b/c/src/librtems++/include/rtems++/rtemsTask.h index 6d19b460f4..6a500b0db0 100644 --- a/c/src/librtems++/include/rtems++/rtemsTask.h +++ b/c/src/librtems++/include/rtems++/rtemsTask.h @@ -127,9 +127,9 @@ public: // notepad control const rtems_status_code get_note(const uint32_t notepad, - uint32_t& note); + uint32_t& note) RTEMS_COMPILER_DEPRECATED_ATTRIBUTE; const rtems_status_code set_note(const uint32_t notepad, - const uint32_t note); + const uint32_t note) RTEMS_COMPILER_DEPRECATED_ATTRIBUTE; // object id, and name const rtems_id id_is() const { return id; } diff --git a/cpukit/libmisc/monitor/monitor.h b/cpukit/libmisc/monitor/monitor.h index 6a85d602eb..799df353a7 100644 --- a/cpukit/libmisc/monitor/monitor.h +++ b/cpukit/libmisc/monitor/monitor.h @@ -104,7 +104,8 @@ typedef struct { rtems_event_set events; rtems_mode modes; rtems_attribute attributes; - uint32_t notepad[RTEMS_NUMBER_NOTEPADS]; + uint32_t notepad[RTEMS_NUMBER_NOTEPADS] + RTEMS_COMPILER_DEPRECATED_ATTRIBUTE; rtems_id wait_id; uint32_t wait_args; uint32_t ticks; diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h index e0fa27e16f..237ec19093 100644 --- a/cpukit/rtems/include/rtems/rtems/tasks.h +++ b/cpukit/rtems/include/rtems/rtems/tasks.h @@ -271,6 +271,8 @@ rtems_status_code rtems_task_delete( /** * @brief RTEMS Get Task Node * + * @deprecated Notepads are deprecated and will be removed. + * * This routine implements the rtems_task_get_note directive. The * value of the indicated notepad for the task associated with ID * is returned in note. @@ -285,11 +287,13 @@ rtems_status_code rtems_task_get_note( rtems_id id, uint32_t notepad, uint32_t *note -); +) RTEMS_COMPILER_DEPRECATED_ATTRIBUTE; /** * @brief RTEMS Set Task Note * + * @deprecated Notepads are deprecated and will be removed. + * * This routine implements the rtems_task_set_note directive. The * value of the indicated notepad for the task associated with ID * is returned in note. @@ -306,7 +310,7 @@ rtems_status_code rtems_task_set_note( rtems_id id, uint32_t notepad, uint32_t note -); +) RTEMS_COMPILER_DEPRECATED_ATTRIBUTE; /** * @brief RTEMS Task Mode @@ -663,10 +667,12 @@ typedef struct { /** * This field contains the notepads for this task. + * + * @deprecated Notepads are deprecated and will be removed. * * @note MUST BE LAST ENTRY. */ - uint32_t Notepads[ RTEMS_ZERO_LENGTH_ARRAY ]; + uint32_t Notepads[ RTEMS_ZERO_LENGTH_ARRAY ] RTEMS_COMPILER_DEPRECATED_ATTRIBUTE; } RTEMS_API_Control; /** diff --git a/cpukit/sapi/include/confdefs.h b/cpukit/sapi/include/confdefs.h index 7d9e3b9e08..0bebb4ed0d 100644 --- a/cpukit/sapi/include/confdefs.h +++ b/cpukit/sapi/include/confdefs.h @@ -1810,7 +1810,11 @@ const rtems_libio_helper rtems_fs_init_helper = #define CONFIGURE_TASKS \ (CONFIGURE_MAXIMUM_TASKS + CONFIGURE_LIBBLOCK_TASKS) - #ifndef CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS + #if defined(CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS) + #warning "CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS is deprecated and will be removed." + #endif + #if defined(CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS) + #warning "CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS is deprecated and will be removed." #define CONFIGURE_NOTEPADS_ENABLED TRUE #else #define CONFIGURE_NOTEPADS_ENABLED FALSE @@ -2613,8 +2617,8 @@ const rtems_libio_helper rtems_fs_init_helper = #endif } Scheduler; RTEMS_API_Control API_RTEMS; - #ifndef CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS - uint32_t Notepads[ RTEMS_NUMBER_NOTEPADS ]; + #if defined(CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS) + uint32_t Notepads[ RTEMS_NUMBER_NOTEPADS ] RTEMS_COMPILER_DEPRECATED_ATTRIBUTE; #endif #ifdef RTEMS_POSIX_API POSIX_API_Control API_POSIX; diff --git a/doc/user/conf.t b/doc/user/conf.t index dc10816909..fe714b42d4 100644 --- a/doc/user/conf.t +++ b/doc/user/conf.t @@ -594,6 +594,40 @@ 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 @@ -612,20 +646,22 @@ Boolean feature macro. Defined or undefined. @item DEFAULT VALUE: -This is not defined by default, and Classic API Notepads are supported. +This is not defined by default, and Classic API Notepads are not supported. @end table @subheading DESCRIPTION: -@code{CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS} should be defined if the -user does not want to have support for Classic API Notepads in their -application. +@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. +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 === diff --git a/doc/user/task.t b/doc/user/task.t index cf7a514b1a..5aec9b19cc 100644 --- a/doc/user/task.t +++ b/doc/user/task.t @@ -645,6 +645,7 @@ 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 @@ -1515,6 +1516,8 @@ 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}, @@ -1567,6 +1570,8 @@ procedure Task_Set_Note ( @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. diff --git a/doc/user/userext.t b/doc/user/userext.t index 97628bdb20..dc6ad4e5ee 100644 --- a/doc/user/userext.t +++ b/doc/user/userext.t @@ -137,7 +137,8 @@ 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. +particular notepads. However, notepads are deprecated and will +be removed. The TCB extension is an array of pointers in the TCB. The index into the table can be obtained from the extension id diff --git a/testsuites/libtests/rtems++/System.h b/testsuites/libtests/rtems++/System.h index e787fe21be..410fccbad8 100644 --- a/testsuites/libtests/rtems++/System.h +++ b/testsuites/libtests/rtems++/System.h @@ -123,6 +123,7 @@ class Io_during_interrupt #define CONFIGURE_MAXIMUM_USER_EXTENSIONS 0 #define CONFIGURE_TICKS_PER_TIMESLICE 100 +#define CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS #define CONFIGURE_INITIAL_EXTENSIONS RTEMS_TEST_INITIAL_EXTENSION #define CONFIGURE_RTEMS_INIT_TASKS_TABLE diff --git a/testsuites/mptests/mp02/system.h b/testsuites/mptests/mp02/system.h index 2ccc1e4a40..69025d4107 100644 --- a/testsuites/mptests/mp02/system.h +++ b/testsuites/mptests/mp02/system.h @@ -30,6 +30,8 @@ rtems_task Test_task( #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER +#define CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS + #define CONFIGURE_MAXIMUM_TASKS 2 #define CONFIGURE_RTEMS_INIT_TASKS_TABLE diff --git a/testsuites/sptests/sp07/system.h b/testsuites/sptests/sp07/system.h index 8bea0fb7f5..c5374553d5 100644 --- a/testsuites/sptests/sp07/system.h +++ b/testsuites/sptests/sp07/system.h @@ -64,6 +64,8 @@ void Task_exit_extension( #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER +#define CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS + #define CONFIGURE_MAXIMUM_USER_EXTENSIONS 2 #define CONFIGURE_TICKS_PER_TIMESLICE 100 diff --git a/testsuites/sptests/spnotepad01/init.c b/testsuites/sptests/spnotepad01/init.c index 97a02f5b8d..9604c32535 100644 --- a/testsuites/sptests/spnotepad01/init.c +++ b/testsuites/sptests/spnotepad01/init.c @@ -53,7 +53,6 @@ rtems_task Init( #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER #define CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER -#define CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS #define CONFIGURE_MAXIMUM_TASKS 1 #define CONFIGURE_INITIAL_EXTENSIONS RTEMS_TEST_INITIAL_EXTENSION diff --git a/testsuites/sptests/sptask_err04/system.h b/testsuites/sptests/sptask_err04/system.h index ef3e78181e..8fd4a14cfa 100644 --- a/testsuites/sptests/sptask_err04/system.h +++ b/testsuites/sptests/sptask_err04/system.h @@ -29,6 +29,8 @@ rtems_task Task_1( #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER +#define CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS + #define CONFIGURE_MAXIMUM_TASKS 2 #define CONFIGURE_RTEMS_INIT_TASKS_TABLE diff --git a/testsuites/tmtests/tm08/system.h b/testsuites/tmtests/tm08/system.h index 3610fe954d..6e2df2f846 100644 --- a/testsuites/tmtests/tm08/system.h +++ b/testsuites/tmtests/tm08/system.h @@ -27,6 +27,8 @@ rtems_task Init( #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER #define CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER +#define CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS + #define CONFIGURE_MAXIMUM_TASKS 3 #define CONFIGURE_TICKS_PER_TIMESLICE 0 -- cgit v1.2.3