home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / utilsm / psionics / devices < prev    next >
Text File  |  1995-01-17  |  26KB  |  740 lines
  1. PSIONICS FILE - DEVICES
  2. =======================
  3. Device driver interfaces
  4. Last modified 1994-09-13
  5. ========================
  6.  
  7. This document describes all known functions for all known device drivers. It
  8. does not include file IO, even when done through the same interfaces.
  9.  
  10. The device drivers documented are:
  11.   SND: Sound device
  12.   TIM: Timer device
  13.   ALM: Alarm device
  14.   WLD: World device
  15.   TTY: Serial port device
  16.   PAR: Parallel port device
  17.   FRC: Free running counter
  18.   XMD: XModem driver
  19.   YMD: YModem driver
  20.   Console device
  21.  
  22.  
  23. Types of device driver
  24. ----------------------
  25. On the Series 3, much functionality, including the filing system, is provided
  26. via device drivers. There are three kinds of device drivers:
  27. * physical device drivers: these drive the hardware directly
  28. * base logical device drivers: these provide a basic abstraction for working
  29.   with logical device drivers
  30. * stacked logical device drivers: these provide higher levels of abstraction
  31. Only logical device drivers need to know about physical device drivers; all
  32. user applications operate through logical device drivers.
  33.  
  34. For example, the 3-Link pod and cable might be accessed through a physical
  35. device driver called TTY.LNK: (all physical device drivers have a two part
  36. name). This is automatically loaded the first time that the logical device
  37. driver TTY: is opened, and TTY: will use it to actually communicate with the
  38. pod.
  39.  
  40. When TTY: is opened, the kernel will return a handle. Read and write operations
  41. on that handle will send data directly to and from the port. Alternatively,
  42. the XMD: device driver could be stacked on top of TTY: on that handle. Once
  43. this has been done, read and write on that handle will now be done via the XMD:
  44. driver, which wraps the data in the XModem protocol and calls the TTY: driver
  45. to do the actual output. There is no limit to how many device drivers can be
  46. stacked upon one another.
  47.  
  48.  
  49. Opening a handle
  50. ----------------
  51. A base logical device driver is opened with the IOOPEN keyword or the IoOpen
  52. system call; a stacked logical device driver is opened with IoOpen. The name is
  53. examined to see whether it has a colon as the fourth character but not the
  54. fifth; if so, it is split into a device name and a channel name. The kernel
  55. then checks that the logical device exists; if not, or if the name does not
  56. have the correct form, it prefixes "FIL:" to the name and tries again (FIL
  57. is the filing system logical device driver). For example:
  58.     "SND:"        device "SND"  channel name ""
  59.     "TTY:A"       device "TTY"  channel name "A"
  60.     "FIL:A:XXX"   device "FIL"  channel name "A:XXX"
  61.     "HELLO.TXT"   device "FIL"  channel name "HELLO.TXT"
  62.     "ROM::XXX"    device "FIL"  channel name "ROM::XXX"
  63.     "FIL:TTY:"    device "FIL"  channel name "TTY:"
  64.     "QXV:"        device "FIL"  channel name "QXV:"
  65. [the last example assumes there is no QXV device driver].
  66.  
  67. The filing system and the FIL: driver are described in the Psionics file
  68. FILEIO. All other known drivers are described here.
  69.  
  70. IOOPEN and IoOpen are passed a mode to open the device or file. Drivers other
  71. than the filing system and those specifically mentioning it ignore the mode.
  72. It is recommended that a mode of -1 be used, as this is always rejected by the
  73. filing system; thus an error in the device name or a missing driver will be
  74. detected.
  75.  
  76. A driver may refuse to open a given channel name, or all channels, more than
  77. a certain number of times without closing some first. For example, a TTY
  78. driver might only allow one open handle at a time for each port.
  79.  
  80.  
  81. Using the device driver
  82. -----------------------
  83. Once a device driver has been opened, it is accessed with the keywords IOW,
  84. IOA, and IOC (Series 3a only). These keywords offer the same services, and
  85. differ only in the way completion is indicated.
  86.  
  87. IOW waits until the operation completes, and then returns. No signal is
  88.     generated.
  89. IOA has an extra status variable argument. The variable is set to -46 at the
  90.     start of the operation, and then to the final result when it completes; a
  91.     signal is generated at this moment (it can be collected with IOWAIT or
  92.     IOWAITSTAT). Note that some operations complete immediately, and so the
  93.     status of -46 is never seen.
  94. IOC is like IOA, but if the operation completes immediately, it places the
  95.     result into the status variable and generates a signal. Thus the code
  96.     making the call can check the result in one place (after collecting the
  97.     signal) rather than two (after the call and after the signal).
  98.  
  99. Each call is passed a function number and two parameters for passing other
  100. information. The latter identify blocks of memory; the actual argument can be
  101. either the name of an OPL variable (typically the first element of an array),
  102. in which case that variable marks the start of the block, or it can be the #
  103. operator applied to the address of the block. The former is equivalent to
  104. #ADDR(variable).
  105.  
  106. If the parameter is shown as "unused", then any variable or value can be used,
  107. as it will be ignored; it is often convenient to use #0 as such an argument.
  108.  
  109. Unless stated otherwise, a successful call returns zero, and an unsuccessful
  110. call some non-zero error code.
  111.  
  112.  
  113. Standard functions
  114. ------------------
  115.  
  116. These functions apply to all drivers.
  117.  
  118. Function:   1 (read)
  119. Function:   2 (write)
  120. Argument 1: buffer
  121. Argument 2: count (word)
  122.  
  123. These functions are equivalent to the IOREAD and IOWRITE keywords. They read
  124. or write up to the specified number of bytes from or to the device; in the
  125. case of function 1, the count is changed to the actual amount read.
  126.  
  127. These functions can be used with any handle that is using a driver labelled
  128. as a data driver (such as the serial port device or the XModem driver).
  129.  
  130.  
  131. Function:   3
  132. Argument 1: unused
  133. Argument 2: unused
  134.  
  135. This will close the handle; it is equivalent to the IOCLOSE keyword.
  136.  
  137.  
  138. Function:   4
  139. Argument 1: unused
  140. Argument 2: unused
  141.  
  142. This will cancel any uncompleted function on the handle; the function will
  143. complete immediately, with the status variable set to -48 ("I/O cancelled").
  144. A signal will still be generated, and must be collected with IOWAITSTAT or
  145. IOWAIT.
  146.  
  147.  
  148. Sound device
  149. ------------
  150.  
  151. The sound device has the name "SND:". There are no channel names.
  152.  
  153.  
  154. Function:   1 (sound channel 1)
  155. Function:   2 (sound channel 2)
  156. Argument 1: note information
  157. Argument 2: word holding number of notes
  158. This function is supported by the HC, MC, and Series 3a only.
  159.  
  160. This plays a sequence of notes on the specified sound channel. The note
  161. information is an array of words, two per note; the first is the frequency of
  162. the note (in Hz), and the second the duration in beats (see function 7).
  163. The sound will not start until both these functions have been called (thus
  164. ensuring the sound is synchronized on both channels). The function completes
  165. when the specified channel finishes playing, even if the other has not.
  166.  
  167.  
  168. Function:   7
  169. Argument 1: 2 byte information block
  170. Argument 2: unused
  171.  
  172. The characteristics of the sound system are set according to the block:
  173.   Offset  0 (byte): beats per minute (2 to 240, default 120)
  174.   Offset  1 (byte): volume (0 max to 5 min)
  175. The beats per minute is only supported by the HC, MC, and Series 3a. On the
  176. Series 3a, volumes 1 and 2 are identical, as are 4 and 5. On the Series 3s,
  177. volumes 0 and 5 are unavailable.
  178.  
  179.  
  180. Function:   8
  181. Argument 1: 2 byte information block
  182. Argument 2: unused
  183.  
  184. The block is filled in with information about the sound channel, using the
  185. same format as function 7.
  186.  
  187.  
  188. Function:   9
  189. Argument 1: alarm type (0 = rings, 1 = chimes)
  190. Argument 2: unused
  191.  
  192. The specified alarm is played; this function completes when the sound has
  193. completely played.
  194.  
  195.  
  196. Function:   10
  197. Argument 1: phone number (cstr)
  198. Argument 2: parameter block
  199.  
  200. This generates DTMF dialling sounds. The number contains the digits to be
  201. dialled (0 to 9, *, #, and A to F can be used; E is the same as *, and F the
  202. same as #). The parameter block has the format:
  203.   Offset 0 (byte): tone length   )
  204.   Offset 1 (byte): delay length  ) all in 1/32 seconds
  205.   Offset 2 (word): pause length  )
  206.  
  207.  
  208.  
  209. Timer device
  210. ------------
  211.  
  212. The timer device has the name "TIM:". There are no channel names.
  213.  
  214. Function:   1
  215. Argument 1: delay in 1/10 seco