gonzui


Format: Advanced Search

tkernel_2/include/device/gdrvif.hbare sourcepermlink (0.01 seconds)

Search this content:

    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__ */