1.. _system_threads_v2:
2
3System Threads
4##############
5
6.. contents::
7    :local:
8    :depth: 2
9
10A :dfn:`system thread` is a thread that the kernel spawns automatically
11during system initialization.
12
13The kernel spawns the following system threads:
14
15**Main thread**
16    This thread performs kernel initialization, then calls the application's
17    :c:func:`main` function (if one is defined).
18
19    By default, the main thread uses the highest configured preemptible thread
20    priority (i.e. 0). If the kernel is not configured to support preemptible
21    threads, the main thread uses the lowest configured cooperative thread
22    priority (i.e. -1).
23
24    The main thread is an essential thread while it is performing kernel
25    initialization or executing the application's :c:func:`main` function;
26    this means a fatal system error is raised if the thread aborts. If
27    :c:func:`main` is not defined, or if it executes and then does a normal
28    return, the main thread terminates normally and no error is raised.
29
30**Idle thread**
31    This thread executes when there is no other work for the system to do.
32    If possible, the idle thread activates the board's power management support
33    to save power; otherwise, the idle thread simply performs a "do nothing"
34    loop. The idle thread remains in existence as long as the system is running
35    and never terminates.
36
37    The idle thread always uses the lowest configured thread priority.
38    If this makes it a cooperative thread, the idle thread repeatedly
39    yields the CPU to allow the application's other threads to run when
40    they need to.
41
42    The idle thread is an essential thread, which means a fatal system error
43    is raised if the thread aborts.
44
45Additional system threads may also be spawned, depending on the kernel
46and board configuration options specified by the application. For example,
47enabling the system workqueue spawns a system thread
48that services the work items submitted to it. (See :ref:`workqueues_v2`.)
49
50Implementation
51**************
52
53Writing a main() function
54=========================
55
56An application-supplied :c:func:`main` function begins executing once
57kernel initialization is complete. The kernel does not pass any arguments
58to the function.
59
60The following code outlines a trivial :c:func:`main` function.
61The function used by a real application can be as complex as needed.
62
63.. code-block:: c
64
65    int main(void)
66    {
67        /* initialize a semaphore */
68	...
69
70	/* register an ISR that gives the semaphore */
71	...
72
73	/* monitor the semaphore forever */
74	while (1) {
75	    /* wait for the semaphore to be given by the ISR */
76	    ...
77	    /* do whatever processing is now needed */
78	    ...
79	}
80    }
81
82Suggested Uses
83**************
84
85Use the main thread to perform thread-based processing in an application
86that only requires a single thread, rather than defining an additional
87application-specific thread.
88