sysdoc/devdoc.5

   1 Copyright (c) 1999 Massachusetts Institute of Technology
   2
   3 This program is free software; you can redistribute it and/or modify
   4 it under the terms of the GNU General Public License as published by
   5 the Free Software Foundation; either version 3 of the License, or (at
   6 your option) any later version.
   7
   8 This program is distributed in the hope that it will be useful, but
   9 WITHOUT ANY WARRANTY; without even the implied warranty of
  10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11 General Public License for more details.
  12
  13 You should have received a copy of the GNU General Public License
  14 along with this program; if not, write to the Free Software
  15 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  16 ------------------------------
  17
  18 \f
  19 SUBTTL I/O DEVICE DISPATCH TABLES
  20
  21 COMMENT |
  22         This page tries to document the ITS I/O device dispatch tables and
  23 dispatch environment.  It is not completed yet.
  24
  25 The tables use several different indices, which are:
  26         opnidx - result of device name lookup in DEVTAB
  27         ioidx  - result of OPEN; has symbolic values.  This is the index
  28                 stored in RH of IOCHNM (per-job channel table)
  29         sidx  - secondary index from DCHSTB(ioidx)
  30         ridx  - secondary index from RSTB(ioidx)
  31
  32 The following system calls are dispatched through these tables.
  33 There are 11 dispatch routines that each device must specify.
  34 The format is "CALL [table name(index-used) -> device-routine]"
  35 Unless otherwise noted, context for all routines has
  36         U/ User index
  37         R/ addr of IOCHNM word for specified channel
  38 and the phrase "all ACs can be used" excludes P and U, of course.
  39 and routines can hang (u.o.n.)
  40
  41 OPEN [DEVADR(opnidx) -> devO]
  42         "opnidx" is looked up from DEVTAB which holds the device names.
  43         The device's OPEN routine is in the RH of DEVADR.
  44         It must set up the user's IOCHNM word for the channel,
  45         by setting the RH to the right "ioidx" and the LH to whatever
  46         the device wants.
  47
  48         Context:
  49                 A/ FN1
  50                 B/ FN2
  51                 C/ <mode bits>,,<device name>
  52                 D/ <mode bits rotated -1>
  53                 E/ <device name>
  54                 TT/ DEVADR word <bits>,,<routine>
  55                 W/ "open" command (0= Normal R/W open, 1= Write-over mode,
  56                         2= Make link, 4= Delete or rename)
  57                 SRN3(U),SRN4(U),SRN5(U) - args 4,5,6 (if present)
  58
  59         Routine is JRST'd to, and must return via POPJ1 for success.
  60         Errors should JRST to the appropriate OPNLnn label.
  61         All ACs can be smashed.
  62
  63 CLOSE [CLSTB(ioidx) -> devCLS]
  64         The device's CLOSE routine is in the RH of CLSTB.
  65
  66         Context:
  67                 A/ 0,,<LH of IOCHNM word>
  68                 B/ 0,,<RH of IOCHNM word>
  69                 C/ CLSTB entry, <bits>,,<rtn addr>
  70                 R/ addr of IOCHNM word
  71         Called via PUSHJ, must return via POPJ (IOCHNM and IOCHST will
  72         be cleared immediately after return).
  73         Can smash all ACs including R.
  74         Must NOT hang!
  75
  76 IOT, SIOT [IOTTB(ioidx) -> devVarious]
  77         These routines do I/O transfers.  The main reason "ioidx"
  78         has so many possible values (causing IOTTB to be large) is
  79         because lots of devices specify different ioidx's for different
  80         modes - input/output, block/unit, image/ascii, etc - in order
  81         to speed up actual I/O transfers, which are probably the most
  82         common device-related system calls.
  83
  84         Context:
  85                 Boy is this complicated.
  86
  87 STATUS  [LH(DSTSTB(sidx)) -> devSTA]
  88         Context:
  89                 R/ addr of IOCHNM word
  90         Called by PUSHJ, must return by POPJ
  91         Must return in RH(D) some device-dependent status stuff.
  92         Calling routine (NSTATUS) fills in the LH from IOCHST.
  93         Must not smash C,R!  Probably should not smash other
  94         stuff either, depending on what USRVAR/USET need.
  95
  96 WHYINT  [RH(DSTSTB(sidx)) -> devWHY]
  97
  98 RCHST, RFNAME   [LH(DRFNTB(sidx)) -> devRCH]
  99
 100 RFPNTR  [RH(DRFNTB(sidx)) -> devRFP]
 101
 102 IOPUSH, IOPOP   [LH(RSTB1(ridx)) -> devIOP]
 103
 104 RESET   [RH(RSTB1(ridx)) -> devRST]
 105         Context:
 106                 R/ addr of IOCHNM wd
 107         Called by JRST from NRESET/ARESET/AIOPP1, must return by POPJ.
 108         Can clobber all ACs.  Must not hang.
 109
 110 FORCE   [LH(DFRCTB(ridx)) -> devFRC]
 111         Context:
 112                 A/ LH of IOCHNM word, in RH.
 113                 H/ IOCHNM word
 114                 R/ <LH of CLSTB entry>,,<addr of IOCHNM word>
 115         Called by JRST from NFORCE.  Returns by POPJ1 for win,
 116         POPJ if fail.  Should not clobber context that FINISH routine
 117         may need.
 118
 119 FINISH  [RH(DFRCTB(ridx)) -> devFIN]
 120         Same as FORCE, except that FORCE is called first, thus
 121         context is whatever FORCE leaves behind.  This routine
 122         must do the actual waiting for FORCE's actions to be
 123         finished.
 124
 125 |