home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / devcon / milan_1991 / devcon91.2 / network / sana2 / sana2device.doc < prev   
Text File  |  1992-09-01  |  35KB  |  1,284 lines
  1. TABLE OF CONTENTS
  2.  
  3. sana2.device
  4. sana2.device/AbortIO()
  5. sana2.device/CMD_READ
  6. sana2.device/CMD_WRITE
  7. sana2.device/SANA2CMD_ADDMULTICASTADDRESS
  8. sana2.device/SANA2CMD_ADDSTATIONALIAS
  9. sana2.device/SANA2CMD_BROADCAST
  10. sana2.device/SANA2CMD_CONFIGINTERFACE
  11. sana2.device/SANA2CMD_DELMULTICASTADDRESS
  12. sana2.device/SANA2CMD_DELSTATIONALIAS
  13. sana2.device/SANA2CMD_DEVICEQUERY
  14. sana2.device/SANA2CMD_GETGLOBALSTATS
  15. sana2.device/SANA2CMD_GETSPECIALSTATS
  16. sana2.device/SANA2CMD_GETSTATIONADDRESS
  17. sana2.device/SANA2CMD_GETTYPESTATS
  18. sana2.device/SANA2CMD_MULTICAST
  19. sana2.device/SANA2CMD_OFFLINE
  20. sana2.device/SANA2CMD_ONEVENT
  21. sana2.device/SANA2CMD_ONLINE
  22. sana2.device/SANA2CMD_READORPHAN
  23. sana2.device/SANA2CMD_TRACKTYPE
  24. sana2.device/SANA2CMD_UNTRACKTYPE
  25. sana2.device                                                     sana2.device
  26.  
  27.     The SANA-II device specification represents a Data Transfer
  28.     Level interface standard for Amigas. The intent is: 1) for all
  29.     Amiga network hardware vendors to create a SANA-II device
  30.     driver for their hardware, 2) for all protocol stack writers
  31.     to access the networks via SANA-II device drivers, 3) any
  32.     protocol stack to work with any SANA-II device driver.
  33.  
  34.  
  35.    GOALS
  36.     Simplicity: A SANA-II device driver should be as simple to
  37.     write as any other Amiga device.
  38.  
  39.     Low cost: A functional SANA-II device driver should take about
  40.     one man month or less for an experienced Amiga programmer with
  41.     Amiga device writing experience to write. A tuned and polished
  42.     SANA-II device should require only one additional man month.
  43.  
  44.     Compatibility: All SANA-II device drivers behave largely the
  45.     same.
  46.  
  47.     Low resource usage: A SANA-II device driver should not require
  48.     large amounts of memory, cpu cycles or any other system
  49.     resource to operate efficiently.
  50.  
  51.     Ease of use: Using SANA-II devices should be the easiest way
  52.     for protocol stack writers to access the networks.
  53.  
  54.  
  55.    NON-GOALS
  56.     Lowest common denominator: Not all network interfaces can
  57.     support all the features available in this specification or
  58.     other network types.
  59.  
  60.     Feature-itis: Not every feature of every type of network is
  61.     represented.
  62.  
  63.     Network management tools: Analysis and debugging of a network
  64.     requires specialized software for that purpose.
  65.  
  66.  
  67.    STRUCTURES
  68.         struct IOSana2Req
  69.             {
  70.             struct Message S2io_Message;
  71.             struct Device *S2io_Device;
  72.             struct Unit   *S2io_Unit;
  73.  
  74.             UWORD S2io_Command;
  75.             UBYTE S2io_Flags;
  76.             BYTE  S2io_Error;
  77.             ULONG S2io_WireError;
  78.  
  79.             struct Sana2PacketType *S2io_PacketType;
  80.             UBYTE S2io_SrcAddr[SANA2_MAX_ADDR_BYTES];
  81.             UBYTE S2io_DstAddr[SANA2_MAX_ADDR_BYTES];
  82.             ULONG S2io_DataLength;
  83.             struct NetBuff S2io_Body;
  84.             void *S2io_StatData;
  85.             };
  86.  
  87.         Message
  88.             Initialized and used the same as all device IORequest
  89.             Message structures.
  90.  
  91.         Device
  92.             Device private.
  93.  
  94.         Unit
  95.             Device private.
  96.  
  97.         Command
  98.             Command requested.
  99.  
  100.         Flags
  101.             Used to request special options and return status
  102.             information.
  103.  
  104.         Error
  105.             Indicates completion status of a command in general
  106.             terms.
  107.  
  108.         WireError
  109.             More specific error number. Only valid when S2io_Error
  110.             is non-zero.
  111.  
  112.         PacketType
  113.             Pointer to a Sana2PacketType structure. The device
  114.             uses the contents of the structure to determine if a
  115.             packet from the network will satisfy a particular read
  116.             command, or to build the appropriate packet header and
  117.             trailer for a packet send. The device will not modify
  118.             either the pointer or the structure.
  119.  
  120.         SrcAddr
  121.             The device fills in this field with the interface
  122.             address of the source of the packet that satisfied a
  123.             read command. The bytes used to hold the address will
  124.             be left justified but the bit layout is dependent on
  125.             the particular type of network.
  126.  
  127.         DstAddr
  128.             This field is filled in with the interface destination
  129.             address of the packet for a send command. The bytes
  130.             used to hold the address will be left justified but
  131.             the bit layout is dependent on the particular type of
  132.             network.
  133.  
  134.         DataLength
  135.             The device fills in this field with the size of the
  136.             packet data as it was sent on the wire. This does not
  137.             include the header and trailer information. Depending
  138.             on the network type and protocol type, the driver may
  139.             have to calculate this value.
  140.  
  141.         Body
  142.             A NetBuff structure with the packet data.
  143.  
  144.         StatData
  145.             Pointer to a data area in memory to place a a snapshot
  146.             of device statics. The data area must be long word
  147.             aligned.
  148.  
  149.     
  150.         struct Sana2PacketType
  151.             {
  152.             ULONG CanonicalType;
  153.             ULONG Magic;
  154.             ULONG Length;
  155.             UBYTE *Match;
  156.             UBYTE *Mask;
  157.             };
  158.  
  159.         CanonicalType
  160.             Not used by the device.
  161.  
  162.         Magic
  163.             Determines how the fields in this structure are to be
  164.             interpretted.
  165.  
  166.         Length
  167.             Number of bytes pointed to be Match and Mask.
  168.  
  169.         Match
  170.             Pointer to packet type match data. The data must be
  171.             long word (32 bit) aligned.
  172.  
  173.         Mask
  174.             Pointer to packet type mask data. The data must be
  175.             long word (32 bit) aligned.
  176.  
  177.  
  178.         struct Sana2DeviceQuery
  179.             {
  180.             /*
  181.              * Standard information
  182.              */
  183.             ULONG SizeAvailable;
  184.             ULONG SizeSupplied;
  185.             LONG DevQueryFormat;
  186.             LONG DeviceLevel;
  187.             /*
  188.              * Common information
  189.              */
  190.             UWORD AddrFieldSize;
  191.             ULONG MTU;
  192.             LONG bps;
  193.             LONG HardwareType;
  194.             /*
  195.              * Format specific information
  196.              */
  197.             };
  198.  
  199.         SizeAvailable
  200.             Size, in bytes, of the space available in which to
  201.             place device information. This includes both size
  202.             fields.
  203.  
  204.         SizeSupplied
  205.             Size, in bytes, of the data supplied.
  206.  
  207.         DevQueryFormat
  208.             The format defined here is format 0.
  209.  
  210.         DeviceLevel
  211.             This spec defines level 0.
  212.  
  213.         AddrFieldSize
  214.             The number of bits in an interface address.
  215.  
  216.         MTU
  217.             Maximum Transmission Unit, the size, in bytes, of the
  218.             maximum packet size, not including header and trailer
  219.             information.
  220.  
  221.         bps
  222.             Best guess at the raw line rate for this network in
  223.             bits per second.
  224.  
  225.         HardwareType
  226.             Specifies the type of network wire the driver
  227.             controls.
  228.  
  229.  
  230.         struct Sana2PacketTypeStats
  231.             {
  232.             LONG PacketsSent;
  233.             LONG PacketsReceived;
  234.             LONG BytesSent;
  235.             LONG BytesReceived;
  236.             LONG PacketsDropped;
  237.             };
  238.  
  239.         PacketsSent
  240.             Number of packets of a particular type sent.
  241.  
  242.         PacketsReceived
  243.             Number of packets of a particular type that satisfied
  244.             a read command.
  245.  
  246.         BytesSent
  247.             Number of bytes of data sent in packets of a
  248.         particular type.
  249.  
  250.         BytesReceived
  251.             Number of bytes of data of a particular packet type
  252.             that satisfied a read command.
  253.  
  254.         PacketsDropped
  255.             Number of packets of a particular type that were
  256.             received while there were no pending reads of that
  257.             packet type.
  258.  
  259.  
  260.         struct Sana2SpecialStatRecord
  261.             {
  262.             ULONG Type;
  263.             LONG Count;
  264.             char *String;
  265.             };
  266.  
  267.         Type
  268.             Statistic identifier.
  269.  
  270.         Count
  271.             Statistic itself.
  272.  
  273.         String
  274.             Identifying string for the statistic. Should be plain
  275.             ASCII with no formatting characters.
  276.  
  277.  
  278.         struct Sana2SpecialStatHeader
  279.             {
  280.             ULONG RecordCountMax;
  281.             ULONG RecordCountSupplied;
  282.             struct Sana2SpecialStatRecord[RecordCountMax];
  283.             };
  284.  
  285.         RecordCountMax
  286.             Space for this many number of records is available to
  287.             place statistics information in.
  288.  
  289.         RecordCountSupplied
  290.             Number of statistic records supplied.
  291.  
  292.  
  293.         struct Sana2DeviceStats
  294.             {
  295.             LONG packets_received;
  296.             LONG packets_sent;
  297.             LONG framing_errors;
  298.             LONG bad_data;
  299.             LONG hard_misses;
  300.             LONG soft_misses;
  301.             LONG unknown_types_received;
  302.             LONG fifo_overruns;
  303.             LONG fifo_underruns;
  304.             LONG reconfigurations;
  305.             struct timeval last_start;
  306.             };
  307.  
  308.         packets_received
  309.             Number of packets that this unit has received.
  310.  
  311.         packets_sent
  312.             Number of packets that this unit has sent.
  313.  
  314.         framing_errors
  315.             Number of framing errors detected.
  316.  
  317.         bad_data
  318.             Number of bad packets received.
  319.  
  320.         hard_misses
  321.             Number of packets lost due to insufficient resources
  322.             available in the network interface.
  323.  
  324.         soft_misses
  325.             Number of packets lost due to insifficient resources
  326.             available on the host.
  327.  
  328.         unknown_type_received
  329.             Number of packets received that had no pending read
  330.             command with the appropriate packet type.
  331.  
  332.         fifo_overruns
  333.             Number of overruns encountered when attempting to
  334.             store received packets.
  335.  
  336.         fifo_underruns
  337.             Number of underruns encountered when attempting to
  338.             send packets.
  339.  
  340.         reconfigurations
  341.             Number of network reconfigurations since this unit was
  342.             last configured.
  343.  
  344.         last_start
  345.             The time when this unit last went online.
  346.  
  347.  
  348.    CONSTANTS
  349.     OpenDevice flags argument (SANA2OPB_xxx):
  350.         MINE
  351.             Exclusive access to the unit requested.
  352.  
  353.         PROM
  354.             Promiscuous mode requested.
  355.  
  356.  
  357.     IOSana2Req S2io_Flags field (SANA2IOB_xxx):
  358.         RAW
  359.             Raw packet read/write requested.
  360.  
  361.         BCAST
  362.             Broadcast packet (received).
  363.  
  364.         MCAST
  365.             Multicast packet (received).
  366.  
  367.         QUICK
  368.             Quick IO requested.
  369.  
  370.  
  371.     IOSana2Req S2io_Error field (S2ERR_xxx):
  372.         NO_RESOURCES
  373.             Insufficient resources available.
  374.  
  375.         UNKNOWN_ENTITY
  376.             Specified entity unknown or not found.
  377.  
  378.         BAD_ARGUMENT
  379.             Noticably bad argument.
  380.  
  381.         BAD_STATE
  382.             Command inappropriate for current state.
  383.  
  384.         BAD_ADDRESS
  385.             Noticably bad address.
  386.  
  387.         MTU_EXCEEDED
  388.             Write data too large.
  389.  
  390.         BAD_PROTOCOL
  391.             Noticably bad packet type.
  392.  
  393.         NOT_SUPPORTED
  394.             Command is not supported by this driver. This is
  395.             similar to IOERR_NOCMD as defined in exec/errors.h but
  396.             S2ERR_NOT_SUPPORTED indicates that the requested
  397.             command is a valid SANA-II command and that the driver
  398.             does not support it, e.g. SANA2CMD_MULTICAST.
  399.  
  400.         SOFTWARE
  401.             Software error of some kind.
  402.  
  403.  
  404.     IOSana2Req S2io_WireError field (S2WERR_xxx):
  405.         NOT_CONFIGURED
  406.             Command requires unit to be configured.
  407.  
  408.         UNIT_ONLINE
  409.             Command requires that the unit be offline.
  410.  
  411.         UNIT_OFFLINE
  412.             Command requires that the unit be online.
  413.  
  414.         ALREADY_TRACKED
  415.             Protocol is already being tracked.
  416.  
  417.         NOT_TRACKED
  418.             Protocol is not being tracked.
  419.  
  420.         NETBUFF_ERROR
  421.             NetBuff.library error return caused error.
  422.  
  423.         SRC_ADDRESS
  424.             Problem with the source address field.
  425.  
  426.         DST_ADDRESS
  427.             Problem with destination address field.
  428.  
  429.         BAD_BROADCAST
  430.             Problem with an attempt to broadcast.
  431.  
  432.         BAD_MULTICAST
  433.             Problem with an attempt to multicast.
  434.  
  435.         ALIAS_LIST_FULL
  436.             Station alias list full.
  437.  
  438.         BAD_ALIAS
  439.             Bad or unknown station alias.
  440.  
  441.         MULTICAST_FULL
  442.             Multicast address list full.
  443.  
  444.         BAD_EVENT
  445.             Event specified is unknown.
  446.  
  447.         BAD_STATDATA
  448.             The S2IO_StatData pointer or the data it points to
  449.             failed a sanity check.
  450.  
  451.         PROTOCOL_UNKNOWN
  452.             The protocol specified is unknown or the type of magic
  453.             used by the request protocol is unknown.
  454.  
  455.         IS_CONFIGURED
  456.             Attempt to reconfigure the unit.
  457.  
  458.         NULL_POINTER
  459.             A NULL pointer was detected in one of the arguments.
  460.  
  461.  
  462.     Event types (S2EVENT_xxx):
  463.         ERROR
  464.             Return when any error occures.
  465.  
  466.         TX
  467.             Return on any transmit error.
  468.  
  469.         RX
  470.             Return on any receive error.
  471.  
  472.         ONLINE
  473.             Return when unit goes online.
  474.  
  475.         OFFLINE
  476.             Return when unit goes offline.
  477.  
  478.         NETBUFF
  479.             Return on any NetBuff.library error.
  480.  
  481.         HARDWARE
  482.             Return when any hardware error occures.
  483.  
  484.         SOFTWARE
  485.             Return when any software error occures.
  486.  
  487.  
  488.    SEE ALSO
  489.     NetBuff.library documentation.
  490.  
  491.     Separate document for each type of network detailing specific
  492.     device requirements.
  493.  
  494.  
  495.    CREDITS
  496.     Raymond S. Brand,   rsbx@cbmvax.commodore.com,  (215) 431-9100
  497.     Martin Hunt,      martin@cbmvax.commodore.com,  (215) 431-9100
  498.     Perry Kivolowitz,           ASDG Incorporated,  (608) 273-6585
  499.  
  500. sana2.device/AbortIO()                                 sana2.device/AbortIO()
  501.  
  502.    NAME
  503.     AbortIO -- Remove an existing device request.
  504.  
  505.    SYNOPSIS
  506.     error = AbortIO( Sana2Req )
  507.     D0               A1
  508.  
  509.     LONG AbortIO( struct IOSana2Req * );
  510.  
  511.    FUNCTION
  512.     This is an exec.library call.
  513.  
  514.     This function aborts an ioRequest. If the request is active,
  515.     it may or may not be aborted. If the request is queued it is
  516.     removed. The request will be returned in the same way as if
  517.     it had normally completed.
  518.  
  519.    INPUTS
  520.     Sana2Req        Sana2Req to be aborted.
  521.  
  522.    RESULTS
  523.     error           Zero if the request was aborted, non-zero
  524.                         otherwise. S2io_Error in Sana2Req will be
  525.                         set to IOERR_ABORTED (-2) if it was
  526.                         aborted.
  527.  
  528.    NOTES
  529.  
  530.    SEE ALSO
  531.     exec.library/AbortIO()
  532.  
  533.    BUGS
  534.  
  535. sana2.device/CMD_READ                                   sana2.device/CMD_READ
  536.  
  537.    NAME
  538.     Read -- Get a packet from the network.
  539.  
  540.    FUNCTION
  541.     Get the next packet available of the requested packet type.
  542.     The data returned in the S2io_Body NetBuff is normally the
  543.     Data Link Layer packet data only. If bit SANA2IOB_RAW is set
  544.     in S2io_Flags, then the entire Data Link Layer packet,
  545.     including both header and trailer information, will be
  546.     returned.
  547.  
  548.    IO REQUEST
  549.     S2io_Command    CMD_READ
  550.     S2io_Flags      Supported flags are:
  551.                         SANA2IOB_RAW
  552.                         SANA2IOB_QUICK
  553.     S2io_PacketType Pointer to packet type desired.
  554.     S2io_Body       NetBuff to hold packet data.
  555.  
  556.    RESULTS
  557.     S2io_Error      Zero if successful; non-zero otherwise.
  558.     S2io_WireError  More specific error number.
  559.     S2io_Flags      The following flags may be returned:
  560.                         SANA2IOB_RAW
  561.                         SANA2IOB_BCAST
  562.                         SANA2IOB_MCAST
  563.     S2io_SrcAddr    Source interface address of packet.
  564.     S2io_DstAddr    Destination interface address of packet.
  565.     S2io_DTLLength  Length of packet data as given by the Data
  566.                         Link Layer protocol.
  567.     S2io_Body       NetBuff with packet data.
  568.  
  569.    NOTES
  570.     Only the first NetBuffSegment in the NetBuff passed is
  571.     guaranteed to be returned.
  572.  
  573.    SEE ALSO
  574.     sana2.device/SANA2CMD_READORPHAN,
  575.     sana2.device/CMD_WRITE
  576.  
  577.    BUGS
  578.  
  579. sana2.device/CMD_WRITE                                 sana2.device/CMD_WRITE
  580.  
  581.    NAME
  582.     Write -- Send packet to the network.
  583.  
  584.    FUNCTION
  585.     This command causes the packet to be sent to the specified
  586.     network interface. Normally, appropriate packet header and
  587.     trailer information will be added to the packet data when it
  588.     is sent. If bit SANA2IOB_RAW is set in io-Flags, then the
  589.     S2io_Body NetBuff is assumed to contain an entire Data Link
  590.     Layer packet and will be sent unmodified.
  591.  
  592.     The data in the S2io_Body NetBuff is returned unmodified; but,
  593.     the distribution of the data in, and the number of
  594.     NetBuffSegments, the S2io_Body NetBuff may be modified.
  595.  
  596.    IO REQUEST
  597.     S2io_Command    CMD_WRITE
  598.     S2io_Flags      Supported flags are:
  599.                         SANA2IOB_RAW
  600.                         SANA2IOB_QUICK
  601.     S2io_PacketType Pointer to type of packet to send.
  602.     S2io_DstAddr    Destination interface address for this packet.
  603.     S2io_Body       NetBuff with packet data.
  604.  
  605.    RESULTS
  606.     S2io_Error      Zero if successful; non-zero otherwise.
  607.     S2io_WireError  More specific error number.
  608.  
  609.    NOTES
  610.  
  611.    SEE ALSO
  612.     sana2.device/CMD_READ,
  613.     sana2.device/SANA2CMD_BROADCAST,
  614.     sana2.device/SANA2CMD_MULTICAST
  615.  
  616.    BUGS
  617.  
  618. sana2.device/SANA2CMD_ADDMULTICASTADDRESS.device/SANA2CMD_ADDMULTICASTADDRESS
  619.  
  620.    NAME
  621.     AddMulticastAddress -- Enable an interface multicast address.
  622.  
  623.    FUNCTION
  624.     This command causes the device driver to enable multicast
  625.     packet reception for the requested address.
  626.  
  627.    IO REQUEST
  628.     S2io_Command    SANA2CMD_ADDMULTICASTADDRESS
  629.     S2io_SrcAddr    Multicast address to enable.
  630.  
  631.    RESULTS
  632.     S2io_Error      Zero if successful; non-zero otherwise.
  633.     S2io_WireError  More specific error number.
  634.  
  635.    NOTES
  636.     Since multicast addresses are not "bound" to a particular
  637.     packet type, each enabled multicast address has an "enabled"
  638.     count associated with it.
  639.  
  640.    SEE ALSO
  641.     sana2.device/SANA2CMD_DELMULTICASTADDRESS
  642.  
  643.    BUGS
  644.  
  645. sana2.device/SANA2CMD_ADDSTATIONALIAS   sana2.device/SANA2CMD_ADDSTATIONALIAS
  646.  
  647.    NAME
  648.     AddStationAlias -- Add interface address alias.
  649.  
  650.    FUNCTION
  651.     This function adds another network interface address to which
  652.     the network interface should respond.
  653.  
  654.    IO REQUEST
  655.     S2io_Command    SANA2CMD_ADDSTATIONALIAS
  656.     S2io_SrcAddr    Alias to add.
  657.  
  658.    RESULTS
  659.     S2io_Error      Zero if successful; non-zero otherwise.
  660.     S2io_WireError  More specific error number.
  661.  
  662.    NOTES
  663.     Since alias interface addresses are not bound to a particular
  664.     packet type or read request, each added interface alias
  665.     address has an "added" count associated with it.
  666.  
  667.    SEE ALSO
  668.     sana2.device/SANA2CMD_DELSTATIONALIAS
  669.  
  670.    BUGS
  671.  
  672. sana2.device/SANA2CMD_BROADCAST               sana2.device/SANA2CMD_BROADCAST
  673.  
  674.    NAME
  675.     Broadcast -- Broadcast a packet on network.
  676.  
  677.    FUNCTION
  678.     This command works the same as CMD_WRITE except that it also
  679.     performs whatever special processing of the packet is required
  680.     to do a broadcast send. The actual broadcast mechanism is
  681.     neccessarily network/interface/device specific.
  682.  
  683.    IO REQUEST
  684.     S2io_Command    SANA2CMD_BROADCAST
  685.     S2io_Flags      Supported flags are:
  686.                         SANA2IOB_RAW
  687.                         SANA2IOB_QUICK
  688.     S2io_PacketType Pointer to type of packet to send.
  689.     S2io_Body       NetBuff with packet data.
  690.  
  691.    RESULTS
  692.     S2io_DstAddr    The contents of this field are to be
  693.                         considered trash upon return of the IOReq.
  694.     S2io_Error      Zero if successful; non-zero otherwise.
  695.                         This command can fail for many reasons and
  696.                         is not supported by all networks and/or
  697.                         network interfaces.
  698.     S2io_WireError  More specific error number.
  699.  
  700.    NOTES
  701.  
  702.    SEE ALSO
  703.     sana2.device/CMD_WRITE,
  704.     sana2.device/SANA2CMD_MULTICAST
  705.  
  706.    BUGS
  707.  
  708. sana2.device/SANA2CMD_CONFIGINTERFACE   sana2.device/SANA2CMD_CONFIGINTERFACE
  709.  
  710.    NAME
  711.     ConfigInterface -- Configure the network interface.
  712.  
  713.    FUNCTION
  714.     This command causes the device driver to initialize the
  715.     interface hardware and to set the network interface address to
  716.     the address in S2io_SrcAddr. This command can only be executed
  717.     once and, if successful, will leave the driver and network
  718.     interface fully operational and the network interface in
  719.     S2io_SrcAddr.
  720.  
  721.     To set the interface address to the factory address, the
  722.     network management software must use GetStationAddress first
  723.     and then call ConfigInterface with the result. If there is no
  724.     factory address then the network software must pick an address
  725.     to use.
  726.  
  727.     Until this command is executed the device will not listen for
  728.     any packets on the hardware.
  729.  
  730.    IO REQUEST
  731.     S2io_Command    SANA2CMD_CONFIGINTERFACE
  732.     S2io_Flags      Supported flags are:
  733.                         SANA2IOB_QUICK
  734.     S2io_SrcAddr    Address for this interface.
  735.  
  736.    RESULTS
  737.     S2io_Error      Zero if successful; non-zero otherwise.
  738.     S2io_WireError  More specific error number.
  739.     S2io_SrcAddr    Address of this interface as configured.
  740.  
  741.    NOTES
  742.     Some networks have the interfaces choose a currently unused
  743.     interface address each time the interface is initialized. The
  744.     caller must check S2io_SrcAddr for the actual interface
  745.     address after configuring the interface.
  746.  
  747.    SEE ALSO
  748.     sana2.device/SANA2CMD_GETSTATIONADDRESS
  749.  
  750.    BUGS
  751.     What to do when/if the network interface address changes due
  752.     to a network reconfiguration.
  753.  
  754. sana2.device/SANA2CMD_DELMULTICASTADDRESS.device/SANA2CMD_DELMULTICASTADDRESS
  755.  
  756.    NAME
  757.     DelMultiCastAddress -- Disable an interface multicast address.
  758.  
  759.    FUNCTION
  760.     This command causes device driver to disable multicast packet
  761.     reception for the requested address.
  762.  
  763.     It is an error to disable a multicast address that is not
  764.     enabled.
  765.  
  766.    IO REQUEST
  767.     S2io_Command    SANA2CMD_DELMULTICASTADDRESS
  768.     S2io_SrcAddr    Multicast address to disable.
  769.  
  770.    RESULTS
  771.     S2io_Error      Zero if successful; non-zero otherwise.
  772.     S2io_WireError  More specific error number.
  773.  
  774.    NOTES
  775.     Since multicast addresses are not "bound" to a particular
  776.     packet type, each enabled multicast address has an "enabled"
  777.     count associated with it.
  778.  
  779.    SEE ALSO
  780.     sana2.device/SANA2CMD_ADDMULTICASTADDRESS
  781.  
  782.    BUGS
  783.  
  784. sana2.device/SANA2CMD_DELSTATIONALIAS   sana2.device/SANA2CMD_DELSTATIONALIAS
  785.  
  786.    NAME
  787.     DelStationAlias -- Delete a interface address alias.
  788.  
  789.    FUNCTION
  790.     This function deletes a network interface address from the
  791.     list of addresses to which this interface should respond.
  792.  
  793.    IO REQUEST
  794.     S2io_Command    SANA2CMD_DELSTATIONALIAS
  795.     S2io_SrcAddr    Alias to delete.
  796.  
  797.    RESULTS
  798.     S2io_Error      Zero if successful; non-zero otherwise.
  799.     S2io_WireError  More specific error number.
  800.  
  801.    NOTES
  802.     Since alias interface addresses are not bound to a particular
  803.     packet type or read request, each added interface alias
  804.     address has an "added" count associated with it.
  805.  
  806.    SEE ALSO
  807.     sana2.device/SANA2CMD_ADDSTATIONALIAS
  808.  
  809.    BUGS
  810.  
  811. sana2.device/SANA2CMD_DEVICEQUERY           sana2.device/SANA2CMD_DEVICEQUERY
  812.  
  813.    NAME
  814.     DeviceQuery -- Return parameters for this network interface.
  815.  
  816.    FUNCTION
  817.     This command causes the device driver to report information
  818.     about the device. Up to DevQuerySizeAvailable bytes of the
  819.     information is copied into a buffer pointed to by
  820.     S2io_StatData. The format of the data is as follows:
  821.  
  822.         struct Sana2DeviceQuery
  823.             {
  824.             /*
  825.              * Standard information
  826.              */
  827.             ULONG DevQuerySizeAvailble; /* bytes available */
  828.             ULONG DevQuerySizeSupplied; /* bytes supplied */
  829.             LONG  DevQueryFormat;   /* this is type 0 */
  830.             LONG  DeviceLevel;      /* this document is level 0 */
  831.  
  832.             /*
  833.              * Common information
  834.              */
  835.             UWORD AddrFieldSize;    /* address size in bits */
  836.             ULONG MTU;              /* maximum packet data size */
  837.             LONG  bps;              /* line rate (bits/sec) */
  838.             LONG  HardwareType;     /* what the wire is */
  839.  
  840.             /*
  841.              * Format specific information
  842.              */
  843.             };
  844.  
  845.     The DeviceQueryAvailable specifies the number of bytes that
  846.     the caller is prepared to accomodate, including the standard
  847.     information fields.
  848.  
  849.     DevQuerySizeSupplied is the number of bytes actually supplied,
  850.     including the standard information fields, which will not
  851.     exceed DevQuerySizeAvailable.
  852.  
  853.     The values used to identify the type of physical hardware are
  854.     the same values used in the hardware type field (hdr) of
  855.     Address Resolution Protocol (ARP) packets as defined by
  856.     RFC-826 (ARP) and RFC-1060 (Assigned Numbers, March 1990).
  857.  
  858.     The following are defined in RFC-1060.
  859.  
  860.         Hardware Type (hrd)
  861.  
  862.             Type   Description
  863.             ----   -----------
  864.               1    Ethernet (10Mb)
  865.               2    Experimental Ethernet (3Mb)
  866.               3    Amateur Radio AX.25
  867.               4    Proteon ProNET Token Ring
  868.               5    Chaos
  869.               6    IEEE 802 Networks
  870.               7    ARCNET
  871.               8    Hyperchannel
  872.               9    Lanstar
  873.              10    Autonet Short Address
  874.              11    LocalTalk
  875.              12    LocalNet (IBM PCNet or SYTEK LocalNET)
  876.  
  877.    IO REQUEST
  878.     S2io_Command    SANA2CMD_DEVICEQUERY
  879.     S2io_StatData   Pointer to Sana2DeviceQuery structure to fill
  880.                         in.
  881.  
  882.    RESULTS
  883.     S2io_Error      Zero if successful; non-zero otherwise.
  884.     S2io_WireError  More specific error number.
  885.  
  886.    NOTES
  887.  
  888.    SEE ALSO
  889.  
  890.    BUGS
  891.  
  892. sana2.device/SANA2CMD_GETGLOBALSTATS     sana2.device/SANA2CMD_GETGLOBALSTATS
  893.  
  894.    NAME
  895.     GetGlobalStats -- Get interface accumulated statistics.
  896.  
  897.    FUNCTION
  898.     This command causes the device driver to retrieve various
  899.     global runtime statistics for this network interface. The
  900.     format of the data returned is as follows:
  901.  
  902.         struct Sana2DeviceStats
  903.             {
  904.             LONG packets_received;
  905.             LONG packets_sent;
  906.             LONG framming_errors;
  907.             LONG bad_data;
  908.             LONG bytes_received;
  909.             LONG bytes_sent;
  910.             LONG hard_misses;
  911.             LONG soft_misses;
  912.             LONG unknown_types_received;
  913.             LONG fifo_overruns;
  914.             LONG fifo_underruns;
  915.             LONG reconfigurations;
  916.             timeval last_start;
  917.             };
  918.  
  919.    IO REQUEST
  920.     S2io_Command    SANA2CMD_GETGLOBALSTATS
  921.     S2io_StatData   Pointer to Sana2DeviceStats structure to fill.
  922.  
  923.    RESULTS
  924.     S2io_Error      Zero if successful; non-zero otherwise.
  925.     S2io_WireError  More specific error number.
  926.  
  927.    NOTES
  928.  
  929.    SEE ALSO
  930.     sana2.device/SANA2CMD_GETSPECIALSTATS
  931.  
  932.    BUGS
  933.  
  934. sana2.device/SANA2CMD_GETSPECIALSTATS   sana2.device/SANA2CMD_GETSPECIALSTATS
  935.  
  936.    NAME
  937.     GetSpecialStats -- Get network type specific statistics.
  938.  
  939.    FUNCTION
  940.     This function returns statistics which are specific to the
  941.     type of network medium this driver controls. For example, this
  942.     command could return statistics common to all Ethernets which
  943.     are not common to all network mediums in general.
  944.  
  945.     The supplied Sana2SpecialStatData structure is given below:
  946.  
  947.         struct Sana2SpecialStatData
  948.             {
  949.             ULONG RecordCountMax;
  950.             ULONG RecordCountSupplied;
  951.             struct Sana2StatRecord[RecordCountMax];
  952.             };
  953.  
  954.     The format of the data returned is:
  955.  
  956.         struct Sana2StatRecord
  957.             {
  958.             ULONG Type;     /* commodore registered */
  959.             LONG Count;     /* the stat itself */
  960.             char *String;   /* null terminated */
  961.             };
  962.  
  963.     The RecordCountMax field specifies the number of records that
  964.     the caller is prepared to accomodate.
  965.  
  966.     RecordCountSupplied is the number of record actually supplied
  967.     which will not exceed RecordCountMax.
  968.  
  969.    IO REQUEST
  970.     S2io_Command    SANA2CMD_GETSPECIALSTATS
  971.     S2io_StatData   Pointer to a Sana2SpecialStatData structure to
  972.                         fill. RecordCountMax must be initialized.
  973.  
  974.    RESULTS
  975.     S2io_Error      Zero if successful; non-zero otherwise.
  976.     S2io_WireError  More specific error number.
  977.  
  978.    NOTES
  979.     Commodore shall maintain registered statistic Types.
  980.  
  981.    SEE ALSO
  982.     sana2.device/SANA2CMD_GETGLOBALSTATS
  983.  
  984.    BUGS
  985.  
  986. sana2.device/SANA2CMD_GETSTATIONADDRESSana2.device/SANA2CMD_GETSTATIONADDRESS
  987.  
  988.    NAME
  989.     GetStationAddress -- Get default and interface address.
  990.  
  991.    FUNCTION
  992.     This command causes the device driver to copy the current
  993.     interface address into S2io_SrcAddr, and to copy the factory
  994.     default station address into S2io_DstAddr.
  995.  
  996.    IO REQUEST
  997.     S2io_Command    SANA2CMD_GETSTATIONADDRESS
  998.  
  999.    RESULTS
  1000.     S2io_Error      Zero if successful; non-zero otherwise.
  1001.     S2io_WireError  More specific error number.
  1002.     S2io_SrcAddr    Default interface address.
  1003.     S2io_DstAddr    Current interface address.
  1004.  
  1005.    NOTES
  1006.  
  1007.    SEE ALSO
  1008.     sana2.device/SANA2CMD_CONFIGINTERFACE
  1009.  
  1010.    BUGS
  1011.  
  1012. sana2.device/SANA2CMD_GETTYPESTATS         sana2.device/SANA2CMD_GETTYPESTATS
  1013.  
  1014.    NAME
  1015.     GetTypeStats -- Get accumulated type specific statistics.
  1016.  
  1017.    FUNCTION
  1018.     This command causes the device driver to retrieve various
  1019.     packet type specific runtime statistics for this network
  1020.     interface. The format of the data returned is as follows:
  1021.  
  1022.         struct Sana2TypeStatData
  1023.             {
  1024.             LONG PacketsSent;
  1025.             LONG PacketsReceived;
  1026.             LONG BytesSent;
  1027.             LONG BytesReceived;
  1028.             LONG PacketsDropped;
  1029.             };
  1030.  
  1031.    IO REQUEST
  1032.     S2io_Command    SANA2CMD_GETTYPESTATS
  1033.     S2io_PacketType Pointer to the packet type of interest.
  1034.     S2io_StatData   Pointer to TypeStatData structure to fill in.
  1035.  
  1036.    RESULTS
  1037.     S2io_Error      Zero if successful; non-zero otherwise.
  1038.     S2io_WireError  More specific error number.
  1039.  
  1040.    NOTES
  1041.     Statistics for a particular packet type are only available
  1042.     while that packet type is being ``tracked''.
  1043.  
  1044.    SEE ALSO
  1045.     sana2.device/SANA2CMD_TRACKTYPE,
  1046.     sana2.device/SANA2CMD_UNTRACKTYPE
  1047.  
  1048.    BUGS
  1049.  
  1050. sana2.device/SANA2CMD_MULTICAST               sana2.device/SANA2CMD_MULTICAST
  1051.  
  1052.    NAME
  1053.     Multicast -- Multicast a packet on network.
  1054.  
  1055.    FUNCTION
  1056.     This command works the same as CMD_WRITE except that it also
  1057.     performs whatever special processing of the packet is required
  1058.     to do a multicast send. The actual multicast mechanism is
  1059.     neccessarily network/interface/device specific.
  1060.  
  1061.    IO REQUEST
  1062.     S2io_Command    SANA2CMD_MULTICAST
  1063.     S2io_Flags      Supported flags are:
  1064.                         SANA2IOB_RAW
  1065.                         SANA2IOB_QUICK
  1066.     S2io_PacketType Pointer to type of packet to send.
  1067.     S2io_DstAddr    Destination interface address for this packet.
  1068.     S2io_Body       NetBuff with packet data.
  1069.  
  1070.    RESULTS
  1071.     S2io_Error      Zero if successful; non-zero otherwise.
  1072.                         This command can fail for many reasons and
  1073.                         is not supported by all networks and/or
  1074.                         network interfaces.
  1075.     S2io_WireError  More specific error number.
  1076.  
  1077.    NOTES
  1078.     The address supplied in S2io_DstAddr will be sanity checked
  1079.     (if possible) by the driver. If the supplied address fails
  1080.     this sanity check, the multicast request will fail
  1081.     immediately.
  1082.  
  1083.    SEE ALSO
  1084.     sana2.device/CMD_WRITE,
  1085.     sana2.device/SANA2CMD_BROADCAST
  1086.  
  1087.    BUGS
  1088.  
  1089. sana2.device/SANA2CMD_OFFLINE                   sana2.device/SANA2CMD_OFFLINE
  1090.  
  1091.    NAME
  1092.     Offline -- Remove interface from service.
  1093.  
  1094.    FUNCTION
  1095.     This command removes a network interface from service.
  1096.  
  1097.    IO REQUEST
  1098.     S2io_Command    SANA2CMD_OFFLINE
  1099.  
  1100.    RESULTS
  1101.     S2io_Error      Zero if successful; non-zero otherwise.
  1102.     S2io_WireError  More specific error number.
  1103.  
  1104.    NOTES
  1105.     Aborts all pending reads and writes with S2io_Error set to
  1106.     SANA2ERROR_OUTOFSERVICE.
  1107.  
  1108.     While the interface is offline, all read, writes and any other
  1109.     command that touches interface hardware will be rejected with
  1110.     S2io_Error set to SANA2ERROR_OUTOFSERVICE.
  1111.  
  1112.     This command is intended to permit a network interface to be
  1113.     tested on an otherwise live system.
  1114.  
  1115.    SEE ALSO
  1116.     sana2.device/SANA2CMD_ONLINE
  1117.  
  1118.    BUGS
  1119.  
  1120. sana2.device/SANA2CMD_ONEVENT                   sana2.device/SANA2CMD_ONEVENT
  1121.  
  1122.    NAME
  1123.     OnEvent -- Return when specified event occures.
  1124.  
  1125.    FUNCTION
  1126.     This command returns when a particular event condition has
  1127.     occured on the network or this network interface.
  1128.  
  1129.    IO REQUEST
  1130.     S2io_Command    SANA2CMD_ONEVENT
  1131.     S2io_Flags      Supported flags are:
  1132.                         SANA2IOB_QUICK
  1133.     S2io_WireError  Event number to wait for.
  1134.  
  1135.    RESULTS
  1136.     S2io_Error      Zero if successful; non-zero otherwise.
  1137.     S2io_WireError  Event number that occured.
  1138.  
  1139.    NOTES
  1140.     If this device driver does not understand the specified event
  1141.     condition then the command returns immediately with S2io_Error
  1142.     non-zero. A successful return will have S2io_Error set to zero
  1143.     S2io_WireError set to the event number.
  1144.  
  1145.     All pending requests for a particular event will be returned
  1146.     when that event occurs.
  1147.  
  1148.     All event types that cover a particular condition are returned
  1149.     when that condition occures. For instance, if an error is
  1150.     returned by NetBuff.library during receive processing, events
  1151.     of types S2EVENT_ERROR, S2EVENT_RX and S2EVENT_NETBUFF would
  1152.     be returned if pending.
  1153.  
  1154.    SEE ALSO
  1155.  
  1156.    BUGS
  1157.  
  1158. sana2.device/SANA2CMD_ONLINE                     sana2.device/SANA2CMD_ONLINE
  1159.  
  1160.    NAME
  1161.     Online -- Put a network interface back in service.
  1162.  
  1163.    FUNCTION
  1164.     This command places an offline network interface back into
  1165.     service.
  1166.  
  1167.    IO REQUEST
  1168.     S2io_Command    SANA2CMD_ONLINE
  1169.  
  1170.    RESULTS
  1171.     S2io_Error      Zero if successful; non-zero otherwise.
  1172.     S2io_WireError  More specific error number.
  1173.  
  1174.    NOTES
  1175.     This command is responsible for putting the network interface
  1176.     hardware back into a known state and resets the unit global
  1177.     and special statistics.
  1178.  
  1179.    SEE ALSO
  1180.     sana2.device/SANA2CMD_OFFLINE
  1181.  
  1182.    BUGS
  1183.  
  1184. sana2.device/SANA2CMD_READORPHAN             sana2.device/SANA2CMD_READORPHAN
  1185.  
  1186.    NAME
  1187.     ReadOrphan -- Get a packet for which there is no reader.
  1188.  
  1189.    FUNCTION
  1190.     Get the next packet available that does not satisfy any
  1191.     then-pending CMD_READ requests. The data returned in the
  1192.     S2io_Body NetBuff is normally the Data Link Layer packet type
  1193.     field and the packet data. If bit SANA2IOB_RAW is set in
  1194.     S2io_Flags, then the entire Data Link Layer packet, including
  1195.     both header and trailer information, will be returned.
  1196.  
  1197.    IO REQUEST
  1198.     S2io_Command    CMD_READORPHAN
  1199.     S2io_Flags      Supported flags are:
  1200.                         SANA2IOB_RAW
  1201.                         SANA2IOB_QUICK
  1202.     S2io_Body       NetBuff to hold packet data.
  1203.  
  1204.    RESULTS
  1205.     S2io_Error      Zero if successful; non-zero otherwise.
  1206.     S2io_WireError  More specific error number.
  1207.     S2io_Flags      The following flags may be returned:
  1208.                         SANA2IOB_RAW
  1209.                         SANA2IOB_BCAST
  1210.                         SANA2IOB_MCAST
  1211.     S2io_SrcAddr    Source interface address of packet.
  1212.     S2io_DstAddr    Destination interface address of packet.
  1213.     S2io_DTLLength  Lenght of packet data as given by the Data
  1214.                         Link Layer protocol.
  1215.     S2io_Body       NetBuff with packet data.
  1216.  
  1217.    NOTES
  1218.     Only the first NetBuffSegment in the NetBuff passed in is
  1219.     guarenteed to be returned.
  1220.  
  1221.     To determine which protocol family the returned packet belongs
  1222.     to you may have to specify SANA2IOB_RAW to get the entire data
  1223.     link layer wrapper (which is where the protocol type may be
  1224.     kept). Notice this necessarily means that this cannot be done
  1225.     in a network interface independent fashion.
  1226.  
  1227.    SEE ALSO
  1228.     sana2.device/CMD_READ,
  1229.     sana2.device/CMD_WRITE
  1230.  
  1231.    BUGS
  1232.  
  1233. sana2.device/SANA2CMD_TRACKTYPE               sana2.device/SANA2CMD_TRACKTYPE
  1234.  
  1235.    NAME
  1236.     TrackType -- Accumulate statistics about a packet type.
  1237.  
  1238.    FUNCTION
  1239.     This command causes the device driver to accumulate statistics
  1240.     about a particular packet type. Packet type statistics, for
  1241.     the particular packet type, are zeroed by this command.
  1242.  
  1243.    IO REQUEST
  1244.     S2io_Command    SANA2CMD_TRACKTYPE
  1245.     S2io_PacketType Pointer to the packet type of interest.
  1246.  
  1247.    RESULTS
  1248.     S2io_Error      Zero if successful; non-zero otherwise.
  1249.     S2io_WireError  More specific error number.
  1250.  
  1251.    NOTES
  1252.  
  1253.    SEE ALSO
  1254.     sana2.device/SANA2CMD_UNTRACKTYPE,
  1255.     sana2.device/SANA2CMD_GETTYPESTATS
  1256.  
  1257.    BUGS
  1258.  
  1259. sana2.device/SANA2CMD_UNTRACKTYPE           sana2.device/SANA2CMD_UNTRACKTYPE
  1260.  
  1261.    NAME
  1262.     UntrackType -- End statistics about a packet type.
  1263.  
  1264.    FUNCTION
  1265.     This command causes the device driver to stop accumulating
  1266.     statistics about a particular packet type.
  1267.  
  1268.    IO REQUEST
  1269.     S2io_Command    SANA2CMD_UNTRACKTYPE
  1270.     S2io_PacketType Pointer to the packet type of interest.
  1271.  
  1272.    RESULTS
  1273.     S2io_Error      Zero if successful; non-zero otherwise.
  1274.     S2io_WireError  More specific error number.
  1275.  
  1276.    NOTES
  1277.  
  1278.    SEE ALSO
  1279.     sana2.device/SANA2CMD_TRACKTYPE,
  1280.     sana2.device/SANA2CMD_GETTYPESTATS
  1281.  
  1282.    BUGS
  1283.  
  1284.