Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/534.lha/SANA_II/sana2device.spec.pp/sana2device.spec

Text File | 1991-08-08 | 47.2 KB | 1,881 lines

$Id: sana2device.spec,v 1.11 91/05/14 14:01:47 rsbx Exp $

TABLE OF CONTENTS

 sana2.device
sana2.device/Init
sana2.device/Open
sana2.device/Close
sana2.device/BeginIO
sana2.device/AbortIO
sana2.device/Expunge
sana2.device/CMD_READ
sana2.device/CMD_WRITE
sana2.device/SANA2CMD_READORPHAN
sana2.device/SANA2CMD_DEVICEQUERY
sana2.device/SANA2CMD_GETSTATIONADDRESS
sana2.device/SANA2CMD_CONFIGINTERFACE
sana2.device/SANA2CMD_ADDSTATIONALIAS
sana2.device/SANA2CMD_DELSTATIONALIAS
sana2.device/SANA2CMD_ADDMULTICASTADDRESS
sana2.device/SANA2CMD_DELMULTICASTADDRESS
sana2.device/SANA2CMD_MULTICAST
sana2.device/SANA2CMD_BROADCAST
sana2.device/SANA2CMD_TRACKTYPE
sana2.device/SANA2CMD_UNTRACKTYPE
sana2.device/SANA2CMD_GETTYPESTATS
sana2.device/SANA2CMD_GETSPECIALSTATS
sana2.device/SANA2CMD_GETGLOBALSTATS
sana2.device/SANA2CMD_ONEVENT
sana2.device/SANA2CMD_ONLINE
sana2.device/SANA2CMD_OFFLINE
sana2.device/CMD_START
sana2.device/CMD_STOP
sana2.device/CMD_CLEAR
sana2.device/CMD_FLUSH
sana2.device/CMD_INVALID
sana2.device/CMD_RESET
sana2.device/CMD_UPDATE


