doc: Various corrections to Kernel Primer

* Ensures all references to kernel functions are correctly
  tagged so they will auto-link to the API guide.

* Adds references to a few functions and macros that were
  omitted.

Change-Id: I26ccd9c29ea123db2807f2df4d05d574932c6849
Signed-off-by: Allan Stephens <allan.stephens@windriver.com>

doc/kernel_v2/data_passing/mailboxes.rst

@@ -484,12 +484,12 @@ The receiving thread must then respond as follows:
   the mailbox has already completed data retrieval and deleted the message.
 
 * If the message descriptor size is non-zero and the receiving thread still
-  wants to retrieve the data, the thread must call :c:func:`k_mbox_data_get()`
+  wants to retrieve the data, the thread must call :cpp:func:`k_mbox_data_get()`
   and supply a message buffer large enough to hold the data. The mailbox copies
   the data into the message buffer and deletes the message.
 
 * If the message descriptor size is non-zero and the receiving thread does *not*
-  want to retrieve the data, the thread must call :c:func:`k_mbox_data_get()`.
+  want to retrieve the data, the thread must call :cpp:func:`k_mbox_data_get()`.
   and specify a message buffer of :c:macro:`NULL`. The mailbox deletes
   the message without copying the data.
 
@@ -548,7 +548,7 @@ A receiving thread may choose to retrieve message data into a memory block,
 rather than a message buffer. This is done in much the same way as retrieving
 data subsequently into a message buffer --- the receiving thread first
 receives the message without its data, then retrieves the data by calling
-:c:func:`k_mbox_data_block_get()`. The mailbox fills in the block descriptor
+:cpp:func:`k_mbox_data_block_get()`. The mailbox fills in the block descriptor
 supplied by the receiving thread, allowing the thread to access the data.
 The mailbox also deletes the received message, since data retrieval
 has been completed. The receiving thread is then responsible for freeing

doc/kernel_v2/data_passing/pipes.rst

@@ -54,7 +54,7 @@ Implementation
 
 A pipe is defined using a variable of type :c:type:`struct k_pipe` and an
 optional character buffer of type :c:type:`unsigned char`. It must then be
-initialized by calling :c:func:`k_pipe_init()`.
+initialized by calling :cpp:func:`k_pipe_init()`.
 
 The following code defines and initializes an empty pipe that has a ring
 buffer capable of holding 100 bytes and is aligned to a 4-byte boundary.
@@ -80,7 +80,7 @@ that that macro defines both the pipe and its ring buffer.
 Writing to a Pipe
 =================
 
-Data is added to a pipe by calling :c:func:`k_pipe_put()`.
+Data is added to a pipe by calling :cpp:func:`k_pipe_put()`.
 
 The following code builds on the example above, and uses the pipe to pass
 data from a producing thread to one or more consuming threads. If the pipe's
@@ -126,7 +126,7 @@ waits for a specified amount of time.
 Reading from a Pipe
 ===================
 
-Data is read from the pipe by calling :c:func:`k_pipe_get()`.
+Data is read from the pipe by calling :cpp:func:`k_pipe_get()`.
 
 The following code builds on the example above, and uses the pipe to
 process data items generated by one or more producing threads.
@@ -172,14 +172,14 @@ Configuration Options
 
 Related configuration options:
 
-* CONFIG_NUM_PIPE_ASYNC_MSGS
+* :option:`CONFIG_NUM_PIPE_ASYNC_MSGS`
 
 APIs
 ****
 
 The following message queue APIs are provided by :file:`kernel.h`:
 
-* :c:func:`k_pipe_init()`
+* :cpp:func:`k_pipe_init()`
-* :c:func:`k_pipe_put()`
+* :cpp:func:`k_pipe_put()`
-* :c:func:`k_pipe_get()`
+* :cpp:func:`k_pipe_get()`
-* :c:func:`k_pipe_block_put()`
+* :cpp:func:`k_pipe_block_put()`

doc/kernel_v2/memory/pools.rst

@@ -214,4 +214,4 @@ The following memory pool APIs are provided by :file:`kernel.h`:
 
 * :cpp:func:`k_mem_pool_alloc()`
 * :cpp:func:`k_mem_pool_free()`
-* :cpp:func:`k_mem_pool_defragment()`
+* :cpp:func:`k_mem_pool_defrag()`

doc/kernel_v2/other/atomic.rst

@@ -65,6 +65,10 @@ by a higher priority context that also calls the routine.
 Manipulating an Array of Atomic Variables
 =========================================
 
