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 [#f1]_    4 B [#f2]_          Yes [#f3]_         Yes             N/A
60LIFO              No                  Queue                  Arbitrary [#f1]_    4 B [#f2]_          Yes [#f3]_         Yes             N/A
61Stack             No                  Array                  Word                Word                Yes [#f3]_         Yes             Undefined behavior
62Message queue     No                  Ring buffer            Arbitrary [#f6]_    Power of two        Yes [#f3]_         Yes             Pend thread or return -errno
63Mailbox           Yes                 Queue                  Arbitrary [#f1]_    Arbitrary           No                 No              N/A
64Pipe              No                  Ring buffer [#f4]_     Arbitrary           Arbitrary           Yes [#f5]_         Yes [#f5]_      Pend thread or return -errno
65===============   ==============      ===================    ================    =================   =================  ==============  ===============================
66
67.. rubric:: Footnotes
68
69.. [#f1] Callers allocate space for queue overhead in the data
70         elements themselves.
71
72.. [#f2] Objects added with :c:func:`k_fifo_alloc_put()` and :c:func:`k_lifo_alloc_put()`
73         do not have alignment constraints, but use temporary memory from the
74         calling thread's resource pool.
75
76.. [#f3] ISRs can receive only when passing K_NO_WAIT as the timeout
77         argument.
78
79.. [#f4] Optional.
80
81.. [#f5] ISRs can send and/or receive only when passing K_NO_WAIT as the
82         timeout argument.
83
84.. [#f6] Data item size must be a multiple of the data alignment.
85
86.. toctree::
87   :maxdepth: 1
88
89   data_passing/queues.rst
90   data_passing/fifos.rst
91   data_passing/lifos.rst
92   data_passing/stacks.rst
93   data_passing/message_queues.rst
94   data_passing/mailboxes.rst
95   data_passing/pipes.rst
96
97.. _kernel_memory_management_api:
98
99Memory Management
100*****************
101
102See :ref:`memory_management_api`.
103
104Timing
105******
106
107These pages cover timing related services.
108
109.. toctree::
110   :maxdepth: 1
111
112   timing/clocks.rst
113   timing/timers.rst
114
115Other
116*****
117
118These pages cover other kernel services.
119
120.. toctree::
121   :maxdepth: 1
122
123   other/atomic.rst
124   other/float.rst
125   other/version.rst
126   other/fatal.rst
127   other/thread_local_storage.rst
128