michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: kernel: flatten kernel docs and add API references

Browse source 
Instead of having kernel APIs documentated in a separate page, move the
API references to the object pages and have everything in one place.

Remove the intermediate category page and list all section under the
kernel directly.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2019-01-21 20:53:59 -05:00
commit 2dc4e270b2
26 changed files with 102 additions and 472 deletions
Download patch file Download diff file Expand all files Collapse all files

183
doc/api/kernel_api.rst
View file

@ -18,169 +18,6 @@ as described in the :ref:`kernel`.
not documenting not documenting
.. doxygengroup:: kernel_apis .. doxygengroup:: kernel_apis
Clocks
******
Kernel clocks enable threads and ISRs to measure the passage of time
with either normal and high precision.
(See :ref:`clocks_v2`.)
.. doxygengroup:: clock_apis
:project: Zephyr
Timers
******
Timers enable threads to measure the passage of time, and to optionally execute
an action when the timer expires.
(See :ref:`timers_v2`.)
.. doxygengroup:: timer_apis
:project: Zephyr
Memory Slabs
************
Memory slabs enable the dynamic allocation and release of fixed-size
memory blocks.
(See :ref:`memory_slabs_v2`.)
.. doxygengroup:: mem_slab_apis
:project: Zephyr
Memory Pools
************
Memory pools enable the dynamic allocation and release of variable-size
memory blocks.
(See :ref:`memory_pools_v2`.)
.. doxygengroup:: mem_pool_apis
:project: Zephyr
Heap Memory Pool
****************
The heap memory pools enable the dynamic allocation and release of memory
in a :cpp:func:`malloc()`-like manner.
(See :ref:`heap_v2`.)
.. doxygengroup:: heap_apis
:project: Zephyr
Semaphores
**********
Semaphores provide traditional counting semaphore capabilities.
(See :ref:`semaphores_v2`.)
.. doxygengroup:: semaphore_apis
:project: Zephyr
Mutexes
*******
Mutexes provide traditional reentrant mutex capabilities
with basic priority inheritance.
(See :ref:`mutexes_v2`.)
.. doxygengroup:: mutex_apis
:project: Zephyr
FIFOs
*****
FIFOs provide traditional first in, first out (FIFO) queuing of data items
of any size.
(See :ref:`fifos_v2`.)
.. doxygengroup:: fifo_apis
:project: Zephyr
LIFOs
*****
LIFOs provide traditional last in, first out (LIFO) queuing of data items
of any size.
(See :ref:`lifos_v2`.)
.. doxygengroup:: lifo_apis
:project: Zephyr
Stacks
******
Stacks provide traditional last in, first out (LIFO) queuing of 32-bit
data items.
(See :ref:`stacks_v2`.)
.. doxygengroup:: stack_apis
:project: Zephyr
Queues
******
.. doxygengroup:: queue_apis
:project: Zephyr
Message Queues
**************
Message queues provide a simple message queuing mechanism
for fixed-size data items.
(See :ref:`message_queues_v2`.)
.. doxygengroup:: msgq_apis
:project: Zephyr
Mailboxes
*********
Mailboxes provide an enhanced message queuing mechanism
for variable-size messages.
(See :ref:`mailboxes_v2`.)
.. doxygengroup:: mailbox_apis
:project: Zephyr
Pipes
*****
Pipes provide a traditional anonymous pipe mechanism for sending
variable-size chunks of data, in whole or in part.
(See :ref:`pipes_v2`.)
.. doxygengroup:: pipe_apis
:project: Zephyr
Asynchronous Polling
********************
.. doxygengroup:: poll_apis
:project: Zephyr
Interrupt Service Routines (ISRs)
*********************************
An interrupt service routine is a series of instructions that is
executed asynchronously in response to a hardware or software interrupt.
(See :ref:`interrupts_v2`.)
.. doxygengroup:: isr_apis
:project: Zephyr
Atomic Services
***************
The atomic services enable multiple threads and ISRs to read and modify
32-bit variables in an uninterruptible manner.
(See :ref:`atomic_v2`.)
.. important::
All atomic services APIs can be used by both threads and ISRs.
.. doxygengroup:: atomic_apis
:project: Zephyr
Profiling Profiling
********* *********
@ -188,26 +25,6 @@ Profiling
.. doxygengroup:: profiling_apis .. doxygengroup:: profiling_apis
:project: Zephyr :project: Zephyr
Floating Point Services
***********************
The floating point services enable threads to use a board's floating point
registers.
(See :ref:`float_v2`.)
.. doxygengroup:: float_apis
:project: Zephyr
Ring Buffers
************
Ring buffers enable simple first in, first out (FIFO) queuing
of variable-size data items.
(See :ref:`ring_buffers_v2`.)
.. doxygengroup:: ring_buffer_apis
:project: Zephyr
:content-only:
Kernel Version Kernel Version
************** **************