+An array of 32-bit atomic variables can be defined in the conventional manner.
+However, you can also define an N-bit array of atomic variables using
+:c:macro:`ATOMIC_DEFINE()`.
+
 A single bit in array of atomic variables can be manipulated using
 the APIs listed at the end of this section that end with :cpp:func:`_bit`.
 
@@ -111,6 +115,8 @@ APIs
 
 The following atomic operation APIs are provided by :file:`atomic.h`:
 
+* :c:macro:`ATOMIC_INIT()`
+* :c:macro:`ATOMIC_DEFINE()`
 * :cpp:func:`atomic_get()`
 * :cpp:func:`atomic_set()`
 * :cpp:func:`atomic_clear()`

doc/kernel_v2/other/event_logger.rst

@@ -47,7 +47,7 @@ Adding a Kernel Event Logging Point
 
 Custom trace points can be added with the following API:
 
-* :c:func:`sys_k_event_logger_put()`
+* :cpp:func:`sys_k_event_logger_put()`
 
   Adds the profile of a new event with custom data.
 
@@ -69,9 +69,9 @@ event logger.
 
 The API functions provided are:
 
-* :c:func:`sys_k_event_logger_get()`
+* :cpp:func:`sys_k_event_logger_get()`
-* :c:func:`sys_k_event_logger_get_wait()`
+* :cpp:func:`sys_k_event_logger_get_wait()`
-* :c:func:`sys_k_event_logger_get_wait_timeout()`
+* :cpp:func:`sys_k_event_logger_get_wait_timeout()`
 
 The above functions specify various ways to retrieve a event message and to
 copy it to the provided buffer. When the buffer size is smaller than the
@@ -249,19 +249,19 @@ The following APIs are provided by the :file:`k_event_logger.h` file:
 :cpp:func:`sys_k_event_logger_register_as_collector()`
    Register the current cooperative thread as the collector thread.
 
-:c:func:`sys_k_event_logger_put()`
+:cpp:func:`sys_k_event_logger_put()`
    Enqueue a kernel event logger message with custom data.
 
 :cpp:func:`sys_k_event_logger_put_timed()`
    Enqueue a kernel event logger message with the current time.
 
-:c:func:`sys_k_event_logger_get()`
+:cpp:func:`sys_k_event_logger_get()`
    De-queue a kernel event logger message.
 
-:c:func:`sys_k_event_logger_get_wait()`
+:cpp:func:`sys_k_event_logger_get_wait()`
    De-queue a kernel event logger message. Wait if the buffer is empty.
 
-:c:func:`sys_k_event_logger_get_wait_timeout()`
+:cpp:func:`sys_k_event_logger_get_wait_timeout()`
    De-queue a kernel event logger message. Wait if the buffer is empty until
    the timeout expires.
 

doc/kernel_v2/other/float.rst

@@ -106,19 +106,19 @@ pre-tag a thread using one of the techniques listed below.
 
 * A dynamically-spawned x86 thread can be pre-tagged by passing the
   :c:macro:`K_FP_REGS` or :c:macro:`K_SSE_REGS` option to
-  :c:func:`k_thread_spawn()`.
+  :cpp:func:`k_thread_spawn()`.
 
 * An already-spawned x86 thread can pre-tag itself once it has started
   by passing the :c:macro:`K_FP_REGS` or :c:macro:`K_SSE_REGS` option to
-  :c:func:`k_float_enable()`.
+  :cpp:func:`k_float_enable()`.
 
 If an x86 thread uses the floating point registers infrequently it can call
-:c:func:`k_float_disable()` to remove its tagging as an FPU user or SSE user.
+:cpp:func:`k_float_disable()` to remove its tagging as an FPU user or SSE user.
 This eliminates the need for the kernel to take steps to preserve
 the contents of the floating point registers during context switches
 when there is no need to do so.
 When the thread again needs to use the floating point registers it can re-tag
-itself as an FPU user or SSE user by calling :c:func:`k_float_enable()`.
+itself as an FPU user or SSE user by calling :cpp:func:`k_float_enable()`.
 
 Implementation
 **************

doc/kernel_v2/other/interrupts.rst

@@ -195,3 +195,4 @@ The following interrupt-related APIs are provided by :file:`irq.h`:
 The following interrupt-related APIs are provided by :file:`kernel.h`:
 
 * :cpp:func:`k_is_in_isr()`
+* :cpp:func:`k_is_preempt_thread`

doc/kernel_v2/other/ring_buffers.rst

@@ -175,8 +175,8 @@ APIs
 
 The following ring buffer APIs are provided by :file:`misc/ring_buffer.h`:
 
