source: trunk/kernel/kern/chdev.h @ 636

Last change on this file since 636 was 625, checked in by alain, 6 years ago

Fix a bug in the vmm_remove_vseg() function: the physical pages
associated to an user DATA vseg were released to the kernel when
the target process descriptor was in the reference cluster.
This physical pages release should be done only when the page
forks counter value is zero.
All other modifications are cosmetic.
File size: 13.9 KB
Line 
1/*
2 * chdev.h - channel device (chdev) descriptor 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 _CHDEV_H_
25#define _CHDEV_H_
26
27#include <kernel_config.h>
28#include <hal_kernel_types.h>
29#include <xlist.h>
30#include <remote_busylock.h>
31#include <dev_iob.h>
32#include <dev_ioc.h>
33#include <dev_nic.h>
34#include <dev_pic.h>
35#include <dev_fbf.h>
36#include <dev_txt.h>
37
38/******************************************************************************************
39 *       Channel Device descriptor definition
40 *
41 * This file defines the kernel representation of a generic (i.e. implementation
42 * independant) Channel Device descriptor (in brief "chdev").
43 * ALMOS-MKH supports multi-channels peripherals, and defines one separated chdev
44 * descriptor for each channel (and for each RX/TX direction for the NIC and TXT devices).
45 * Each chdev contains a trans-clusters waiting queue, registering the "client threads",
46 * and an associated "server thread", handling these requests.
47 * These descriptors are physically distributed on all clusters to minimize contention.
48 * Therefore a given I/O operation involve generally three clusters:
49 * - the client cluster, containing the client thread,
50 * - the server cluster, containing the chdev and the server thread,
51 * - the I/O cluster, containing the physical device.
52 *****************************************************************************************/
53
54/****  Forward declarations  ****/
55
56struct  chdev_s;
57struct  thread_s;
58struct  boot_info_s;
59
60/******************************************************************************************
61 * These macros extract the functionality and the implementation from the peripheral type.
62 *****************************************************************************************/
63 
64#define FUNC_FROM_TYPE( type )    ((uint32_t)(type>>16))
65#define IMPL_FROM_TYPE( type )    ((uint32_t)(type & 0x0000FFFF))
66
67/******************************************************************************************
68 * This define the generic prototypes for the three functions that must be defined
69 * by the drivers implementing a generic device:
70 * - "cmd"     : start a blocking I/O operation.
71 * - "isr"     : complete an I/O operation.
72 * - "aux"     : not for all drivers (implement special functions)
73 * The "cmd", "isr", and "aux" driver functions are registered in the generic chdev
74 * descriptor at kernel init, and are called to start and complete an I/O operation. 
75*****************************************************************************************/
76
77typedef void (dev_ini_t) ( xptr_t dev );     
78typedef void (dev_cmd_t) ( xptr_t thread ); 
79typedef void (dev_isr_t) ( struct chdev_s * dev ); 
80typedef void (dev_aux_t) ( void * args ); 
81
82/******************************************************************************************
83 * This enum defines the supported generic device types.
84 * These types are functionnal types: all (architecture specific) implementations
85 * provide the same set of operations and the same driver API.
86 * This enum must be consistent with the enum in files arch_info.h, and arch_class.py.
87 *
88 * WARNING : The ICU device exist in boot_info to specify the base address of the
89 *           distributed LAPIC controler, but it does not exist as a chdev in the kernel,
90 *           as it is hidden in the driver associated to the PIC device.
91 *****************************************************************************************/
92 
93enum dev_func_type
94{
95        DEV_FUNC_RAM   =  0,
96        DEV_FUNC_ROM   =  1,
97        DEV_FUNC_FBF   =  2,
98    DEV_FUNC_IOB   =  3,
99    DEV_FUNC_IOC   =  4,
100        DEV_FUNC_MMC   =  5,
101        DEV_FUNC_DMA   =  6,
102        DEV_FUNC_NIC   =  7,
103        DEV_FUNC_TIM   =  8,
104        DEV_FUNC_TXT   =  9,
105    DEV_FUNC_ICU   = 10,   
106    DEV_FUNC_PIC   = 11,
107
108    DEV_FUNC_NR    = 12,
109};
110
111/******************************************************************************************
112 * This structure defines a chdev descriptor.
113 * This structure is NOT replicated, and can be located in any cluster.
114 * One kernel thread, in charge of handling the commands registered in the waiting queue
115 * of client threads is associated to each chdev descriptor (not for ICU, PIC, IOB).
116 * For each device type ***, the specific extension is defined in the "dev_***.h" file.
117 *
118 * NOTE : For most chdevs, the busylock is used to protect the waiting queue changes,
119 *        when a thread register in this queue, or is removed after service.
120 *        This busylock is also used to protect direct access to the kernel TXT0 terminal
121 *        (without using the server thread).
122 *****************************************************************************************/
123
124typedef struct chdev_s
125{
126        uint32_t             func;        /*! peripheral functionnal type                    */
127        uint32_t             impl;        /*! peripheral inplementation subtype              */
128    uint32_t             channel;     /*! channel index                                  */
129    bool_t               is_rx;       /*! relevant for NIC and TXT peripherals           */
130        xptr_t               base;        /*! extended pointer on channel device segment     */
131    char                 name[16];    /*! name (required by DEVFS)                       */
132
133    dev_cmd_t          * cmd;         /*! local pointer on driver CMD function           */
134    dev_isr_t          * isr;         /*! local pointer on driver ISR function           */
135    dev_aux_t          * aux;         /*! local pointer on driver AUX function           */
136
137    struct thread_s    * server;      /*! local pointer on associated server thread      */
138
139    uint32_t             irq_type;    /*! associated IRQ type in local ICU               */
140    uint32_t             irq_id;      /*! associated IRQ index in local ICU              */
141
142        xlist_entry_t        wait_root;   /*! root of client threads waiting queue           */
143    remote_busylock_t    wait_lock;   /*! lock protecting waiting queue                  */
144
145    union
146    {
147        iob_extend_t     iob;         /*! IOB specific extension                         */
148        ioc_extend_t     ioc;         /*! IOC specific extension                         */
149        nic_extend_t     nic;         /*! NIC specific extension                         */
150        pic_extend_t     pic;         /*! PIC specific extension                         */
151        fbf_extend_t     fbf;         /*! FBF specific extension                         */
152        txt_extend_t     txt;         /*! TXT specific extension                         */
153    } 
154    ext;
155}
156chdev_t;
157
158/******************************************************************************************
159 * This structure defines the channel_devices descriptors directory.
160 * Each entry in this structure contains an extended pointer on a chdev descriptor.
161 * There is one entry per channel OR per cluster, depending on peripheral type.
162 * This structure is replicated in each cluster, and is initialised during kernel init.
163 * It is used for fast access to a device descriptor, from type and channel for an
164 * external peripheral, or from type and cluster for an internal peripheral.
165 * - a "shared" chdev can be accessed by any thread running in any cluster.
166 * - a "private" chdev can only be accessed by a thread running in local cluster.
167 *****************************************************************************************/
168
169typedef struct chdev_directory_s
170{
171    xptr_t   iob;                                // external / single channel / shared
172    xptr_t   pic;                                // external / single channel / shared
173
174    xptr_t   ioc[CONFIG_MAX_IOC_CHANNELS];       // external / multi-channels / shared
175    xptr_t   fbf[CONFIG_MAX_FBF_CHANNELS];       // external / multi-channels / shared
176    xptr_t   txt_rx[CONFIG_MAX_TXT_CHANNELS];    // external / multi-channels / shared
177    xptr_t   txt_tx[CONFIG_MAX_TXT_CHANNELS];    // external / multi-channels / shared
178    xptr_t   nic_rx[CONFIG_MAX_NIC_CHANNELS];    // external / multi-channels / shared
179    xptr_t   nic_tx[CONFIG_MAX_NIC_CHANNELS];    // external / multi-channels / shared
180
181    xptr_t   mmc[CONFIG_MAX_CLUSTERS];           // internal / single channel / shared
182
183    xptr_t   dma[CONFIG_MAX_DMA_CHANNELS];       // internal / multi-channels / private
184}
185chdev_directory_t;
186
187/******************************************************************************************
188 * This function display relevant values for a chdev descriptor.
189 ******************************************************************************************
190 * @ chdev   : pointer on chdev.
191 *****************************************************************************************/
192void chdev_print( chdev_t * chdev );
193
194/******************************************************************************************
195 * This function returns a printable string for a device functionnal types.
196 ******************************************************************************************
197 * @ func_type  : functionnal type.
198 * @ return pointer on string.
199 *****************************************************************************************/
200char * chdev_func_str( uint32_t func_type );
201
202/******************************************************************************************
203 * This  function allocates memory and initializes a chdev descriptor in local cluster,
204 * from arguments values.  It should be called by a local thread.
205 * The device specific fields are initialised later.
206 ******************************************************************************************
207 * @ func      : functionnal type.
208 * @ impl      : implementation type.
209 * @ channel   : channel index / for multi-channels peripherals.
210 * @ is_rx     : for NIC peripheral / NIC RX if true / NIC TX if false.
211 * @ base      : extended pointer on peripheral segment base.
212 * @ return a local pointer on created chdev / return NULL if failure.
213 *****************************************************************************************/
214chdev_t * chdev_create( uint32_t    func,
215                        uint32_t    impl,
216                        uint32_t    channel,
217                        bool_t      is_rx,
218                        xptr_t      base );
219
220/******************************************************************************************
221 * This function registers the calling thread in the waiting queue of a remote
222 * chdev descriptor, activates (i.e. unblock) the server thread associated to chdev,
223 * and blocks itself on the THREAD_BLOCKED_IO condition.
224 ******************************************************************************************
225 * @ chdev_xp  : extended pointer on remote chdev descriptor.
226 *****************************************************************************************/
227void chdev_register_command( xptr_t chdev_xp );
228
229/******************************************************************************************
230 * This function is executed by the server thread associated to a chdev descriptor.
231 * It executes an infinite loop to handle sequencially all commands registered by the
232 * client threads in the device waiting queue, until the queue is empty.
233 * The driver CMD function being blocking, these functions return only when the command
234 * is completed. These functions can use either a busy waiting policy, or a descheduling
235 * policy, blocking on the THREAD_BLOCKED_IO_ISR condition, and reactivated by the ISR.
236 * When the waiting queue is empty, the server thread blocks on the THREAD_BLOCKED_IO_CMD
237 * condition and deschedule. It is re-activated by a client thread registering a command.
238 ******************************************************************************************
239 * @ chdev   : local pointer on device descriptor.
240 *****************************************************************************************/
241void chdev_server_func( chdev_t * chdev );
242
243/******************************************************************************************
244 * This function returns an extended pointer on the chdev associated to a pseudo file
245 * descriptor (type INODE_TYPE_DEV) identified by the <file_xp> argument.
246 * It can be called by a thread running in any cluster.
247 * It enters kernel panic if the inode has not the expected type.
248 ******************************************************************************************
249 * @ file_xp   : extended pointer on the pseudo file descriptor.
250 * @ return an extended pointer on chdev.
251 *****************************************************************************************/
252xptr_t chdev_from_file( xptr_t file_xp );
253
254/******************************************************************************************
255 * This function displays the local copy of the external chdevs directory.
256 * (global variable replicated in all clusters)
257 *****************************************************************************************/
258void chdev_dir_display( void );
259
260/******************************************************************************************
261 * This function displays the list of threads registered in the queue associated
262 * to the chdev identified by the <chdev_xp>.
263 ******************************************************************************************
264 * # root_xp  : extended pointer
265 *****************************************************************************************/
266void chdev_queue_display( xptr_t chdev_xp );
267
268#endif  /* _CHDEV_H_ */
Note: See TracBrowser for help on using the repository browser.