TABLE OF CONTENTS sana2.device sana2.device/AbortIO() sana2.device/CMD_READ sana2.device/CMD_WRITE sana2.device/SANA2CMD_ADDMULTICASTADDRESS sana2.device/SANA2CMD_ADDSTATIONALIAS sana2.device/SANA2CMD_BROADCAST sana2.device/SANA2CMD_CONFIGINTERFACE sana2.device/SANA2CMD_DELMULTICASTADDRESS sana2.device/SANA2CMD_DELSTATIONALIAS sana2.device/SANA2CMD_DEVICEQUERY sana2.device/SANA2CMD_GETGLOBALSTATS sana2.device/SANA2CMD_GETSPECIALSTATS sana2.device/SANA2CMD_GETSTATIONADDRESS sana2.device/SANA2CMD_GETTYPESTATS sana2.device/SANA2CMD_MULTICAST sana2.device/SANA2CMD_OFFLINE sana2.device/SANA2CMD_ONEVENT sana2.device/SANA2CMD_ONLINE sana2.device/SANA2CMD_READORPHAN sana2.device/SANA2CMD_TRACKTYPE sana2.device/SANA2CMD_UNTRACKTYPE sana2.device 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, rsbx@cbmvax.commodore.com, (215) 431-9100 Martin Hunt, martin@cbmvax.commodore.com, (215) 431-9100 Perry Kivolowitz, ASDG Incorporated, (608) 273-6585 sana2.device/AbortIO() 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 sana2.device/CMD_READ 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 sana2.device/CMD_WRITE 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 sana2.device/SANA2CMD_ADDMULTICASTADDRESS.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 sana2.device/SANA2CMD_ADDSTATIONALIAS 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 sana2.device/SANA2CMD_BROADCAST 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 sana2.device/SANA2CMD_CONFIGINTERFACE 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. sana2.device/SANA2CMD_DELMULTICASTADDRESS.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 sana2.device/SANA2CMD_DELSTATIONALIAS 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 sana2.device/SANA2CMD_DEVICEQUERY 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 sana2.device/SANA2CMD_GETGLOBALSTATS 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 sana2.device/SANA2CMD_GETSPECIALSTATS 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 sana2.device/SANA2CMD_GETSTATIONADDRESSana2.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 sana2.device/SANA2CMD_GETTYPESTATS 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 sana2.device/SANA2CMD_MULTICAST 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 sana2.device/SANA2CMD_OFFLINE 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 sana2.device/SANA2CMD_ONEVENT 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 sana2.device/SANA2CMD_ONLINE 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 sana2.device/SANA2CMD_READORPHAN 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 sana2.device/SANA2CMD_TRACKTYPE 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 sana2.device/SANA2CMD_UNTRACKTYPE 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