[5] | 1 | /* |
---|
[657] | 2 | * chdev.h - channel device (chdev) descriptor and API definition. |
---|
[5] | 3 | * |
---|
[657] | 4 | * Authors Alain Greiner (2016,2017,2018,2019,2020) |
---|
[5] | 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 | |
---|
[14] | 27 | #include <kernel_config.h> |
---|
[457] | 28 | #include <hal_kernel_types.h> |
---|
[5] | 29 | #include <xlist.h> |
---|
[564] | 30 | #include <remote_busylock.h> |
---|
[346] | 31 | #include <dev_iob.h> |
---|
[5] | 32 | #include <dev_ioc.h> |
---|
| 33 | #include <dev_nic.h> |
---|
| 34 | #include <dev_pic.h> |
---|
| 35 | #include <dev_fbf.h> |
---|
[428] | 36 | #include <dev_txt.h> |
---|
[5] | 37 | |
---|
[657] | 38 | /**************************************************************************************** |
---|
[5] | 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"). |
---|
[23] | 43 | * ALMOS-MKH supports multi-channels peripherals, and defines one separated chdev |
---|
[657] | 44 | * descriptor for each channel (and for each RX/TX direction for NIC and TXT devices). |
---|
[564] | 45 | * Each chdev contains a trans-clusters waiting queue, registering the "client threads", |
---|
[5] | 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, |
---|
[204] | 50 | * - the server cluster, containing the chdev and the server thread, |
---|
| 51 | * - the I/O cluster, containing the physical device. |
---|
[657] | 52 | ***************************************************************************************/ |
---|
[5] | 53 | |
---|
| 54 | /**** Forward declarations ****/ |
---|
| 55 | |
---|
| 56 | struct chdev_s; |
---|
| 57 | struct thread_s; |
---|
| 58 | struct boot_info_s; |
---|
| 59 | |
---|
[657] | 60 | /**************************************************************************************** |
---|
| 61 | * These macros extract functionality and implementation from the peripheral type. |
---|
| 62 | ***************************************************************************************/ |
---|
[5] | 63 | |
---|
| 64 | #define FUNC_FROM_TYPE( type ) ((uint32_t)(type>>16)) |
---|
| 65 | #define IMPL_FROM_TYPE( type ) ((uint32_t)(type & 0x0000FFFF)) |
---|
| 66 | |
---|
[657] | 67 | /**************************************************************************************** |
---|
[669] | 68 | * This defines the generic prototypes for the functions that must be defined |
---|
| 69 | * by all drivers implementing a generic device: |
---|
[407] | 70 | * - "cmd" : start a blocking I/O operation. |
---|
[5] | 71 | * - "isr" : complete an I/O operation. |
---|
[407] | 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. |
---|
[657] | 75 | ***************************************************************************************/ |
---|
[5] | 76 | |
---|
| 77 | typedef void (dev_ini_t) ( xptr_t dev ); |
---|
| 78 | typedef void (dev_cmd_t) ( xptr_t thread ); |
---|
| 79 | typedef void (dev_isr_t) ( struct chdev_s * dev ); |
---|
[407] | 80 | typedef void (dev_aux_t) ( void * args ); |
---|
[5] | 81 | |
---|
[657] | 82 | /**************************************************************************************** |
---|
[5] | 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. |
---|
[204] | 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. |
---|
[657] | 91 | ***************************************************************************************/ |
---|
[5] | 92 | |
---|
| 93 | enum 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, |
---|
[204] | 105 | DEV_FUNC_ICU = 10, |
---|
[5] | 106 | DEV_FUNC_PIC = 11, |
---|
| 107 | |
---|
| 108 | DEV_FUNC_NR = 12, |
---|
| 109 | }; |
---|
| 110 | |
---|
| 111 | /****************************************************************************************** |
---|
[662] | 112 | * This structure defines a chdev (channel device) descriptor. |
---|
[5] | 113 | * This structure is NOT replicated, and can be located in any cluster. |
---|
[662] | 114 | * One server thread is in charge of handling the commands registered in the queue |
---|
| 115 | * of clients associated to each chdev descriptor. |
---|
| 116 | * |
---|
[428] | 117 | * For each device type ***, the specific extension is defined in the "dev_***.h" file. |
---|
[564] | 118 | * |
---|
[657] | 119 | * NOTE . For most chdevs, the busylock is used to protect the waiting queue changes, |
---|
[662] | 120 | * when a client registers in this queue, or is removed after service. |
---|
[657] | 121 | * . This busylock is also used to protect direct access to the shared |
---|
| 122 | * kernel TXT0 terminal, that does not use the waiting queue. |
---|
[662] | 123 | * . For mostd chdevs, the client waiting queue is an xlist of threads, but it is |
---|
| 124 | * a list of sockets for the NIC chdevs. It is unused for ICU, PIC, and IOB. |
---|
[5] | 125 | *****************************************************************************************/ |
---|
| 126 | |
---|
| 127 | typedef struct chdev_s |
---|
| 128 | { |
---|
| 129 | uint32_t func; /*! peripheral functionnal type */ |
---|
[657] | 130 | uint32_t impl; /*! peripheral implementation type */ |
---|
[5] | 131 | uint32_t channel; /*! channel index */ |
---|
[407] | 132 | bool_t is_rx; /*! relevant for NIC and TXT peripherals */ |
---|
[188] | 133 | xptr_t base; /*! extended pointer on channel device segment */ |
---|
[23] | 134 | char name[16]; /*! name (required by DEVFS) */ |
---|
[5] | 135 | |
---|
[407] | 136 | dev_cmd_t * cmd; /*! local pointer on driver CMD function */ |
---|
| 137 | dev_isr_t * isr; /*! local pointer on driver ISR function */ |
---|
| 138 | dev_aux_t * aux; /*! local pointer on driver AUX function */ |
---|
| 139 | |
---|
[5] | 140 | struct thread_s * server; /*! local pointer on associated server thread */ |
---|
| 141 | |
---|
| 142 | uint32_t irq_type; /*! associated IRQ type in local ICU */ |
---|
| 143 | uint32_t irq_id; /*! associated IRQ index in local ICU */ |
---|
| 144 | |
---|
[662] | 145 | xlist_entry_t wait_root; /*! root of clients waiting queue */ |
---|
[564] | 146 | remote_busylock_t wait_lock; /*! lock protecting waiting queue */ |
---|
[662] | 147 | uint32_t wait_nr; /*! number of registered clients (NIC only) */ |
---|
[5] | 148 | |
---|
| 149 | union |
---|
| 150 | { |
---|
[346] | 151 | iob_extend_t iob; /*! IOB specific extension */ |
---|
[5] | 152 | ioc_extend_t ioc; /*! IOC specific extension */ |
---|
| 153 | nic_extend_t nic; /*! NIC specific extension */ |
---|
| 154 | pic_extend_t pic; /*! PIC specific extension */ |
---|
| 155 | fbf_extend_t fbf; /*! FBF specific extension */ |
---|
[428] | 156 | txt_extend_t txt; /*! TXT specific extension */ |
---|
[5] | 157 | } |
---|
| 158 | ext; |
---|
| 159 | } |
---|
| 160 | chdev_t; |
---|
| 161 | |
---|
| 162 | /****************************************************************************************** |
---|
| 163 | * This structure defines the channel_devices descriptors directory. |
---|
| 164 | * Each entry in this structure contains an extended pointer on a chdev descriptor. |
---|
| 165 | * There is one entry per channel OR per cluster, depending on peripheral type. |
---|
| 166 | * This structure is replicated in each cluster, and is initialised during kernel init. |
---|
| 167 | * It is used for fast access to a device descriptor, from type and channel for an |
---|
[450] | 168 | * external peripheral, or from type and cluster for an internal peripheral. |
---|
[5] | 169 | * - a "shared" chdev can be accessed by any thread running in any cluster. |
---|
| 170 | * - a "private" chdev can only be accessed by a thread running in local cluster. |
---|
| 171 | *****************************************************************************************/ |
---|
| 172 | |
---|
| 173 | typedef struct chdev_directory_s |
---|
| 174 | { |
---|
| 175 | xptr_t iob; // external / single channel / shared |
---|
| 176 | xptr_t pic; // external / single channel / shared |
---|
| 177 | |
---|
| 178 | xptr_t ioc[CONFIG_MAX_IOC_CHANNELS]; // external / multi-channels / shared |
---|
| 179 | xptr_t fbf[CONFIG_MAX_FBF_CHANNELS]; // external / multi-channels / shared |
---|
[407] | 180 | xptr_t txt_rx[CONFIG_MAX_TXT_CHANNELS]; // external / multi-channels / shared |
---|
| 181 | xptr_t txt_tx[CONFIG_MAX_TXT_CHANNELS]; // external / multi-channels / shared |
---|
[5] | 182 | xptr_t nic_rx[CONFIG_MAX_NIC_CHANNELS]; // external / multi-channels / shared |
---|
| 183 | xptr_t nic_tx[CONFIG_MAX_NIC_CHANNELS]; // external / multi-channels / shared |
---|
| 184 | |
---|
| 185 | xptr_t mmc[CONFIG_MAX_CLUSTERS]; // internal / single channel / shared |
---|
| 186 | |
---|
| 187 | xptr_t dma[CONFIG_MAX_DMA_CHANNELS]; // internal / multi-channels / private |
---|
| 188 | } |
---|
| 189 | chdev_directory_t; |
---|
| 190 | |
---|
[657] | 191 | /**************************************************************************************** |
---|
[5] | 192 | * This function display relevant values for a chdev descriptor. |
---|
[657] | 193 | **************************************************************************************** |
---|
[5] | 194 | * @ chdev : pointer on chdev. |
---|
[657] | 195 | ***************************************************************************************/ |
---|
[5] | 196 | void chdev_print( chdev_t * chdev ); |
---|
| 197 | |
---|
[657] | 198 | /**************************************************************************************** |
---|
[5] | 199 | * This function returns a printable string for a device functionnal types. |
---|
[657] | 200 | **************************************************************************************** |
---|
[5] | 201 | * @ func_type : functionnal type. |
---|
[16] | 202 | * @ return pointer on string. |
---|
[657] | 203 | ***************************************************************************************/ |
---|
[5] | 204 | char * chdev_func_str( uint32_t func_type ); |
---|
| 205 | |
---|
[657] | 206 | /**************************************************************************************** |
---|
[5] | 207 | * This function allocates memory and initializes a chdev descriptor in local cluster, |
---|
| 208 | * from arguments values. It should be called by a local thread. |
---|
| 209 | * The device specific fields are initialised later. |
---|
[657] | 210 | **************************************************************************************** |
---|
[5] | 211 | * @ func : functionnal type. |
---|
| 212 | * @ impl : implementation type. |
---|
| 213 | * @ channel : channel index / for multi-channels peripherals. |
---|
| 214 | * @ is_rx : for NIC peripheral / NIC RX if true / NIC TX if false. |
---|
| 215 | * @ base : extended pointer on peripheral segment base. |
---|
| 216 | * @ return a local pointer on created chdev / return NULL if failure. |
---|
[657] | 217 | ***************************************************************************************/ |
---|
[5] | 218 | chdev_t * chdev_create( uint32_t func, |
---|
| 219 | uint32_t impl, |
---|
| 220 | uint32_t channel, |
---|
| 221 | bool_t is_rx, |
---|
| 222 | xptr_t base ); |
---|
| 223 | |
---|
[657] | 224 | /**************************************************************************************** |
---|
| 225 | * This generid function is executed by an user thread requesting an IOC or TXT chdev |
---|
| 226 | * service. It registers the calling thread in the waiting queue of a the remote |
---|
| 227 | * chdev descriptor identified by the <chdev_xp> argument. |
---|
| 228 | * It activates (i.e. unblocks) the server thread associated to chdev, blocks itself, |
---|
| 229 | * and deschedule. It is supposed to be re-activated by the server thread. |
---|
| 230 | * It can be called by a thread running in any cluster. |
---|
| 231 | * It cannot be used for a NIC or FBF chdev, because it is only convenient for one shot |
---|
| 232 | * I/O operations, as the server thread removes the client thread from the waiting |
---|
| 233 | * queue when it starts to execute the command. |
---|
| 234 | **************************************************************************************** |
---|
| 235 | * Implementation Note: |
---|
| 236 | * The following actions are executed in a critical section, thanks to the |
---|
| 237 | * busylock_acquire / busylock_release mechanism : |
---|
| 238 | * 1) it takes the lock protecting the waiting queue. |
---|
| 239 | * 2) it registers client thread in the server queue. |
---|
| 240 | * 3) it unblocks the server thread from the THREAD_BLOCKED_CLIENT condition. |
---|
| 241 | * 4) it blocks the client thread on the THREAD_BLOCKED_IO condition. |
---|
| 242 | * 5) it send an IPI to the core running the server thread to force scheduling. |
---|
| 243 | * 6) it releases the lock protecting waiting queue. |
---|
| 244 | * 7) it deschedules. |
---|
| 245 | **************************************************************************************** |
---|
[5] | 246 | * @ chdev_xp : extended pointer on remote chdev descriptor. |
---|
[657] | 247 | ***************************************************************************************/ |
---|
[407] | 248 | void chdev_register_command( xptr_t chdev_xp ); |
---|
[5] | 249 | |
---|
[657] | 250 | /**************************************************************************************** |
---|
| 251 | * This generic function is executed by the server thread associated to an IOC or TXT |
---|
| 252 | * chdev identified by the <chdev> argument, to execute all commands registered in the |
---|
| 253 | * waiting queue attached to this chev. |
---|
| 254 | * When the clients queue is empty, the server thread blocks on the THREAD_BLOCKED_CLIENT |
---|
| 255 | * condition and deschedules. It is supposed to be re-activated by a client thread |
---|
| 256 | * registering a new command. |
---|
| 257 | * It cannot be used for a NIC or FBF chdev, because it is only convenient for one shot |
---|
| 258 | * I/O operations, as the server thread removes the client thread from the waiting |
---|
| 259 | * queue when it starts to execute the command. |
---|
| 260 | **************************************************************************************** |
---|
| 261 | * Implementation Note: |
---|
| 262 | * All driver CMD functions are supposed to be blocking, and return only when the command |
---|
[5] | 263 | * is completed. These functions can use either a busy waiting policy, or a descheduling |
---|
[657] | 264 | * policy, blocking on the THREAD_BLOCKED_ISR condition. In the descheduling scenario, |
---|
| 265 | * the server thread is supposed to be reactivated by the ISR attached to the hardware |
---|
| 266 | * interrupts signaling command completion. |
---|
| 267 | **************************************************************************************** |
---|
[5] | 268 | * @ chdev : local pointer on device descriptor. |
---|
[657] | 269 | ***************************************************************************************/ |
---|
[619] | 270 | void chdev_server_func( chdev_t * chdev ); |
---|
[5] | 271 | |
---|
[657] | 272 | /**************************************************************************************** |
---|
[428] | 273 | * This function returns an extended pointer on the chdev associated to a pseudo file |
---|
[669] | 274 | * descriptor (type FILE_TYPE_DEV) identified by the <file_xp> argument. |
---|
[428] | 275 | * It can be called by a thread running in any cluster. |
---|
| 276 | * It enters kernel panic if the inode has not the expected type. |
---|
[657] | 277 | **************************************************************************************** |
---|
[428] | 278 | * @ file_xp : extended pointer on the pseudo file descriptor. |
---|
| 279 | * @ return an extended pointer on chdev. |
---|
[657] | 280 | ***************************************************************************************/ |
---|
[428] | 281 | xptr_t chdev_from_file( xptr_t file_xp ); |
---|
| 282 | |
---|
[657] | 283 | /**************************************************************************************** |
---|
[317] | 284 | * This function displays the local copy of the external chdevs directory. |
---|
| 285 | * (global variable replicated in all clusters) |
---|
[657] | 286 | ***************************************************************************************/ |
---|
[485] | 287 | void chdev_dir_display( void ); |
---|
[5] | 288 | |
---|
[657] | 289 | /**************************************************************************************** |
---|
[447] | 290 | * This function displays the list of threads registered in the queue associated |
---|
| 291 | * to the chdev identified by the <chdev_xp>. |
---|
[657] | 292 | **************************************************************************************** |
---|
[447] | 293 | * # root_xp : extended pointer |
---|
[657] | 294 | ***************************************************************************************/ |
---|
[447] | 295 | void chdev_queue_display( xptr_t chdev_xp ); |
---|
| 296 | |
---|
[5] | 297 | #endif /* _CHDEV_H_ */ |
---|