source: trunk/kernel/kern/device.h @ 4

Last change on this file since 4 was 1, checked in by alain, 8 years ago

First import
File size: 11.3 KB
Line 
1/*
2 * device.h - kernel definition of a device
3 *
4 * Authors  Ghassan Almaless (2008,2009,2010,2011,2012)
5 *          Mohamed Karaoui  (2015)
6 *          Alain Greiner    (2016)
7 *
8 * Copyright (c) UPMC Sorbonne Universites
9 *
10 * This file is part of ALMOS-MKH
11 *
12 * ALMOS-MKH is free software; you can redistribute it and/or modify it
13 * under the terms of the GNU General Public License as published by
14 * the Free Software Foundation; version 2.0 of the License.
15 *
16 * ALMOS-MKH is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
23 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24 */
25
26#ifndef _DEVICE_H_
27#define _DEVICE_H_
28
29#include <almos_config.h>
30#include <hal_types.h>
31#include <xlist.h>
32#include <metafs.h>
33#include <remote_spinlock.h>
34#include <dev_ioc.h>
35#include <dev_nic.h>
36#include <dev_icu.h>
37#include <dev_pic.h>
38
39/****  Forward declarations  ****/
40
41struct  device_s;
42struct  thread_s;
43struct  boot_info_s;
44
45/******************************************************************************************
46 * These macros extract the functionality and the implementation from the peripheral type.
47 *****************************************************************************************/
48 
49#define FUNC_FROM_TYPE( type )    ((uint32_t)(type>>16))
50#define IMPL_FROM_TYPE( type )    ((uint32_t)(type & 0x0000FFFF))
51
52/******************************************************************************************
53 * This define the generic prototypes for the three functions that must be defined
54 * by all drivers :
55 * - "init"    : device initialisation.
56 * - "command" : start an I/O operation.
57 * - "isr"     : complete an I/O operation.
58 * The "init" function is called by kernel_init() to initialise the hardware device.
59 * The "cmd" and "isr" are registered in the generic device descriptor by kernel_init(),
60 * and are called to start and complete an I/O operation. 
61*****************************************************************************************/
62
63typedef void (dev_ini_t) ( xptr_t dev );     
64typedef void (dev_cmd_t) ( xptr_t thread ); 
65typedef void (dev_isr_t) ( struct device_s * dev ); 
66
67/******************************************************************************************
68 * This enum defines the supported generic device types.
69 * These types are functionnal types: all (architecture specific) implementations
70 * provide the same set of operations and the same driver API.
71 * This enum must be kept consistent with the enum in arch_info.h file
72 *****************************************************************************************/
73 
74enum dev_func_type
75{
76        DEV_FUNC_RAM   =  0,     /*! Random Access Memory                                    */
77        DEV_FUNC_ROM   =  1,     /*! Read Only Memory                                        */
78        DEV_FUNC_TXT   =  2,     /*! Text Terminal Controler                                 */
79    DEV_FUNC_FBF   =  3,     /*! Frame Buffer Controler                                  */
80    DEV_FUNC_IOB   =  4,     /*! I/O Bridge Component                                    */
81        DEV_FUNC_IOC   =  5,     /*! Block Device Controler                                  */
82        DEV_FUNC_MMC   =  6,     /*! L2 cache Configuration                                  */
83        DEV_FUNC_MWR   =  7,     /*! Hardware coprocessor                                    */
84        DEV_FUNC_NIC   =  8,     /*! GMII Network Interface Controler                        */
85        DEV_FUNC_CMA   =  9,     /*! Chained buffers DMA Controler                           */
86        DEV_FUNC_ICU   = 10,     /*! Interrupt Controler Unit                                */
87        DEV_FUNC_PIC   = 11,     /*! HWI to WTI translator                                   */
88
89    DEV_FUNC_NR    = 12,
90};
91
92/******************************************************************************************
93 * This structure defines a device descriptor.
94 * There is one device descriptor per peripheral channel.
95 * This structure is NOT replicated, and can be located in any cluster.
96 * One kernel thread, in charge of handling the commands registered in the waiting queue
97 * of client threads is associated to each device descriptor.
98 * The device specific extensions are defined in the relevant device file.
99 *****************************************************************************************/
100
101typedef struct device_s
102{
103        uint32_t             func;        /*! peripheral functionnal type                    */
104        uint32_t             impl;        /*! peripheral inplementation subtype              */
105    uint32_t             channel;     /*! channel index                                  */
106    bool_t               is_rx;       /*! relevant for NIC peripheral channels only      */
107        xptr_t               base;        /*! extended pointer on channel segment            */
108    uint32_t             size;        /*! channel_segment size                           */
109
110    dev_cmd_t          * cmd;         /*! local pointer on driver command function       */
111    dev_isr_t          * isr;         /*! local pointer on driver ISR function           */ 
112    struct thread_s    * server;      /*! local pointer on associated server thread      */
113
114    uint32_t             irq_type;    /*! associated IRQ type in local ICU               */
115    uint32_t             irq_id;      /*! associated IRQ index in local ICU              */
116
117    metafs_t             node;        /*! Metafs node associated with this device        */
118        char                 name[16];    /*! device name in file system                     */
119
120        remote_spinlock_t    wait_lock;   /*! lock protecting exclusive access to queue      */
121    xlist_entry_t        wait_root;   /*! root of waiting threads queue                  */
122
123    union
124    {
125        ioc_extend_t     ioc;         /*! IOC specific extension                         */
126        nic_extend_t     nic;         /*! NIC specific extension                         */
127        icu_extend_t     icu;         /*! ICU specific extension                         */
128        pic_extend_t     pic;         /*! PIC specific extension                         */
129    } 
130    ext;
131}
132device_t;
133
134/******************************************************************************************
135 * This structure defines the devices descriptors directory.
136 * Each entry in this structure contains an extended pointers on a device descriptor.
137 * There is one entry per channel for an external peripheral.
138 * There is one entry per cluster for an internal peripheral.
139 * This structure exists in each cluster, and is initialised during kernel init.
140 * It is used for fast access to a device descriptor, from type and channel for an
141 * external peripheral, or from type and cluster for an internal peripheral.
142 *****************************************************************************************/
143
144typedef struct devices_directory_s
145{
146    xptr_t   txt[CONFIG_MAX_TXT_CHANNELS];
147    xptr_t   ioc;
148    xptr_t   nic_rx[CONFIG_MAX_NIC_CHANNELS];
149    xptr_t   nic_tx[CONFIG_MAX_NIC_CHANNELS];
150    xptr_t   pic;
151    xptr_t   iob;
152    xptr_t   icu[CONFIG_MAX_CLUSTERS];
153    xptr_t   mmc[CONFIG_MAX_CLUSTERS];
154    xptr_t   mwr[CONFIG_MAX_CLUSTERS];
155}
156devices_directory_t;
157
158/******************************************************************************************
159 * This structure defines the input IRQS for the PIC and ICU devices.
160 * External peripherals IRQS (IOC, TXT, NIC) are connected to the PIC component, while
161 * internal peripherals IRQs (MMC, MWR) are connected to the local ICU component.
162 * Each entry in this structure contains the input IRQ index in PIC or ICU.
163 * Value is -1 if the IRQ for a peripheral channel is not connected.
164 * There is one entry per channel for an external peripheral.
165 * There is one entry per cluster for an internal peripheral.
166 * This structure exists in each cluster, and is initialised during kernel init.
167 * It is mainly used for fast PIC configuration when the kernel start a new I/O
168 * operation to an external peripheral, as it gives the IRQ index from type and channel.
169 *****************************************************************************************/
170
171typedef struct devices_input_irq_s
172{
173    uint32_t   txt[CONFIG_MAX_TXT_CHANNELS];
174    uint32_t   ioc;
175    uint32_t   nic_rx[CONFIG_MAX_NIC_CHANNELS];
176    uint32_t   nic_tx[CONFIG_MAX_CMA_CHANNELS];
177    uint32_t   mmc[CONFIG_MAX_CLUSTERS];
178    uint32_t   mwr[CONFIG_MAX_CLUSTERS];
179}
180devices_input_irq_t;
181
182
183
184/******************************************************************************************
185 * This  function allocates memory for a device descriptor.
186 * - For a local (replicated) peripheral it allocates memory in local cluster.
187 * - For an external peripheral, it uses the global variable "device_alloc_index"
188 *   to select a remote cluster and send a RPC to make the allocation.
189 * In both cases it returns an extended pointer on the device descriptor.
190 ******************************************************************************************
191 * @ info       : pointer on local boot_info structure.
192 * @ is_local   : local (replicated) peripheral.
193 * @ returns an extended pointer on device if success / returns XPTR_NUL if error.
194 *****************************************************************************************/
195xptr_t device_alloc( struct boot_info_s * info,
196                     bool_t               is_local );
197
198/******************************************************************************************
199 * This  function initialises the basic fields from arguments values.
200 * The device specific fields are initialised later.
201 * It uses remote_write accesses, and can be called in any cluster.
202 ******************************************************************************************
203 * @ dev       : extended pointer to device descriptor.
204 * @ func      : functionnal type.
205 * @ impl      : implementation type.
206 * @ channel   : channel index / for multi-channels peripherals.
207 * @ is_rx     : for NIC peripheral / NIC RX if true / NIC TX if false.
208 * @ base      : extended pointer on channel segment base.
209 * @ size      : channel segment size (bytes).
210 *****************************************************************************************/
211void device_init( xptr_t      dev,
212                  uint32_t    func,
213                  uint32_t    impl,
214                  uint32_t    channel,
215                  bool_t      is_rx,
216                  xptr_t      base,
217                  uint32_t    size );
218
219/******************************************************************************************
220 * This function registers a local client thread in the waiting queue of a remote
221 * device descriptor, activates (i.e. unblock) the server thread associated to device,
222 * and blocks itself on the THREAD_BLOCKED_IO condition.
223 ******************************************************************************************
224 * @ dev     : extended pointer on remote device descriptor.
225 * @ thread  : local pointer on client thread.
226 *****************************************************************************************/
227void device_register_command( xptr_t            xp_dev,
228                              struct thread_s * thread );
229
230
231#endif  /* _DEVICE_H_ */
Note: See TracBrowser for help on using the repository browser.