From ea310faa3a705bf118036ac7d1d7081a057edf89 Mon Sep 17 00:00:00 2001 From: Andrew Boie Date: Tue, 13 Jun 2017 08:51:46 -0700 Subject: [PATCH] doc: update for new stack macros __stack is now deprecated. Signed-off-by: Andrew Boie --- doc/kernel/threads/lifecycle.rst | 16 ++++++++++++---- doc/kernel/threads/workqueues.rst | 8 +++++--- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/doc/kernel/threads/lifecycle.rst b/doc/kernel/threads/lifecycle.rst index f52ff7a8437..ecd6db7f5f5 100644 --- a/doc/kernel/threads/lifecycle.rst +++ b/doc/kernel/threads/lifecycle.rst @@ -20,7 +20,8 @@ A thread has the following key properties: * A **stack area**, which is a region of memory used for the thread's stack. The **size** of the stack area can be tailored to conform to the actual needs - of the thread's processing. + of the thread's processing. Special macros exist to create and work with + stack memory regions. * A **thread control block** for private kernel bookkeeping of the thread's metadata. This is an instance of type :c:type:`struct k_thread`. @@ -149,7 +150,8 @@ Spawning a Thread A thread is spawned by defining its stack area and its thread control block, and then calling :cpp:func:`k_thread_create()`. The stack area must be defined -using the :c:macro:`__stack` attribute to ensure it is properly aligned. +using :c:macro:`K_THREAD_STACK_DEFINE` to ensure it is properly set up in +memory. The thread spawning function returns its thread id, which can be used to reference the thread. @@ -163,11 +165,12 @@ The following code spawns a thread that starts immediately. extern void my_entry_point(void *, void *, void *); - char __noinit __stack my_stack_area[MY_STACK_SIZE]; + K_THREAD_STACK_DEFINE(my_stack_area, MY_STACK_SIZE); struct k_thread my_thread_data; k_tid_t my_tid = k_thread_create(&my_thread_data, my_stack_area, - MY_STACK_SIZE, my_entry_point, + K_THREAD_STACK_SIZEOF(my_stack_area), + my_entry_point, NULL, NULL, NULL, MY_PRIORITY, 0, K_NO_WAIT); @@ -237,3 +240,8 @@ The following thread APIs are provided by :file:`kernel.h`: * :cpp:func:`k_thread_abort()` * :cpp:func:`k_thread_suspend()` * :cpp:func:`k_thread_resume()` +* :c:macro:`K_THREAD_STACK_DEFINE` +* :c:macro:`K_THREAD_STACK_ARRAY_DEFINE` +* :c:macro:`K_THREAD_STACK_MEMBER` +* :c:macro:`K_THREAD_STACK_SIZEOF` +* :c:macro:`K_THREAD_STACK_BUFFER` diff --git a/doc/kernel/threads/workqueues.rst b/doc/kernel/threads/workqueues.rst index 50786173b21..4f5f25aa1bb 100644 --- a/doc/kernel/threads/workqueues.rst +++ b/doc/kernel/threads/workqueues.rst @@ -150,7 +150,8 @@ Defining a Workqueue A workqueue is defined using a variable of type :c:type:`struct k_work_q`. The workqueue is initialized by defining the stack area used by its thread and then calling :cpp:func:`k_work_q_start()`. The stack area must be defined -using the :c:macro:`__stack` attribute to ensure it is properly aligned. +using :c:macro:`K_THREAD_STACK_DEFINE` to ensure it is properly set up in +memory. The following code defines and initializes a workqueue. @@ -159,11 +160,12 @@ The following code defines and initializes a workqueue. #define MY_STACK_SIZE 512 #define MY_PRIORITY 5 - char __noinit __stack my_stack_area[MY_STACK_SIZE]; + K_THREAD_STACK_DEFINE(my_stack_area, MY_STACK_SIZE); struct k_work_q my_work_q; - k_work_q_start(&my_work_q, my_stack_area, MY_STACK_SIZE, MY_PRIORITY); + k_work_q_start(&my_work_q, my_stack_area, + K_THREAD_STACK_SIZEOF(my_stack_area), MY_PRIORITY); Submitting a Work Item ======================