home *** CD-ROM | disk | FTP | other *** search
/ Chip 1994 February / CHIP0294.ISO / digital / magazin / trumpet / pktdrvs / packet_d.109 < prev    next >
Encoding:
Text File  |  1992-08-04  |  38.1 KB  |  1,387 lines
  1.  
  2.  
  3.  
  4. PC/TCP Version 1.09 Packet Driver Specification                           1
  5. FTP Software, Inc.
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.             PC/TCP Packet Driver Specification
  13.  
  14.  
  15. Revision 1.09
  16. September-14-1989
  17. Developed by:
  18.  
  19. FTP Software, Inc.
  20. 26 Princess St.
  21. Wakefield, MA  01880-3004
  22. (617) 246-0900
  23.  
  24.  
  25. Copyright (c) 1986, 1989 by FTP Software Inc.     Permission  is  granted to
  26. reproduce and distribute this document    without  restriction  or  fee. This
  27. document  may  be   re-formatted   or    translated,   but   the  functional
  28. specification  of the programming interface described  herein  may  not  be
  29. changed  without  FTP  Software's permission.  FTP Software's name and this
  30. notice     must    appear     on  any  reproduction    of  this  document.    This
  31. specification was originally developed at FTP Software by John Romkey.
  32.  
  33. Support of a hardware interface, or mention of    an  interface manufacturer,
  34. by the Packet Driver specification does not necessarily  indicate  that the
  35. manufacturer endorses this specification.
  36.  
  37.  
  38. 1  Document Conventions
  39.  
  40.  
  41. All numbers in this document are given in  C-style  representation. Decimal
  42. is expressed as 11, hexadecimal is expressed as 0x0B, octal is expressed as
  43. 013.  All reference to    network hardware addresses (source, destination and
  44. multicast) and demultiplexing information for  the  packet  headers assumes
  45. they  are  represented    as they would be in a MAC-level packet header being
  46. passed to the send_pkt() function.
  47.  
  48.  
  49. 2  Introduction and Motivation
  50.  
  51.  
  52. This document describes the  programming  interface  to FTP Software Packet
  53. Drivers.  Packet drivers provide  a  simple,  common  programming interface
  54. that allows multiple applications to share a network interface at  the data
  55. link  level.  The packet drivers demultiplex  incoming    packets  among    the
  56. applications by using the network media's standard packet  type  or service
  57. access point field(s).
  58.  
  59. The intent of this specification is to allow protocol stack implementations
  60. to  be independent of the actual brand or model of the network interface in
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. 2                PC/TCP Version 1.09 Packet Driver Specification
  71.                              FTP Software, Inc.
  72.  
  73.  
  74. use on a particular machine.  Different versions of various protocol stacks
  75. still must exist for different    network media (Ethernet, 802.5 ring, serial
  76. lines),  because  of  differences  in protocol-to-physical address mapping,
  77. header formats, maximum transmission units (MTUs) and so forth.
  78.  
  79. The packet driver provides calls to initiate access to    a  specific  packet
  80. type, to  end  access  to  it,    to  send a packet, to get statistics on the
  81. network interface and to get information about the interface.
  82.  
  83. Protocol implementations  that use the packet driver can completely coexist
  84. on a PC and can  make  use  of    one  another's    services,  whereas multiple
  85. applications which do  not  use  the  driver  do not coexist on one machine
  86. properly.   Through use of the packet driver, a user could run TCP/IP, XNS,
  87. and  a    proprietary  protocol  implementation  such  as  DECnet,  Banyan's,
  88. LifeNet's, Novell's or 3Com's without the difficulties associated with pre-
  89. empting the network interface.
  90.  
  91. Applications  which  use the packet driver can    also  run  on  new  network
  92. hardware of the same class without being modified; only a new packet driver
  93. need be supplied.
  94.  
  95. Several levels of packet drivers are described in  this  specification. The
  96. first is the basic packet  driver, which provides minimal functionality but
  97. should    be simple to implement and which uses very few host resources.    The
  98. basic driver provides operations  to  broadcast  and  receive packets.    The
  99. second driver is the extended packet driver, which  is    a  superset  of the
  100. basic driver.  The extended driver supports less commonly used functions of
  101. the network interface such as multicast, and also gathers statistics on use
  102. of the interface and makes these available to the  application.  The  third
  103. level, the high-performance functions, support performance improvements and
  104. tuning.
  105.  
  106. Functions which are available in only the extended packet driver  are noted
  107. as such  in  their  descriptions.    All  basic packet driver functions are
  108. available  in  the  extended driver.  The high-performance functions may be
  109. available with either basic or extended drivers.
  110.  
  111.  
  112. 3  Identifying network interfaces
  113.  
  114.  
  115. Network interfaces are    named  by  a  triplet  of  integers,  <class, type,
  116. number>.  The first number is the class of interface.  The class tells what
  117. kind of media the interface  supports:    DEC/Intel/Xerox  (DIX  or Bluebook)
  118. Ethernet, IEEE 802.3 Ethernet, IEEE 802.5 Token Ring, ProNET-10, Appletalk,
  119. serial line, etc.
  120.  
  121. The second number  is  the  type  of interface: this specifies a particular
  122. instance of an interface  supporting  a class of network medium.  Interface
  123. types for Ethernet  might  name  these    interfaces:  3Com  3C503  or 3C505,
  124. Interlan NI5210, Univation, BICC Data Networks ISOLAN,    Ungermann-Bass NIC,
  125. etc.  Interface types for IEEE 802.5 might name these interfaces: IBM Token
  126. Ring adapter, Proteon p1340, etc.
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PC/TCP Version 1.09 Packet Driver Specification                           3
  137. FTP Software, Inc.
  138.  
  139.  
  140. The last  number  is  the  interface number.  If a machine is equipped with
  141. more  than  one  interface  of    a  class  and type, the interfaces must  be
  142. numbered to distinguish between them.
  143.  
  144. An  appendix  details  constants for classes and types.  The  class  of  an
  145. interface is an 8-bit integer, and its type is a 16 bit integer.  Class and
  146. type  constants are managed by FTP Software.  Contact FTP to register a new
  147. class or type number.
  148.  
  149. The  type  0xFFFF  is a wildcard type which matches any  interface  in    the
  150. specified class.   It  is  unnecessary    to wildcard interface numbers, as 0
  151. will always correspond to the first interface of the  specified  class    and
  152. type.
  153.  
  154. This specification has no  provision  for  the    support of multiple network
  155. interfaces (with  similar or different characteristics) via a single Packet
  156. Driver and associated interrupt.  We feel that this issue is best addressed
  157. by  loading  several  Packet  Drivers,    one per interface,  with  different
  158. interrupts (although all may be included in a single TSR  software module).
  159. Applications  software    must  check the class  and  type  returned  from  a
  160. driver_info()  call in any case, to make sure that the Packet Driver is for
  161. the correct media and packet format.  This  can  easily  be  generalized by
  162. searching for another Packet Driver if the first is not of the right kind.
  163.  
  164.  
  165. 4  Initiating driver operations
  166.  
  167.  
  168. The packet driver is invoked via a software  interrupt    in  the  range 0x60
  169. through 0x80.  This  document  does not specify a particular interrupt, but
  170. describes a mechanism for locating which interrupt the driver  uses.    The
  171. interrupt  must be configurable to avoid conflicts  with  other  pieces  of
  172. software that also use software  interrupts. The program which installs the
  173. packet driver should  provide  some  mechanism    for the user to specify the
  174. interrupt.
  175.  
  176. The handler  for  the  interrupt  is  assumed  to  start  with    3  bytes of
  177. executable code; this can either be a 3-byte jump instruction, or  a 2-byte
  178. jump  followed by a NOP (do not specify "jmp short" unless you also specify
  179. an explicit NOP).  This must be followed by the null-terminated  ASCII text
  180. string    "PKT  DRVR".  To find the interrupt being used by  the    driver,  an
  181. application should scan through the  handlers for vectors 0x60 through 0x80
  182. until  it  finds  one with the text string  "PKT  DRVR"  in  the  12  bytes
  183. immediately following the entry point.
  184.  
  185.  
  186. 5  Link-layer demultiplexing
  187.  
  188.  
  189. If a network  media  standard  is  to support simultaneous use by different
  190. transport protocols (e.g. TCP/IP, XNS, OSI), it must define some link-level
  191. mechanism which allows a host to decide which protocol a packet is intended
  192. for.  In  DIX  Ethernet,  this    is the 16-bit "ethertype" field immediately
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. 4                PC/TCP Version 1.09 Packet Driver Specification
  203.                              FTP Software, Inc.
  204.  
  205.  
  206. following the 6-byte destination and source addresses.    In IEEE 802.3 where
  207. 802.2  headers    are  used, this information is in the variable-length 802.2
  208. header.  In Proteon's ProNET-10, this is done via the 32-bit  "type" field.
  209. Other media standards may demultiplex via  a  method of their own, or 802.2
  210. headers as in 802.3.
  211.  
  212. Our   access_type()   function     provides   access   to   this     link-layer
  213. demultiplexing.  Each call establishes    a destination for a particular type
  214. of  link-layer    packet,  which remains in effect  until  release_type()  is
  215. called with the handle returned by that particular access_type(). The link-
  216. layer demultiplexing information is passed via the type and typelen fields,
  217. but values and    interpretation    depend    on  the class of packet driver (and
  218. thus on the media in use).
  219.  
  220. A class  1  driver  (DIX  Ethernet)  should  expect  type  to  point  at an
  221. "ethertype" value (in network  byte  order,  and  greater than 0x05EE), and
  222. might reasonably require typelen to  equal  2.      A  class  2  driver could
  223. require 4  bytes.    However,  a class 3 (802.5) or 11 (Ethernet with 802.2
  224. headers) driver should be prepared for typelen values between  2  (for    the
  225. DSAP/SSAP fields only) and  8  (3 byte 802.2 header plus 3-byte Sub-Network
  226. Access Protocol extension header plus  2-byte "ethertype" as defined in RFC
  227. 1042).
  228.  
  229.  
  230. 6  Programming interface
  231.  
  232.  
  233. All functions are accessed via the software interrupt determined to  be the
  234. driver's via the  mechanism  described    earlier.    On    entry,    register AH
  235. contains the code of the function desired.
  236.  
  237. The handle is an  arbitrary  integer  value  associated with each MAC-level
  238. demultiplexing type that has been  established    via  the  access_type call.
  239. Internally  to the packet driver, it will probably be a pointer, or a table
  240. offset.   The application calling the packet driver  cannot  depend  on  it
  241. assuming  any  particular   range,   or  any  other  characteristics.     In
  242. particular,  if an application uses two or  more  packet  drivers,  handles
  243. returned by different drivers for the same or different types may  have the
  244. same value.
  245.  
  246. Note  that some of the functions defined below    are  labelled  as  extended
  247. driver functions and  high-performance    functions.  Because  these  are not
  248. required  for  basic  network  operations,  their  implementation   may  be
  249. considered  optional.     Programs wishing to use these functions should use
  250. the driver_info() function to determine if they are available  in  a  given
  251. packet driver.
  252.  
  253.  
  254.  
  255. 6.1  Entry conditions
  256.  
  257. FTP  Software  applications  which call the  packet  driver  are  coded  in
  258. Microsoft C and assembly language.  All necessary registers  are  saved  by
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. PC/TCP Version 1.09 Packet Driver Specification                           5
  269. FTP Software, Inc.
  270.  
  271.  
  272. FTP's  routines before the INT instruction to call  the  packet  driver  is
  273. executed.  Our current    receiver()  functions behave as follows: DS, SS, SP
  274. and the flags are saved and restored.  All other registers may be modified,
  275. and  should  be  saved    by  the  packet  driver,  if  necessary.  Processor
  276. interrupts may    be  enabled  while  in    the  upcall, but the upcall doesn't
  277. assume interrupts are disabled on entry.  On entry, receiver()    switches to
  278. a local stack, and switches back before returning.
  279.  
  280. Note that some older versions of PC/TCP may enable  interrupts    during    the
  281. upcall, and leave them enabled on return to the Packet Driver.
  282.  
  283. When  using a class 1 driver, PC/TCP will  normally  make  5  access_type()
  284. calls for IP, ARP and 3 kinds of Berkeley  Trailer  encapsulation  packets.
  285. On other media,  the number of handles we open will vary, but it is usually
  286. at least two (IP and ARP).  Implementors  should  make    their  tables large
  287. enough to allow two protocol stacks to co-exist.  We recommend    support for
  288. at least 10 open handles simultaneously.
  289.  
  290.  
  291. 6.2  Byte and Bit ordering
  292.  
  293. Developers  should  note  that, on many networks and protocol families, the
  294. byte-ordering of 16-bit quantities on the network is opposite to the native
  295. byte-order of the PC.  (802.5 Token Ring is an exception).  This means that
  296. DEC-Intel-Xerox ethertype values passed to  access_type()  must  be swapped
  297. (passed  in  network order).  The IEE  802.3  length  field  needs  similar
  298. handling, and care should be taken with packets passed    to  send_pkt(),  so
  299. all  fields  are  in the proper order.    Developers working  with  MSB  LANs
  300. (802.5    and  FDDI)  should be aware that a MAC address    changes  bit  order
  301. depending on whether it appears in the header or as data.
  302.  
  303.  
  304. 6.3  driver_info()
  305.  
  306.     driver_info(handle)    AH == 1, AL == 255
  307.         int    handle; BX        /* Optional */
  308.  
  309. error return:
  310.     carry flag set
  311.     error code        DH
  312.     possible errors:
  313.         BAD_HANDLE            /* older drivers only */
  314.  
  315. non-error return:
  316.     carry flag clear
  317.     version                 BX
  318.     class            CH
  319.     type            DX
  320.     number            CL
  321.     name            DS:SI
  322.     functionality        AL
  323.                        1 == basic functions present.
  324.                        2 == basic and extended present.
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. 6                PC/TCP Version 1.09 Packet Driver Specification
  335.                              FTP Software, Inc.
  336.  
  337.  
  338.                        5 == basic and high-performance.
  339.                        6 == basic, high-performance, extended.
  340.                        255 == not installed.
  341.  
  342. This  function returns information about the interface.    The    version  is
  343. assumed to be an internal hardware driver identifier.  In  earlier versions
  344. of  this  spec, the handle argument (which  must  have    been  obtained    via
  345. access_type()) was required.   It  is  now  optional, but drivers developed
  346. according to versions  of  this  spec  previous  to 1.07 may require it, so
  347. implementers should take care.
  348.  
  349.  
  350. 6.4  access_type()
  351.  
  352.     int access_type(if_class, if_type, if_number, type, typelen, receiver)    AH ==
  353. 2
  354.         int    if_class;        AL
  355.         int    if_type;        BX
  356.         int    if_number;        DL
  357.         char far *type;                 DS:SI
  358.         unsigned typelen;        CX
  359.         int    (far *receiver)();    ES:DI
  360.  
  361. error return:
  362.     carry flag set
  363.     error code            DH
  364.     possible errors:
  365.         NO_CLASS
  366.         NO_TYPE
  367.         NO_NUMBER
  368.         BAD_TYPE
  369.         NO_SPACE
  370.         TYPE_INUSE
  371.  
  372. non-error return:
  373.     carry flag clear
  374.     handle                AX
  375.  
  376. receiver call:
  377.     (*receiver)(handle, flag, len [, buffer])
  378.         int    handle;         BX
  379.         int    flag;        AX
  380.         unsigned len;        CX
  381.     if AX == 1,
  382.         char far *buffer;    DS:SI
  383.  
  384. Initiates  access to packets of the specified type.  The argument type is a
  385. pointer to a packet type specification.  The argument typelen is the length
  386. in  bytes  of  the  type  field.  The argument receiver is a pointer  to  a
  387. subroutine  which  is  called when a packet is received.   If  the  typelen
  388. argument  is  0,  this indicates that the caller wants to match all packets
  389. (match all requests may  be  refused by packet drivers developed to conform
  390. to versions of this spec previous to 1.07).
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. PC/TCP Version 1.09 Packet Driver Specification                           7
  401. FTP Software, Inc.
  402.  
  403.  
  404. When a packet is received, receiver  is  called twice by the packet driver.
  405. The first  time  it  is  called to request a buffer from the application to
  406. copy the packet into.  AX == 0 on this call.  The application should return
  407. a pointer to the buffer in ES:DI.  If the application  has  no    buffers, it
  408. may return 0:0 in ES:DI, and  the  driver  should throw away the packet and
  409. not perform the second call.
  410.  
  411. It is important  that  the packet length (CX) be valid on the AX == 0 call,
  412. so that the receiver can allocate a buffer of the proper size.    This length
  413. (as well as the copy  performed prior to the AX == 1 call) must include the
  414. MAC header and all received data, but not the trailing Frame Check Sequence
  415. (if any).
  416.  
  417. On  the  second  call, AX == 1.  This call indicates that the copy has been
  418. completed, and the application may do  as  it  wishes with the buffer.    The
  419. buffer that the packet was copied into is pointed to by DS:SI.
  420.  
  421.  
  422. 6.5  release_type()
  423.  
  424.     int release_type(handle)    AH == 3
  425.         int    handle;         BX
  426.  
  427. error return:
  428.     carry flag set
  429.     error code            DH
  430.     possible errors:
  431.         BAD_HANDLE
  432.  
  433. non-error return:
  434.     carry flag clear
  435.  
  436. This function ends access  to  packets associated with a handle returned by
  437. access_type().    The handle is no longer valid.
  438.  
  439.  
  440. 6.6  send_pkt()
  441.  
  442.     int send_pkt(buffer, length)    AH == 4
  443.         char far *buffer;    DS:SI
  444.         unsigned length;    CX
  445.  
  446. error return:
  447.     carry flag set
  448.     error code            DH
  449.     possible errors:
  450.         CANT_SEND
  451.  
  452. non-error return:
  453.     carry flag clear
  454.  
  455. Transmits length bytes of  data,  starting at buffer.  The application must
  456. supply the entire packet, including local network headers.  Any MAC  or LLC
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. 8                PC/TCP Version 1.09 Packet Driver Specification
  467.                              FTP Software, Inc.
  468.  
  469.  
  470. information in use  for  packet  demultiplexing  (e.g.    the DEC-Intel-Xerox
  471. Ethertype) must be filled in by  the  application  as well.  This cannot be
  472. performed  by  the  driver,  as  no  handle is specified in a call  to    the
  473. send_packet() function.
  474.  
  475.  
  476. 6.7  terminate()
  477.  
  478.     terminate(handle)        AH == 5
  479.         int    handle;         BX
  480.  
  481. error return:
  482.     carry flag set
  483.     error code            DH
  484.     possible errors:
  485.         BAD_HANDLE
  486.         CANT_TERMINATE
  487.  
  488. non-error return:
  489.     carry flag clear
  490.  
  491. Terminates the driver associated with handle.  If possible, the driver will
  492. exit and allow MS-DOS to reclaim the memory it was using.
  493.  
  494.  
  495. 6.8  get_address()
  496.  
  497.     get_address(handle, buf, len)    AH == 6
  498.         int    handle;         BX
  499.         char far *buf;        ES:DI
  500.         int    len;        CX
  501.  
  502. error return:
  503.     carry flag set
  504.     error code            DH
  505.     possible errors:
  506.         BAD_HANDLE
  507.         NO_SPACE
  508.  
  509. non-error return:
  510.     carry flag clear
  511.     length            CX
  512.  
  513. Copies the current local net address of the interface into buf.  The buffer
  514. buf is len bytes long.    The actual number of bytes  copied  is    returned in
  515. CX.    If  the    NO_SPACE  error  is  returned, this indicates that len    was
  516. insufficient to hold the local net address. If the address has been changed
  517. by set_address(), the new address should be returned.
  518.  
  519.  
  520. 6.9  reset_interface()
  521.  
  522.     reset_interface(handle)         AH == 7
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. PC/TCP Version 1.09 Packet Driver Specification                           9
  533. FTP Software, Inc.
  534.  
  535.  
  536.         int    handle;         BX
  537.  
  538. error return:
  539.     carry flag set
  540.     error code            DH
  541.     possible errors:
  542.         BAD_HANDLE
  543.         CANT_RESET
  544.  
  545. non-error return:
  546.     carry flag clear
  547.  
  548. Resets the interface associated with handle to a known state,  aborting any
  549. transmits in process and reinitializing the receiver. The local net address
  550. is  reset to the default (from ROM), the multicast list is cleared, and the
  551. receive mode is set to 3 (own address & broadcasts).    If multiple handles
  552. are open, these actions  might    seriously  disrupt other applications using
  553. the interface, so CANT_RESET should be returned.
  554.  
  555.  
  556. 6.10  get_parameters()
  557.  
  558. high-performance driver function
  559.     get_parameters()        AH = 10
  560.  
  561. error return:
  562.     carry flag set
  563.     error code            DH
  564.     possible errors:
  565.         BAD_COMMAND        /* No high-performance support */
  566.  
  567. non error return:
  568.     carry flag clear
  569.     struct param far *;        ES:DI
  570.  
  571.     struct param {
  572.     unsigned char    major_rev;    /* Revision of Packet Driver spec */
  573.     unsigned char    minor_rev;    /*  this driver conforms to. */
  574.     unsigned char    length;         /* Length of structure in bytes */
  575.     unsigned char    addr_len;    /* Length of a MAC-layer address */
  576.     unsigned short    mtu;        /* MTU, including MAC headers */
  577.     unsigned short    multicast_aval; /* Buffer size for multicast addr */
  578.     unsigned short    rcv_bufs;    /* (# of back-to-back MTU rcvs) - 1 */
  579.     unsigned short    xmt_bufs;    /* (# of successive xmits) - 1 */
  580.     unsigned short    int_num;    /* Interrupt # to hook for post-EOI
  581.                        processing, 0 == none */
  582.     };
  583.  
  584. The performance of  an    application may benefit from using get_parameters()
  585. to  obtain a number of driver parameters.  This function was added to v1.09
  586. of this  specification,  and  may  not    be  implemented by all drivers (see
  587. driver_info()).
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. 10                PC/TCP Version 1.09 Packet Driver Specification
  599.                              FTP Software, Inc.
  600.  
  601.  
  602. The major_rev and minor_rev fields are the major and minor revision numbers
  603. of the version    of  this  specification  the  driver conforms to.  For this
  604. document, major_rev is    1 and minor_rev is 9.  The length field may be used
  605. to  determine  which values are valid, should  a  later  revision  of  this
  606. specification  add  more  values at the end of this structure.      For  this
  607. document,  length is 14. The addr_len field is the length of a MAC address,
  608. in bytes. Note the param structure is assumed to be packed, such that these
  609. fields occupy four consecutive bytes of storage.
  610.  
  611. In the param structure, the mtu is the maximum MAC-level packet  the driver
  612. can  handle  (on Ethernet this number is fixed, but it may  vary  on  other
  613. media, e.g. 802.5  or  FDDI).     The  multicast_aval field is the number of
  614. bytes required to  store  all  the  multicast  addresses  supported  by any
  615. "perfect filter" mechanism in the hardware.    Calling set_multicast_list()
  616. with its len argument equal to this value should not  fail  with a NO_SPACE
  617. error.    A value of zero implies no multicast support.
  618.  
  619. The rcv_bufs and xmt_bufs indicate the number of  back-to-back    receives or
  620. transmits  the    card/driver  combination  can  accomodate,  minus  1.    The
  621. application can use this information  to  adjust  flow-control    or transmit
  622. strategies.  A single-buffered card (for example, an Interlan NI5010) would
  623. normally return 0 in both fields. A value of 0 in  rcv_bufs  could  also be
  624. used by a driver author to indicate that the hardware has limitations which
  625. prevent  it  from  receiving  as  fast    as  other systems can send, and  to
  626. recommend that the  upper-layer  protocols invoke lock-step flow control to
  627. avoid packet loss.
  628.  
  629. The  int_num  field  should  be  set  to  a  hardware  interrupt  that    the
  630. application can hook in order to perform interrupt-time protocol processing
  631. after the EOI has been sent to the 8259 interrupt  controller  and the card
  632. is  ready for more interrupts.    A value of zero indicates that there is  no
  633. such interrupt.  Any application hooking this interrupt and finding  a non-
  634. zero value in the vector must  pass  the  interrupt down the chain and wait
  635. for  its  predecessors    to return before performing any processing or stack
  636. switches.  Any    driver    which  implements  this function via a separate INT
  637. instruction and vector, instead of  just using the hardware interrupt, must
  638. prevent any saved context from being overwritten by a later interrupt.     In
  639. other words,  if  the  driver  switches to its own stack, it must allow re-
  640. entrancy.
  641.  
  642.  
  643. 6.11  as_send_pkt()
  644.  
  645. high-performance driver function
  646.     int as_send_pkt(buffer, length, upcall) AH == 11
  647.         char far *buffer;        DS:SI
  648.         unsigned length;        CX
  649.         int    (far *upcall)();    ES:DI
  650.  
  651. error return:
  652.     carry flag set
  653.     error code            DH
  654.     possible errors:
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664. PC/TCP Version 1.09 Packet Driver Specification                          11
  665. FTP Software, Inc.
  666.  
  667.  
  668.         CANT_SEND        /* transmit error, re-entered, etc. */
  669.         BAD_COMMAND        /* Level 0 or 1 driver */
  670.  
  671. non-error return:
  672.     carry flag clear
  673.  
  674. buffer available upcall:
  675.     (*upcall)(buffer, result)
  676.         int    result;         AX    /* 0 for copy ok */
  677.         char far *buffer;    ES:DI    /* from as_send_pkt() call */
  678.  
  679. as_send_pkt()  differs    from  send_pkt() in that the  upcall()    routine  is
  680. called when the application's data has    been  copied out of the buffer, and
  681. the application can safely modify or re-use the  buffer.    The  driver may
  682. pass a non-zero error code to  upcall()  if  the copy failed, or some other
  683. error  was  detected,  otherwise  it  should indicate success, even if    the
  684. packet hasn't actually been  transmitted  yet.    Note that the buffer passed
  685. to send_pkt() is assumed  to  be modifiable when that call returns, whereas
  686. with as_send_pkt(), the buffer may be  queued  by the driver and dealt with
  687. later.    If an error is returned on the initial call, the upcall will not be
  688. executed.  This function was added in v1.09 of this specification,  and may
  689. not be implemented by all drivers (see driver_info()).
  690.  
  691.  
  692. 6.12  set_rcv_mode()
  693.  
  694. extended driver function
  695.     set_rcv_mode(handle, mode)    AH == 20
  696.         int    handle;         BX
  697.         int    mode;        CX
  698.  
  699.  
  700. error return:
  701.     carry flag set
  702.     error code        DH
  703.     possible errors:
  704.         BAD_HANDLE
  705.         BAD_MODE
  706.  
  707. non-error return:
  708.     carry flag clear
  709.  
  710. Sets  the  receive  mode  on  the  interface  associated with  handle.    The
  711. following values are accepted for mode:
  712.  
  713. mode      meaning
  714.  
  715. 1      turn off receiver
  716. 2      receive only packets sent to this interface
  717. 3      mode 2 plus broadcast packets
  718. 4      mode 3 plus limited multicast packets
  719. 5      mode 3 plus all multicast packets
  720. 6      all packets
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. 12                PC/TCP Version 1.09 Packet Driver Specification
  731.                              FTP Software, Inc.
  732.  
  733.  
  734. Note that not all interfaces support  all  modes.  The receive mode affects
  735. all  packets  received    by this interface, not just packets associated with
  736. the   handle   argument.       See    the    extended     driver   functions
  737. get_multicast_list()  and  set_multicast_list()  for  programming  "perfect
  738. filters" to receive specific multicast addresses.
  739.  
  740. Note  that mode 3 is the default, and if the set_rcv_mode() function is not
  741. implemented, mode 3 is assumed to be in force as long  as  any    handles are
  742. open (from the first access_type() to the last release_type()).
  743.  
  744.  
  745. 6.13  get_rcv_mode()
  746.  
  747. extended driver function
  748.     get_rcv_mode(handle, mode)    AH == 21
  749.         int    handle;         BX
  750.  
  751.  
  752. error return:
  753.     carry flag set
  754.     error code            DH
  755.     possible errors:
  756.         BAD_HANDLE
  757.  
  758. non-error return:
  759.     carry flag clear
  760.     mode                AX
  761.  
  762. Returns the current receive mode of the interface associated with handle.
  763.  
  764.  
  765. 6.14  set_multicast_list()
  766.  
  767. extended driver function
  768.     set_multicast_list(addrlst, len)    AH == 22
  769.         char far *addrlst;    ES:DI
  770.         int    len;        CX
  771.  
  772. error return:
  773.     carry flag set
  774.     error code            DH
  775.     possible errors:
  776.         NO_MULTICAST
  777.         NO_SPACE
  778.         BAD_ADDRESS
  779.  
  780. non-error return:
  781.     carry flag clear
  782.  
  783. The addrlst argument is assumed to point to an len-byte buffer containing a
  784. number of multicast addresses.      BAD_ADDRESS is returned if len modulo the
  785. size of an address is  not equal to 0, or the data is unacceptable for some
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796. PC/TCP Version 1.09 Packet Driver Specification                          13
  797. FTP Software, Inc.
  798.  
  799.  
  800. reason.   NO_SPACE is returned (and no addresses are set) if there are more
  801. addresses than the hardware supports directly.
  802.  
  803. The recommended procedure for  setting    multicast  addresses  is to issue a
  804. get_multicast_list(),  copy  the  information to a local  buffer,  add    any
  805. addresses  desired,  and  issue  a  set_multicast_list().  This  should  be
  806. reversed when the application exits.  If the set_multicast_list() fails due
  807. to NO_SPACE, use set_rcv_mode() to set mode 5 instead.
  808.  
  809.  
  810. 6.15  get_multicast_list()
  811.  
  812. extended driver function
  813.     get_multicast_list()        AH == 23
  814.  
  815. error return:
  816.     carry flag set
  817.     error code            DH
  818.     possible errors:
  819.         NO_MULTICAST
  820.         NO_SPACE
  821.  
  822. non-error return:
  823.     carry flag clear
  824.     char far *addrlst;        ES:DI
  825.     int    len;            CX
  826.  
  827. On a successful return, addrlst points to len bytes of    multicast addresses
  828. currently in use.  The application program must not modify this information
  829. in-place.  A NO_SPACE error indicates that there wasn't enough room for all
  830. active multicast addresses.
  831.  
  832.  
  833. 6.16  get_statistics()
  834.  
  835. extended driver function
  836.     get_statistics(handle)        AH == 24
  837.         int handle;        BX
  838.  
  839. error return:
  840.     carry flag set
  841.     error code            DH
  842.     possible errors:
  843.         BAD_HANDLE
  844.  
  845. non-error return:
  846.     carry flag clear
  847.     char far *stats;        DS:SI
  848.  
  849.     struct statistics {
  850.     unsigned long    packets_in;    /* Totals across all handles */
  851.     unsigned long    packets_out;
  852.     unsigned long    bytes_in;    /* Including MAC headers */
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862. 14                PC/TCP Version 1.09 Packet Driver Specification
  863.                              FTP Software, Inc.
  864.  
  865.  
  866.     unsigned long    bytes_out;
  867.     unsigned long    errors_in;    /* Totals across all error types */
  868.     unsigned long    errors_out;
  869.     unsigned long    packets_lost;    /* No buffer from receiver(), card */
  870.                     /*  out of resources, etc. */
  871.     };
  872.  
  873. Returns a pointer to a statistics structure for the interface.     The values
  874. are stored as to be normal 80xx 32-bit integers.
  875.  
  876.  
  877. 6.17  set_address()
  878.  
  879. extended driver function
  880.     set_address(addr, len)        AH == 25
  881.         char far *addr;         ES:DI
  882.         int len;        CX
  883.  
  884. error return:
  885.     carry flag set
  886.     error code            DH
  887.     possible errors:
  888.         CANT_SET
  889.         BAD_ADDRESS
  890.  
  891. non-error return:
  892.     carry flag clear
  893.     length                CX
  894.  
  895. This call  is  used  when  the application or protocol stack needs to use a
  896. specific  LAN  address.   For instance, DECnet protocols on Ethernet encode
  897. the protocol address in the Ethernet address, requiring that it be set when
  898. the protocol  stack  is  loaded.    A  BAD_ADDRESS error indicates that the
  899. Packet Driver  doesn't    like  the  len (too short or too long), or the data
  900. itself.  Note that packet drivers should refuse to change the address (with
  901. a  CANT_SET error) if more than one handle is open (lest it be changed    out
  902. from under another protocol stack).
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928. PC/TCP Version 1.09 Packet Driver Specification                         A.1
  929. FTP Software, Inc.
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.                 Appendix A
  939.  
  940.             Interface classes and types
  941.  
  942.  
  943. The  following    are  defined  as  network  interface  classes,    with  their
  944. individual types listed immediately following the class.
  945.  
  946. DEC/Intel/Xerox "Bluebook" Ethernet
  947.      Class              1
  948.      3COM 3C500/3C501          1
  949.      3COM 3C505               2
  950.      Interlan Ni5010          3
  951.      BICC Data Networks 4110  4
  952.      BICC Data Networks 4117  5
  953.      MICOM-Interlan NP600     6
  954.      Ungermann-Bass PC-NIC    8
  955.      Univation NC-516          9
  956.      TRW PC-2000          10
  957.      Interlan Ni5210          11
  958.      3COM 3C503               12
  959.      3COM 3C523               13
  960.      Western Digital WD8003   14
  961.      Spider Systems S4          15
  962.      Torus Frame Level          16
  963.      10NET Communications     17
  964.      Gateway PC-bus          18
  965.      Gateway AT-bus          19
  966.      Gateway MCA-bus          20
  967.      IMC PCnic              21
  968.      IMC PCnic II          22
  969.      IMC PCnic 8bit          23
  970.      Tigan Communications     24
  971.      Micromatic Research      25
  972.      Clarkson "Multiplexor"   26
  973.      D-Link 8-bit          27
  974.      D-Link 16-bit          28
  975.      D-Link PS/2          29
  976.      Research Machines 8      30
  977.      Research Machines 16     31
  978.      Research Machines MCA    32
  979.      Radix Microsys. EXM1 16-bit
  980.      33
  981.      Interlan Ni9210          34
  982.      Interlan Ni6510          35
  983.      Vestra LANMASTER 16-bit  36
  984.      Vestra LANMASTER 8-bit   37
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994. A.2                PC/TCP Version 1.09 Packet Driver Specification
  995.                              FTP Software, Inc.
  996.  
  997.  
  998.      Allied Telesis PC/XT/AT  38
  999.      Allied Telesis NEC PC-98 39
  1000.      Allied Telesis Fujitsu FMR
  1001.      40
  1002.      Ungermann-Bass NIC/PS2   41
  1003.      Tiara LANCard/E AT       42
  1004.      Tiara LANCard/E MC       43
  1005.      Tiara LANCard/E TP       44
  1006.      Spider Comm. SpiderComm 845
  1007.      Spider Comm. SpiderComm 16
  1008.      46
  1009.      AT&T Starlan NAU          47
  1010.      AT&T Starlan-10 NAU      48
  1011.      AT&T Ethernet NAU          49
  1012.      Intel smart card          50
  1013.  
  1014. ProNET-10
  1015.      Class              2
  1016.      Proteon p1300          1
  1017.      Proteon p1800          2
  1018.  
  1019. IEEE 802.5/ProNET-4
  1020.      Class              3
  1021.      IBM Token ring adapter   1
  1022.      Proteon p1340          2
  1023.      Proteon p1344          3
  1024.      Gateway PC-bus          4
  1025.      Gateway AT-bus          5
  1026.      Gateway MCA-bus          6
  1027.  
  1028. Omninet
  1029.      Class              4
  1030.  
  1031. Appletalk
  1032.      Class              5
  1033.  
  1034. Serial line
  1035.      Class              6
  1036.      Clarkson 8250-SLIP       1
  1037.      Clarkson "Multiplexor"   2
  1038.  
  1039. Starlan
  1040.      Class              7    (NOTE: Class has been subsumed by Ethernet)
  1041.  
  1042. ArcNet
  1043.      Class              8
  1044.      Datapoint RIM          1
  1045.  
  1046. AX.25Class              9
  1047.  
  1048. KISS Class              10
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060. PC/TCP Version 1.09 Packet Driver Specification                         A.3
  1061. FTP Software, Inc.
  1062.  
  1063.  
  1064. IEE 802.3 w/802.2 hdrs
  1065.      Class              11
  1066.      Types as given under DIX Ethernet
  1067.      See Appendix D.
  1068.  
  1069. FDDI w/802.2 hdrs
  1070.      Class              12
  1071.  
  1072. Internet X.25
  1073.      Class              13
  1074.      Western Digital          1
  1075.      Frontier Technology      2
  1076.  
  1077. N.T. LANSTAR (encapsulating DIX)
  1078.      Class              14
  1079.      NT LANSTAR/8          1
  1080.      NT LANSTAR/MC          2
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126. PC/TCP Version 1.09 Packet Driver Specification                         B.1
  1127. FTP Software, Inc.
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.                 Appendix B
  1137.  
  1138.                Function call numbers
  1139.  
  1140.  
  1141. The  following    decimal  numbers  are  used to specify which operation    the
  1142. packet    driver should perform.    The number is stored in register AH on call
  1143. to the packet driver.
  1144.  
  1145. driver_info              1
  1146. access_type              2
  1147. release_type              3
  1148. send_pkt              4
  1149. terminate              5
  1150. get_address              6
  1151. reset_interface               7
  1152. +get_parameters               10
  1153. +as_send_pkt              11
  1154. *set_rcv_mode              20
  1155. *get_rcv_mode              21
  1156. *set_multicast_list          22
  1157. *get_multicast_list          23
  1158. *get_statistics               24
  1159. *set_address              25
  1160.  
  1161. + indicates a high-performance packet driver function
  1162. * indicates an extended packet driver function
  1163.  
  1164. AH values from 128 through 255 (0x80 through 0xFF) are reserved for
  1165. user-developed extensions to this specification.  While FTP Software
  1166. cannot support user extensions, we are willing to act as a clearing
  1167. house for information about them.  For more information, contact us.
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192. PC/TCP Version 1.09 Packet Driver Specification                         C.1
  1193. FTP Software, Inc.
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.                 Appendix C
  1203.  
  1204.                 Error codes
  1205.  
  1206.  
  1207. Packet driver calls  indicate  error  by  setting the carry flag on return.
  1208. The  error  code is returned in register DH (a register not  used  to  pass
  1209. values    to functions must be used to return the error code).  The following
  1210. error codes are defined:
  1211.  
  1212. 1    BAD_HANDLE               Invalid handle number,
  1213.  
  1214. 2    NO_CLASS              No interfaces of specified class found,
  1215.  
  1216. 3    NO_TYPE              No interfaces of specified type found,
  1217.  
  1218. 4    NO_NUMBER              No interfaces of specified number found,
  1219.  
  1220. 5    BAD_TYPE              Bad packet type specified,
  1221.  
  1222. 6    NO_MULTICAST          This interface does not support multicast,
  1223.  
  1224. 7    CANT_TERMINATE          This packet driver cannot terminate,
  1225.  
  1226. 8    BAD_MODE              An invalid receiver mode was specified,
  1227.  
  1228. 9    NO_SPACE              Operation failed because of insufficient space,
  1229.  
  1230. 10   TYPE_INUSE               The type had previously been accessed, and not
  1231.                   released,
  1232.  
  1233. 11   BAD_COMMAND          The command was out of range, or not implemented,
  1234.  
  1235. 12   CANT_SEND              The packet couldn't be sent (usually hardware error),
  1236.  
  1237. 13   CANT_SET              Hardware address couldn't be changed (more than 1
  1238.                   handle open),
  1239.  
  1240. 14   BAD_ADDRESS          Hardware address has bad length or format,
  1241.  
  1242. 15   CANT_RESET               Couldn't reset interface (more than 1 handle open).
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258. PC/TCP Version 1.09 Packet Driver Specification                         D.1
  1259. FTP Software, Inc.
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.                 Appendix D
  1269.  
  1270.                802.3 vs. Blue Book Ethernet
  1271.  
  1272.  
  1273. One weakness of the present specification is that there is no provision for
  1274. simultaneous  support  of  802.3  and  Blue Book (the  old  DEC-Intel-Xerox
  1275. standard) Ethernet headers via a single Packet Driver (as  defined  by    its
  1276. interrupt).  The problem is that the "ethertype" of Blue Book packets is in
  1277. bytes 12  and  13  of  the header, and in 802.3 the corresponding bytes are
  1278. interpreted as a length.  In 802.3, the field which would appear to be most
  1279. useful to begin the type check in is the 802.2 header, starting at byte 14.
  1280. This is only a problem on Ethernet and variants (e.g. Starlan), where 802.3
  1281. headers and Blue Book headers are likely to need co-exist for many years to
  1282. come.
  1283.  
  1284. One solution  is  to  redefine    class 1 as Blue Book Ethernet, and define a
  1285. parallel class for 802.3 with 802.2  packet  headers.  This requires that a
  1286. 2nd Packet Driver (as defined by its interrupt) be implemented where  it is
  1287. necessary to handle both kinds of packets, although they could both be part
  1288. of the same TSR module.
  1289.  
  1290. As of v1.07 of this specification, class 11  was  assigned  to    802.3 using
  1291. 802.2 headers, to implement the above.
  1292.  
  1293. Note: According to  this  scheme,  an  application  wishing  to  receive IP
  1294. encapsulated with an 802.2 SNAP header and "ethertype" of  0x800,  per    RFC
  1295. 1042, would specify an typelen argument of 8, and type would point to:
  1296.  
  1297.     char    iee_ip[] = {0xAA, 0xAA, 3, 0, 0, 0, 0x00, 0x08};
  1298.  
  1299.  
  1300.                       James B. VanBokkelen
  1301.                       jbvb@ftp.com
  1302.                       ...!ftp!jbvb
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.                  Table of Contents
  1331.  
  1332.  
  1333.  
  1334.  
  1335.     1  Document Conventions  . . . . . . . . . . . . . . . . . . 1
  1336.     2  Introduction and Motivation . . . . . . . . . . . . . . . 1
  1337.     3  Identifying network interfaces  . . . . . . . . . . . . . 2
  1338.     4  Initiating driver operations  . . . . . . . . . . . . . . 3
  1339.     5  Link-layer demultiplexing . . . . . . . . . . . . . . . . 3
  1340.     6  Programming interface . . . . . . . . . . . . . . . . . . 4
  1341.        6.1    Entry conditions . . . . . . . . . . . . . . . . . . 4
  1342.        6.2    Byte and Bit ordering  . . . . . . . . . . . . . . . 5
  1343.        6.3    driver_info()  . . . . . . . . . . . . . . . . . . . 5
  1344.        6.4    access_type()  . . . . . . . . . . . . . . . . . . . 6
  1345.        6.5    release_type() . . . . . . . . . . . . . . . . . . . 7
  1346.        6.6    send_pkt() . . . . . . . . . . . . . . . . . . . . . 7
  1347.        6.7    terminate()  . . . . . . . . . . . . . . . . . . . . 8
  1348.        6.8    get_address()  . . . . . . . . . . . . . . . . . . . 8
  1349.        6.9    reset_interface()  . . . . . . . . . . . . . . . . . 9
  1350.        6.10  get_parameters()  . . . . . . . . . . . . . . . . . 9
  1351.        6.11  as_send_pkt() . . . . . . . . . . . . . . . . . .  10
  1352.        6.12  set_rcv_mode()  . . . . . . . . . . . . . . . . .  11
  1353.        6.13  get_rcv_mode()  . . . . . . . . . . . . . . . . .  12
  1354.        6.14  set_multicast_list()  . . . . . . . . . . . . . .  12
  1355.        6.15  get_multicast_list()  . . . . . . . . . . . . . .  13
  1356.        6.16  get_statistics()  . . . . . . . . . . . . . . . .  13
  1357.        6.17  set_address() . . . . . . . . . . . . . . . . . .  14
  1358.  
  1359.      Appendix A  Interface classes and types               A-1
  1360.  
  1361.      Appendix B  Function call numbers                   B-1
  1362.  
  1363.      Appendix C  Error codes                       C-1
  1364.  
  1365.      Appendix D  802.3 vs. Blue Book Ethernet               D-1
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.                      i
  1384.  
  1385.  
  1386.  
  1387.