source: trunk/kernel/devices/dev_pic.h @ 193

Last change on this file since 193 was 188, checked in by alain, 7 years ago

Redefine the PIC device API.

File size: 11.8 KB
Line 
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
77struct 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
85typedef void   (pic_bind_t)    ( lid_t lid , struct chdev_s * src_chdev );   
86typedef void   (pic_enable_t)  ( struct chdev_s * src_chdev );   
87typedef void   (pic_disable_t) ( struct chdev_s * src_chdev );   
88typedef void   (pic_timer_t)   ( uint32_t period );   
89typedef void   (pic_ipi_t)     ( cxy_t cxy , lid_t lid ); 
90typedef void   (pic_init_t)    ( uint32_t * lapic_base ); 
91 
92typedef 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}
101pic_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
113typedef 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}
121iopic_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
133typedef struct lapic_input_s
134{
135    uint32_t   dma[CONFIG_MAX_DMA_CHANNELS];
136    uint32_t   mmc;                             // MMC is single channel
137}
138lapic_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
145enum pic_impl_e
146{
147    IMPL_PIC_SCL =   0,     
148    IMPL_PIC_I86 =   1,
149}
150pic_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 ****************************************************************************************/
161void 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 ****************************************************************************************/
172void 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 ****************************************************************************************/
184void 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 ****************************************************************************************/
194void 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 ****************************************************************************************/
204void 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 ****************************************************************************************/
213void 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 ****************************************************************************************/
222void dev_pic_send_ipi( cxy_t  cxy,
223                       lid_t  lid );
224
225
226#endif  /* _DEV_PIC_H_ */
Note: See TracBrowser for help on using the repository browser.