1.. _kernel_api:
2
3Kernel Services
4###############
5
6The Zephyr kernel lies at the heart of every Zephyr application. It provides
7a low footprint, high performance, multi-threaded execution environment
8with a rich set of available features. The rest of the Zephyr ecosystem,
9including device drivers, networking stack, and application-specific code,
10uses the kernel's features to create a complete application.
11
12The configurable nature of the kernel allows you to incorporate only those
13features needed by your application, making it ideal for systems with limited
14amounts of memory (as little as 2 KB!) or with simple multi-threading
15requirements (such as a set of interrupt handlers and a single background task).
16Examples of such systems include: embedded sensor hubs, environmental sensors,
17simple LED wearable, and store inventory tags.
18
19Applications requiring more memory (50 to 900 KB), multiple communication
20devices (like Wi-Fi and Bluetooth Low Energy), and complex multi-threading,
21can also be developed using the Zephyr kernel. Examples of such systems
22include: fitness wearables, smart watches, and IoT wireless gateways.
23
24Scheduling, Interrupts, and Synchronization
25*******************************************
26
27These pages cover basic kernel services related to thread scheduling and
28synchronization.
29
30.. toctree::
31   :maxdepth: 1
32
33   threads/index.rst
34   scheduling/index.rst
35   threads/system_threads.rst
36   threads/workqueue.rst
37   threads/nothread.rst
38   interrupts.rst
39   polling.rst
40   synchronization/semaphores.rst
41   synchronization/mutexes.rst
42   synchronization/condvar.rst
43   synchronization/events.rst
44   smp/smp.rst
45
46.. _kernel_data_passing_api:
47
48Data Passing
49************
50
51These pages cover kernel objects which can be used to pass data between
52threads and ISRs.
53
54The following table summarizes their high-level features.
55
56===============   ==============      ===================    ==============      ==============   =================  ==============  ===============================
57Object            Bidirectional?      Data structure         Data item size      Data Alignment   ISRs can receive?  ISRs can send?  Overrun handling
58===============   ==============      ===================    ==============      ==============   =================  ==============  ===============================
59FIFO              No                  Queue                  Arbitrary [1]              4 B [2]   Yes [3]            Yes             N/A
60LIFO              No                  Queue                  Arbitrary [1]              4 B [2]   Yes [3]            Yes             N/A
61Stack             No                  Array                  Word                          Word   Yes [3]            Yes             Undefined behavior
62Message queue     No                  Ring buffer            Arbitrary [6]         Power of two   Yes [3]            Yes             Pend thread or return -errno
63Mailbox           Yes                 Queue                  Arbitrary [1]            Arbitrary   No                 No              N/A
64Pipe              No                  Ring buffer [4]        Arbitrary                Arbitrary   Yes [5]            Yes [5]         Pend thread or return -errno
65===============   ==============      ===================    ==============      ==============   =================  ==============  ===============================
66
67[1] Callers allocate space for queue overhead in the data
68elements themselves.
69
70[2] Objects added with k_fifo_alloc_put() and k_lifo_alloc_put()
71do not have alignment constraints, but use temporary memory from the
72calling thread's resource pool.
73
74[3] ISRs can receive only when passing K_NO_WAIT as the timeout
75argument.
76
77[4] Optional.
78
79[5] ISRS can send and/or receive only when passing K_NO_WAIT as the
80timeout argument.
81
82[6] Data item size must be a multiple of the data alignment.
83
84.. toctree::
85   :maxdepth: 1
86
87   data_passing/queues.rst
88   data_passing/fifos.rst
89   data_passing/lifos.rst
90   data_passing/stacks.rst
91   data_passing/message_queues.rst
92   data_passing/mailboxes.rst
93   data_passing/pipes.rst
94
95.. _kernel_memory_management_api:
96
97Memory Management
98*****************
99
100See :ref:`memory_management_api`.
101
102Timing
103******
104
105These pages cover timing related services.
106
107.. toctree::
108   :maxdepth: 1
109
110   timing/clocks.rst
111   timing/timers.rst
112
113Other
114*****
115
116These pages cover other kernel services.
117
118.. toctree::
119   :maxdepth: 1
120
121   other/atomic.rst
122   other/float.rst
123   other/version.rst
124   other/fatal.rst
125   other/thread_local_storage.rst
126