Changeset 657 for trunk/kernel/kern/chdev.h
- Timestamp:
- Mar 18, 2020, 11:16:59 PM (4 years ago)
- File:
-
- 1 edited
-
trunk/kernel/kern/chdev.h (modified) (13 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/kernel/kern/chdev.h
r625 r657 1 1 /* 2 * chdev.h - channel device (chdev) descriptor definition.2 * chdev.h - channel device (chdev) descriptor and API definition. 3 3 * 4 * Authors Alain Greiner (2016 )4 * Authors Alain Greiner (2016,2017,2018,2019,2020) 5 5 * 6 6 * Copyright (c) UPMC Sorbonne Universites … … 36 36 #include <dev_txt.h> 37 37 38 /**************************************************************************************** **38 /**************************************************************************************** 39 39 * Channel Device descriptor definition 40 40 * … … 42 42 * independant) Channel Device descriptor (in brief "chdev"). 43 43 * ALMOS-MKH supports multi-channels peripherals, and defines one separated chdev 44 * descriptor for each channel (and for each RX/TX direction for theNIC and TXT devices).44 * descriptor for each channel (and for each RX/TX direction for NIC and TXT devices). 45 45 * Each chdev contains a trans-clusters waiting queue, registering the "client threads", 46 46 * and an associated "server thread", handling these requests. … … 50 50 * - the server cluster, containing the chdev and the server thread, 51 51 * - the I/O cluster, containing the physical device. 52 *************************************************************************************** **/52 ***************************************************************************************/ 53 53 54 54 /**** Forward declarations ****/ … … 58 58 struct boot_info_s; 59 59 60 /**************************************************************************************** **61 * These macros extract the functionality and theimplementation from the peripheral type.62 *************************************************************************************** **/60 /**************************************************************************************** 61 * These macros extract functionality and implementation from the peripheral type. 62 ***************************************************************************************/ 63 63 64 64 #define FUNC_FROM_TYPE( type ) ((uint32_t)(type>>16)) 65 65 #define IMPL_FROM_TYPE( type ) ((uint32_t)(type & 0x0000FFFF)) 66 66 67 /**************************************************************************************** **67 /**************************************************************************************** 68 68 * This define the generic prototypes for the three functions that must be defined 69 69 * by the drivers implementing a generic device: … … 73 73 * The "cmd", "isr", and "aux" driver functions are registered in the generic chdev 74 74 * descriptor at kernel init, and are called to start and complete an I/O operation. 75 *************************************************************************************** **/75 ***************************************************************************************/ 76 76 77 77 typedef void (dev_ini_t) ( xptr_t dev ); … … 80 80 typedef void (dev_aux_t) ( void * args ); 81 81 82 /**************************************************************************************** **82 /**************************************************************************************** 83 83 * This enum defines the supported generic device types. 84 84 * These types are functionnal types: all (architecture specific) implementations … … 89 89 * distributed LAPIC controler, but it does not exist as a chdev in the kernel, 90 90 * as it is hidden in the driver associated to the PIC device. 91 *************************************************************************************** **/91 ***************************************************************************************/ 92 92 93 93 enum dev_func_type … … 116 116 * For each device type ***, the specific extension is defined in the "dev_***.h" file. 117 117 * 118 * NOTE :For most chdevs, the busylock is used to protect the waiting queue changes,118 * NOTE . For most chdevs, the busylock is used to protect the waiting queue changes, 119 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). 120 * . This busylock is also used to protect direct access to the shared 121 * kernel TXT0 terminal, that does not use the waiting queue. 122 * . For the NIC chdevs it is also used to protect registration (or removal) of a 123 * socket in the list of attached sockets rooted in NIC device extension. 122 124 *****************************************************************************************/ 123 125 … … 125 127 { 126 128 uint32_t func; /*! peripheral functionnal type */ 127 uint32_t impl; /*! peripheral i nplementation subtype*/129 uint32_t impl; /*! peripheral implementation type */ 128 130 uint32_t channel; /*! channel index */ 129 131 bool_t is_rx; /*! relevant for NIC and TXT peripherals */ … … 185 187 chdev_directory_t; 186 188 187 /**************************************************************************************** **189 /**************************************************************************************** 188 190 * This function display relevant values for a chdev descriptor. 189 **************************************************************************************** **191 **************************************************************************************** 190 192 * @ chdev : pointer on chdev. 191 *************************************************************************************** **/193 ***************************************************************************************/ 192 194 void chdev_print( chdev_t * chdev ); 193 195 194 /**************************************************************************************** **196 /**************************************************************************************** 195 197 * This function returns a printable string for a device functionnal types. 196 **************************************************************************************** **198 **************************************************************************************** 197 199 * @ func_type : functionnal type. 198 200 * @ return pointer on string. 199 *************************************************************************************** **/201 ***************************************************************************************/ 200 202 char * chdev_func_str( uint32_t func_type ); 201 203 202 /**************************************************************************************** **204 /**************************************************************************************** 203 205 * This function allocates memory and initializes a chdev descriptor in local cluster, 204 206 * from arguments values. It should be called by a local thread. 205 207 * The device specific fields are initialised later. 206 **************************************************************************************** **208 **************************************************************************************** 207 209 * @ func : functionnal type. 208 210 * @ impl : implementation type. … … 211 213 * @ base : extended pointer on peripheral segment base. 212 214 * @ return a local pointer on created chdev / return NULL if failure. 213 *************************************************************************************** **/215 ***************************************************************************************/ 214 216 chdev_t * chdev_create( uint32_t func, 215 217 uint32_t impl, … … 218 220 xptr_t base ); 219 221 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 ****************************************************************************************** 222 /**************************************************************************************** 223 * This generid function is executed by an user thread requesting an IOC or TXT chdev 224 * service. It registers the calling thread in the waiting queue of a the remote 225 * chdev descriptor identified by the <chdev_xp> argument. 226 * It activates (i.e. unblocks) the server thread associated to chdev, blocks itself, 227 * and deschedule. It is supposed to be re-activated by the server thread. 228 * It can be called by a thread running in any cluster. 229 * It cannot be used for a NIC or FBF chdev, because it is only convenient for one shot 230 * I/O operations, as the server thread removes the client thread from the waiting 231 * queue when it starts to execute the command. 232 **************************************************************************************** 233 * Implementation Note: 234 * The following actions are executed in a critical section, thanks to the 235 * busylock_acquire / busylock_release mechanism : 236 * 1) it takes the lock protecting the waiting queue. 237 * 2) it registers client thread in the server queue. 238 * 3) it unblocks the server thread from the THREAD_BLOCKED_CLIENT condition. 239 * 4) it blocks the client thread on the THREAD_BLOCKED_IO condition. 240 * 5) it send an IPI to the core running the server thread to force scheduling. 241 * 6) it releases the lock protecting waiting queue. 242 * 7) it deschedules. 243 **************************************************************************************** 225 244 * @ chdev_xp : extended pointer on remote chdev descriptor. 226 *************************************************************************************** **/245 ***************************************************************************************/ 227 246 void chdev_register_command( xptr_t chdev_xp ); 228 247 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 248 /**************************************************************************************** 249 * This generic function is executed by the server thread associated to an IOC or TXT 250 * chdev identified by the <chdev> argument, to execute all commands registered in the 251 * waiting queue attached to this chev. 252 * When the clients queue is empty, the server thread blocks on the THREAD_BLOCKED_CLIENT 253 * condition and deschedules. It is supposed to be re-activated by a client thread 254 * registering a new command. 255 * It cannot be used for a NIC or FBF chdev, because it is only convenient for one shot 256 * I/O operations, as the server thread removes the client thread from the waiting 257 * queue when it starts to execute the command. 258 **************************************************************************************** 259 * Implementation Note: 260 * All driver CMD functions are supposed to be blocking, and return only when the command 234 261 * is completed. These functions can use either a busy waiting policy, or a descheduling 235 * policy, blocking on the THREAD_BLOCKED_I O_ISR condition, and reactivated by the ISR.236 * When the waiting queue is empty, the server thread blocks on the THREAD_BLOCKED_IO_CMD237 * condition and deschedule. It is re-activated by a client thread registering a command.238 **************************************************************************************** **262 * policy, blocking on the THREAD_BLOCKED_ISR condition. In the descheduling scenario, 263 * the server thread is supposed to be reactivated by the ISR attached to the hardware 264 * interrupts signaling command completion. 265 **************************************************************************************** 239 266 * @ chdev : local pointer on device descriptor. 240 *************************************************************************************** **/267 ***************************************************************************************/ 241 268 void chdev_server_func( chdev_t * chdev ); 242 269 243 /**************************************************************************************** **270 /**************************************************************************************** 244 271 * This function returns an extended pointer on the chdev associated to a pseudo file 245 272 * descriptor (type INODE_TYPE_DEV) identified by the <file_xp> argument. 246 273 * It can be called by a thread running in any cluster. 247 274 * It enters kernel panic if the inode has not the expected type. 248 **************************************************************************************** **275 **************************************************************************************** 249 276 * @ file_xp : extended pointer on the pseudo file descriptor. 250 277 * @ return an extended pointer on chdev. 251 *************************************************************************************** **/278 ***************************************************************************************/ 252 279 xptr_t chdev_from_file( xptr_t file_xp ); 253 280 254 /**************************************************************************************** **281 /**************************************************************************************** 255 282 * This function displays the local copy of the external chdevs directory. 256 283 * (global variable replicated in all clusters) 257 *************************************************************************************** **/284 ***************************************************************************************/ 258 285 void chdev_dir_display( void ); 259 286 260 /**************************************************************************************** **287 /**************************************************************************************** 261 288 * This function displays the list of threads registered in the queue associated 262 289 * to the chdev identified by the <chdev_xp>. 263 **************************************************************************************** **290 **************************************************************************************** 264 291 * # root_xp : extended pointer 265 *************************************************************************************** **/292 ***************************************************************************************/ 266 293 void chdev_queue_display( xptr_t chdev_xp ); 267 294
Note: See TracChangeset
for help on using the changeset viewer.