17
doc/kernel/data_passing/data_passing.rst
View file

@ -1,17 +0,0 @@
.. _data_passing_v2:
Data Passing
############
This section describes kernel services for passing data
between different threads, or between an ISR and a thread.
.. toctree::
:maxdepth: 2
fifos.rst
lifos.rst
stacks.rst
message_queues.rst
mailboxes.rst
pipes.rst

17
doc/kernel/data_passing/fifos.rst
View file

@ -154,17 +154,10 @@ Configuration Options
Related configuration options: Related configuration options:
* None. * None
APIs API Reference
**** *************
The following fifo APIs are provided by :file:`kernel.h`: .. doxygengroup:: fifo_apis
:project: Zephyr
* :c:macro:`K_FIFO_DEFINE`
* :cpp:func:`k_fifo_init()`
* :cpp:func:`k_fifo_alloc_put()`
* :cpp:func:`k_fifo_put()`
* :cpp:func:`k_fifo_put_list()`
* :cpp:func:`k_fifo_put_slist()`
* :cpp:func:`k_fifo_get()`

12
doc/kernel/data_passing/lifos.rst
View file

@ -144,12 +144,8 @@ Related configuration options:
* None. * None.
APIs API Reference
**** *************
The following lifo APIs are provided by :file:`kernel.h`: .. doxygengroup:: lifo_apis
:project: Zephyr
* :c:macro:`K_LIFO_DEFINE`
* :cpp:func:`k_lifo_init()`
* :cpp:func:`k_lifo_put()`
* :cpp:func:`k_lifo_get()`

15
doc/kernel/data_passing/mailboxes.rst
View file

@ -630,15 +630,8 @@ Related configuration options:
* :option:`CONFIG_NUM_MBOX_ASYNC_MSGS` * :option:`CONFIG_NUM_MBOX_ASYNC_MSGS`
APIs API Reference
**** *************
The following APIs for a mailbox are provided by :file:`kernel.h`: .. doxygengroup:: mailbox_apis
:project: Zephyr
* :c:macro:`K_MBOX_DEFINE`
* :cpp:func:`k_mbox_init()`
* :cpp:func:`k_mbox_put()`
* :cpp:func:`k_mbox_async_put()`
* :cpp:func:`k_mbox_get()`
* :cpp:func:`k_mbox_data_get()`
* :cpp:func:`k_mbox_data_block_get()`

16
doc/kernel/data_passing/message_queues.rst
View file

@ -199,16 +199,8 @@ Related configuration options:
* None. * None.
APIs API Reference
**** *************
The following message queue APIs are provided by :file:`kernel.h`: .. doxygengroup:: msgq_apis
:project: Zephyr
* :c:macro:`K_MSGQ_DEFINE`
* :cpp:func:`k_msgq_init()`
* :cpp:func:`k_msgq_put()`
* :cpp:func:`k_msgq_get()`
* :cpp:func:`k_msgq_peek()`
* :cpp:func:`k_msgq_purge()`
* :cpp:func:`k_msgq_num_used_get()`
* :cpp:func:`k_msgq_num_free_get()`

13
doc/kernel/data_passing/pipes.rst
View file

@ -174,13 +174,8 @@ Related configuration options:
* :option:`CONFIG_NUM_PIPE_ASYNC_MSGS` * :option:`CONFIG_NUM_PIPE_ASYNC_MSGS`
APIs API Reference
**** *************
The following message queue APIs are provided by :file:`kernel.h`: .. doxygengroup:: pipe_apis
:project: Zephyr
* :c:macro:`K_PIPE_DEFINE`
* :cpp:func:`k_pipe_init()`
* :cpp:func:`k_pipe_put()`
* :cpp:func:`k_pipe_get()`
* :cpp:func:`k_pipe_block_put()`

11
doc/kernel/data_passing/stacks.rst
View file

