home *** CD-ROM | disk | FTP | other *** search
/ HAM Radio 3 / hamradioversion3.0examsandprograms1992.iso / bbs / msys113 / hapnmsys.com / HAPN-API.DOC next >
Text File  |  1991-01-13  |  14KB  |  442 lines
  1.  
  2.  
  3. HAPN1.SYS DEVICE DRIVER
  4.  
  5.  
  6.  
  7. (C) Copyright Hamilton and Area Packet Network 1990
  8.  
  9.  
  10.  
  11. DESCRIPTION
  12.  
  13.  
  14. HAPN1.SYS is a  device driver that  supports the  8273 HDLC controller on the
  15. HAPN-1 adapter. In order to use it, it must be defined in the DOS  CONFIG.SYS
  16. file. DOS will then load it when the system is booted.
  17.  
  18. The  CONFIG.SYS entry appears as follows, where  items within square  brakets
  19. are optional:
  20.  
  21. device=[d:\path\]hapn1.sys [base=bbb][,irq=i][,cts=xx][,ttsiz=z]
  22.                            [,rxbuffers=rr][,txbuffers=tt]
  23.                            [,reserve=y/n][,pri=n][,tim=alt]
  24.  
  25. where bbb is the adapter 8273 base address (in hex) (i.e. 310).
  26.           The default value is 310.
  27.         i is the IRQ level. Values may be 0 through 7, and the
  28.           default value is 2.
  29.        rr is the number of Rx buffers to allocate. Minimum
  30.           number is 10, maximum number is 99, default number is 25.
  31.        tt is the number of Tx buffers to allocate. Minimum
  32.           number is 10, maximum number is 99, default number is 15.
  33.        xx is the clear-to-send delay in timer ticks (55 ms).
  34.           Values are 0 to 99, with default value 0.
  35.         z is the size of the trace table in kbytes. May be between
  36.           1 and 9. The default value is 4. Set it smaller to conserve
  37.           memory and larger to do datastream debugging.
  38.     pri=n (priority=no) By default the driver will change the priority
  39.           on the PC's interrupt controller so that the adapter interrupt
  40.           has the highest priority. This parameter tells the driver to
  41.           leave the interrupt controller priority setting alone. Use
  42.           this parameter when you have more than one adapter installed,
  43.           to help you manage the interrupt priorities. If the adapter
  44.           interrupt priority is not high enough, you will get numerous
  45.           interrupt overruns and underruns.
  46.   tim=alt tells the driver to use int 1c (hex) for the timer tick
  47.           interrupt instead of int 8. Int 8 is generally more reliable
  48.           when programs are run that use the timer tick interrupt but
  49.           do not share it properly; however in some cases it may be
  50.           desired to use int 1c instead.
  51.  
  52. The  device  driver contains all  the HAPN-1 adapter hardware  specific  code
  53. (level 1). It is used by M25.COM, which provides the AX.25 support (level 2).
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64. HAPN1.SYS Device Driver                                                     1
  65.  
  66. PROGRAMMING INTERFACE
  67.  
  68.  
  69. Although  the driver may be opened as a DOS file,  it  does  not provide  I/O
  70. services via  DOS. This  is because DOS is not re-entrant, and  M25  must get
  71. access to the HAPN-1 driver from the timer tick  interrupt. If the timer tick
  72. interrupt  occurs while  an application program  is  accessing  DOS  for some
  73. function, and M25 tried to access HAPN1.SYS via DOS,  the system would crash.
  74. Therefore, an alternate means is  provided for programs such as M25 to access
  75. the functions within HAPN1.SYS without using DOS.
  76.  
  77. Programs wishing to access HAPN1.SYS directly may do so as follows:
  78.  
  79. 1.  Issue DOS OPEN to file with name  "HAPN1-A1" for adapter 1 and "HAPN1-A2"
  80.     for adapter 2.
  81.  
  82. 2.  Using  the handle returned from the open, issue  a  DOS IOCTL  READ for 4
  83.     bytes  of data. The 4 bytes are the long address of the HAPN1.SYS program
  84.     interface.
  85.  
  86. 3.  Issue DOS CLOSE.
  87.  
  88. The interface is then  accessed by  loading  a request  code in ah  register,
  89. possibly loading other registers,  and issuing a far call to the api address.
  90. From assembler this  is simply done by a call  instruction.  Other  languages
  91. must  provide a means to  load  registers  (including segment  registers) and
  92. issue  a far call.  (CI C/86 provides a  function  called farcall  which does
  93. this.)
  94.  
  95. The api function code goes  in ah for every call.  For most calls, a  port id
  96. goes in al. Port ids are  integers starting with  0.  Use  the "Get number of
  97. ports..." api function call to find out how  many ports  are supported by the
  98. driver. If you  use an invalid port id, calls to the  api will do nothing and
  99. return error if possible. (Note: the HAPN-1  supports only one port,  port 0.
  100. However multi-ported adapters may be available in the future.)
  101.  
  102.  
  103.  
  104. Activate Driver
  105.  
  106.  
  107. Load  ah  with 0  and call the api.  The  driver will be  activated and start
  108. receiving  packets. If  the  driver is  already active, the  8273  port B  is
  109. updated. There is no return code.
  110.  
  111.  
  112.  
  113. De-activate Driver
  114.  
  115.  
  116. Load ah with 1 and call the  api. The  driver will be  de-activated.  If  the
  117. driver is already inactive, -1 is returned in AX, otherwise 0 is returned.
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127. HAPN1.SYS Device Driver                                                     2
  128.  
  129. Read a Frame
  130.  
  131.  
  132. Load ah with 2, load es:di  with the address of  a  buffer,  load cx with the
  133. size of the  buffer,  and load al with the port number.  Call  the api.  If a
  134. frame  is available, it will be  moved to your buffer and the number of bytes
  135. returned in ax. If no frame is available,  ax will be returned with 0. If the
  136. frame is  larger than your buffer, only the amount requested will be returned
  137. and the rest discarded.  Use  the  "get maximum frame  size"  api function to
  138. find out the size of the HAPN-1 internal buffer.
  139.  
  140.  
  141.  
  142. Write a Frame
  143.  
  144.  
  145. Load ah with 3,  load es:di with the  address of the buffer, load cx with the
  146. length  of  data  in the buffer, and  load  al with  the port  number.  If  a
  147. transmit buffer is available, your frame will be copied in and the  number of
  148. bytes  returned in ax. If no  transmit  buffers  are  available,  ax will  be
  149. returned with 0. If your data is longer than the size of the transmit buffer,
  150. only the transmit buffer  length will be copied and transmitted, and the rest
  151. discarded.  In  this  case ax  will  contain  the  number of  bytes  actually
  152. accepted. Use the "get maximum frame size" api function  to find out the size
  153. of the HAPN-1 internal buffer.
  154.  
  155.  
  156.  
  157. Request Transmission
  158.  
  159.  
  160. Load ah with 4, and load al with the port number.  Call the  api.  Any frames
  161. in the Tx buffers will be transmitted. The RTS signal  will be  asserted, and
  162. the frames  transmitted after the clear-to-send delay number  of  timer ticks
  163. have  elapsed. (The CTS delay defaults to  0 or whatever was on the HAPN1.SYS
  164. command  line, and  may  be changed  using the "set  Clear-To-Send delay" api
  165. function.)  The driver does not test for carrier  detect before transmitting.
  166. It is the user's responsibility to do this and issue this api function at the
  167. appropriate time. If  necessary,  use  the  "get carrier  detect  state"  api
  168. function to test the channel.
  169.  
  170.  
  171.  
  172. Get Driver Status
  173.  
  174.  
  175. Load ah with 5 and call the api. On  return,  ax  will be 0 if  the driver is
  176. inactive, and 1 if the driver is active.
  177.  
  178.  
  179.  
  180. Get Trace Table Data
  181.  
  182.  
  183. Load ah  with 6,  load es:di with the  address of a  buffer, load cx with the
  184. size of the buffer,  and load  al with  the port  number.  Call  the api. The
  185. trace table will be returned in your buffer, up to the size passed in cx. The
  186. buffer  should  be  large  enough  for  the  whole  trace table, since  it is
  187. wrap-around. The size may be obtained  from  the  "get  trace table size" api
  188.  
  189.  
  190. HAPN1.SYS Device Driver                                                     3
  191.  
  192. function,  described below.  The  trace table includes  a 4-byte  header. The
  193. header  consists of 2 words, the first being the size of the data area of the
  194. trace table, and the second being the offset to the  next  byte to use in the
  195. data area.
  196.  
  197.  
  198.  
  199. Get Statistical Counters
  200.  
  201.  
  202. Load ah with 7, load es:di with the address of a buffer, and load cx with the
  203. size of the  buffer,  and load al with  the port  number.  Call the  api. The
  204. statistical counters  will be returned in your buffer, up to the size  passed
  205. in cx. The statistical counters are all long (4 bytes), and the buffer should
  206. be 100 bytes (i.3. 25 counters).
  207.  
  208.  
  209.  
  210. Get Carrier Detect State
  211.  
  212.  
  213. Load ah with 8, and  load  al with the port number.  Call the api. On return,
  214. ax will be 0 if there is no carrier detect, 1 if there is carrier detect, and
  215. -1 if the status cannot be determined.  Indeterminant  carrier  detect occurs
  216. when the driver is transmitting and  cannot  test the channel. In this  case,
  217. the application should interpret the channel as busy.
  218.  
  219.  
  220.  
  221. Set 8273 Port B
  222.  
  223.  
  224. Load ah with 9, put the port B state in cl, and load al with the port number.
  225. Call  the api.  For the  change  to become  effective, the adapter  should be
  226. activated  after changing port B.  (Activating the driver when it is  already
  227. active is OK and will do nothing except reset port B.)
  228.  
  229.  
  230.  
  231. Get Trace Table Size
  232.  
  233.  
  234. Load ah with 10 and load al with  the port number.  Call the  api. On return,
  235. ax will contain the trace table size, including the header.
  236.  
  237.  
  238.  
  239. Set Clear-To-Send Delay
  240.  
  241.  
  242. Load  ah with 11, put the CTS delay in cx, and  load al with the port number.
  243. Call the api. The CTS delay is measured in timer ticks, where one tick equals
  244. 55  milliseconds.  Note that the default  value is  zero (no delay) which  is
  245. only suitable where a hardware CTS is available. Otherwise, a value between 2
  246. and 6 is suitable for most rigs. (Note that when the delay is not 0, there is
  247. uncertainty  of up to one tick, which  is the time  between when the transmit
  248. order was received and the next timer tick,  so  use  the next higher value.)
  249. The  CTS delay  may  also be set as one of  the parameters when the driver is
  250. installed, in which case it will override the default value of zero.
  251.  
  252.  
  253. HAPN1.SYS Device Driver                                                     4
  254.  
  255. Reset the 8273
  256.  
  257.  
  258. Load ah with 12, and load al with the  port number.  Call  the  api. The 8273
  259. will be reset.
  260.  
  261.  
  262.  
  263. Get HAPN-1.SYS size
  264.  
  265.  
  266. Load  ah with 13  and call the api. On  return,  ax will contain the size the
  267. driver occupies in memory.
  268.  
  269.  
  270.  
  271. Get transmitter status
  272.  
  273.  
  274. Load ah with  14, and load al  with the  port  number, and  call the api.  On
  275. return, ax will contain 0 if the transmitter is idle and 1 if the transmitter
  276. is busy.
  277.  
  278.  
  279.  
  280. Get number of ports for this driver
  281.  
  282.  
  283. Load ah with 15  and call the api. On return  ax will contain the  number  of
  284. ports available in this driver. Generally, the number of ports will be 1  but
  285. may be 2 or more.
  286.  
  287.  
  288.  
  289. Get maximum frame size
  290.  
  291.  
  292. Load ah with 16 and call the api. On return ax will contain the largest frame
  293. that can be received or transmitted  by this  driver.  The size  includes the
  294. ax.25 address field.
  295.  
  296.  
  297.  
  298. Get duplex mode
  299.  
  300.  
  301. Load ah with 17 and  call the api. On return ax will contain  0 for HDX and 1
  302. for FDX.
  303.  
  304.  
  305.  
  306. Query Rx Data Available
  307.  
  308.  
  309. Load  ah with 18 and the physical port id in al, and call the api.  On return
  310. ax will contain 0 if no Rx data is avilable, or  the length of the next frame
  311. if available.
  312.  
  313.  
  314.  
  315.  
  316. HAPN1.SYS Device Driver                                                     5
  317.  
  318. Set duplex mode
  319.  
  320.  
  321. Load ah with 19 and cl with 0 (HDX) or 1 (FDX) and call the api.
  322.  
  323.  
  324.  
  325. Query reserve status
  326.  
  327.  
  328. Load ah  with  20 and call the api. If reserve=y was specified on the command
  329. line, 1 will be returned, otherwise 0 will be returned in ax.
  330.  
  331.  
  332.  
  333. Query if any Tx buffers available
  334.  
  335.  
  336. Load ah with 21 and al with the physical port id, and call the api.  If there
  337. is at least one Tx buffer free 1 is returned in ax, otherwise 0 is returned.
  338.  
  339.  
  340.  
  341. Get port name
  342.  
  343.  
  344. Load ah with 22 and al with the physical port  id, and place the address of a
  345. 30-byte buffer in es:di.  On return,  the  name of the port is  moved  to the
  346. buffer, as a null-terminated string.
  347.  
  348.  
  349.  
  350. TRACE TABLE DESCRIPTION
  351.  
  352.  
  353. The trace  table consists of a four byte header and  a quantity of data.  The
  354. header contains a 2-byte integer specifying  the  length of the  data,  and a
  355. 2-byte  integer  specifying the offset in the data area to the location where
  356. the next byte will be entered. The data area wraps around from the  bottom to
  357. the top, so the 2nd header integer points to where the oldest byte is. As new
  358. data is written over old data in  the table, the  oldest  entry may be partly
  359. overwritten, and will  therefore be  incomplete.  The table is initialized to
  360. nulls and nulls are interpreted as unused areas.
  361.  
  362. Each trace table entry has the following format:
  363.  
  364.     One byte code (alphabetic) defining the entry type.
  365.  
  366.     Four byte time stamp. This is present in all entries  except Rx  data and
  367.     Tx data. The time stamp is  a long integer and consists of the timer tick
  368.     counter in the driver.  Therefore, the  resolution is only in units of 55
  369.     ms. and cannot distinguish events between timer ticks.
  370.  
  371.     Zero or more bytes of data for the entry.
  372.  
  373.  
  374.  Code   Additional Data                          Description Of Entry
  375. ======  =======================================  ===========================
  376. B (42)  Rx-byte                                  8273 byte received
  377.  
  378.  
  379. HAPN1.SYS Device Driver                                                     6
  380.  
  381. C (43)                                           8273 Rx command issued
  382. D (44)  Tx-byte                                  8273 byte transmitted
  383. E (45)  8273-stat-reg hapn1-stat-1 hapn1-stat-2  8273 Rx results malfunction
  384. F (46)                                           Timer: Raise RTS
  385. G (47)                                           HAPN-1 activate driver
  386. H (48)                                           8273 Tx timeout error
  387. K (4B)                                           HAPN-1 deactivate driver
  388. M (4D)                                           Disable Rx before Tx
  389. P (50)                                           8273 reset
  390. Q (51)                                           Enable 8273 rcv after reset
  391. R (52)                                           TxInt: Rx command issued
  392. S (53)  8273-status-reg                          8273 unknown interrupt
  393. T (54)                                           8273 Rx timeout error
  394. X (58)  8273-ric rx-len-lsb rx-len-msb ctrl-byte 8273 Rx result
  395. Y (59)  8273-tic                                 8273 Tx result
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442. HAPN1.SYS Device Driver                                                     7