| tkernel_2/include/device/gdrvif.h | bare source | permlink (0.01 seconds) |
1: /* 2: *---------------------------------------------------------------------- 3: * T-Kernel 2.0 Software Package 4: * 5: * Copyright 2011 by Ken Sakamura. 6: * This software is distributed under the latest version of T-License 2.x. 7: *---------------------------------------------------------------------- 8: * 9: * Released by T-Engine Forum(http://www.t-engine.org/) at 2011/05/17. 10: * Modified by T-Engine Forum at 2013/03/11. 11: * Modified by TRON Forum(http://www.tron.org/) at 2015/06/01. 12: * 13: *---------------------------------------------------------------------- 14: */ 15: 16: /* 17: * gdrvif.h (device) 18: * 19: * General-purpose device driver I/F layer 20: * 21: * Used for all general devices that process in order of request. 22: * The device driver holds one or more request processing tasks 23: * and process the requests asynchronously. 24: * 25: * Driver I/F layer 26: * ------------------------------------------------- 27: * | ^ 28: * | | 29: * open/close/abort/event Accept/Reply 30: * | | 31: * v | 32: * +---------------------+ +-------------------------+ 33: * | Process function | | Request processing task | 34: * | | | (one or more) | 35: * +---------------------+ +-------------------------+ 36: * 37: * Except where otherwise stated, the functions defined here cannot be 38: * called from the task-independent part or when dispatch or interrupt 39: * disabled. 40: */ 41: 42: #ifndef __DEVICE_GDRVIF_H__ 43: #define __DEVICE_GDRVIF_H__ 44: 45: #include <basic.h> 46: #include <tk/devmgr.h> 47: 48: #ifdef __cplusplus 49: extern "C" { 50: #endif 51: 52: /* 53: * Driver I/F access handle 54: */ 55: typedef struct GeneralDriverInterface * GDI; 56: 57: /* 58: * Device register information 59: */ 60: typedef struct { 61: void* exinf; /* Extended information (may be optional) */ 62: UB devnm[L_DEVNM+1]; /* Physical device name */ 63: UH maxreqq; /* Maximum queued requests (1 or more) */ 64: ATR drvatr; /* Driver attributes */ 65: ATR devatr; /* Device attributes */ 66: INT nsub; /* Number of subunits */ 67: INT blksz; /* Unique data block size (-1 = unknown) */ 68: 69: /* 70: * Processing function (set to NULL if processing function not required) 71: * In all cases, processing must be completed promptly without 72: * switching to wait mode on an irregular basis. With the 73: * exception of abort, the processing function calls only one task 74: * at a time, because the driver I/F exercises exclusive control. 75: * Although abort can be called during execution of other 76: * processing functions, multiple abort functions will never be 77: * called simultaneously. 78: * Processing functions are executed as quasi task portions in the 79: * request task(application task) context. Since processing 80: * functions operate in the request task context,in the event of a 81: * change in task priority or other change, it is necessary to 82: * return them to their original state before returning from the 83: * processing function. 84: * 85: * abort stops a devreq request being processed by a request 86: * process task. The abort function has limited power to call GDI 87: * functions. Only the functions listed below can be called from 88: * the abort function: GDI_devid(), GDI_exinf(), GDI_ddev(), 89: * GDI_Send Cmd() 90: */ 91: ER (*open )( ID devid, UINT omode, GDI ); 92: ER (*close)( ID devid, UINT option, GDI ); 93: ER (*abort)( T_DEVREQ *devreq, GDI ); 94: INT (*event)( INT evttyp, void *evtinf, GDI ); 95: } GDefDev; 96: 97: /* 98: * Driver attributes 99: * If TDA_LOCKREQ is specified, the input/output buffer 100: * (T_DEVREQ.buf) area is locked (made resident) in the 101: * driver I/F. 102: */ 103: #ifndef TDA_OPENREQ 104: #define TDA_OPENREQ 0x0001 /* Each time open/close */ 105: #endif 106: #define TDA_LOCKREQ 0x8000 /* Address space lock required */ 107: #define TDA_LIMITEDREQ 0x4000 /* Limit request queue by request type */ 108: 109: /* 110: * Device register 111: * Registers the device in accordance with the ddev registration 112: * information. 113: * Initial device information is returned in idev. If idev = NULL, 114: * information is not returned. 115: * The driver I/F access handle is returned in GDI. 116: * Update 117: * Updates the GDI device registration in accordance with the ddev 118: * registration information . The device name (devnm) and maximum number 119: * of queued requests (maxreqq) cannot (and must not) be changed. 120: * Accepted requests are held in a queue. Any requests not yet accepted 121: * will be aborted. 122: * The update process does not alter the device ID. 123: * Delete 124: * Deletes the GID device registration. 125: */ 126: IMPORT ER GDefDevice( const GDefDev *ddev, T_IDEV *idev, GDI* ); /* define */ 127: IMPORT ER GRedefDevice( const GDefDev *ddev, GDI ); /* re-define */ 128: IMPORT ER GDelDevice( GDI ); /* delete */ 129: 130: /* 131: * Get information from GDI 132: * These functions can be called from the task-independent part and when 133: * dispatch or interrupt is disabled. 134: */ 135: IMPORT ID GDI_devid( GDI ); /* Physical device ID */ 136: IMPORT void* GDI_exinf( GDI ); /* Extended information (exinf) */ 137: IMPORT const GDefDev* GDI_ddev( GDI ); /* Registration information */ 138: 139: /* 140: * Accept request 141: * Gets one request from the accepted requests queue. 142: * If there are no requests in the queue, it switches to wait mode 143: * until a request is received. 144: * In acpptn, the value obtained from DEVREQ_ACPPTN() is specified 145: * in OR in terms of the accepted request type (TDC_READ/TDC_WRITE) 146: * or the user command pattern. Although ordinary requests 147: * (TDC_READ/TDC_WRITE) have priority over user commands, an 148: * ordinary request and a user command may on occasion be accepted 149: * at the same time. 150: * tmout specifies the timeout interval in milliseconds. TMO_POL 151: * and TMO_FEVR may also be specified. The return value is either 152: * the request pattern or an error. 153: * 154: * [Ordinary requests] 155: * The return value is the pattern that indicates the accepted 156: * request type. 157: * The accepted request is returned in *devreq. 158: * 159: * [User commands] 160: * The return value is the pattern that indicates the user commands 161: * accepted. Where multiple types of user commands are waiting, 162: * all user commands specified in acpptn are accepted together, 163: * and returned in an OR pattern. NULL is returned in *devreq. 164: * 165: * [Ordinary requests and user commands accepted at the same time] 166: * The return value is an OR pattern with both the accepted 167: * ordinary requests and the accepted user commands. 168: * The accepted ordinary requests are returned in *devreq. 169: * 170: * [Timeout or error] 171: * The return value is the error code, or E_TMOUT in the event 172: * of a timeout. 173: * *devreq is undefined. 174: * 175: * exinf of the accepted request (T_DEVREQ) cannot be changed. 176: * A buf area check (ChkSpace) has been implemented in the 177: * driver I/F. 178: * Reply to user command (GDI_Reply) is not required. 179: * 180: * Normally, a request will not be accepted until processing 181: * of the previous request has been completed and the result 182: * returned. However, multiple requests may be accepted and 183: * processed simultaneously. 184: * Multiple requests may be processed either in parallel, 185: * whereby multiple request processing tasks each execute their 186: * own GDI_Accept(), or simultaneously, whereby a single processing 187: * task performs multiple repetitions of GDI_Accept(). 188: * The order in which the results are returned does not need 189: * to be the same as the order in which the requests were accepted. 190: */ 191: 192: IMPORT INT GDI_Accept( T_DEVREQ **devreq, INT acpptn, TMO tmout, GDI ); 193: 194: /* cmd = TDC_READ || TDC_WRITE || user commands (16 - 23) */ 195: #define DEVREQ_ACPPTN(cmd) ( 1 << (cmd) ) 196: 197: #define DRP_READ DEVREQ_ACPPTN(TDC_READ) /* Read */ 198: #define DRP_WRITE DEVREQ_ACPPTN(TDC_WRITE) /* Write */ 199: #define DRP_NORMREQ ( DRP_READ|DRP_WRITE ) /* Ordinary request */ 200: #define DRP_USERCMD 0x00ff0000 /* User command */ 201: 202: /* 203: * Extended accept request (Specified attribute/unique data) 204: * DRP_DREAD Read unique data 205: * DRP_DWRITE Write unique data 206: * DRP_AREAD Read attribute data 207: * DRP_AWRITE Write attribute data 208: * 209: * DRP_DREAD | DRP_AREAD = DRP_READ 210: * DRP_DWRITE | DRP_AWRITE = DRP_WRITE 211: * 212: * These option cannot be used with DRP_READ/DRP_WRITE. 213: */ 214: #define DRP_ADSEL 0x00000100 /* set unique, attribute data */ 215: #define DRP_DREAD ( DRP_ADSEL | DEVREQ_ACPPTN(TDC_READ) ) 216: #define DRP_DWRITE ( DRP_ADSEL | DEVREQ_ACPPTN(TDC_WRITE) ) 217: #define DRP_AREAD ( DRP_ADSEL | DEVREQ_ACPPTN(TDC_READ + 8) ) 218: #define DRP_AWRITE ( DRP_ADSEL | DEVREQ_ACPPTN(TDC_WRITE + 8) ) 219: 220: #define DRP_REQMASK ( DRP_ADSEL | DRP_NORMREQ | (DRP_NORMREQ << 8) ) 221: 222: /* 223: * Issue user command 224: * Issues the user command specified in cmd. 225: * Only values in the range 16 - 23 may be specified in cmd. 226: * Issued user commands are accepted by GDI_Accept(). 227: * Where user commands are waiting to be accepted by GDI_Accept(), 228: * only one of each command type is allowed. If the same command is 229: * issued several times, only one can be retained; accordingly, the 230: * command already waiting at GDI_Accept() will be deleted. 231: * Note that GDI_SendCmd() is only for issuing user commands; 232: * as a result, it returns withoutwaiting to be accepted by 233: * GDI_Accept(). 234: * 235: * User commands are generally used to enable release from 236: * GDI_Accept() waiting status at any time. 237: */ 238: IMPORT ER GDI_SendCmd( INT cmd, GDI ); 239: 240: /* 241: * Request response 242: * Returns the processing result for the request accepted 243: * by GDI_Accept(). 244: * Task issues GDI_Accept() and task issues GDI_Reply() do not 245: * have to be the same. 246: */ 247: IMPORT void GDI_Reply( T_DEVREQ*, GDI ); 248: 249: #ifdef __cplusplus 250: } 251: #endif 252: #endif /* __DEVICE_GDRVIF_H__ */