@ -134,12 +134,9 @@ Related configuration options:
* None. * None.
APIs API Reference
**** *************
The following stack APIs are provided by :file:`kernel.h`: .. doxygengroup:: stack_apis
:project: Zephyr
* :c:macro:`K_STACK_DEFINE`
* :cpp:func:`k_stack_init()`
* :cpp:func:`k_stack_push()`
* :cpp:func:`k_stack_pop()`

25
doc/kernel/kernel.rst
View file

@ -26,9 +26,24 @@ include: fitness wearables, smart watches, and IoT wireless gateways.
:maxdepth: 2 :maxdepth: 2
threads/index.rst threads/index.rst
timing/timing.rst other/interrupts.rst
memory/memory.rst
synchronization/synchronization.rst
data_passing/data_passing.rst
usermode/usermode.rst usermode/usermode.rst
other/other.rst synchronization/semaphores.rst
synchronization/mutexes.rst
data_passing/fifos.rst
data_passing/lifos.rst
data_passing/stacks.rst
data_passing/message_queues.rst
data_passing/mailboxes.rst
data_passing/pipes.rst
timing/clocks.rst
other/cpu_idle.rst
timing/timers.rst
memory/slabs.rst
memory/pools.rst
memory/heap.rst
other/atomic.rst
other/polling.rst
other/float.rst
other/ring_buffers.rst
other/cxx_support.rst

10
doc/kernel/memory/heap.rst
View file

@ -129,10 +129,8 @@ Related configuration options:
* :option:`CONFIG_HEAP_MEM_POOL_SIZE` * :option:`CONFIG_HEAP_MEM_POOL_SIZE`
APIs API Reference
**** *************
The following heap memory pool APIs are provided by :file:`kernel.h`: .. doxygengroup:: heap_apis
:project: Zephyr
* :cpp:func:`k_malloc()`
* :cpp:func:`k_free()`

14
doc/kernel/memory/memory.rst
View file

@ -1,14 +0,0 @@
.. _memory_v2:
Memory Allocation
#################
This section describes kernel services that allow threads to dynamically
allocate memory.
.. toctree::
:maxdepth: 2
slabs.rst
pools.rst
heap.rst

14
doc/kernel/memory/pools.rst
View file

@ -200,15 +200,9 @@ Use a memory pool to allocate memory in variable-size blocks.
Use memory pool blocks when sending large amounts of data from one thread Use memory pool blocks when sending large amounts of data from one thread
to another, to avoid unnecessary copying of the data. to another, to avoid unnecessary copying of the data.
APIs API Reference
**** *************
The following memory pool APIs are provided by :file:`kernel.h`: .. doxygengroup:: mem_pool_apis
:project: Zephyr
* :c:macro:`K_MEM_POOL_DEFINE`
* :cpp:func:`k_mem_pool_alloc()`
* :cpp:func:`k_mem_pool_free()`
* :cpp:func:`k_mem_pool_malloc()`
* :cpp:func:`k_free()`
* :cpp:func:`k_thread_resource_pool_assign()`
* :cpp:func:`k_thread_system_pool_assign()`

16
doc/kernel/memory/slabs.rst
View file

@ -139,16 +139,10 @@ Configuration Options
Related configuration options: Related configuration options:
* None. * None
APIs API Reference
**** *************
The following memory slab APIs are provided by :file:`kernel.h`: .. doxygengroup:: mem_slab_apis
:project: Zephyr
* :c:macro:`K_MEM_SLAB_DEFINE`
* :cpp:func:`k_mem_slab_init()`
* :cpp:func:`k_mem_slab_alloc()`
* :cpp:func:`k_mem_slab_free()`
* :cpp:func:`k_mem_slab_num_used_get()`
* :cpp:func:`k_mem_slab_num_free_get()`

29
doc/kernel/other/atomic.rst
View file

