1 | /* |
---|
2 | * dev_pic.h - PIC (Programmable Interrupt Controler) generic device API definition. |
---|
3 | * |
---|
4 | * Authors Alain Greiner (2016) |
---|
5 | * |
---|
6 | * Copyright (c) UPMC Sorbonne Universites |
---|
7 | * |
---|
8 | * This file is part of ALMOS-MKH. |
---|
9 | * |
---|
10 | * ALMOS-MKH is free software; you can redistribute it and/or modify it |
---|
11 | * under the terms of the GNU General Public License as published by |
---|
12 | * the Free Software Foundation; version 2.0 of the License. |
---|
13 | * |
---|
14 | * ALMOS-MKH is distributed in the hope that it will be useful, but |
---|
15 | * WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
---|
17 | * General Public License for more details. |
---|
18 | * |
---|
19 | * You should have received a copy of the GNU General Public License |
---|
20 | * along with ALMOS-MKH; if not, write to the Free Software Foundation, |
---|
21 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA |
---|
22 | */ |
---|
23 | |
---|
24 | #ifndef _DEV_PIC_H_ |
---|
25 | #define _DEV_PIC_H_ |
---|
26 | |
---|
27 | #include <kernel_config.h> |
---|
28 | #include <hal_types.h> |
---|
29 | |
---|
30 | /***************************************************************************************** |
---|
31 | * Generic Programmable Interrupt Controler definition |
---|
32 | * |
---|
33 | * The PIC generic device describes the the programmable hardware infrastructure used |
---|
34 | * to route a given IRQ to a given core, in a given cluster, and to help the interrupt |
---|
35 | * handler to select and execute the relevant ISR (Interrupt Service Routine). |
---|
36 | * It handles the following type of interrupts: |
---|
37 | * - External IRQs generated by the external (shared) peripherals. |
---|
38 | * - Internal IRQs generated by the internal (replicated) peripherals. |
---|
39 | * - Timer IRQs generated by the timers (one timer per core). |
---|
40 | * - Inter Processor IRQs (IPI) generated by software. |
---|
41 | * |
---|
42 | * In most supported manycores architectures, the PIC device contains two types |
---|
43 | * of hardware components: |
---|
44 | * - the IOPIC is an external component, handling all external peripherals IRQs. |
---|
45 | * - The LAPIC is an internal component, replicated in each cluster, handling local |
---|
46 | * peripherals IRQS, Timer IRQs and IPIs (inter-processor-interupts). |
---|
47 | * |
---|
48 | * The "source" device for each input IRQ to the external IOPIC component, is defined |
---|
49 | * in the "arch_info" file, and registered in the "iopic_input" global variable |
---|
50 | * at kernel initialization. |
---|
51 | * |
---|
52 | * The "source" device for each input IRQ to the replicated LAPIC components, is defined |
---|
53 | * in the "arch_info" file, and stored in the "lapic_input" global variable |
---|
54 | * at kernel initialization. |
---|
55 | * |
---|
56 | * The PIC device defines 4 generic commands that can be used by each kernel instance, |
---|
57 | * - to create in local cluster the PIC implementation specific interupt vector(s), |
---|
58 | * - to bind a given IRQ (internal or external IRQ to a given core in the local cluster, |
---|
59 | * - to configure and activate the TICK timer for a given core in the local cluster, |
---|
60 | * - to allows the software to send an IPI to any core in any cluster. |
---|
61 | * This API is detailed below, and must be implemented by all PIC implementations. |
---|
62 | * |
---|
63 | * In each cluster, a PIC implementation specific structure can be linked to the |
---|
64 | * cluster manager or to the core descriptors to register the interrupt vectors |
---|
65 | * used by the kernel to select the relevant ISR when an interrupt is received |
---|
66 | * by a given core in agiven cluster. |
---|
67 | |
---|
68 | * This PIC device does not execute itself I/O operations. It is just acting as a |
---|
69 | * configurable interrupt router for I/O operation executed by other peripherals. |
---|
70 | * Therefore, ALMOS-MKH does not use the PIC device waiting queue, does not creates |
---|
71 | * a server thread for the PIC device, and does not register the command in the calling |
---|
72 | * thread descriptor, but call directly the relevant driver function. |
---|
73 | ****************************************************************************************/ |
---|
74 | |
---|
75 | /**** Forward declarations ****/ |
---|
76 | |
---|
77 | struct chdev_s; |
---|
78 | |
---|
79 | /***************************************************************************************** |
---|
80 | * This defines the specific extension for the PIC chdev descriptor. |
---|
81 | * It contains four function pointers on the four PIC command types, |
---|
82 | * that must be implemented by all drivers. |
---|
83 | ****************************************************************************************/ |
---|
84 | |
---|
85 | typedef void (pic_bind_t) ( lid_t lid , struct chdev_s * src_chdev ); |
---|
86 | typedef void (pic_enable_t) ( lid_t lid , struct chdev_s * src_chdev ); |
---|
87 | typedef void (pic_disable_t) ( lid_t lid , struct chdev_s * src_chdev ); |
---|
88 | typedef void (pic_timer_t) ( uint32_t period ); |
---|
89 | typedef void (pic_ipi_t) ( cxy_t cxy , lid_t lid ); |
---|
90 | typedef void (pic_init_t) ( uint32_t * lapic_base ); |
---|
91 | |
---|
92 | typedef struct pic_extend_s |
---|
93 | { |
---|
94 | pic_bind_t * bind_irq; /*! pointer on the driver "bind_irq" function */ |
---|
95 | pic_enable_t * enable_irq; /*! pointer on the driver "enable_irq" function */ |
---|
96 | pic_disable_t * disable_irq; /*! pointer on the driver "disable_irq" function */ |
---|
97 | pic_timer_t * enable_timer; /*! pointer on the driver "enable_timer" function */ |
---|
98 | pic_ipi_t * send_ipi; /*! pointer on the driver "send_ipi" function */ |
---|
99 | pic_init_t * extend_init; /*! pointer on the driver "init_extend" function */ |
---|
100 | } |
---|
101 | pic_extend_t; |
---|
102 | |
---|
103 | /****************************************************************************************** |
---|
104 | * This structure defines the input IRQS for the external IOPIC controller, that is used |
---|
105 | * by external peripherals (IOC, NIC, TXT, etc.) to signal completion of an I/O operation. |
---|
106 | * It describes the hardware wiring of IRQs between external peripherals and the IOPIC, |
---|
107 | * as each entry contains the input IRQ index in IOPIC. |
---|
108 | * For a multi-channels peripheral, there is one chdev and one IRQ per channel. |
---|
109 | * This structure is replicated in each cluster. It is allocated as a global variable |
---|
110 | * in the kernel_init.c file. |
---|
111 | *****************************************************************************************/ |
---|
112 | |
---|
113 | typedef struct iopic_input_s |
---|
114 | { |
---|
115 | uint32_t txt[CONFIG_MAX_TXT_CHANNELS]; |
---|
116 | uint32_t ioc[CONFIG_MAX_IOC_CHANNELS]; |
---|
117 | uint32_t nic_rx[CONFIG_MAX_NIC_CHANNELS]; |
---|
118 | uint32_t nic_tx[CONFIG_MAX_NIC_CHANNELS]; |
---|
119 | uint32_t iob; |
---|
120 | } |
---|
121 | iopic_input_t; |
---|
122 | |
---|
123 | /****************************************************************************************** |
---|
124 | * This structure defines the input IRQS for the internal LAPIC controllers, that are used |
---|
125 | * by internal peripherals IRQS (DMA, MMC) to signal completion of an I/O operation. |
---|
126 | * It describes the hardware wiring of IRQs between internal peripherals and ICU, |
---|
127 | * as each entry contains the input IRQ index in the LAPIC component. |
---|
128 | * For a multi-channels peripheral, there is one chdev and one IRQ per channel. |
---|
129 | * This structure is replicated in each cluster. It is allocated as a global variable |
---|
130 | * in the kernel_init.c file. |
---|
131 | *****************************************************************************************/ |
---|
132 | |
---|
133 | typedef struct lapic_input_s |
---|
134 | { |
---|
135 | uint32_t dma[CONFIG_MAX_DMA_CHANNELS]; |
---|
136 | uint32_t mmc; // MMC is single channel |
---|
137 | } |
---|
138 | lapic_input_t; |
---|
139 | |
---|
140 | /***************************************************************************************** |
---|
141 | * This enum defines the various implementations of the PIC device. |
---|
142 | * This array must be kept consistent with the define in arch_info.h file |
---|
143 | ****************************************************************************************/ |
---|
144 | |
---|
145 | enum pic_impl_e |
---|
146 | { |
---|
147 | IMPL_PIC_SCL = 0, |
---|
148 | IMPL_PIC_I86 = 1, |
---|
149 | } |
---|
150 | pic_impl_t; |
---|
151 | |
---|
152 | /***************************************************************************************** |
---|
153 | * This function makes two initialisations : |
---|
154 | * - It initializes the PIC specific fields of the chdev descriptor. |
---|
155 | * - it initializes the implementation specific PIC hardware registers. |
---|
156 | * It is executed once in cluster containing the PIC chdev, during kernel initialisation. |
---|
157 | * The calling core goes to sleep in case of failure. |
---|
158 | ***************************************************************************************** |
---|
159 | * @ pic : local pointer on PIC device descriptor. |
---|
160 | ****************************************************************************************/ |
---|
161 | void dev_pic_init( struct chdev_s * pic ); |
---|
162 | |
---|
163 | /***************************************************************************************** |
---|
164 | * This function completes the PIC infrastructure initialisation in each cluster. |
---|
165 | * It allocates memory for the local PIC extensions in the core descriptors and/or |
---|
166 | * in the cluster manager, as required by the specific PIC implementation. |
---|
167 | * This function is called by CPO in all clusters, during kernel initialisation phase. |
---|
168 | * The calling core goes to sleep in case of failure. |
---|
169 | ***************************************************************************************** |
---|
170 | * @ lapic_base : local pointer on LAPIC component segment base. |
---|
171 | ****************************************************************************************/ |
---|
172 | void dev_pic_extend_init( uint32_t * lapic_base ); |
---|
173 | |
---|
174 | /***************************************************************************************** |
---|
175 | * This function configure the PIC device to route the IRQ generated by a local chdev, |
---|
176 | * defined by the <src_chdev> argument, to a local core identified by the <lid> argument. |
---|
177 | * This is a static binding, defined during kernel init: IRQ can be enabled/disabled, |
---|
178 | * but the binding cannot be released. It can be used for both internal & external IRQs. |
---|
179 | * WARNING : the IRQ must be explicitely enabled by the dev_pic_enable_irq() function. |
---|
180 | ***************************************************************************************** |
---|
181 | * @ lid : target core local index. |
---|
182 | * @ src_chdev : local pointer on source chdev descriptor. |
---|
183 | ****************************************************************************************/ |
---|
184 | void dev_pic_bind_irq( lid_t lid, |
---|
185 | struct chdev_s * src_chdev ); |
---|
186 | |
---|
187 | /***************************************************************************************** |
---|
188 | * This function disables the IRQ generated by a local chdev, defined by the <src_chdev> |
---|
189 | * argument. It can be used for both internal & external IRQs. |
---|
190 | ***************************************************************************************** |
---|
191 | * @ lid : target core local index. |
---|
192 | * @ src_chdev : local pointer on source chdev descriptor. |
---|
193 | ****************************************************************************************/ |
---|
194 | void dev_pic_disable_irq( lid_t lid, |
---|
195 | struct chdev_s * src_chdev ); |
---|
196 | |
---|
197 | /***************************************************************************************** |
---|
198 | * This function enables the IRQ generated by a local chdev, defined by the <src_chdev> |
---|
199 | * argument. It can be used for both internal & external IRQs. |
---|
200 | ***************************************************************************************** |
---|
201 | * @ lid : target core local index. |
---|
202 | * @ src_chdev : local pointer on source chdev descriptor. |
---|
203 | ****************************************************************************************/ |
---|
204 | void dev_pic_enable_irq( lid_t lid, |
---|
205 | struct chdev_s * src_chdev ); |
---|
206 | |
---|
207 | /***************************************************************************************** |
---|
208 | * This function activates the TICK timer for the calling core. |
---|
209 | * The <period> argument define the number of cycles between IRQs. |
---|
210 | ***************************************************************************************** |
---|
211 | * @ period : number of cycles between IRQs. |
---|
212 | ****************************************************************************************/ |
---|
213 | void dev_pic_enable_timer( uint32_t period ); |
---|
214 | |
---|
215 | /***************************************************************************************** |
---|
216 | * This function allows the calling thread to send an IPI to any core in any cluster. |
---|
217 | * The target core is identified by the <cxy> & <lid> arguments. |
---|
218 | ***************************************************************************************** |
---|
219 | * @ cxy : target core cluster. |
---|
220 | * @ lid : target core local index. |
---|
221 | ****************************************************************************************/ |
---|
222 | void dev_pic_send_ipi( cxy_t cxy, |
---|
223 | lid_t lid ); |
---|
224 | |
---|
225 | |
---|
226 | #endif /* _DEV_PIC_H_ */ |
---|