******* sana2.device *************************************************
*
*    The SANA-II device specification represents a Data Transfer
*    Level interface standard for Amigas. The intent is: 1) for all
*    Amiga network hardware vendors to create a SANA-II device
*    driver for their hardware, 2) for all protocol stack writers
*    to access the networks via SANA-II device drivers, 3) any
*    protocol stack to work with any SANA-II device driver.
*
*
*   GOALS
*    Simplicity: A SANA-II device driver should be as simple to
*    write as any other Amiga device.
*
*    Low cost: A functional SANA-II device driver should take about
*    one man month or less for an experienced Amiga programmer with
*    Amiga device writing experience to write. A tuned and polished
*    SANA-II device should require only one additional man month.
*
*    Compatibility: All SANA-II device drivers behave largely the
*    same.
*
*    Low resource usage: A SANA-II device driver should not require
*    large amounts of memory, cpu cycles or any other system
*    resource to operate efficiently.
*
*    Ease of use: Using SANA-II devices should be the easiest way
*    for protocol stack writers to access the networks.
*
*
*   NON-GOALS
*    Lowest common denominator: Not all network interfaces can
*    support all the features available in this specification or
*    other network types.
*
*    Feature-itis: Not every feature of every type of network is
*    represented.
*
*    Network management tools: Analysis and debugging of a network
*    requires specialized software for that purpose.
*
*
*   STRUCTURES
*        struct IOSana2Req
*            {
*            struct Message S2io_Message;
*            struct Device *S2io_Device;
*            struct Unit   *S2io_Unit;
*
*            UWORD S2io_Command;
*            UBYTE S2io_Flags;
*            BYTE  S2io_Error;
*            ULONG S2io_WireError;
*
*            struct Sana2PacketType *S2io_PacketType;
*            UBYTE S2io_SrcAddr[SANA2_MAX_ADDR_BYTES];
*            UBYTE S2io_DstAddr[SANA2_MAX_ADDR_BYTES];
*            ULONG S2io_DataLength;
*            struct NetBuff S2io_Body;
*            void *S2io_StatData;
*            };
*
*        Message
*            Initialized and used the same as all device IORequest
*            Message structures.
*
*        Device
*            Device private.
*
*        Unit
*            Device private.
*
*        Command
*            Command requested.
*
*        Flags
*            Used to request special options and return status
*            information.
*
*        Error
*            Indicates completion status of a command in general
*            terms.
*
*        WireError
*            More specific error number. Only valid when S2io_Error
*            is non-zero.
*
*        PacketType
*            Pointer to a Sana2PacketType structure. The device
*            uses the contents of the structure to determine if a
*            packet from the network will satisfy a particular read
*            command, or to build the appropriate packet header and
*            trailer for a packet send. The device will not modify
*            either the pointer or the structure.
*
*        SrcAddr
*            The device fills in this field with the interface
*            address of the source of the packet that satisfied a
*            read command. The bytes used to hold the address will
*            be left justified but the bit layout is dependent on
*            the particular type of network.
*
*        DstAddr
*            This field is filled in with the interface destination
*            address of the packet for a send command. The bytes
*            used to hold the address will be left justified but
*            the bit layout is dependent on the particular type of
*            network.
*
*        DataLength
*            The device fills in this field with the size of the
*            packet data as it was sent on the wire. This does not
*            include the header and trailer information. Depending
*            on the network type and protocol type, the driver may
*            have to calculate this value.
*
*        Body
*            A NetBuff structure with the packet data.
*
*        StatData
*            Pointer to a data area in memory to place a a snapshot
*            of device statics. The data area must be long word
*            aligned.
*
*
*        struct Sana2PacketType
*            {
*            ULONG CanonicalType;
*            ULONG Magic;
*            ULONG Length;
*            UBYTE *Match;
*            UBYTE *Mask;
*            };
*
*        CanonicalType
*            Not used by the device.
*
*        Magic
*            Determines how the fields in this structure are to be
*            interpretted.
*
*        Length
*            Number of bytes pointed to be Match and Mask.
*
*        Match
*            Pointer to packet type match data. The data must be
*            long word (32 bit) aligned.
*
*        Mask
*            Pointer to packet type mask data. The data must be
*            long word (32 bit) aligned.
*
*
*        struct Sana2DeviceQuery
*            {
*            /*
*             * Standard information
*             */
*            ULONG SizeAvailable;
*            ULONG SizeSupplied;
*            LONG DevQueryFormat;
*            LONG DeviceLevel;
*            /*
*             * Common information
*             */
*            UWORD AddrFieldSize;
*            ULONG MTU;
*            LONG bps;
*            LONG HardwareType;
*            /*
*             * Format specific information
*             */
*            };
*
*        SizeAvailable
*            Size, in bytes, of the space available in which to
*            place device information. This includes both size
*            fields.
*
*        SizeSupplied
*            Size, in bytes, of the data supplied.
*
*        DevQueryFormat
*            The format defined here is format 0.
*
*        DeviceLevel
*            This spec defines level 0.
*
*        AddrFieldSize
*            The number of bits in an interface address.
*
*        MTU
*            Maximum Transmission Unit, the size, in bytes, of the
*            maximum packet size, not including header and trailer
*            information.
*
*        bps
*            Best guess at the raw line rate for this network in
*            bits per second.
*
*        HardwareType
*            Specifies the type of network wire the driver
*            controls.
*
*
*        struct Sana2PacketTypeStats
*            {
*            LONG PacketsSent;
*            LONG PacketsReceived;
*            LONG BytesSent;
*            LONG BytesReceived;
*            LONG PacketsDropped;
*            };
*
*        PacketsSent
*            Number of packets of a particular type sent.
*
*        PacketsReceived
*            Number of packets of a particular type that satisfied
*            a read command.
*
*        BytesSent
*            Number of bytes of data sent in packets of a
*        particular type.
*
*        BytesReceived
*            Number of bytes of data of a particular packet type
*            that satisfied a read command.
*
*        PacketsDropped
*            Number of packets of a particular type that were
*            received while there were no pending reads of that
*            packet type.
*
*
*        struct Sana2SpecialStatRecord
*            {
*            ULONG Type;
*            LONG Count;
*            char *String;
*            };
*
*        Type
*            Statistic identifier.
*
*        Count
*            Statistic itself.
*
*        String
*            Identifying string for the statistic. Should be plain
*            ASCII with no formatting characters.
*
*
*        struct Sana2SpecialStatHeader
*            {
*            ULONG RecordCountMax;
*            ULONG RecordCountSupplied;
*            struct Sana2SpecialStatRecord[RecordCountMax];
*            };
*
*        RecordCountMax
*            Space for this many number of records is available to
*            place statistics information in.
*
*        RecordCountSupplied
*            Number of statistic records supplied.
*
*
*        struct Sana2DeviceStats
*            {
*            LONG packets_received;
*            LONG packets_sent;
*            LONG framing_errors;
*            LONG bad_data;
*            LONG hard_misses;
*            LONG soft_misses;
*            LONG unknown_types_received;
*            LONG fifo_overruns;
*            LONG fifo_underruns;
*            LONG reconfigurations;
*            struct timeval last_start;
*            };
*
*        packets_received
*            Number of packets that this unit has received.
*
*        packets_sent
*            Number of packets that this unit has sent.
*
*        framing_errors
*            Number of framing errors detected.
*
*        bad_data
*            Number of bad packets received.
*
*        hard_misses
*            Number of packets lost due to insufficient resources
*            available in the network interface.
*
*        soft_misses
*            Number of packets lost due to insifficient resources
*            available on the host.
*
*        unknown_type_received
*            Number of packets received that had no pending read
*            command with the appropriate packet type.
*
*        fifo_overruns
*            Number of overruns encountered when attempting to
*            store received packets.
*
*        fifo_underruns
*            Number of underruns encountered when attempting to
*            send packets.
*
*        reconfigurations
*            Number of network reconfigurations since this unit was
*            last configured.
*
*        last_start
*            The time when this unit last went online.
*
*
*   CONSTANTS
*    OpenDevice flags argument (SANA2OPB_xxx):
*        MINE
*            Exclusive access to the unit requested.
*
*        PROM
*            Promiscuous mode requested.
*
*
*    IOSana2Req S2io_Flags field (SANA2IOB_xxx):
*        RAW
*            Raw packet read/write requested.
*
*        BCAST
*            Broadcast packet (received).
*
*        MCAST
*            Multicast packet (received).
*
*        QUICK
*            Quick IO requested.
*
*
*    IOSana2Req S2io_Error field (S2ERR_xxx):
*        NO_RESOURCES
*            Insufficient resources available.
*
*        UNKNOWN_ENTITY
*            Specified entity unknown or not found.
*
*        BAD_ARGUMENT
*            Noticably bad argument.
*
*        BAD_STATE
*            Command inappropriate for current state.
*
*        BAD_ADDRESS
*            Noticably bad address.
*
*        MTU_EXCEEDED
*            Write data too large.
*
*        BAD_PROTOCOL
*            Noticably bad packet type.
*
*        NOT_SUPPORTED
*            Command is not supported by this driver. This is
*            similar to IOERR_NOCMD as defined in exec/errors.h but
*            S2ERR_NOT_SUPPORTED indicates that the requested
*            command is a valid SANA-II command and that the driver
*            does not support it, e.g. SANA2CMD_MULTICAST.
*
*        SOFTWARE
*            Software error of some kind.
*
*
*    IOSana2Req S2io_WireError field (S2WERR_xxx):
*        NOT_CONFIGURED
*            Command requires unit to be configured.
*
*        UNIT_ONLINE
*            Command requires that the unit be offline.
*
*        UNIT_OFFLINE
*            Command requires that the unit be online.
*
*        ALREADY_TRACKED
*            Protocol is already being tracked.
*
*        NOT_TRACKED
*            Protocol is not being tracked.
*
*        NETBUFF_ERROR
*            NetBuff.library error return caused error.
*
*        SRC_ADDRESS
*            Problem with the source address field.
*
*        DST_ADDRESS
*            Problem with destination address field.
*
*        BAD_BROADCAST
*            Problem with an attempt to broadcast.
*
*        BAD_MULTICAST
*            Problem with an attempt to multicast.
*
*        ALIAS_LIST_FULL
*            Station alias list full.
*
*        BAD_ALIAS
*            Bad or unknown station alias.
*
*        MULTICAST_FULL
*            Multicast address list full.
*
*        BAD_EVENT
*            Event specified is unknown.
*
*        BAD_STATDATA
*            The S2IO_StatData pointer or the data it points to
*            failed a sanity check.
*
*        PROTOCOL_UNKNOWN
*            The protocol specified is unknown or the type of magic
*            used by the request protocol is unknown.
*
*        IS_CONFIGURED
*            Attempt to reconfigure the unit.
*
*        NULL_POINTER
*            A NULL pointer was detected in one of the arguments.
*
*
*    Event types (S2EVENT_xxx):
*        ERROR
*            Return when any error occures.
*
*        TX
*            Return on any transmit error.
*
*        RX
*            Return on any receive error.
*
*        ONLINE
*            Return when unit goes online.
*
*        OFFLINE
*            Return when unit goes offline.
*
*        NETBUFF
*            Return on any NetBuff.library error.
*
*        HARDWARE
*            Return when any hardware error occures.
*
*        SOFTWARE
*            Return when any software error occures.
*
*
*   SEE ALSO
*    NetBuff.library documentation.
*
*    Separate document for each type of network detailing specific
*    device requirements.
*
*
*   CREDITS
*    Raymond S. Brand,   [e-mail],  [phone]
*    Martin Hunt,      [e-mail],  [phone]
*    Perry Kivolowitz,           ASDG Incorporated,  [phone]
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