-* :c:func:`SYS_RING_BUF_DECLARE_POW2()`
+* :cpp:func:`SYS_RING_BUF_DECLARE_POW2()`
-* :c:func:`SYS_RING_BUF_DECLARE_SIZE()`
+* :cpp:func:`SYS_RING_BUF_DECLARE_SIZE()`
 * :cpp:func:`sys_ring_buf_init()`
 * :cpp:func:`sys_ring_buf_is_empty()`
 * :cpp:func:`sys_ring_buf_space_get()`

doc/kernel_v2/synchronization/alerts.rst

@@ -234,5 +234,6 @@ APIs
 
 The following alert APIs are provided by :file:`kernel.h`:
 
+* :cpp:func:`k_alert_init()`
 * :cpp:func:`k_alert_send()`
 * :cpp:func:`k_alert_recv()`

doc/kernel_v2/threads/lifecycle.rst

@@ -78,7 +78,7 @@ automatically aborts a thread if the thread triggers a fatal error condition,
 such as dereferencing a null pointer.
 
 A thread can also be aborted by another thread (or by itself)
-by calling :c:func:`k_thread_abort()`. However, it is typically preferable
+by calling :cpp:func:`k_thread_abort()`. However, it is typically preferable
 to signal a thread to terminate itself gracefully, rather than aborting it.
 
 As with thread termination, the kernel does not reclaim shared resources
@@ -92,16 +92,16 @@ Thread Suspension
 =================
 
 A thread can be prevented from executing for an indefinite period of time
-if it becomes **suspended**. The function :c:func:`k_thread_suspend()`
+if it becomes **suspended**. The function :cpp:func:`k_thread_suspend()`
 can be used to suspend any thread, including the calling thread.
 Suspending a thread that is already suspended has no additional effect.
 
 Once suspended, a thread cannot be scheduled until another thread calls
-:c:func:`k_thread_resume()` to remove the suspension.
+:cpp:func:`k_thread_resume()` to remove the suspension.
 
 .. note::
    A thread can prevent itself from executing for a specified period of time
-   using :c:func:`k_sleep()`. However, this is different from suspending
+   using :cpp:func:`k_sleep()`. However, this is different from suspending
    a thread since a sleeping thread becomes executable automatically when the
    time limit is reached.
 
@@ -146,7 +146,7 @@ Spawning a Thread
 
 A thread is spawned by defining its stack area and then calling
 :cpp:func:`k_thread_spawn()`. The stack area is an array of bytes
-whose size must equal :c:func:`sizeof(struct k_thread)` plus the size
+whose size must equal :c:macro:`K_THREAD_SIZEOF` plus the size
 of the thread's stack. The stack area must be defined using the
 :c:macro:`__stack` attribute to ensure it is properly aligned.
 
@@ -226,7 +226,7 @@ Related configuration options:
 APIs
 ****
 
-The following thread APIs are are provided by :file:`kernel.h`:
+The following thread APIs are provided by :file:`kernel.h`:
 
 * :cpp:func:`k_thread_spawn()`
 * :cpp:func:`k_thread_cancel()`

doc/kernel_v2/threads/scheduling.rst

@@ -135,7 +135,7 @@ are measured in system clock ticks. The time slice size is configurable,
 but this size can be changed while the application is running.
 
 At the end of every time slice, the scheduler checks to see if the current
-thread is preemptible and, if so, implicitly invokes :c:func:`k_yield()`
+thread is preemptible and, if so, implicitly invokes :cpp:func:`k_yield()`
 on behalf of the thread. This gives other ready threads of the same priority
 the opportunity to execute before the current thread is scheduled again.
 If no threads of equal priority are ready, the current thread remains
@@ -234,6 +234,8 @@ APIs
 The following thread scheduling-related APIs are provided by :file:`kernel.h`:
 
 * :cpp:func:`k_current_get()`
+* :cpp:func:`k_sched_lock()`
+* :cpp:func:`k_sched_unlock()`
 * :cpp:func:`k_yield()`
 * :cpp:func:`k_sleep()`
 * :cpp:func:`k_wakeup()`

doc/kernel_v2/threads/workqueues.rst

@@ -150,7 +150,7 @@ 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 is an array
-of bytes whose size must equal :c:func:`sizeof(struct k_thread)` plus the size
+of bytes whose size must equal :c:macro:`K_THREAD_SIZEOF` plus the size
 of the thread's stack. The stack area must be defined using the
 :c:macro:`__stack` attribute to ensure it is properly aligned.
 
@@ -158,7 +158,7 @@ The following code defines and initializes a workqueue.
 
 .. code-block:: c
 
-    #define MY_STACK_SIZE 500
+    #define MY_STACK_SIZE (K_THREAD_SIZEOF + 500)
     #define MY_PRIORITY 5
 
     char __noinit __stack my_stack_area[MY_STACK_SIZE];