forked from shkwon98/rpi4-xenomai3
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathipipe-core-4.19.82-arm-6-mod-4.49.86.patch
20568 lines (19652 loc) · 597 KB
/
ipipe-core-4.19.82-arm-6-mod-4.49.86.patch
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
diff --git a/Documentation/ipipe-arm.rst b/Documentation/ipipe-arm.rst
new file mode 100644
index 000000000000..71ba475543c3
--- /dev/null
+++ b/Documentation/ipipe-arm.rst
@@ -0,0 +1,833 @@
+.. include:: <isonum.txt>
+
+===============================================
+Porting the interrupt pipeline to a new ARM SoC
+===============================================
+
+:Copyright: |copy| 2014: Gilles Chanteperdrix
+:Copyright: |copy| 2018: Philippe Gerum
+
+Purpose
+=======
+
+This document is an adaptation of the original article [#f1]_ by
+Gilles Chanteperdrix for the Xenomai project, detailing the changes
+introduced by the interrupt pipeline into the ARM kernel.
+
+It is aimed at guiding you through the task of porting the I-pipe core
+to a new ARM SoC, for interfacing a co-kernel such as Xenomai with
+Linux, in order to implement a real-time, dual kernel system.
+
+.. [#f1] "Porting Xenomai dual kernel to a new ARM SoC"
+ https://xenomai.org/2014/09/porting-xenomai-dual-kernel-to-a-new-arm-soc/
+
+Terminology
+-----------
+
+If you are reading this document, chances are you want to get the
+I-pipe to run on an ARM based *board*. Examples of **board**s are
+*beagleboard*, *beaglebone*, *raspberry pi*.
+
+This board uses an ARM based *SoC*. Examples of **SoC**s are Atmel
+AT91RM9200, Atmel AT91SAM9263, TI OMAP3530, TI OMAP4430, Freescale
+IMX53. We use *SoC family* to loosely designate groups of SoCs which
+have so many peripherals in common that peripheral support code is
+shared between them. For instance, there is an "AT91" family,
+including the AT91RM9200 and AT91SAM9263 SoCs, and several others.
+
+This SoC is based on a processor *core* implementing the ARM
+instruction set, examples of such **core**s are ARM 926EJ-S,
+Intel/Marvell Xscale, Marvell Feroceon, ARM Cortex A8, ARM Cortex A9.
+
+Finally, this processor core implements an ARM *architecture*, sort of
+revision of the ARM instruction set. Examples of ARM **architecture**s
+are armv4, armv5, armv6 and armv7.
+
+So, for instance, the IGEPv2 *board* uses the TI OMAP3530 *SoC*,
+member of the OMAP *SoC family*, based on the ARM Cortex A8 *core*,
+implementing the armv7 *architecture*.
+
+.. CAUTION: Starting from kernel 4.14, the I-pipe does not support
+ armv4 or armv5 architectures anymore, but only armv6 onward.
+
+Locate the ARM-specific code to port
+------------------------------------
+
+Initially, you should identify what are the SoC, processor core and
+architecture of the SoC used by your board, then locate the
+corresponding SoC and board-specific code.
+
+In order to figure out such information, you can use the Linux kernel
+Kconfig and Makefiles in various sub-directories in the Linux kernel
+sources. Linux code specific to an ARM based SoC or SoC family X is
+located in arch/arm/mach-X or arch/arm/plat-X, some code may also live
+in the drivers/ directory, typically in drivers/clocksource,
+drivers/gpio or drivers/irqchip.
+
+Some devices managed by the I-pipe core (hardware timer, high
+resolution counter, interrupt controller, GPIO controller) may be
+specific to each SoC, and has to be adapted to run with the I-pipe
+core.
+
+.. NOTE: If the processor core is an ARM Cortex A9, things are going
+to be a bit easier, as such core contains an interrupt controller, a
+hardware timer and a high resolution counter, for which drivers have
+already been ported to the I-pipe.
+
+.. _`hardware-timer`:
+Hardware timer
+--------------
+
+A hardware timer programmable for ticking in one-shot mode is required
+by I-pipe clients such as co-kernels. Support for such timer is
+abstracted by the I-pipe core in ``struct ipipe_timer``.
+
+For most ARM SoCs, the hardware timer details are specific to each SoC
+or SoC family, therefore such ``ipipe_timer`` descriptor must be added
+on a SoC per SoC basis. There are several ways, to implement this
+timer descriptor in the I-pipe core.
+
+.. _`A9-timer`:
+The Cortex-A9 case
+~~~~~~~~~~~~~~~~~~
+
+If the SoC you use is not based on the ARM Cortex A9 core, skip to the
+:ref:`non-A9-timer <next section>`. In case of SoCs based on the ARM
+Cortex A9 core, the hardware timer is provided by the processor core,
+and not specific to the SoC: the good news is that the timer code has
+already been modified to implement the ``struct ipipe_timer``
+descriptor into the I-pipe core (arch/arm/kernel/smp_twd.c). However,
+you should make sure that the Linux kernel compiles and uses the ARM
+Cortex A9 hardware timer code when compiled for your SoC.
+
+To this end, you should make sure that the ``smp_twd`` timer is
+registered. You should make sure it declares a clock source with a
+*compatible* string containing *twd-timer*.
+
+If the SoC does not use the ``smp_twd`` timer and there is no kernel
+configuration option allowing to select it, you will have to register
+per-cpu timers using :ref:`non-A9-timer <next section>`.
+
+.. NOTE: In some cases, the Linux support code for the Cortex A9 timer
+may give imprecise timer frequency calibration results when I-pipe
+updates are patched in, resulting in early shots. With proper device
+tree support for the board, the proper clock frequency may be
+determined automatically by the driver without resorting to any
+imprecise calibration.
+
+.. _`non-A9-timer`
+The general case
+~~~~~~~~~~~~~~~~
+
+You should look for the hardware timer support code for your SoC.
+Usually, this may be found in drivers/clocksource or
+arch/arm/mach-X/time.c or arch/arm/plat-Y/time.c. Assuming your board
+uses a device tree file, you should look for a device with a
+compatible string containing ``-timer`` and try and find the
+corresponding file in one of the places mentioned above.
+
+Assuming the hardware timer is driven by the ``clock_event_device``
+infrastructure, and provides support for the one-shot mode (the
+``features`` member of the clock_event_device structure contains
+``CLOCK_EVT_FEAT_ONESHOT``), your job will be easy. Otherwise, you
+should find the SoC data-sheet or reference guide containing the
+documentation for the hardware timer registers, and try to find out
+what type it is (decrementer or free-running counter with match
+register), and how to use it in one-shot mode.
+
+You have to decide finally if you choose to share the hardware timer
+used by Linux with the co-kernel, or if you are going to use a
+different hardware timer (some SoC have several hardware timers
+available). As a rule of thumb, it is better to use the same timer.
+
+The ``ipipe_timer`` structure somewhat piggybacks on the
+``clock_event_device`` structure, adding a set of capabilities
+required by co-kernels for receiving high-precision events from the
+timer hardware via the interrupt pipeline. It is defined in
+include/linux/ipipe_tickdev.h contains the following members:
+
+* `int irq`
+
+This is the IRQ number used for the timer interrupt. Providing it is
+mandatory.
+
+* `void (*request)(struct ipipe_timer *timer, int steal)`
+
+This callback is invoked by the I-pipe core when the co-kernel starts
+using the hardware timer. It should set the hardware timer to one-shot
+mode. The ``steal`` parameter is true if the co-kernel is taking
+control over the timer currently in use by Linux.
+
+If the hardware timer support code for Linux uses the
+``clock_event_device`` infrastructure, supports one-shot mode, and the
+I-pipe core is going to use the same timer as Linux, this handler may
+be omitted. In such a case, the I-pipe core is going to call the
+default ``set_mode`` handler defined by the corresponding
+``clock_event_device`` structure.
+
+* `int (*set)(unsigned long ticks, void *timer)`
+
+This handler is called by the I-pipe core each time the co-kernel asks
+for programming the next event into the hardware timer registers. It
+should program the hardware timer to elapse in ``ticks`` in hardware
+time unit.
+
+For instance, if the hardware timer is based on a decrementer, this
+handler should set the decrementer register with the ``ticks``
+value.
+
+If the hardware timer is based on a free-running counter and a match
+register instead, this handler should set the match register to the
+sum of the current value of the free-running counter and the ``ticks``
+parameter.
+
+This function should return 0 upon success or a negative value if the
+delay is too short (in case of a free-running counter and a match
+register, this can be detected by re-reading the free-running counter
+after having programmed the match register, if the free-running
+counter has now passed the match register value, the delay was too
+short, and the programming may have failed).
+
+If the hardware timer support code for Linux uses the
+``clock_event_device`` infrastructure, supports one-shot mode, and the
+I-pipe core is going to use the same timer as Linux, this handler may
+be omitted. In such a case, the I-pipe core is going to call the
+default ``set_next_event`` handler defined by the corresponding
+``clock_event_device`` structure.
+
+.. CAUTION: Care must be taken however that this handler is called
+from co-kernel context, therefore it may neither call any regular
+Linux services, nor hold regular spinlocks. Otherwise, a separate
+handler must be implemented (or if a spinlock has to be held, the
+original spinlock should be turned into an :ref:`hard-spinlocks
+<I-pipe spinlock>`, provided the critical sections being covered by
+such lock are short).
+
+* `void (*ack)(void)`
+
+This handler is called by the I-pipe core upon timer interrupt, and it
+should acknowledge the timer interrupt at hardware timer level. It is
+almost always necessary to provide such handler.
+
+If the hardware timer is shared with Linux, the code implementing the
+proper hardware acknowledge code is generally contained in the Linux
+timer interrupt. This interrupt code should be modified to only
+acknowledge the timer interrupt if the timer is not controlled by the
+co-kernel. See the :ref:`Example <example>` for a way to do this
+avoiding code duplication of the timer acknowledgement code.
+
+* `void (*release)(struct ipipe_timer *timer)`
+
+This handler is called by the I-pipe core when the co-kernel releases
+the hardware timer. It should restore the timer to its state at the
+time when the ``request`` handler was called. For instance, if the
+timer was running in periodic mode, and the ``request`` handler
+switched it to one-shot mode, this handler should turn it back to
+periodic mode.
+
+If the hardware timer support code for Linux uses the
+``clock_event_device`` infrastructure, supports one-shot mode, and the
+I-pipe core is going to use the same timer as Linux, this handler may
+be omitted. In such a case, the I-pipe core is going to call the
+default ``set_mode`` handler defined by the corresponding
+``clock_event_device`` structure.
+
+* `const char *name`
+
+Name of the timer.
+
+If the I-pipe core is going to use the same timer as Linux, this
+setting may be omitted, in which case the name defined by the
+``clock_event_device`` descriptor for such timer will be used.
+
+* `unsigned int rating`
+
+Rating of the timer. If support for several hardware timers is
+provided with different ratings, the one with the highest rating will
+be used by the co-kernel.
+
+If the I-pipe core is going to use the same timer as Linux, this
+setting may be omitted, in which case the rating defined by the
+``clock_event_device`` descriptor for such timer will be used.
+
+* `unsigned long freq`
+
+Frequency of the hardware timer. Usually, this value can be obtained
+from the clock framework (``clk_get_rate()``).
+
+If the I-pipe core is going to use the same timer as Linux, this
+setting may be omitted, in which case the frequency defined by the
+``clock_event_device`` descriptor for such timer will be used.
+
+* `unsigned int min_delay_ticks`
+
+The hardware timer minimum delay as a count of ticks. Almost all timers
+based on free-running counters and match register have a threshold below
+which they can not be programmed. When you program such a timer with a
+too short value, the free-running counter will need to wrap before it
+matches the match register again, so the timer will appear to be stopped
+for a long time, then suddenly restart.
+
+In case when this minimum delay is known as a wallclock delay instead
+of a count of hardware ticks, ``ipipe_timer_ns2ticks()`` can be used
+to convert values, making sure the ``ipipe_timer.freq`` has been set
+prior to that call.
+
+If the I-pipe core is going to use the same timer as Linux, this
+setting may be omitted, in which case the delay defined by the
+``clock_event_device`` descriptor for such timer will be used.
+
+* `const struct cpumask *cpumask`
+
+A cpumask containing the set of cpus where this timer will be run. On
+SMP systems, there should be several ``ipipe_timer`` structures
+defined, each with only one cpu in the ``cpumask`` member.
+
+If the I-pipe core is going to use the same timer as Linux, this
+setting may be omitted, in which case the mask defined by the
+``clock_event_device`` descriptor for such timer will be used.
+
+Once this structure is defined, there are two ways to register it to the
+I-pipe core:
+
+* if the hardware timer support code for Linux uses the
+``clock_event_device`` infrastructure and the I-pipe core is going to
+use the same hardware timer as Linux, the member ``ipipe_timer`` of
+the ``clock_event_device`` descriptor should be set to point at this
+structure, causing an automatic registration of both descriptors when
+``clockevents_register_device()`` is called by the regular kernel
+code.
+
+* otherwise, the ``ipipe_timer_register()`` service should be called
+for registering the descriptor individually.
+
+.. _example:
+Example
+~~~~~~~
+
+As an example, let us look at the OMAP3 code in the I-pipe core.
+Previous to the introduction of the I-pipe bits, the code looked like:
+
+-------------------------------------------------------------------------------
+ static irqreturn_t omap2_gp_timer_interrupt(int irq, void *dev_id)
+ {
+ struct clock_event_device *evt = &clockevent_gpt;
+
+ __omap_dm_timer_write_status(&clkev, OMAP_TIMER_INT_OVERFLOW);
+
+ evt->event_handler(evt);
+ return IRQ_HANDLED;
+ }
+-------------------------------------------------------------------------------
+
+The call to ``__omap_dm_timer_write_status()`` acknowledges the
+interrupt hardware timer level.
+
+-------------------------------------------------------------------------------
+ static struct clock_event_device clockevent_gpt = {
+ .name = "gp timer",
+ .features = CLOCK_EVT_FEAT_PERIODIC | CLOCK_EVT_FEAT_ONESHOT,
+ .shift = 32,
+ .set_next_event = omap2_gp_timer_set_next_event,
+ .set_mode = omap2_gp_timer_set_mode,
+ };
+-------------------------------------------------------------------------------
+
+This shows that the Linux hardware timer support code handles one-shot
+mode, and closer inspection reveals that
+``omap2_gp_timer_set_next_event()`` does not call any Linux service
+which could not be called from out-of-band context. Therefore, this
+implementation can be safely shared with the co-kernel. The I-pipe
+core modifies this code in the following way:
+
+-------------------------------------------------------------------------------
+ static void omap2_gp_timer_ack(void)
+ {
+ __omap_dm_timer_write_status(&clkev, OMAP_TIMER_INT_OVERFLOW);
+ }
+
+ static irqreturn_t omap2_gp_timer_interrupt(int irq, void *dev_id)
+ {
+ struct clock_event_device *evt = &clockevent_gpt;
+
+ if (!clockevent_ipipe_stolen(evt))
+ omap2_gp_timer_ack();
+
+ evt->event_handler(evt);
+ return IRQ_HANDLED;
+ }
+
+ #ifdef CONFIG_IPIPE
+ static struct ipipe_timer omap_shared_itimer = {
+ .ack = omap2_gp_timer_ack,
+ .min_delay_ticks = 3,
+ };
+ #endif /* CONFIG_IPIPE */
+
+ static struct clock_event_device clockevent_gpt = {
+ .features = CLOCK_EVT_FEAT_PERIODIC |
+ CLOCK_EVT_FEAT_ONESHOT,
+ .rating = 300,
+ .set_next_event = omap2_gp_timer_set_next_event,
+ .set_state_shutdown = omap2_gp_timer_shutdown,
+ .set_state_periodic = omap2_gp_timer_set_periodic,
+ .set_state_oneshot = omap2_gp_timer_shutdown,
+ .tick_resume = omap2_gp_timer_shutdown,
+ };
+
+ static void __init omap2_gp_clockevent_init(int gptimer_id,
+ const char *fck_source)
+ {
+ /* ... */
+ #ifdef CONFIG_IPIPE
+ /* ... */
+ omap_shared_itimer.irq = clkev.irq;
+ clockevent_gpt.ipipe_timer = &omap_shared_itimer;
+ /* ... */
+ #endif /* CONFIG_IPIPE */
+
+ clockevents_register_device(&clockevent_gpt);
+
+ /* ... */
+ }
+-------------------------------------------------------------------------------
+
+High resolution counter
+-----------------------
+
+Since the co-kernel timer management is based on a timer running in
+one-shot mode, and in order for applications to be able to measure
+short time intervals, a high resolution counter is needed.
+
+Again, the hardware which can be used for such purposes depends on the
+SoC. Reminiscent from the first Xenomai co-kernel using the I-pipe
+which ran on the x86 processor architecture, this high resolution
+counter is (abusively) called tsc (short for timestamp counter).
+
+As in the case of timer management, a C structure named
+``__ipipe_tscinfo`` must be filled and registered to the I-pipe
+core. You should also ensure that the symbol
+"CONFIG_IPIPE_ARM_KUSER_TSC" gets selected. For instance, in
+arch/arm/mach-socfpga/Kconfig, you may find:
+
+-------------------------------------------------------------------------------
+menuconfig ARCH_SOCFPGA
+ bool "Altera SOCFPGA family"
+ depends on ARCH_MULTI_V7
+ ...
+ select IPIPE_ARM_KUSER_TSC if IPIPE
+-------------------------------------------------------------------------------
+
+.. _`A9-counter`:
+The Cortex A9 case
+~~~~~~~~~~~~~~~~~~
+
+If the SoC you use is not based on the ARM Cortex A9 core, skip to the
+:ref:`non-A9-counter <next section>`. In case of SoCs based on the ARM
+Cortex A9 core, the hardware used as high resolution counter is
+provided by the ARM core (aka "global timer"). Since this hardware is
+not SoC-specific, the existing addition of ``__ipipe_tscinfo`` to
+support the I-pipe (arch/arm/kernel/smp_twd.c) can be reused for all
+A9-based SoCs.
+
+.. _`non-A9-counter`:
+The general case
+~~~~~~~~~~~~~~~~
+
+The ``__ipipe_tscinfo`` C structure, defined in
+arch/arm/include/asm/ipipe.h contains the following members:
+
+* ``unsigned int type``
+
+The type, possible values are:
+
+** ``IPIPE_TSC_TYPE_FREERUNNING``
+
+the tsc is based on a free-running counter
+
+** ``IPIPE_TSC_TYPE_DECREMENTER``
+
+the tsc is based on a decrementer
+
+** ``IPIPE_TSC_TYPE_FREERUNNING_COUNTDOWN``
+
+the tsc is based on a free-running counter, counting down
+
+** ``IPIPE_TSC_TYPE_FREERUNNING_TWICE``
+
+the tsc is based on a free-running counter which needs to be read
+twice (it sometimes returns wrong values, but never twice in a row)
+
+If the hardware you have at hand is not one of these, you need to
+
+** add a define for the type of hardware you have
+(``IPIPE_TSC_TYPE_xxx``)
+
+** add an implementation (in assembly) for reading this counter and
+extending it to a 64 bits value. See arch/arm/kernel/ipipe_tsc_asm.S and
+arch/arm/kernel/ipipe_tsc.c for more details. Note that the assembly
+implementation is limited in size to 96 bytes, or 24 x 32 bits
+instructions.
+
+* ``unsigned int freq``
+
+The counter frequency
+
+* ``unsigned long counter_vaddr``
+
+The virtual address (in kernel-space) of the counter
+
+* ``unsigned long u.counter_paddr``
+
+The physical address of the counter
+
+* ``unsigned long u.mask``
+
+The mask of valid bits in the counter value.
+
+For instance 0xffffffff for a 32 bits counter, or 0xffff for a 16 bits
+counter. Only a limited set of values are supported for each counter
+type. If you need an unsupported value, arch/arm/kernel/ipipe_tsc.c
+and arch/arm/kernel/ipipe_tsc_asm.S must be modified.
+
+Once a variable of type ``__ipipe_tscinfo`` is defined, it can be
+registered to the I-pipe core with ``__ipipe_tsc_register()``.
+
+For instance, in arch/arm/mach-davinci/time.c, we have:
+
+-------------------------------------------------------------------------------
+#ifdef CONFIG_IPIPE
+static struct __ipipe_tscinfo tsc_info = {
+ .type = IPIPE_TSC_TYPE_FREERUNNING,
+ .u = {
+ {
+ .mask = 0xffffffff,
+ },
+ },
+};
+#endif /* CONFIG_IPIPE */
+
+void __init davinci_timer_init(void)
+{
+#ifdef CONFIG_IPIPE
+ tsc_info.freq = davinci_clock_tick_rate;
+ tsc_info.counter_vaddr = (void *)(timers[TID_CLOCKSOURCE].base +
+ timers[TID_CLOCKSOURCE].tim_off);
+ tsc_info.u.counter_paddr = timers[TID_CLOCKSOURCE].pbase +
+ timers[TID_CLOCKSOURCE].tim_off;
+ __ipipe_tsc_register(&tsc_info);
+ /* ... */
+#endif /* CONFIG_IPIPE */
+}
+
+-------------------------------------------------------------------------------
+
+Since the tsc implementation extends the precision of the underlying
+hardware counter to 64 bits, it also needs to be refreshed at a lower
+period than the hardware counter wrap time. This refreshing is done by
+``__ipipe_tsc_update()``, which is called periodically for a
+registered tsc.
+
+If your hardware timer is based on a 16 bits counter,
+``__ipipe_tsc_update()`` should be called in the ``ipipe_timer``'s
+``set()`` handler as well, every time the hardware timer is
+programmed.
+
+.. _`interrupt-controller`:
+Interrupt controller
+--------------------
+
+The I-pipe core interacts with the SoC interrupt controller, for
+implementing the deferred interrupt model. An interrupt is first
+acknowledged and masked at the interrupt controller level, but handled
+then unmasked by the regular Linux IRQ handler only when all
+out-of-band activity is done.
+
+Fortunately, as for timer management, interrupt controllers specifics
+are embedded in the ``irq_chip`` C structure, and interactions with
+them are implemented in a generic way, so almost no modifications need
+to be done in the SoC-specific code. There are a few things to which
+you should pay attention to, though.
+
+As in the case of the timer and high resolution counter, the Cortex A9
+processor core contains an interrupt controller. If your SoC is based
+on the Cortex A9 core, you can skip to :ref:`config-multi-irq-handler
+<the CONFIG_MULTI_IRQ_HANDLER section>`.
+
+Otherwise, you should locate the code for the interrupt controller
+management. Usually, the IRQ controller driver is located in
+drivers/irqchip, arch/arm/mach-X/irq.c or arch/arm/plat-Y/irq.c. As
+for the hardware timer, the irqchip should be registered through the
+device tree, so you should look in the SoC device tree file for a node
+with one of the "compatible" strings passed to the IRQCHIP_DECLARE
+macro in the kernel sources.
+
+IC handlers
+~~~~~~~~~~~
+
+The following handlers defined by the ``irq_chip`` C structure may be
+called from an out-of-band context immediately upon IRQ receipt, so
+they must not call any regular Linux services:
+
+* ``irq_ack``
+* ``irq_mask_ack``
+* ``irq_eoi``
+* ``irq_mask``
+* ``irq_unmask``
+
+In particular, regular Linux spinlocks used in those routines should
+be turned into an :ref:`hard-spinlocks <I-pipe spinlock>`, making sure
+this would not entail unacceptable latencies from other places such
+lock is held.
+
+flow handlers
+~~~~~~~~~~~~~
+
+If the original flow handler for the IRQ is ``handle_fasteoi_irq()``,
+two I-pipe specific IC handlers should be defined by the ``irq_chip``
+descriptor:
+
+* ``irq_hold`` should mask then EOI the interrupt line, i.e. same as
+ calling ``irq_mask`` and ``irq_eoi`` subsequently.
+
+* ``irq_release`` should unmask the interrupt line, i.e. same as
+ calling ``irq_unmask``.
+
+If the flow handler is ``handle_edge_irq()`` and the systems locks up
+when the first interrupt is received, try turning the flow handler to
+``handle_level_irq()`` instead.
+
+.. _`config-multi-irq-handler`:
+CONFIG_MULTI_IRQ_HANDLER
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the SoC you use enables this option, look into the board file
+between the MACHINE_START and MACHINE_END declarations for the
+``handle_irq`` member. The original implementation of this routine
+should be in the interrupt controller file, exhibiting a decoding loop
+of interrupts numbers reading the hardware registers, eventually
+calling ``handle_IRQ`` for each decoded IRQ.
+
+Once again, you must make sure that no regular Linux routine is called
+by this low-level IRQ decoding handler, invoking
+``ipipe_handle_domain_irq`` instead of ``handle_domain_irq``.
+
+Likewise, on SMP systems, calls to ``handle_IPI`` should be replaced
+by a call to ``ipipe_handle_multi_ipi``.
+
+multi-processor systems
+~~~~~~~~~~~~~~~~~~~~~~~
+
+On multi-processor systems, IPIs are mapped to virtual pipelined IRQs
+(aka *virqs*), and the SoC support needs no addition.
+
+.. _GPIOs
+GPIOs
+~~~~~
+
+Most SoCs have GPIOs. In the context of a co-kernel, they are
+interesting for two reasons:
+
+* they may be used by real-time drivers as input or output for
+communicating with external peripherals.
+* they may be used as interrupt sources.
+
+GPIOs in real-time drivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As for hardware timers and interrupt controllers, the specifics of a
+GPIO controller are embedded in a structure, i.e. ``gpio_chip``. The
+definition for the SoC is usually found in one of the files:
+drivers/gpio-X.c, arch/arm/mach-Y/gpio.c, arch/arm/plat-Z/gpio.c.
+
+These handlers are accessible using the regular *gpiolib*
+infrastructure.
+
+For instance, the ``gpio_chip`` descriptor defines a ``get`` handler,
+which is indirectly called from ``gpio_get_value`` for reading out the
+current level for any given pin.
+
+Here again, you must make sure that no regular Linux routine is called
+by GPIO handlers. If this is the case:
+
+* if the implementation of these handlers need to communicate with an
+I2C or SPI chip, the code as it is needs significant changes to be made
+available to real-time drivers, starting with rewriting the driver for
+the I2C or SPI controller as a driver running in real-time domain;
+
+* if the implementation of these handlers simply uses a spinlock, the
+spinlock may be turned into an :ref:`hard-spinlocks <I-pipe spinlock>`
+(pay attention, however, that there is not other Linux service called,
+or actions which may take an unbounded time when holding the
+spinlock).
+
+GPIOs as interrupt sources
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most SoCs have so many GPIOs, that each one can not have a separate
+line at the interrupt controller level, so they are multiplexed. What
+happens then is that there is a single line for a whole GPIO bank, the
+interrupt handler for this irq line should read a GPIO controller
+register to find out which of the GPIOs interrupts are pending, then
+invoke the handler for each of them. The mechanism used by the Linux
+kernel to handle this situation is called "chained interrupts", you
+can find whether the SoC you use in this case if it calls the function
+"irq_set_chained_handler". It is usually found in
+drivers/gpio/gpio-X.c, arch/arm/mach-Y/gpio.c, arch/arm/plat-Z/gpio.c,
+arch/arm/mach-X/irq.c, or arch/arm/plat-Y/irq.c.
+
+What will happen with the I-pipe core, is that the handler registered
+with "irq_set_chained_handler" will be called in real-time context, so
+should not use any Linux service which can not be used from real-time
+context, in particular, calls to "generic_handle_irq", should be
+replaced with calls to "ipipe_handle_demuxed_irq".
+
+When GPIOs are used as interrupt sources, a "struct irq_chip" is
+defined, allowing the kernel to see the GPIOs controller as an
+interrupt controller, so, most of what is said in the
+:ref:`interrupt-controller <"Interrupt controller" section>` also
+applies to the GPIO controller. Most of the time, though, the "flow
+handler" for these interrupts is "handle_simple_irq", and nothing
+needs to be done.
+
+.. _`hard-spinlocks`
+I-pipe spinlocks
+----------------
+
+Occasionally, some spinlocks need to be shared between the real-time and
+Linux domains. We have talked about this in the
+:ref:`hardware-timer <"Hardware timer">`,
+:ref:`interrupt-controller <"Interrupt controller">` and
+:ref:`GPIOs <"GPIOs">` sections.
+
+However, beware, this is not a panacea: calling a regular kernel
+routine while holding this spinlock may end up in a train wreck for
+the system, at the very least cause the response time skyrocket for
+the co-kernel applications.
+
+The I-pipe provides macros to turn a regular or raw kernel spinlock
+definitions into I-pipe hard spinlocks, and others to declare the
+latter.
+
+[cols=",",]
+|==============================================================
+|Linux code |Should be replaced with
+|``extern raw_spinlock_t foo`` |``IPIPE_DECLARE_RAW_SPINLOCK(foo)``
+|``DEFINE_RAW_SPINLOCK(foo)`` |``IPIPE_DEFINE_RAW_SPINLOCK(foo)``
+|``extern spinlock_t foo`` |``IPIPE_DECLARE_SPINLOCK(foo)``
+|``DEFINE_SPINLOCK(foo)`` |``IPIPE_DEFINE_SPINLOCK(foo)``
+|==============================================================
+
+For instance, in arch/arm/mm/context.c
+
+-------------------------------------------------------------------------------
+ static DEFINE_RAW_SPINLOCK(cpu_asid_lock);
+-------------------------------------------------------------------------------
+
+is replaced with:
+
+-------------------------------------------------------------------------------
+ static IPIPE_DEFINE_RAW_SPINLOCK(cpu_asid_lock);
+-------------------------------------------------------------------------------
+
+In addition to the usual ``spin_lock()``, ``spin_unlock()``,
+``spin_lock_irqsave()`` and ``spin_unlock_irqrestore()`` routines, the
+I-pipe core provides the ``spin_lock_irqsave_cond()``,
+``spin_unlock_irqrestore_cond()``.
+
+These services are replaced with their ``spin_lock_irqsave()`` /
+``spin_unlock_irqrestore()`` counterparts when compiling the Linux
+kernel with the I-pipe core enabled, and replaced with ``spin_lock()``
+/ ``spin_unlock()`` otherwise.
+
+This is useful for protecting a critical section of the regular kernel
+code against preemption from out-of-band IRQ handlers.
+
+[[troubleshooting]]
+Troubleshooting
+---------------
+
+When you have modified the I-pipe core for supporting your board, try:
+
+* to boot the kernel for your board compiled without CONFIG_IPIPE
+enabled
+* boot the kernel for your board compiled with CONFIG_IPIPE enabled but
+without the co-kernel (e.g. disable CONFIG_XENOMAI).
+* boot the kernel for your board compiles with CONFIG_IPIPE and
+the co-kernel (e.g. enable CONFIG_XENOMAI).
+* run the latency test
+
+If any of this step does not work correctly, do not go further, try and
+debug the said step first.
+
+Common issues include:
+
+[[the-kernel-stops-after-the-message-uncompressing-linux]]
+The kernel stops after the message "Uncompressing Linux... done, booting the kernel."
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The screen remains blank, nothing happens. It means that the kernel has
+a oops, or lock-up early during the boot process. In order to understand
+what happens:
+
+* enable CONFIG_DEBUG_LL and CONFIG_EARLY_PRINTK in the kernel
+configuration, recompile the kernel.
+
+.. CAUTION: make sure to configure the debug UART properly, otherwise
+ this may crash the kernel in the early boot stage.
+
+* add "earlyprintk" to the kernel parameters
+
+The kernel messages should then be displayed immediately, allowing to
+figure out at what point in the boot process the kernel crashes or
+locks up.
+
+[[the-kernel-stops-after-the-message-calibrating-delay-loop]]
+The kernel stops after the message "Calibrating delay loop..."
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It means that the timer interrupt is not ticking and that the delay
+calibration routine is running an infinite loop at ``while (ticks ==
+jiffies)`` in the function ``calibrate_delay()``, file
+init/calibrate.c
+
+This probably means that changes you made to the hardware timer support
+or interrupt controller code broke something. To help debugging this
+situation, you can print any hardware timer or interrupt controller
+register in the ``while (ticks == jiffies)`` loop.
+
+[[timer-issues]]
+Timer issues
+~~~~~~~~~~~~
+
+Most issues when porting the I-pipe core to a new ARM SoC are timer
+issues, the timer is the hardest part to get right.
+
+When you boot the kernel without CONFIG_IPIPE, the timer code should
+be almost not modified, except maybe for timer acknowledgement. If at
+this point the kernel does not work, it probably means that you got
+the timer acknowledgement wrong.
+
+When you boot the kernel with CONFIG_IPIPE, but without enabling the
+co-kernel (e.g. CONFIG_XENOMAI), the hardware timer remains controlled
+by the Linux kernel. If at this point the kernel does not work, it
+probably means that something else than the timer is wrong, most
+likely in the interrupt controller support code.
+
+When you boot the dual kernel system, the co-kernel usually takes
+control over the hardware timer, invoking the ``struct ipipe_timer``
+:ref:`non-A9-timer <handlers>` for processing a regular Linux timer
+tick. If at this point the kernel does not work, it probably means
+that some of those handlers are wrong.
+
+Finally, only when running some co-kernel application like a latency
+measurement test, the timer is eventually used to activate co-kernel
+threads in the real-time domain. You should check that the latency
+test prints a message every second, if it does not, it probably means
+that the timer frequency is wrong, but in accordance with the tsc
+frequency.
+
+A *drift* in the minimum and maximum latency values indicates a
+mismatch between the timer and the tsc frequency. Unacceptably large
+latency values is likely caused by a section of code running for too
+long with interrupts masked, or some issue caused by the idle loop.
diff --git a/Documentation/ipipe.rst b/Documentation/ipipe.rst
new file mode 100644
index 000000000000..9fba08b66253
--- /dev/null
+++ b/Documentation/ipipe.rst
@@ -0,0 +1,924 @@
+.. include:: <isonum.txt>
+
+===================================
+The Interrupt Pipeline (aka I-pipe)
+===================================
+
+:Copyright: |copy| 2018: Philippe Gerum
+
+Purpose
+=======
+
+Using Linux as a host for lightweight software cores specialized in
+delivering very short and bounded response times has been a popular
+way of supporting real-time applications in the embedded space over
+the years.
+
+This design - known as the *dual kernel* approach - introduces a small
+real-time infrastructure which schedules time-critical activities
+independently from the main kernel. Application threads co-managed by
+this infrastructure still benefit from the ancillary kernel services
+such as virtual memory management, and can also leverage the rich GPOS
+feature set Linux provides such as networking, data storage or GUIs.
+
+Although the real-time infrastructure has to present specific driver
+stack and API implementations to applications, there are nonetheless
+significant upsides to keeping the real-time core separate from the
+GPOS infrastructure:
+
+- because the two kernels are independent, real-time activities are
+ not serialized with GPOS operations internally, removing potential
+ delays which might be induced by the non time-critical
+ work. Likewise, there is no requirement for keeping the GPOS
+ operations fine-grained and highly preemptible at any time, which
+ would otherwise induce noticeable overhead on low-end hardware, due
+ to the requirement for pervasive task priority inheritance and IRQ
+ threading.
+
+- the functional isolation of the real-time infrastructure from the
+ rest of the kernel code restricts common bug hunting to the scope of
+ the smaller kernel, excluding most interactions with the very large
+ GPOS kernel base.
+
+- with a dedicated infrastructure providing a specific, well-defined
+ set of real-time services, applications can unambiguously figure out
+ which API calls are available for supporting time-critical work,
+ excluding all the rest as being potentially non-deterministic with
+ respect to response time.
+
+To support such a *dual kernel system*, we need the kernel to exhibit
+a high-priority execution context, for running out-of-band real-time
+duties concurrently to the regular operations.
+
+.. NOTE:: The I-pipe only introduces the basic mechanisms for hosting
+such a real-time core, enabling the common programming model for its
+applications in user-space. It does *not* implement the real-time core
+per se, which should be provided by a separate kernel component.
+
+The issue of interrupt response time
+====================================
+
+The real-time core has to act upon device interrupts with no delay,
+regardless of the regular kernel operations which may be ongoing when
+the interrupt is received by the CPU.
+
+However, to protect from deadlocks and maintain data integrity, Linux
+normally hard disables interrupts around any critical section of code
+which must not be preempted by interrupt handlers on the same CPU,
+enforcing a strictly serialized execution among those contexts.
+
+The unpredictable delay this may cause before external events can be
+handled is a major roadblock for kernel components requiring
+predictable and very short response times to external events, in the
+range of a few microseconds.
+
+Therefore, there is a basic requirement for prioritizing interrupt
+masking and delivery between the real-time core and GPOS operations,
+while maintaining consistent internal serialization for the kernel.
+
+To address this issue, the I-pipe implements a mechanism called
+*interrupt pipelining* turns all device IRQs into NMIs, only to run
+NMI-safe interrupt handlers from the perspective of the regular kernel
+activities.
+
+Two-stage IRQ pipeline
+======================
+
+.. _pipeline
+Interrupt pipelining is a lightweight approach based on the
+introduction of a separate, high-priority execution stage for running
+out-of-band interrupt handlers immediately upon IRQ receipt, which
+cannot be delayed by the in-band, regular kernel work even if the
+latter serializes the execution by - seemingly - disabling interrupts.
+
+IRQs which have no handlers in the high priority stage may be deferred
+on the receiving CPU until the out-of-band activity has quiesced on
+that CPU. Eventually, the preempted in-band code can resume normally,
+which may involve handling the deferred interrupts.
+
+In other words, interrupts are flowing down from the out-of-band to
+the in-band interrupt stages, which form a two-stage pipeline for
+prioritizing interrupt delivery.
+
+The runtime context of the out-of-band interrupt handlers is known as
+the *head stage* of the pipeline, as opposed to the in-band kernel
+activities sitting on the *root stage*::
+
+ Out-of-band In-band
+ IRQ handlers() IRQ handlers()
+ __________ _______________________ ______
+ . / / . . / / .
+ . / / . . / / .
+ . / / . . / / .
+ ___/ /______________________/ / .
+ [IRQ] -----> _______________________________/ .
+ . . . .
+ . Head . . Root .
+ . Stage . . Stage .
+ _____________________________________________
+
+
+A software core may base its own activities on the head stage,
+interposing on specific IRQ events, for delivering real-time
+capabilities to a particular set of applications. Meanwhile, the
+regular kernel operations keep going over the root stage unaffected,
+only delayed by short preemption times for running the out-of-band
+work.
+
+.. NOTE:: Interrupt pipelining is a partial implementation of [#f2]_,
+ in which an interrupt *stage* is a limited form of an
+ operating system *domain*.
+
+Virtual interrupt flag
+----------------------
+
+.. _flag:
+As hinted earlier, predictable response time of out-of-band handlers
+to IRQ receipts requires the in-band kernel work not to be allowed to
+delay them by masking interrupts in the CPU.
+
+However, critical sections delimited this way by the in-band code must
+still be enforced for the *root stage*, so that system integrity is
+not at risk. This means that although out-of-band IRQ handlers may run
+at any time while the *head stage* is accepting interrupts, in-band
+IRQ handlers should be allowed to run only when the root stage is
+accepting interrupts too.
+
+So we need to decouple the interrupt masking and delivery logic which
+applies to the head stage from the one in effect on the root stage, by
+implementing a dual interrupt control mechanism.
+
+To this end, a software logic managing a virtual interrupt flag (aka
+*IPIPE_STALL_FLAG*) is introduced by the interrupt pipeline between
+the hardware and the generic IRQ management layer. This logic can mask
+IRQs from the perspective of the regular kernel work when
+:c:func:`local_irq_save`, :c:func:`local_irq_disable` or any