*****i* sana2.device/Init() ******************************************
*
*   NAME
*    Init -- Initialize the device from nothing.
*
*   SYNOPSIS
*    Init( SegList )
*          A0
*
*    void Init( void * );
*
*   FUNCTION
*    This routine initializes the device from nothing.
*
*   INPUTS
*    SegList         Pointer to the SegList for the device code.
*
*   NOTES
*
*   SEE ALSO
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*
*   REGISTER USAGE
*
* A0 --    seglist    ?????    ?????
* A6 --    exec    ?????    exec
*


*****i* sana2.device/Open() ******************************************
*
*   NAME
*    Open -- Request an opening of the network device.
*
*   SYNOPSIS
*    error = Open( unit, Sana2Req, flags )
*    D0            D0    A1        D1
*
*    BYTE Open( ULONG, struct IOSana2Req *, ULONG );
*
*   FUNCTION
*    This function is called by exec.library OpenDevice().
*
*    This function performs whatever initialization is required per
*    device open and initializes the Sana2Req for use by the
*    device.
*
*   INPUTS
*    unit            Device unit to open.
*    Sana2Req        Pointer to IOSana2Req structure to be
*                        initialized by the sana2.device.
*    flags           Supported flags are:
*                        SANA2OPB_MINE
*                        SANA2OPB_PROM
*
*   RESULTS
*    error           same as io_Error
*    io_Error        Zero if successful; non-zero otherwise.
*    io_Device       A pointer to whatever device will handle the
*                        calls for this unit.  This pointer may be
*                        different depending on what unit is
*                        requested.
*
*   NOTES
*
*   SEE ALSO
*    exec.library/OpenDevice(),
*    exec.library/CloseDevice()
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*    The system is single threaded while executing this function.
*
*
*   REGISTER USAGE
*
* D0 --    unit    ?????    ?????
* D1 --    flags    ?????    ?????
* A1 -- IOReq    ?????    ?????
* A6 --    device    ?????    device
*