@ -110,27 +110,12 @@ Related configuration options:
* :option:`CONFIG_ATOMIC_OPERATIONS_CUSTOM` * :option:`CONFIG_ATOMIC_OPERATIONS_CUSTOM`
* :option:`CONFIG_ATOMIC_OPERATIONS_C` * :option:`CONFIG_ATOMIC_OPERATIONS_C`
APIs API Reference
**** *************
The following atomic operation APIs are provided by :file:`atomic.h`: .. important::
All atomic services APIs can be used by both threads and ISRs.
.. doxygengroup:: atomic_apis
:project: Zephyr
* :c:macro:`ATOMIC_INIT`
* :c:macro:`ATOMIC_DEFINE`
* :cpp:func:`atomic_get()`
* :cpp:func:`atomic_set()`
* :cpp:func:`atomic_clear()`
* :cpp:func:`atomic_add()`
* :cpp:func:`atomic_sub()`
* :cpp:func:`atomic_inc()`
* :cpp:func:`atomic_dec()`
* :cpp:func:`atomic_and()`
* :cpp:func:`atomic_or()`
* :cpp:func:`atomic_xor()`
* :cpp:func:`atomic_nand()`
* :cpp:func:`atomic_cas()`
* :cpp:func:`atomic_set_bit()`
* :cpp:func:`atomic_clear_bit()`
* :cpp:func:`atomic_test_bit()`
* :cpp:func:`atomic_test_and_set_bit()`
* :cpp:func:`atomic_test_and_clear_bit()`

10
doc/kernel/other/cpu_idle.rst
View file

@ -134,10 +134,8 @@ i.e. not doing any real work, like in this example below.
**Do not use these APIs unless absolutely necessary.** In a normal system, **Do not use these APIs unless absolutely necessary.** In a normal system,
the idle thread takes care of power management, including CPU idling. the idle thread takes care of power management, including CPU idling.
APIs API Reference
**** *************
The following CPU idling APIs are provided by :file:`kernel.h`: .. doxygengroup:: cpu_idle_apis
:project: Zephyr
* :cpp:func:`k_cpu_idle()`
* :cpp:func:`k_cpu_atomic_idle()`

9
doc/kernel/other/float.rst
View file

@ -172,10 +172,9 @@ during context switches, as described above.
Use the :option:`CONFIG_SSE` configuration option to enable support for Use the :option:`CONFIG_SSE` configuration option to enable support for
SSEx instructions (x86 only). SSEx instructions (x86 only).
APIs API Reference
**** *************
The following floating point APIs (x86 only) are provided by :file:`kernel.h`: .. doxygengroup:: float_apis
:project: Zephyr
* :cpp:func:`k_float_enable()`
* :cpp:func:`k_float_disable()`

25
doc/kernel/other/interrupts.rst
View file

@ -437,25 +437,8 @@ Related configuration options:
Additional architecture-specific and device-specific configuration options Additional architecture-specific and device-specific configuration options
also exist. also exist.
APIs API Reference
**** *************
The following interrupt-related APIs are provided by :file:`irq.h`: .. doxygengroup:: isr_apis
:project: Zephyr
* :c:macro:`IRQ_CONNECT`
* :c:macro:`IRQ_DIRECT_CONNECT`
* :c:macro:`ISR_DIRECT_HEADER`
* :c:macro:`ISR_DIRECT_FOOTER`
* :c:macro:`ISR_DIRECT_PM`
* :c:macro:`ISR_DIRECT_DECLARE`
* :cpp:func:`irq_lock()`
* :cpp:func:`irq_unlock()`
* :cpp:func:`irq_enable()`
* :cpp:func:`irq_disable()`
* :cpp:func:`irq_is_enabled()`
* :cpp:func:`irq_connect_dynamic()`
The following interrupt-related APIs are provided by :file:`kernel.h`:
* :cpp:func:`k_is_in_isr()`
* :cpp:func:`k_is_preempt_thread`

17
doc/kernel/other/other.rst
View file

@ -1,17 +0,0 @@
.. _other_v2:
Other Services
##############
This section describes other services provided by the kernel.
.. toctree::
:maxdepth: 1
interrupts.rst
atomic.rst
polling.rst
ring_buffers.rst
float.rst
cxx_support.rst
cpu_idle.rst

14
doc/kernel/other/polling.rst
View file

@ -280,14 +280,8 @@ Related configuration options:
* :option:`CONFIG_POLL` * :option:`CONFIG_POLL`
APIs API Reference
**** *************
The following polling APIs are provided by :file:`kernel.h`: .. doxygengroup:: poll_apis
:project: Zephyr
* :c:macro:`K_POLL_EVENT_INITIALIZER`
* :c:macro:`K_POLL_EVENT_STATIC_INITIALIZER`
* :cpp:func:`k_poll_event_init()`
* :cpp:func:`k_poll()`
* :cpp:func:`k_poll_signal_init()`
* :cpp:func:`k_poll_signal_raise()`

20
doc/kernel/other/ring_buffers.rst
View file

