From b417442575e8c73b0261c68b45f4cd2842ff8c7a Mon Sep 17 00:00:00 2001 From: Peter Bigot Date: Mon, 19 Oct 2020 10:52:06 -0500 Subject: [PATCH] doc: kernel: document general policy for Zephyr without threads This provides the documentation of scope required as a stage towards removing deprecation for CONFIG_MULTITHREADING=n. The specific lists of what does work will follow as the code base is inspected and updated. Signed-off-by: Peter Bigot Signed-off-by: Krzysztof Chruscinski --- doc/reference/kernel/index.rst | 5 + doc/reference/kernel/threads/index.rst | 3 + doc/reference/kernel/threads/nothread.rst | 121 ++++++++++++++++++++++ 3 files changed, 129 insertions(+) create mode 100644 doc/reference/kernel/threads/nothread.rst diff --git a/doc/reference/kernel/index.rst b/doc/reference/kernel/index.rst index 732a7d7ec6b..b0bffc9004f 100644 --- a/doc/reference/kernel/index.rst +++ b/doc/reference/kernel/index.rst @@ -34,6 +34,7 @@ synchronization. scheduling/index.rst threads/system_threads.rst threads/workqueue.rst + threads/nothread.rst other/interrupts.rst other/polling.rst synchronization/semaphores.rst @@ -41,6 +42,8 @@ synchronization. synchronization/condvar.rst smp/smp.rst +.. _kernel_data_passing_api: + Data Passing ************ @@ -83,6 +86,8 @@ argument. data_passing/mailboxes.rst data_passing/pipes.rst +.. _kernel_memory_management_api: + Memory Management ***************** diff --git a/doc/reference/kernel/threads/index.rst b/doc/reference/kernel/threads/index.rst index 81e69a3fb79..db7abc29632 100644 --- a/doc/reference/kernel/threads/index.rst +++ b/doc/reference/kernel/threads/index.rst @@ -3,6 +3,9 @@ Threads ####### +.. note:: + There is also limited support for using :ref:`nothread`. + .. contents:: :local: :depth: 2 diff --git a/doc/reference/kernel/threads/nothread.rst b/doc/reference/kernel/threads/nothread.rst new file mode 100644 index 00000000000..c3931e24273 --- /dev/null +++ b/doc/reference/kernel/threads/nothread.rst @@ -0,0 +1,121 @@ +.. _nothread: + +Zephyr Without Threads +###################### + +Thread support is not necessary in some applications: + +* Bootloaders +* Simple event-driven applications +* Examples intended to demonstrate core functionality + +Thread support can be disabled in Zephyr by setting +:option:`CONFIG_MULTITHREADING` to ``n``. Since this configuration has +a significant impact on Zephyr's functionality and testing of it has +been limited, there are conditions on what can be expected to work in +this configuration. + +What Can be Expected to Work +**************************** + +These core capabilities shall function correctly when +:option:`CONFIG_MULTITHREADING` is disabled: + +* The :ref:`build system ` + +* The ability to boot the application to ``main()`` + +* :ref:`Interrupt management ` + +* The system clock including :c:func:`k_uptime_get` + +* Timers, i.e. :c:func:`k_timer` + +* Non-sleeping delays e.g. :c:func:`k_busy_wait`. + +* Sleeping :c:func:`k_cpu_idle`. + +* Pre ``main()`` drivers and subsystems initialization e.g. :c:macro:`SYS_INIT`. + +* :ref:`kernel_memory_management_api` + +* Specifically identified drivers in certain subsystems, listed below. + +The expectations above affect selection of other features; for example +:option:`CONFIG_SYS_CLOCK_EXISTS` cannot be set to ``n``. + +What Cannot be Expected to Work +******************************* + +Functionality that will not work with :option:`CONFIG_MULTITHREADING` +includes majority of the kernel API: + +* :ref:`threads_v2` + +* :ref:`scheduling_v2` + +* :ref:`workqueues_v2` + +* :ref:`polling_v2` + +* :ref:`semaphores_v2` + +* :ref:`mutexes_v2` + +* :ref:`condvar` + +* :ref:`kernel_data_passing_api` + +.. contents:: + :local: + :depth: 1 + +Subsystem Behavior Without Thread Support +***************************************** + +The sections below list driver and functional subsystems that are +expected to work to some degree when :option:`CONFIG_MULTITHREADING` is +disabled. Subsystems that are not listed here should not be expected to +work. + +Some existing drivers within the listed subsystems do not work when +threading is disabled, but are within scope based on their subsystem, or +may be sufficiently isolated that supporting them on a particular +platform is low-impact. Enhancements to add support to existing +capabilities that were not originally implemented to work with threads +disabled will be considered. + +Flash +===== + +The :ref:`flash_api` is expected to work for all SoC flash peripheral +drivers. Bus-accessed devices like serial memories may not be +supported. + +*List/table of supported drivers to go here* + +GPIO +==== + +The :ref:`gpio_api` is expected to work for all SoC GPIO peripheral +drivers. Bus-accessed devices like GPIO extenders may not be supported. + +*List/table of supported drivers to go here* + +UART +==== + +A subset of the :ref:`uart_api` is expected to work for all SoC UART +peripheral drivers. + +* Applications that select :option:`CONFIG_UART_INTERRUPT_DRIVEN` may + work, depending on driver implementation. + +* Applications that select :option:`CONFIG_UART_ASYNC_API` may + work, depending on driver implementation. + +* Applications that do not select either :option:`CONFIG_UART_ASYNC_API` + or :option:`CONFIG_UART_INTERRUPT_DRIVEN` are expected to work. + +*List/table of supported drivers to go here, including which API options +are supported*