*****i* sana2.device/Close() *****************************************
*
*   NAME
*    CloseDevice -- Close the device.
*
*   SYNOPSIS
*    Close( Sana2Req )
*           A1
*
*    void Close( struct IOSana2Req * );
*
*   FUNCTION
*    This function is called by exec.library CloseDevice().
*
*    This function performs whatever cleanup is required at device
*    closes.
*
*    Note that all IORequests MUST be complete before closing. If
*    any are pending, your program must AbortIO() then WaitIO()
*    each outstanding IORequest to complete them.
*
*   INPUTS
*    Sana2Req        Pointer to Sana2Req initialized by Open().
*
*   NOTES
*
*   SEE ALSO
*    exec.library/CloseDevice(),
*    exec.library/OpenDevice()
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*
*   REGISTER USAGE
*
* D0 --    ?????    ?????    SegList
* A1 -- IOReq    ?????    ?????
* A6 --    device    ?????    device
*


*****i* sana2.device/BeginIO() ***************************************
*
*   NAME
*    BeginIO -- Start an IO operation.
*
*   SYNOPSIS
*    BeginIO( Sana2Req )
*             A1
*
*    void BeginIO( struct IOSana2Req * );
*
*   FUNCTION
*    This is a direct function call to the device. It is intended
*    for more advanced programmers. See exec's DoIO() and SendIO()
*    for the normal method of calling devices.
*
*    This function initiates a I/O request made to a sana2.device.
*
*   INPUTS
*    Sana2Req        Pointer to an initialized IOSana2Req
*                        structure.
*    S2io_Message    A mn_ReplyPort is required.
*    S2io_Device     Set by Open().
*    S2io_Unit       Set by Open().
*    S2io_Command    Needs to be set to proper command
*    S2io_Flags      If the IOB_QUICK bit is set the device will
*                        attempt to finish command without
*                        'Replying' through the exec message
*                        system. The IOB_QUICK bit will be cleared
*                        if the request will 'Replied' when
*                        complete.
*    S2io_PacketType Pointer to the Sana2PacketType structure for
*                        the packet type of interest.
*    S2io_SrcAddr    Source interface address of the packet.
*    S2io_DstAddr    Destination interface address of the packet.
*    S2io_Body       Contents depend on particular command.
*    S2io_StatData   Pointer to area to store statistics data.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*    S2io_SrcAddr    Source interface address of the packet.
*    S2io_DstAddr    Destination interface address of the packet.
*    S2io_Body       Contents depend on particular command.
*
*   NOTES
*
*   SEE ALSO
*    exec.library/DoIO(),
*    exec.library/SendIO()
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*
*   REGISTER USAGE
*
* A1 -- IOReq    ?????    ?????
* A6 --    device    ?????    device
*


******* sana2.device/AbortIO() ***************************************
*
*   NAME
*    AbortIO -- Remove an existing device request.
*
*   SYNOPSIS
*    error = AbortIO( Sana2Req )
*    D0               A1
*
*    LONG AbortIO( struct IOSana2Req * );
*
*   FUNCTION
*    This is an exec.library call.
*
*    This function aborts an ioRequest. If the request is active,
*    it may or may not be aborted. If the request is queued it is
*    removed. The request will be returned in the same way as if
*    it had normally completed.
*
*   INPUTS
*    Sana2Req        Sana2Req to be aborted.
*
*   RESULTS
*    error           Zero if the request was aborted, non-zero
*                        otherwise. S2io_Error in Sana2Req will be
*                        set to IOERR_ABORTED (-2) if it was
*                        aborted.
*
*   NOTES
*
*   SEE ALSO
*    exec.library/AbortIO()
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*
*   REGISTER USAGE
*
* D0 --    ?????    ?????    error
* A1 -- IOReq    ?????    ?????
* A6 --    device    ?????    device
*


*****i* sana2.device/Expunge() ***************************************
*
*   NAME
*    Expunge -- Free device resources and dependencies.
*
*   SYNOPSIS
*    Expunge( )
*
*    void Expunge( void );
*
*   FUNCTION
*    This function deallocates all memory and other resources
*    associated with the device, if possible.
*
*   NOTES
*    This function is not permitted to wait.
*
*   SEE ALSO
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*
*   REGISTER USAGE
*
* D0 --    ?????    ?????    SegList
* A6 --    device    ?????    device
*