@ -303,22 +303,10 @@ operations on the ring buffer's memory. For example:
... ...
} }
APIs API Reference
**** *************
The following ring buffer APIs are provided by :file:`include/ring_buffer.h`: The following ring buffer APIs are provided by :file:`include/ring_buffer.h`:
* :cpp:func:`RING_BUF_ITEM_DECLARE_POW2()` .. doxygengroup:: ring_buffer_apis
* :cpp:func:`RING_BUF_ITEM_DECLARE_SIZE()` :project: Zephyr
* :cpp:func:`RING_BUF_DECLARE_SIZE()`
* :cpp:func:`ring_buf_init()`
* :cpp:func:`ring_buf_is_empty()`
* :cpp:func:`ring_buf_space_get()`
* :cpp:func:`ring_buf_item_put()`
* :cpp:func:`ring_buf_item_get()`
* :cpp:func:`ring_buf_put()`
* :cpp:func:`ring_buf_put_claim()`
* :cpp:func:`ring_buf_put_finish()`
* :cpp:func:`ring_buf_get()`
* :cpp:func:`ring_buf_get_claim()`
* :cpp:func:`ring_buf_get_finish()`

11
doc/kernel/synchronization/mutexes.rst
View file

@ -161,12 +161,9 @@ Related configuration options:
* :option:`CONFIG_PRIORITY_CEILING` * :option:`CONFIG_PRIORITY_CEILING`
APIs API Reference
**** *************
The following mutex APIs are provided by :file:`kernel.h`: .. doxygengroup:: mutex_apis
:project: Zephyr
* :c:macro:`K_MUTEX_DEFINE`
* :cpp:func:`k_mutex_init()`
* :cpp:func:`k_mutex_lock()`
* :cpp:func:`k_mutex_unlock()`

13
doc/kernel/synchronization/semaphores.rst
View file

@ -125,14 +125,9 @@ Related configuration options:
* None. * None.
APIs API Reference
**** **************
The following semaphore APIs are provided by :file:`kernel.h`: .. doxygengroup:: semaphore_apis
:project: Zephyr
* :c:macro:`K_SEM_DEFINE`
* :cpp:func:`k_sem_init()`
* :cpp:func:`k_sem_give()`
* :cpp:func:`k_sem_take()`
* :cpp:func:`k_sem_reset()`
* :cpp:func:`k_sem_count_get()`

13
doc/kernel/synchronization/synchronization.rst
View file

@ -1,13 +0,0 @@
.. _synchronization_v2:
Synchronization
###############
This section describes kernel services for synchronizing the operation
of different threads, or the operation of an ISR and a thread.
.. toctree::
:maxdepth: 2
semaphores.rst
mutexes.rst

20
doc/kernel/timing/clocks.rst
View file

@ -154,20 +154,8 @@ Related configuration options:
* :option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` * :option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC`
APIs API Reference
**** *************
The following kernel clock APIs are provided by :file:`kernel.h`: .. doxygengroup:: clock_apis
:project: Zephyr
* :cpp:func:`k_uptime_get()`
* :cpp:func:`k_uptime_get_32()`
* :cpp:func:`k_uptime_delta()`
* :cpp:func:`k_uptime_delta_32()`
* :cpp:func:`k_cycle_get_32()`
* :c:macro:`SYS_CLOCK_HW_CYCLES_TO_NS`
* :c:macro:`K_NO_WAIT`
* :c:macro:`K_MSEC`
* :c:macro:`K_SECONDS`
* :c:macro:`K_MINUTES`
* :c:macro:`K_HOURS`
* :c:macro:`K_FOREVER`

17
doc/kernel/timing/timers.rst
View file

@ -235,17 +235,10 @@ Configuration Options
Related configuration options: Related configuration options:
* None. * None
APIs API Reference
**** *************
The following timer APIs are provided by :file:`kernel.h`: .. doxygengroup:: timer_apis
:project: Zephyr
* :c:macro:`K_TIMER_DEFINE`
* :cpp:func:`k_timer_init()`
* :cpp:func:`k_timer_start()`
* :cpp:func:`k_timer_stop()`
* :cpp:func:`k_timer_status_get()`
* :cpp:func:`k_timer_status_sync()`
* :cpp:func:`k_timer_remaining_get()`

13
doc/kernel/timing/timing.rst
View file

@ -1,13 +0,0 @@
.. _timing_v2:
Timing
######
This section describes the kernel's time-based services, such as
specifying time delays or for measuring the passage of time.
.. toctree::
:maxdepth: 2
clocks.rst
timers.rst