1.. _samples_scheduler_metairq_dispatch:
2
3MetaIRQ Thread Priority Demonstration
4#####################################
5
6Overview
7********
8
9This sample demonstrates the use of a thread running at a MetaIRQ
10priority level to implement "bottom half" style processing
11synchronously with the end of a hardware ISR.  It implements a
12simulated "device" that produces messages that need to be dispatched
13to asynchronous queues feeding several worker threads, each running at
14a different priority.  The dispatch is handled by a MetaIRQ thread fed
15via a queue from the device ISR (really just a timer interrupt).
16
17Each message has a random (and non-trivial) amount of processing that
18must happen in the worker thread.  This implements a "bursty load"
19environment where occasional spikes in load require preemption of
20running threads and delay scheduling of lower priority threads.
21Messages are accompanied by a timestamp that allows per-message
22latencies to be computed at several points:
23
24* The cycle time between message creation in the ISR and receipt by
25  the MetaIRQ thread for dispatch.
26
27* The time between ISR and receipt by the worker thread.
28
29* The real time spent processing the message in the worker thread, for
30  comparison with the required processing time.  This provides a way
31  to measure preemption overhead where the thread is not scheduled.
32
33Aspects to note in the results:
34
35* On average, higher priority (lower numbered) threads have better
36  latencies and lower processing delays, as expected.
37
38* Cooperatively scheduled threads have significantly better processing
39  delay behavior than preemptible ones, as they can only be preempted
40  by the MetaIRQ thread.
41
42* Because of queueing and the bursty load, all worker threads of any
43  priority will experience some load-dependent delays, as the CPU
44  occasionally has more work to do than time available.
45
46* But, no matter the system load or thread configuration, the MetaIRQ
47  thread always runs immediately after the ISR.  It shows reliable,
48  constant latency under all circumstances because it can preempt all
49  other threads, including cooperative ones that cannot normally be
50  preempted.
51
52Requirements
53************
54
55This sample should run well on any Zephyr platform that provides
56preemption of running threads by interrupts, a working timer driver,
57and working log output.  For precision reasons, it produces better
58(and more) data on systems with a high timer tick rate (ideally 10+
59kHz).
60
61Note that because the test is fundamentally measuring thread
62preemption behavior, it does not run without modification on
63native_sim platforms. In that emulation environment, threads will
64not be preempted except at specific instrumentation points (e.g. in
65k_busy_wait()) where they will voluntarily release the CPU.
66
67Building and Running
68********************
69
70This application can be built and executed on frdm_k64f as follows:
71
72.. zephyr-app-commands::
73   :zephyr-app: samples/kernel/metairq_dispatch
74   :board: frdm_k64f
75   :goals: build flash
76   :compact:
77
78To build for another board, change "frdm_k64f" above to that board's name.
79
80Sample Output
81=============
82
83Sample output shown below is from frdm_k64f. The numbers will
84look different based upon the clock frequency of the board and other
85factors.
86
87Note: The 'real' values may be significantly higher than corresponding 'proc' values
88(intended) for non-cooperative threads like T2 and T3 which is attributed to delays
89due to thread preemption.
90
91
92.. code-block:: console
93
94   I: Starting Thread0 at priority -2
95   I: Starting Thread1 at priority -1
96   II: M0 T0 mirq 4478 disp 7478 proc 24336 real 24613
97   I: M8 T0 mirq 4273 disp 86983 proc 9824 real 16753
98   I: M10 T0 mirq 4273 disp 495455 proc 21177 real 28273
99   I: M11 T0 mirq 4273 disp 981565 proc 48337 real 48918
100   I: M14 T0 mirq 4273 disp 1403627 proc 7079 real 7690
101   I: M17 T0 mirq 4273 disp 1810028 proc 42143 real 42925
102   I: M19 T0 mirq 4273 disp 2369217 proc 42471 real 42925
103   I: M20 T0 mirq 4273 disp 2940429 proc 30427 real 30775
104   I: M21 T0 mirq 4273 disp 3524151 proc 35871 real 36850
105   I: M22 T0 mirq 4273 disp 4042148 proc 33738 real 34420
106   I: M23 T0 mirq 4273 disp 4557010 proc 5757 real 6475
107   I: M29 T0 mirq 4273 disp 4759422 proc 49748 real 50215
108   I: M33 T0 mirq 4273 disp 5218935 proc 32105 real 33205
109   I: M35 T0 mirq 4273 disp 5732769 proc 32678 real 33205
110   I: M36 T0 mirq 4273 disp 6294586 proc 9303 real 10120
111   I: M37 T0 mirq 4273 disp 6819398 proc 29960 real 30775
112   I: M40 T0 mirq 3189 disp 7199139 proc 19692 real 21055
113   I: M9 T1 mirq 4273 disp 9417562 proc 53844 real 55075
114   I: M18 T1 mirq 4273 disp 9522780 proc 4560 real 5260
115   I: M25 T1 mirq 4273 disp 9713189 proc 56656 real 57505
116   I: M27 T1 mirq 4273 disp 10238978 proc 48347 real 49000
117   : Starting Thread2 at priority 0
118   I: M1 T2 mirq 4273 disp 12740821 proc 40449 real 41710
119   I: M2 T2 mirq 4273 disp 13311098 proc 43926 real 44140
120   I: M3 T2 mirq 4273 disp 13824365 proc 41212 real 41710
121   I: M4 T2 mirq 4273 disp 14382522 proc 12859 real 13765
122   I: M5 T2 mirq 4273 disp 14869754 proc 17303 real 18625
123   I: M7 T2 mirq 4273 disp 15368993 proc 10666 real 11335
124   I: M15 T2 mirq 4273 disp 15364239 proc 45304 real 46570
125   I: M24 T2 mirq 4273 disp 15602017 proc 39637 real 40495
126   I: M28 T2 mirq 4273 disp 15989555 proc 24436 real 24700
127   I: M30 T2 mirq 4273 disp 16493444 proc 44374 real 45355
128   I: M31 T2 mirq 4273 disp 17078141 proc 21947 real 22270
129   I: M34 T2 mirq 4273 disp 17555966 proc 47779 real 49000
130   I: M39 T2 mirq 4273 disp 17843806 proc 10954 real 11335
131   I: Starting Thread3 at priority 1
132   I: M6 T3 mirq 4273 disp 20625899 proc 13459 real 13765
133   I: M12 T3 mirq 4273 disp 20813171 proc 13534 real 13765
134   I: M13 T3 mirq 4273 disp 21334833 proc 37091 real 38065
135   I: M16 T3 mirq 4273 disp 21744289 proc 42514 real 42925
136   I: M26 T3 mirq 4273 disp 21846939 proc 36261 real 36850
137   I: M32 T3 mirq 4273 disp 22207336 proc 49987 real 50215
138   I: M38 T3 mirq 4273 disp 22532228 proc 37164 real 38065
139   I:         ---------- Latency (cyc) ----------
140   I:             Best    Worst     Mean    Stdev
141   I: MetaIRQ     4273     4478     4278       32
142   I: Thread0     7478  6819398  3190200  2183592
143   I: Thread1  9417562 10238978  9723127   316113
144   I: Thread2 12740821 17843806 15417286  1525493
145   I: Thread3 20625899 22532228 21586385   649911
146   I: MetaIRQ Test Complete
147