******* sana2.device/CMD_READ ****************************************
*
*   NAME
*    Read -- Get a packet from the network.
*
*   FUNCTION
*    Get the next packet available of the requested packet type.
*    The data returned in the S2io_Body NetBuff is normally the
*    Data Link Layer packet data only. If bit SANA2IOB_RAW is set
*    in S2io_Flags, then the entire Data Link Layer packet,
*    including both header and trailer information, will be
*    returned.
*
*   IO REQUEST
*    S2io_Command    CMD_READ
*    S2io_Flags      Supported flags are:
*                        SANA2IOB_RAW
*                        SANA2IOB_QUICK
*    S2io_PacketType Pointer to packet type desired.
*    S2io_Body       NetBuff to hold packet data.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*    S2io_Flags      The following flags may be returned:
*                        SANA2IOB_RAW
*                        SANA2IOB_BCAST
*                        SANA2IOB_MCAST
*    S2io_SrcAddr    Source interface address of packet.
*    S2io_DstAddr    Destination interface address of packet.
*    S2io_DTLLength  Length of packet data as given by the Data
*                        Link Layer protocol.
*    S2io_Body       NetBuff with packet data.
*
*   NOTES
*    Only the first NetBuffSegment in the NetBuff passed is
*    guaranteed to be returned.
*
*   SEE ALSO
*    sana2.device/SANA2CMD_READORPHAN,
*    sana2.device/CMD_WRITE
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/CMD_WRITE ***************************************
*
*   NAME
*    Write -- Send packet to the network.
*
*   FUNCTION
*    This command causes the packet to be sent to the specified
*    network interface. Normally, appropriate packet header and
*    trailer information will be added to the packet data when it
*    is sent. If bit SANA2IOB_RAW is set in io-Flags, then the
*    S2io_Body NetBuff is assumed to contain an entire Data Link
*    Layer packet and will be sent unmodified.
*
*    The data in the S2io_Body NetBuff is returned unmodified; but,
*    the distribution of the data in, and the number of
*    NetBuffSegments, the S2io_Body NetBuff may be modified.
*
*   IO REQUEST
*    S2io_Command    CMD_WRITE
*    S2io_Flags      Supported flags are:
*                        SANA2IOB_RAW
*                        SANA2IOB_QUICK
*    S2io_PacketType Pointer to type of packet to send.
*    S2io_DstAddr    Destination interface address for this packet.
*    S2io_Body       NetBuff with packet data.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*
*   SEE ALSO
*    sana2.device/CMD_READ,
*    sana2.device/SANA2CMD_BROADCAST,
*    sana2.device/SANA2CMD_MULTICAST
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_READORPHAN *****************************
*
*   NAME
*    ReadOrphan -- Get a packet for which there is no reader.
*
*   FUNCTION
*    Get the next packet available that does not satisfy any
*    then-pending CMD_READ requests. The data returned in the
*    S2io_Body NetBuff is normally the Data Link Layer packet type
*    field and the packet data. If bit SANA2IOB_RAW is set in
*    S2io_Flags, then the entire Data Link Layer packet, including
*    both header and trailer information, will be returned.
*
*   IO REQUEST
*    S2io_Command    CMD_READORPHAN
*    S2io_Flags      Supported flags are:
*                        SANA2IOB_RAW
*                        SANA2IOB_QUICK
*    S2io_Body       NetBuff to hold packet data.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*    S2io_Flags      The following flags may be returned:
*                        SANA2IOB_RAW
*                        SANA2IOB_BCAST
*                        SANA2IOB_MCAST
*    S2io_SrcAddr    Source interface address of packet.
*    S2io_DstAddr    Destination interface address of packet.
*    S2io_DTLLength  Lenght of packet data as given by the Data
*                        Link Layer protocol.
*    S2io_Body       NetBuff with packet data.
*
*   NOTES
*    Only the first NetBuffSegment in the NetBuff passed in is
*    guarenteed to be returned.
*
*    To determine which protocol family the returned packet belongs
*    to you may have to specify SANA2IOB_RAW to get the entire data
*    link layer wrapper (which is where the protocol type may be
*    kept). Notice this necessarily means that this cannot be done
*    in a network interface independent fashion.
*
*   SEE ALSO
*    sana2.device/CMD_READ,
*    sana2.device/CMD_WRITE
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_DEVICEQUERY ****************************
*
*   NAME
*    DeviceQuery -- Return parameters for this network interface.
*
*   FUNCTION
*    This command causes the device driver to report information
*    about the device. Up to DevQuerySizeAvailable bytes of the
*    information is copied into a buffer pointed to by
*    S2io_StatData. The format of the data is as follows:
*
*        struct Sana2DeviceQuery
*            {
*            /*
*             * Standard information
*             */
*            ULONG DevQuerySizeAvailble; /* bytes available */
*            ULONG DevQuerySizeSupplied; /* bytes supplied */
*            LONG  DevQueryFormat;   /* this is type 0 */
*            LONG  DeviceLevel;      /* this document is level 0 */
*
*            /*
*             * Common information
*             */
*            UWORD AddrFieldSize;    /* address size in bits */
*            ULONG MTU;              /* maximum packet data size */
*            LONG  bps;              /* line rate (bits/sec) */
*            LONG  HardwareType;     /* what the wire is */
*
*            /*
*             * Format specific information
*             */
*            };
*
*    The DeviceQueryAvailable specifies the number of bytes that
*    the caller is prepared to accomodate, including the standard
*    information fields.
*
*    DevQuerySizeSupplied is the number of bytes actually supplied,
*    including the standard information fields, which will not
*    exceed DevQuerySizeAvailable.
*
*    The values used to identify the type of physical hardware are
*    the same values used in the hardware type field (hdr) of
*    Address Resolution Protocol (ARP) packets as defined by
*    RFC-826 (ARP) and RFC-1060 (Assigned Numbers, March 1990).
*
*    The following are defined in RFC-1060.
*
*        Hardware Type (hrd)
*
*            Type   Description
*            ----   -----------
*              1    Ethernet (10Mb)
*              2    Experimental Ethernet (3Mb)
*              3    Amateur Radio AX.25
*              4    Proteon ProNET Token Ring
*              5    Chaos
*              6    IEEE 802 Networks
*              7    ARCNET
*              8    Hyperchannel
*              9    Lanstar
*             10    Autonet Short Address
*             11    LocalTalk
*             12    LocalNet (IBM PCNet or SYTEK LocalNET)
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_DEVICEQUERY
*    S2io_StatData   Pointer to Sana2DeviceQuery structure to fill
*                        in.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*
*   SEE ALSO
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_GETSTATIONADDRESS **********************
*
*   NAME
*    GetStationAddress -- Get default and interface address.
*
*   FUNCTION
*    This command causes the device driver to copy the current
*    interface address into S2io_SrcAddr, and to copy the factory
*    default station address into S2io_DstAddr.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_GETSTATIONADDRESS
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*    S2io_SrcAddr    Default interface address.
*    S2io_DstAddr    Current interface address.
*
*   NOTES
*
*   SEE ALSO
*    sana2.device/SANA2CMD_CONFIGINTERFACE
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_CONFIGINTERFACE ************************
*
*   NAME
*    ConfigInterface -- Configure the network interface.
*
*   FUNCTION
*    This command causes the device driver to initialize the
*    interface hardware and to set the network interface address to
*    the address in S2io_SrcAddr. This command can only be executed
*    once and, if successful, will leave the driver and network
*    interface fully operational and the network interface in
*    S2io_SrcAddr.
*
*    To set the interface address to the factory address, the
*    network management software must use GetStationAddress first
*    and then call ConfigInterface with the result. If there is no
*    factory address then the network software must pick an address
*    to use.
*
*    Until this command is executed the device will not listen for
*    any packets on the hardware.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_CONFIGINTERFACE
*    S2io_Flags      Supported flags are:
*                        SANA2IOB_QUICK
*    S2io_SrcAddr    Address for this interface.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*    S2io_SrcAddr    Address of this interface as configured.
*
*   NOTES
*    Some networks have the interfaces choose a currently unused
*    interface address each time the interface is initialized. The
*    caller must check S2io_SrcAddr for the actual interface
*    address after configuring the interface.
*
*   SEE ALSO
*    sana2.device/SANA2CMD_GETSTATIONADDRESS
*
*   BUGS
*    What to do when/if the network interface address changes due
*    to a network reconfiguration.
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_ADDSTATIONALIAS ************************
*
*   NAME
*    AddStationAlias -- Add interface address alias.
*
*   FUNCTION
*    This function adds another network interface address to which
*    the network interface should respond.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_ADDSTATIONALIAS
*    S2io_SrcAddr    Alias to add.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*    Since alias interface addresses are not bound to a particular
*    packet type or read request, each added interface alias
*    address has an "added" count associated with it.
*
*   SEE ALSO
*    sana2.device/SANA2CMD_DELSTATIONALIAS
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_DELSTATIONALIAS ************************
*
*   NAME
*    DelStationAlias -- Delete a interface address alias.
*
*   FUNCTION
*    This function deletes a network interface address from the
*    list of addresses to which this interface should respond.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_DELSTATIONALIAS
*    S2io_SrcAddr    Alias to delete.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*    Since alias interface addresses are not bound to a particular
*    packet type or read request, each added interface alias
*    address has an "added" count associated with it.
*
*   SEE ALSO
*    sana2.device/SANA2CMD_ADDSTATIONALIAS
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_ADDMULTICASTADDRESS ********************
*
*   NAME
*    AddMulticastAddress -- Enable an interface multicast address.
*
*   FUNCTION
*    This command causes the device driver to enable multicast
*    packet reception for the requested address.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_ADDMULTICASTADDRESS
*    S2io_SrcAddr    Multicast address to enable.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*    Since multicast addresses are not "bound" to a particular
*    packet type, each enabled multicast address has an "enabled"
*    count associated with it.
*
*   SEE ALSO
*    sana2.device/SANA2CMD_DELMULTICASTADDRESS
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_DELMULTICASTADDRESS ********************
*
*   NAME
*    DelMultiCastAddress -- Disable an interface multicast address.
*
*   FUNCTION
*    This command causes device driver to disable multicast packet
*    reception for the requested address.
*
*    It is an error to disable a multicast address that is not
*    enabled.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_DELMULTICASTADDRESS
*    S2io_SrcAddr    Multicast address to disable.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*    Since multicast addresses are not "bound" to a particular
*    packet type, each enabled multicast address has an "enabled"
*    count associated with it.
*
*   SEE ALSO
*    sana2.device/SANA2CMD_ADDMULTICASTADDRESS
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_MULTICAST ******************************
*
*   NAME
*    Multicast -- Multicast a packet on network.
*
*   FUNCTION
*    This command works the same as CMD_WRITE except that it also
*    performs whatever special processing of the packet is required
*    to do a multicast send. The actual multicast mechanism is
*    neccessarily network/interface/device specific.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_MULTICAST
*    S2io_Flags      Supported flags are:
*                        SANA2IOB_RAW
*                        SANA2IOB_QUICK
*    S2io_PacketType Pointer to type of packet to send.
*    S2io_DstAddr    Destination interface address for this packet.
*    S2io_Body       NetBuff with packet data.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*                        This command can fail for many reasons and
*                        is not supported by all networks and/or
*                        network interfaces.
*    S2io_WireError  More specific error number.
*
*   NOTES
*    The address supplied in S2io_DstAddr will be sanity checked
*    (if possible) by the driver. If the supplied address fails
*    this sanity check, the multicast request will fail
*    immediately.
*
*   SEE ALSO
*    sana2.device/CMD_WRITE,
*    sana2.device/SANA2CMD_BROADCAST
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_BROADCAST ******************************
*
*   NAME
*    Broadcast -- Broadcast a packet on network.
*
*   FUNCTION
*    This command works the same as CMD_WRITE except that it also
*    performs whatever special processing of the packet is required
*    to do a broadcast send. The actual broadcast mechanism is
*    neccessarily network/interface/device specific.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_BROADCAST
*    S2io_Flags      Supported flags are:
*                        SANA2IOB_RAW
*                        SANA2IOB_QUICK
*    S2io_PacketType Pointer to type of packet to send.
*    S2io_Body       NetBuff with packet data.
*
*   RESULTS
*    S2io_DstAddr    The contents of this field are to be
*                        considered trash upon return of the IOReq.
*    S2io_Error      Zero if successful; non-zero otherwise.
*                        This command can fail for many reasons and
*                        is not supported by all networks and/or
*                        network interfaces.
*    S2io_WireError  More specific error number.
*
*   NOTES
*
*   SEE ALSO
*    sana2.device/CMD_WRITE,
*    sana2.device/SANA2CMD_MULTICAST
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_TRACKTYPE ******************************
*
*   NAME
*    TrackType -- Accumulate statistics about a packet type.
*
*   FUNCTION
*    This command causes the device driver to accumulate statistics
*    about a particular packet type. Packet type statistics, for
*    the particular packet type, are zeroed by this command.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_TRACKTYPE
*    S2io_PacketType Pointer to the packet type of interest.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*
*   SEE ALSO
*    sana2.device/SANA2CMD_UNTRACKTYPE,
*    sana2.device/SANA2CMD_GETTYPESTATS
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_UNTRACKTYPE ****************************
*
*   NAME
*    UntrackType -- End statistics about a packet type.
*
*   FUNCTION
*    This command causes the device driver to stop accumulating
*    statistics about a particular packet type.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_UNTRACKTYPE
*    S2io_PacketType Pointer to the packet type of interest.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*
*   SEE ALSO
*    sana2.device/SANA2CMD_TRACKTYPE,
*    sana2.device/SANA2CMD_GETTYPESTATS
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_GETTYPESTATS ***************************
*
*   NAME
*    GetTypeStats -- Get accumulated type specific statistics.
*
*   FUNCTION
*    This command causes the device driver to retrieve various
*    packet type specific runtime statistics for this network
*    interface. The format of the data returned is as follows:
*
*        struct Sana2TypeStatData
*            {
*            LONG PacketsSent;
*            LONG PacketsReceived;
*            LONG BytesSent;
*            LONG BytesReceived;
*            LONG PacketsDropped;
*            };
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_GETTYPESTATS
*    S2io_PacketType Pointer to the packet type of interest.
*    S2io_StatData   Pointer to TypeStatData structure to fill in.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*    Statistics for a particular packet type are only available
*    while that packet type is being ``tracked''.
*
*   SEE ALSO
*    sana2.device/SANA2CMD_TRACKTYPE,
*    sana2.device/SANA2CMD_UNTRACKTYPE
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_GETSPECIALSTATS ************************
*
*   NAME
*    GetSpecialStats -- Get network type specific statistics.
*
*   FUNCTION
*    This function returns statistics which are specific to the
*    type of network medium this driver controls. For example, this
*    command could return statistics common to all Ethernets which
*    are not common to all network mediums in general.
*
*    The supplied Sana2SpecialStatData structure is given below:
*
*        struct Sana2SpecialStatData
*            {
*            ULONG RecordCountMax;
*            ULONG RecordCountSupplied;
*            struct Sana2StatRecord[RecordCountMax];
*            };
*
*    The format of the data returned is:
*
*        struct Sana2StatRecord
*            {
*            ULONG Type;     /* commodore registered */
*            LONG Count;     /* the stat itself */
*            char *String;   /* null terminated */
*            };
*
*    The RecordCountMax field specifies the number of records that
*    the caller is prepared to accomodate.
*
*    RecordCountSupplied is the number of record actually supplied
*    which will not exceed RecordCountMax.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_GETSPECIALSTATS
*    S2io_StatData   Pointer to a Sana2SpecialStatData structure to
*                        fill. RecordCountMax must be initialized.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*    Commodore shall maintain registered statistic Types.
*
*   SEE ALSO
*    sana2.device/SANA2CMD_GETGLOBALSTATS
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_GETGLOBALSTATS *************************
*
*   NAME
*    GetGlobalStats -- Get interface accumulated statistics.
*
*   FUNCTION
*    This command causes the device driver to retrieve various
*    global runtime statistics for this network interface. The
*    format of the data returned is as follows:
*
*        struct Sana2DeviceStats
*            {
*            LONG packets_received;
*            LONG packets_sent;
*            LONG framming_errors;
*            LONG bad_data;
*            LONG bytes_received;
*            LONG bytes_sent;
*            LONG hard_misses;
*            LONG soft_misses;
*            LONG unknown_types_received;
*            LONG fifo_overruns;
*            LONG fifo_underruns;
*            LONG reconfigurations;
*            timeval last_start;
*            };
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_GETGLOBALSTATS
*    S2io_StatData   Pointer to Sana2DeviceStats structure to fill.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*
*   SEE ALSO
*    sana2.device/SANA2CMD_GETSPECIALSTATS
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_ONEVENT ********************************
*
*   NAME
*    OnEvent -- Return when specified event occures.
*
*   FUNCTION
*    This command returns when a particular event condition has
*    occured on the network or this network interface.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_ONEVENT
*    S2io_Flags      Supported flags are:
*                        SANA2IOB_QUICK
*    S2io_WireError  Event number to wait for.
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  Event number that occured.
*
*   NOTES
*    If this device driver does not understand the specified event
*    condition then the command returns immediately with S2io_Error
*    non-zero. A successful return will have S2io_Error set to zero
*    S2io_WireError set to the event number.
*
*    All pending requests for a particular event will be returned
*    when that event occurs.
*
*    All event types that cover a particular condition are returned
*    when that condition occures. For instance, if an error is
*    returned by NetBuff.library during receive processing, events
*    of types S2EVENT_ERROR, S2EVENT_RX and S2EVENT_NETBUFF would
*    be returned if pending.
*
*   SEE ALSO
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_ONLINE *********************************
*
*   NAME
*    Online -- Put a network interface back in service.
*
*   FUNCTION
*    This command places an offline network interface back into
*    service.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_ONLINE
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*    This command is responsible for putting the network interface
*    hardware back into a known state and resets the unit global
*    and special statistics.
*
*   SEE ALSO
*    sana2.device/SANA2CMD_OFFLINE
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


******* sana2.device/SANA2CMD_OFFLINE ********************************
*
*   NAME
*    Offline -- Remove interface from service.
*
*   FUNCTION
*    This command removes a network interface from service.
*
*   IO REQUEST
*    S2io_Command    SANA2CMD_OFFLINE
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*    S2io_WireError  More specific error number.
*
*   NOTES
*    Aborts all pending reads and writes with S2io_Error set to
*    SANA2ERROR_OUTOFSERVICE.
*
*    While the interface is offline, all read, writes and any other
*    command that touches interface hardware will be rejected with
*    S2io_Error set to SANA2ERROR_OUTOFSERVICE.
*
*    This command is intended to permit a network interface to be
*    tested on an otherwise live system.
*
*   SEE ALSO
*    sana2.device/SANA2CMD_ONLINE
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


*****i* sana2.device/CMD_START ***************************************
*
*   NAME
*    Start -- Restart device operation.
*
*   FUNCTION
*    Does not apply to this class of device.
*
*   IO REQUEST
*    S2io_Command    CMD_ONLINE
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*
*   NOTES
*
*   SEE ALSO
*    sana2.device/CMD_STOP
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*    Does not apply to this class of device.
*


*****i* sana2.device/CMD_STOP ****************************************
*
*   NAME
*    Stop -- Pause device operation.
*
*   FUNCTION
*    Does not apply to this class of device.
*
*   IO REQUEST
*    S2io_Command    CMD_OFFLINE
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*
*   NOTES
*
*   SEE ALSO
*    sana2.device/CMD_START
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*    Does not apply to this class of device.
*


*****i* sana2.device/CMD_CLEAR ***************************************
*
*   NAME
*    Clear -- Clear internal network interface read buffers.
*
*   FUNCTION
*    Does not apply to this class of device.
*
*   IO REQUEST
*    S2io_Command    CMD_CLEAR
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*
*   NOTES
*
*   SEE ALSO
*    sana2.device/UPDATE,
*    sana2.device/CLEAR
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*    Does not apply to this class of device.
*


*****i* sana2.device/CMD_FLUSH ***************************************
*
*   NAME
*    Flush -- Clear internal network interface write buffers.
*
*   FUNCTION
*    Does not apply to this class of device.
*
*   IO REQUEST
*    S2io_Command    CMD_FLUSH
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*
*   NOTES
*
*   SEE ALSO
*    sana2.device/AbortIO(),
*    sana2.device/CMD_UPDATE,
*    sana2.device/CMD_CLEAR
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*    Does not apply to this class of device.
*


*****i* sana2.device/CMD_INVALID *************************************
*
*   NAME
*    Invalid -- Return with error IOERR_NOCMD.
*
*   FUNCTION
*    This command causes device driver to reply with an error
*    IOERR_NOCMD as defined in exec/errors.h indicating the command
*    is not supported.
*
*   IO REQUEST
*    S2io_Command    CMD_INVALID
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*
*   NOTES
*
*   SEE ALSO
*
*   BUGS
*    Not known to be useful at this time.
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*


*****i* sana2.device/CMD_RESET ***************************************
*
*   NAME
*    Reset -- Reset the network interface to initialized state.
*
*   FUNCTION
*    Does not apply to this class of device.
*
*   IO REQUEST
*    S2io_Command    CMD_RESET
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*
*   NOTES
*
*   SEE ALSO
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*    Does not apply to this class of device.
*


*****i* sana2.device/CMD_UPDATE **************************************
*
*   NAME
*    Update -- Force packets out to device
*
*   FUNCTION
*    Does not apply to this class of device.
*
*   IO REQUEST
*    S2io_Command    CMD_UPDATE
*
*   RESULTS
*    S2io_Error      Zero if successful; non-zero otherwise.
*
*   NOTES
*
*   SEE ALSO
*    sana2.device/CMD_CLEAR,
*    sana2.device/CMD_FLUSH
*
*   BUGS
*
**********************************************************************
*
*   IMPLEMENTATION NOTES
*
*    Does not apply to this class of device.
*