Path: news.larc.nasa.gov!amiga-request From: amiga-request@ab20.larc.nasa.gov (Amiga Sources/Binaries Moderator) Subject: v91i142: SANA-II - SANA-II Network Device Driver Specification, Part03/03 Reply-To: rsbx@cbmvax.uucp (Raymond S. Brand) Newsgroups: comp.sources.amiga Message-ID: References: Date: 30 Jul 91 00:26:09 GMT Approved: tadguy@uunet.UU.NET (Tad Guy) X-Mail-Submissions-To: amiga@uunet.uu.net X-Post-Discussions-To: comp.sys.amiga.misc Submitted-by: rsbx@cbmvax.uucp (Raymond S. Brand) Posting-number: Volume 91, Issue 142 Archive-name: devices/sana-ii/part03 #!/bin/sh # This is a shell archive. Remove anything before this line, then unpack # it by saving it into a file and typing "sh file". To overwrite existing # files, type "sh file -c". You can also feed this as standard input via # unshar, or by typing "sh 'sana2device.spec' <<'END_OF_FILE' X$Id: sana2device.spec,v 1.11 91/05/14 14:01:47 rsbx Exp $ X XTABLE OF CONTENTS X X sana2.device Xsana2.device/Init Xsana2.device/Open Xsana2.device/Close Xsana2.device/BeginIO Xsana2.device/AbortIO Xsana2.device/Expunge Xsana2.device/CMD_READ Xsana2.device/CMD_WRITE Xsana2.device/SANA2CMD_READORPHAN Xsana2.device/SANA2CMD_DEVICEQUERY Xsana2.device/SANA2CMD_GETSTATIONADDRESS Xsana2.device/SANA2CMD_CONFIGINTERFACE Xsana2.device/SANA2CMD_ADDSTATIONALIAS Xsana2.device/SANA2CMD_DELSTATIONALIAS Xsana2.device/SANA2CMD_ADDMULTICASTADDRESS Xsana2.device/SANA2CMD_DELMULTICASTADDRESS Xsana2.device/SANA2CMD_MULTICAST Xsana2.device/SANA2CMD_BROADCAST Xsana2.device/SANA2CMD_TRACKTYPE Xsana2.device/SANA2CMD_UNTRACKTYPE Xsana2.device/SANA2CMD_GETTYPESTATS Xsana2.device/SANA2CMD_GETSPECIALSTATS Xsana2.device/SANA2CMD_GETGLOBALSTATS Xsana2.device/SANA2CMD_ONEVENT Xsana2.device/SANA2CMD_ONLINE Xsana2.device/SANA2CMD_OFFLINE Xsana2.device/CMD_START Xsana2.device/CMD_STOP Xsana2.device/CMD_CLEAR Xsana2.device/CMD_FLUSH Xsana2.device/CMD_INVALID Xsana2.device/CMD_RESET Xsana2.device/CMD_UPDATE X X X******* sana2.device ************************************************* X* X* The SANA-II device specification represents a Data Transfer X* Level interface standard for Amigas. The intent is: 1) for all X* Amiga network hardware vendors to create a SANA-II device X* driver for their hardware, 2) for all protocol stack writers X* to access the networks via SANA-II device drivers, 3) any X* protocol stack to work with any SANA-II device driver. X* X* X* GOALS X* Simplicity: A SANA-II device driver should be as simple to X* write as any other Amiga device. X* X* Low cost: A functional SANA-II device driver should take about X* one man month or less for an experienced Amiga programmer with X* Amiga device writing experience to write. A tuned and polished X* SANA-II device should require only one additional man month. X* X* Compatibility: All SANA-II device drivers behave largely the X* same. X* X* Low resource usage: A SANA-II device driver should not require X* large amounts of memory, cpu cycles or any other system X* resource to operate efficiently. X* X* Ease of use: Using SANA-II devices should be the easiest way X* for protocol stack writers to access the networks. X* X* X* NON-GOALS X* Lowest common denominator: Not all network interfaces can X* support all the features available in this specification or X* other network types. X* X* Feature-itis: Not every feature of every type of network is X* represented. X* X* Network management tools: Analysis and debugging of a network X* requires specialized software for that purpose. X* X* X* STRUCTURES X* struct IOSana2Req X* { X* struct Message S2io_Message; X* struct Device *S2io_Device; X* struct Unit *S2io_Unit; X* X* UWORD S2io_Command; X* UBYTE S2io_Flags; X* BYTE S2io_Error; X* ULONG S2io_WireError; X* X* struct Sana2PacketType *S2io_PacketType; X* UBYTE S2io_SrcAddr[SANA2_MAX_ADDR_BYTES]; X* UBYTE S2io_DstAddr[SANA2_MAX_ADDR_BYTES]; X* ULONG S2io_DataLength; X* struct NetBuff S2io_Body; X* void *S2io_StatData; X* }; X* X* Message X* Initialized and used the same as all device IORequest X* Message structures. X* X* Device X* Device private. X* X* Unit X* Device private. X* X* Command X* Command requested. X* X* Flags X* Used to request special options and return status X* information. X* X* Error X* Indicates completion status of a command in general X* terms. X* X* WireError X* More specific error number. Only valid when S2io_Error X* is non-zero. X* X* PacketType X* Pointer to a Sana2PacketType structure. The device X* uses the contents of the structure to determine if a X* packet from the network will satisfy a particular read X* command, or to build the appropriate packet header and X* trailer for a packet send. The device will not modify X* either the pointer or the structure. X* X* SrcAddr X* The device fills in this field with the interface X* address of the source of the packet that satisfied a X* read command. The bytes used to hold the address will X* be left justified but the bit layout is dependent on X* the particular type of network. X* X* DstAddr X* This field is filled in with the interface destination X* address of the packet for a send command. The bytes X* used to hold the address will be left justified but X* the bit layout is dependent on the particular type of X* network. X* X* DataLength X* The device fills in this field with the size of the X* packet data as it was sent on the wire. This does not X* include the header and trailer information. Depending X* on the network type and protocol type, the driver may X* have to calculate this value. X* X* Body X* A NetBuff structure with the packet data. X* X* StatData X* Pointer to a data area in memory to place a a snapshot X* of device statics. The data area must be long word X* aligned. X* X* X* struct Sana2PacketType X* { X* ULONG CanonicalType; X* ULONG Magic; X* ULONG Length; X* UBYTE *Match; X* UBYTE *Mask; X* }; X* X* CanonicalType X* Not used by the device. X* X* Magic X* Determines how the fields in this structure are to be X* interpretted. X* X* Length X* Number of bytes pointed to be Match and Mask. X* X* Match X* Pointer to packet type match data. The data must be X* long word (32 bit) aligned. X* X* Mask X* Pointer to packet type mask data. The data must be X* long word (32 bit) aligned. X* X* X* struct Sana2DeviceQuery X* { X* /* X* * Standard information X* */ X* ULONG SizeAvailable; X* ULONG SizeSupplied; X* LONG DevQueryFormat; X* LONG DeviceLevel; X* /* X* * Common information X* */ X* UWORD AddrFieldSize; X* ULONG MTU; X* LONG bps; X* LONG HardwareType; X* /* X* * Format specific information X* */ X* }; X* X* SizeAvailable X* Size, in bytes, of the space available in which to X* place device information. This includes both size X* fields. X* X* SizeSupplied X* Size, in bytes, of the data supplied. X* X* DevQueryFormat X* The format defined here is format 0. X* X* DeviceLevel X* This spec defines level 0. X* X* AddrFieldSize X* The number of bits in an interface address. X* X* MTU X* Maximum Transmission Unit, the size, in bytes, of the X* maximum packet size, not including header and trailer X* information. X* X* bps X* Best guess at the raw line rate for this network in X* bits per second. X* X* HardwareType X* Specifies the type of network wire the driver X* controls. X* X* X* struct Sana2PacketTypeStats X* { X* LONG PacketsSent; X* LONG PacketsReceived; X* LONG BytesSent; X* LONG BytesReceived; X* LONG PacketsDropped; X* }; X* X* PacketsSent X* Number of packets of a particular type sent. X* X* PacketsReceived X* Number of packets of a particular type that satisfied X* a read command. X* X* BytesSent X* Number of bytes of data sent in packets of a X* particular type. X* X* BytesReceived X* Number of bytes of data of a particular packet type X* that satisfied a read command. X* X* PacketsDropped X* Number of packets of a particular type that were X* received while there were no pending reads of that X* packet type. X* X* X* struct Sana2SpecialStatRecord X* { X* ULONG Type; X* LONG Count; X* char *String; X* }; X* X* Type X* Statistic identifier. X* X* Count X* Statistic itself. X* X* String X* Identifying string for the statistic. Should be plain X* ASCII with no formatting characters. X* X* X* struct Sana2SpecialStatHeader X* { X* ULONG RecordCountMax; X* ULONG RecordCountSupplied; X* struct Sana2SpecialStatRecord[RecordCountMax]; X* }; X* X* RecordCountMax X* Space for this many number of records is available to X* place statistics information in. X* X* RecordCountSupplied X* Number of statistic records supplied. X* X* X* struct Sana2DeviceStats X* { X* LONG packets_received; X* LONG packets_sent; X* LONG framing_errors; X* LONG bad_data; X* LONG hard_misses; X* LONG soft_misses; X* LONG unknown_types_received; X* LONG fifo_overruns; X* LONG fifo_underruns; X* LONG reconfigurations; X* struct timeval last_start; X* }; X* X* packets_received X* Number of packets that this unit has received. X* X* packets_sent X* Number of packets that this unit has sent. X* X* framing_errors X* Number of framing errors detected. X* X* bad_data X* Number of bad packets received. X* X* hard_misses X* Number of packets lost due to insufficient resources X* available in the network interface. X* X* soft_misses X* Number of packets lost due to insifficient resources X* available on the host. X* X* unknown_type_received X* Number of packets received that had no pending read X* command with the appropriate packet type. X* X* fifo_overruns X* Number of overruns encountered when attempting to X* store received packets. X* X* fifo_underruns X* Number of underruns encountered when attempting to X* send packets. X* X* reconfigurations X* Number of network reconfigurations since this unit was X* last configured. X* X* last_start X* The time when this unit last went online. X* X* X* CONSTANTS X* OpenDevice flags argument (SANA2OPB_xxx): X* MINE X* Exclusive access to the unit requested. X* X* PROM X* Promiscuous mode requested. X* X* X* IOSana2Req S2io_Flags field (SANA2IOB_xxx): X* RAW X* Raw packet read/write requested. X* X* BCAST X* Broadcast packet (received). X* X* MCAST X* Multicast packet (received). X* X* QUICK X* Quick IO requested. X* X* X* IOSana2Req S2io_Error field (S2ERR_xxx): X* NO_RESOURCES X* Insufficient resources available. X* X* UNKNOWN_ENTITY X* Specified entity unknown or not found. X* X* BAD_ARGUMENT X* Noticably bad argument. X* X* BAD_STATE X* Command inappropriate for current state. X* X* BAD_ADDRESS X* Noticably bad address. X* X* MTU_EXCEEDED X* Write data too large. X* X* BAD_PROTOCOL X* Noticably bad packet type. X* X* NOT_SUPPORTED X* Command is not supported by this driver. This is X* similar to IOERR_NOCMD as defined in exec/errors.h but X* S2ERR_NOT_SUPPORTED indicates that the requested X* command is a valid SANA-II command and that the driver X* does not support it, e.g. SANA2CMD_MULTICAST. X* X* SOFTWARE X* Software error of some kind. X* X* X* IOSana2Req S2io_WireError field (S2WERR_xxx): X* NOT_CONFIGURED X* Command requires unit to be configured. X* X* UNIT_ONLINE X* Command requires that the unit be offline. X* X* UNIT_OFFLINE X* Command requires that the unit be online. X* X* ALREADY_TRACKED X* Protocol is already being tracked. X* X* NOT_TRACKED X* Protocol is not being tracked. X* X* NETBUFF_ERROR X* NetBuff.library error return caused error. X* X* SRC_ADDRESS X* Problem with the source address field. X* X* DST_ADDRESS X* Problem with destination address field. X* X* BAD_BROADCAST X* Problem with an attempt to broadcast. X* X* BAD_MULTICAST X* Problem with an attempt to multicast. X* X* ALIAS_LIST_FULL X* Station alias list full. X* X* BAD_ALIAS X* Bad or unknown station alias. X* X* MULTICAST_FULL X* Multicast address list full. X* X* BAD_EVENT X* Event specified is unknown. X* X* BAD_STATDATA X* The S2IO_StatData pointer or the data it points to X* failed a sanity check. X* X* PROTOCOL_UNKNOWN X* The protocol specified is unknown or the type of magic X* used by the request protocol is unknown. X* X* IS_CONFIGURED X* Attempt to reconfigure the unit. X* X* NULL_POINTER X* A NULL pointer was detected in one of the arguments. X* X* X* Event types (S2EVENT_xxx): X* ERROR X* Return when any error occures. X* X* TX X* Return on any transmit error. X* X* RX X* Return on any receive error. X* X* ONLINE X* Return when unit goes online. X* X* OFFLINE X* Return when unit goes offline. X* X* NETBUFF X* Return on any NetBuff.library error. X* X* HARDWARE X* Return when any hardware error occures. X* X* SOFTWARE X* Return when any software error occures. X* X* X* SEE ALSO X* NetBuff.library documentation. X* X* Separate document for each type of network detailing specific X* device requirements. X* X* X* CREDITS X* Raymond S. Brand, rsbx@cbmvax.commodore.com, (215) 431-9100 X* Martin Hunt, martin@cbmvax.commodore.com, (215) 431-9100 X* Perry Kivolowitz, ASDG Incorporated, (608) 273-6585 X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X*****i* sana2.device/Init() ****************************************** X* X* NAME X* Init -- Initialize the device from nothing. X* X* SYNOPSIS X* Init( SegList ) X* A0 X* X* void Init( void * ); X* X* FUNCTION X* This routine initializes the device from nothing. X* X* INPUTS X* SegList Pointer to the SegList for the device code. X* X* NOTES X* X* SEE ALSO X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* X* REGISTER USAGE X* X* A0 -- seglist ????? ????? X* A6 -- exec ????? exec X* X X X*****i* sana2.device/Open() ****************************************** X* X* NAME X* Open -- Request an opening of the network device. X* X* SYNOPSIS X* error = Open( unit, Sana2Req, flags ) X* D0 D0 A1 D1 X* X* BYTE Open( ULONG, struct IOSana2Req *, ULONG ); X* X* FUNCTION X* This function is called by exec.library OpenDevice(). X* X* This function performs whatever initialization is required per X* device open and initializes the Sana2Req for use by the X* device. X* X* INPUTS X* unit Device unit to open. X* Sana2Req Pointer to IOSana2Req structure to be X* initialized by the sana2.device. X* flags Supported flags are: X* SANA2OPB_MINE X* SANA2OPB_PROM X* X* RESULTS X* error same as io_Error X* io_Error Zero if successful; non-zero otherwise. X* io_Device A pointer to whatever device will handle the X* calls for this unit. This pointer may be X* different depending on what unit is X* requested. X* X* NOTES X* X* SEE ALSO X* exec.library/OpenDevice(), X* exec.library/CloseDevice() X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* The system is single threaded while executing this function. X* X* X* REGISTER USAGE X* X* D0 -- unit ????? ????? X* D1 -- flags ????? ????? X* A1 -- IOReq ????? ????? X* A6 -- device ????? device X* X X X*****i* sana2.device/Close() ***************************************** X* X* NAME X* CloseDevice -- Close the device. X* X* SYNOPSIS X* Close( Sana2Req ) X* A1 X* X* void Close( struct IOSana2Req * ); X* X* FUNCTION X* This function is called by exec.library CloseDevice(). X* X* This function performs whatever cleanup is required at device X* closes. X* X* Note that all IORequests MUST be complete before closing. If X* any are pending, your program must AbortIO() then WaitIO() X* each outstanding IORequest to complete them. X* X* INPUTS X* Sana2Req Pointer to Sana2Req initialized by Open(). X* X* NOTES X* X* SEE ALSO X* exec.library/CloseDevice(), X* exec.library/OpenDevice() X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* X* REGISTER USAGE X* X* D0 -- ????? ????? SegList X* A1 -- IOReq ????? ????? X* A6 -- device ????? device X* X X X*****i* sana2.device/BeginIO() *************************************** X* X* NAME X* BeginIO -- Start an IO operation. X* X* SYNOPSIS X* BeginIO( Sana2Req ) X* A1 X* X* void BeginIO( struct IOSana2Req * ); X* X* FUNCTION X* This is a direct function call to the device. It is intended X* for more advanced programmers. See exec's DoIO() and SendIO() X* for the normal method of calling devices. X* X* This function initiates a I/O request made to a sana2.device. X* X* INPUTS X* Sana2Req Pointer to an initialized IOSana2Req X* structure. X* S2io_Message A mn_ReplyPort is required. X* S2io_Device Set by Open(). X* S2io_Unit Set by Open(). X* S2io_Command Needs to be set to proper command X* S2io_Flags If the IOB_QUICK bit is set the device will X* attempt to finish command without X* 'Replying' through the exec message X* system. The IOB_QUICK bit will be cleared X* if the request will 'Replied' when X* complete. X* S2io_PacketType Pointer to the Sana2PacketType structure for X* the packet type of interest. X* S2io_SrcAddr Source interface address of the packet. X* S2io_DstAddr Destination interface address of the packet. X* S2io_Body Contents depend on particular command. X* S2io_StatData Pointer to area to store statistics data. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* S2io_SrcAddr Source interface address of the packet. X* S2io_DstAddr Destination interface address of the packet. X* S2io_Body Contents depend on particular command. X* X* NOTES X* X* SEE ALSO X* exec.library/DoIO(), X* exec.library/SendIO() X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* X* REGISTER USAGE X* X* A1 -- IOReq ????? ????? X* A6 -- device ????? device X* X X X******* sana2.device/AbortIO() *************************************** X* X* NAME X* AbortIO -- Remove an existing device request. X* X* SYNOPSIS X* error = AbortIO( Sana2Req ) X* D0 A1 X* X* LONG AbortIO( struct IOSana2Req * ); X* X* FUNCTION X* This is an exec.library call. X* X* This function aborts an ioRequest. If the request is active, X* it may or may not be aborted. If the request is queued it is X* removed. The request will be returned in the same way as if X* it had normally completed. X* X* INPUTS X* Sana2Req Sana2Req to be aborted. X* X* RESULTS X* error Zero if the request was aborted, non-zero X* otherwise. S2io_Error in Sana2Req will be X* set to IOERR_ABORTED (-2) if it was X* aborted. X* X* NOTES X* X* SEE ALSO X* exec.library/AbortIO() X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* X* REGISTER USAGE X* X* D0 -- ????? ????? error X* A1 -- IOReq ????? ????? X* A6 -- device ????? device X* X X X*****i* sana2.device/Expunge() *************************************** X* X* NAME X* Expunge -- Free device resources and dependencies. X* X* SYNOPSIS X* Expunge( ) X* X* void Expunge( void ); X* X* FUNCTION X* This function deallocates all memory and other resources X* associated with the device, if possible. X* X* NOTES X* This function is not permitted to wait. X* X* SEE ALSO X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* X* REGISTER USAGE X* X* D0 -- ????? ????? SegList X* A6 -- device ????? device X* X X X******* sana2.device/CMD_READ **************************************** X* X* NAME X* Read -- Get a packet from the network. X* X* FUNCTION X* Get the next packet available of the requested packet type. X* The data returned in the S2io_Body NetBuff is normally the X* Data Link Layer packet data only. If bit SANA2IOB_RAW is set X* in S2io_Flags, then the entire Data Link Layer packet, X* including both header and trailer information, will be X* returned. X* X* IO REQUEST X* S2io_Command CMD_READ X* S2io_Flags Supported flags are: X* SANA2IOB_RAW X* SANA2IOB_QUICK X* S2io_PacketType Pointer to packet type desired. X* S2io_Body NetBuff to hold packet data. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* S2io_Flags The following flags may be returned: X* SANA2IOB_RAW X* SANA2IOB_BCAST X* SANA2IOB_MCAST X* S2io_SrcAddr Source interface address of packet. X* S2io_DstAddr Destination interface address of packet. X* S2io_DTLLength Length of packet data as given by the Data X* Link Layer protocol. X* S2io_Body NetBuff with packet data. X* X* NOTES X* Only the first NetBuffSegment in the NetBuff passed is X* guaranteed to be returned. X* X* SEE ALSO X* sana2.device/SANA2CMD_READORPHAN, X* sana2.device/CMD_WRITE X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/CMD_WRITE *************************************** X* X* NAME X* Write -- Send packet to the network. X* X* FUNCTION X* This command causes the packet to be sent to the specified X* network interface. Normally, appropriate packet header and X* trailer information will be added to the packet data when it X* is sent. If bit SANA2IOB_RAW is set in io-Flags, then the X* S2io_Body NetBuff is assumed to contain an entire Data Link X* Layer packet and will be sent unmodified. X* X* The data in the S2io_Body NetBuff is returned unmodified; but, X* the distribution of the data in, and the number of X* NetBuffSegments, the S2io_Body NetBuff may be modified. X* X* IO REQUEST X* S2io_Command CMD_WRITE X* S2io_Flags Supported flags are: X* SANA2IOB_RAW X* SANA2IOB_QUICK X* S2io_PacketType Pointer to type of packet to send. X* S2io_DstAddr Destination interface address for this packet. X* S2io_Body NetBuff with packet data. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* X* SEE ALSO X* sana2.device/CMD_READ, X* sana2.device/SANA2CMD_BROADCAST, X* sana2.device/SANA2CMD_MULTICAST X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_READORPHAN ***************************** X* X* NAME X* ReadOrphan -- Get a packet for which there is no reader. X* X* FUNCTION X* Get the next packet available that does not satisfy any X* then-pending CMD_READ requests. The data returned in the X* S2io_Body NetBuff is normally the Data Link Layer packet type X* field and the packet data. If bit SANA2IOB_RAW is set in X* S2io_Flags, then the entire Data Link Layer packet, including X* both header and trailer information, will be returned. X* X* IO REQUEST X* S2io_Command CMD_READORPHAN X* S2io_Flags Supported flags are: X* SANA2IOB_RAW X* SANA2IOB_QUICK X* S2io_Body NetBuff to hold packet data. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* S2io_Flags The following flags may be returned: X* SANA2IOB_RAW X* SANA2IOB_BCAST X* SANA2IOB_MCAST X* S2io_SrcAddr Source interface address of packet. X* S2io_DstAddr Destination interface address of packet. X* S2io_DTLLength Lenght of packet data as given by the Data X* Link Layer protocol. X* S2io_Body NetBuff with packet data. X* X* NOTES X* Only the first NetBuffSegment in the NetBuff passed in is X* guarenteed to be returned. X* X* To determine which protocol family the returned packet belongs X* to you may have to specify SANA2IOB_RAW to get the entire data X* link layer wrapper (which is where the protocol type may be X* kept). Notice this necessarily means that this cannot be done X* in a network interface independent fashion. X* X* SEE ALSO X* sana2.device/CMD_READ, X* sana2.device/CMD_WRITE X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_DEVICEQUERY **************************** X* X* NAME X* DeviceQuery -- Return parameters for this network interface. X* X* FUNCTION X* This command causes the device driver to report information X* about the device. Up to DevQuerySizeAvailable bytes of the X* information is copied into a buffer pointed to by X* S2io_StatData. The format of the data is as follows: X* X* struct Sana2DeviceQuery X* { X* /* X* * Standard information X* */ X* ULONG DevQuerySizeAvailble; /* bytes available */ X* ULONG DevQuerySizeSupplied; /* bytes supplied */ X* LONG DevQueryFormat; /* this is type 0 */ X* LONG DeviceLevel; /* this document is level 0 */ X* X* /* X* * Common information X* */ X* UWORD AddrFieldSize; /* address size in bits */ X* ULONG MTU; /* maximum packet data size */ X* LONG bps; /* line rate (bits/sec) */ X* LONG HardwareType; /* what the wire is */ X* X* /* X* * Format specific information X* */ X* }; X* X* The DeviceQueryAvailable specifies the number of bytes that X* the caller is prepared to accomodate, including the standard X* information fields. X* X* DevQuerySizeSupplied is the number of bytes actually supplied, X* including the standard information fields, which will not X* exceed DevQuerySizeAvailable. X* X* The values used to identify the type of physical hardware are X* the same values used in the hardware type field (hdr) of X* Address Resolution Protocol (ARP) packets as defined by X* RFC-826 (ARP) and RFC-1060 (Assigned Numbers, March 1990). X* X* The following are defined in RFC-1060. X* X* Hardware Type (hrd) X* X* Type Description X* ---- ----------- X* 1 Ethernet (10Mb) X* 2 Experimental Ethernet (3Mb) X* 3 Amateur Radio AX.25 X* 4 Proteon ProNET Token Ring X* 5 Chaos X* 6 IEEE 802 Networks X* 7 ARCNET X* 8 Hyperchannel X* 9 Lanstar X* 10 Autonet Short Address X* 11 LocalTalk X* 12 LocalNet (IBM PCNet or SYTEK LocalNET) X* X* IO REQUEST X* S2io_Command SANA2CMD_DEVICEQUERY X* S2io_StatData Pointer to Sana2DeviceQuery structure to fill X* in. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* X* SEE ALSO X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_GETSTATIONADDRESS ********************** X* X* NAME X* GetStationAddress -- Get default and interface address. X* X* FUNCTION X* This command causes the device driver to copy the current X* interface address into S2io_SrcAddr, and to copy the factory X* default station address into S2io_DstAddr. X* X* IO REQUEST X* S2io_Command SANA2CMD_GETSTATIONADDRESS X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* S2io_SrcAddr Default interface address. X* S2io_DstAddr Current interface address. X* X* NOTES X* X* SEE ALSO X* sana2.device/SANA2CMD_CONFIGINTERFACE X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_CONFIGINTERFACE ************************ X* X* NAME X* ConfigInterface -- Configure the network interface. X* X* FUNCTION X* This command causes the device driver to initialize the X* interface hardware and to set the network interface address to X* the address in S2io_SrcAddr. This command can only be executed X* once and, if successful, will leave the driver and network X* interface fully operational and the network interface in X* S2io_SrcAddr. X* X* To set the interface address to the factory address, the X* network management software must use GetStationAddress first X* and then call ConfigInterface with the result. If there is no X* factory address then the network software must pick an address X* to use. X* X* Until this command is executed the device will not listen for X* any packets on the hardware. X* X* IO REQUEST X* S2io_Command SANA2CMD_CONFIGINTERFACE X* S2io_Flags Supported flags are: X* SANA2IOB_QUICK X* S2io_SrcAddr Address for this interface. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* S2io_SrcAddr Address of this interface as configured. X* X* NOTES X* Some networks have the interfaces choose a currently unused X* interface address each time the interface is initialized. The X* caller must check S2io_SrcAddr for the actual interface X* address after configuring the interface. X* X* SEE ALSO X* sana2.device/SANA2CMD_GETSTATIONADDRESS X* X* BUGS X* What to do when/if the network interface address changes due X* to a network reconfiguration. X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_ADDSTATIONALIAS ************************ X* X* NAME X* AddStationAlias -- Add interface address alias. X* X* FUNCTION X* This function adds another network interface address to which X* the network interface should respond. X* X* IO REQUEST X* S2io_Command SANA2CMD_ADDSTATIONALIAS X* S2io_SrcAddr Alias to add. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* Since alias interface addresses are not bound to a particular X* packet type or read request, each added interface alias X* address has an "added" count associated with it. X* X* SEE ALSO X* sana2.device/SANA2CMD_DELSTATIONALIAS X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_DELSTATIONALIAS ************************ X* X* NAME X* DelStationAlias -- Delete a interface address alias. X* X* FUNCTION X* This function deletes a network interface address from the X* list of addresses to which this interface should respond. X* X* IO REQUEST X* S2io_Command SANA2CMD_DELSTATIONALIAS X* S2io_SrcAddr Alias to delete. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* Since alias interface addresses are not bound to a particular X* packet type or read request, each added interface alias X* address has an "added" count associated with it. X* X* SEE ALSO X* sana2.device/SANA2CMD_ADDSTATIONALIAS X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_ADDMULTICASTADDRESS ******************** X* X* NAME X* AddMulticastAddress -- Enable an interface multicast address. X* X* FUNCTION X* This command causes the device driver to enable multicast X* packet reception for the requested address. X* X* IO REQUEST X* S2io_Command SANA2CMD_ADDMULTICASTADDRESS X* S2io_SrcAddr Multicast address to enable. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* Since multicast addresses are not "bound" to a particular X* packet type, each enabled multicast address has an "enabled" X* count associated with it. X* X* SEE ALSO X* sana2.device/SANA2CMD_DELMULTICASTADDRESS X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_DELMULTICASTADDRESS ******************** X* X* NAME X* DelMultiCastAddress -- Disable an interface multicast address. X* X* FUNCTION X* This command causes device driver to disable multicast packet X* reception for the requested address. X* X* It is an error to disable a multicast address that is not X* enabled. X* X* IO REQUEST X* S2io_Command SANA2CMD_DELMULTICASTADDRESS X* S2io_SrcAddr Multicast address to disable. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* Since multicast addresses are not "bound" to a particular X* packet type, each enabled multicast address has an "enabled" X* count associated with it. X* X* SEE ALSO X* sana2.device/SANA2CMD_ADDMULTICASTADDRESS X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_MULTICAST ****************************** X* X* NAME X* Multicast -- Multicast a packet on network. X* X* FUNCTION X* This command works the same as CMD_WRITE except that it also X* performs whatever special processing of the packet is required X* to do a multicast send. The actual multicast mechanism is X* neccessarily network/interface/device specific. X* X* IO REQUEST X* S2io_Command SANA2CMD_MULTICAST X* S2io_Flags Supported flags are: X* SANA2IOB_RAW X* SANA2IOB_QUICK X* S2io_PacketType Pointer to type of packet to send. X* S2io_DstAddr Destination interface address for this packet. X* S2io_Body NetBuff with packet data. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* This command can fail for many reasons and X* is not supported by all networks and/or X* network interfaces. X* S2io_WireError More specific error number. X* X* NOTES X* The address supplied in S2io_DstAddr will be sanity checked X* (if possible) by the driver. If the supplied address fails X* this sanity check, the multicast request will fail X* immediately. X* X* SEE ALSO X* sana2.device/CMD_WRITE, X* sana2.device/SANA2CMD_BROADCAST X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_BROADCAST ****************************** X* X* NAME X* Broadcast -- Broadcast a packet on network. X* X* FUNCTION X* This command works the same as CMD_WRITE except that it also X* performs whatever special processing of the packet is required X* to do a broadcast send. The actual broadcast mechanism is X* neccessarily network/interface/device specific. X* X* IO REQUEST X* S2io_Command SANA2CMD_BROADCAST X* S2io_Flags Supported flags are: X* SANA2IOB_RAW X* SANA2IOB_QUICK X* S2io_PacketType Pointer to type of packet to send. X* S2io_Body NetBuff with packet data. X* X* RESULTS X* S2io_DstAddr The contents of this field are to be X* considered trash upon return of the IOReq. X* S2io_Error Zero if successful; non-zero otherwise. X* This command can fail for many reasons and X* is not supported by all networks and/or X* network interfaces. X* S2io_WireError More specific error number. X* X* NOTES X* X* SEE ALSO X* sana2.device/CMD_WRITE, X* sana2.device/SANA2CMD_MULTICAST X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_TRACKTYPE ****************************** X* X* NAME X* TrackType -- Accumulate statistics about a packet type. X* X* FUNCTION X* This command causes the device driver to accumulate statistics X* about a particular packet type. Packet type statistics, for X* the particular packet type, are zeroed by this command. X* X* IO REQUEST X* S2io_Command SANA2CMD_TRACKTYPE X* S2io_PacketType Pointer to the packet type of interest. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* X* SEE ALSO X* sana2.device/SANA2CMD_UNTRACKTYPE, X* sana2.device/SANA2CMD_GETTYPESTATS X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_UNTRACKTYPE **************************** X* X* NAME X* UntrackType -- End statistics about a packet type. X* X* FUNCTION X* This command causes the device driver to stop accumulating X* statistics about a particular packet type. X* X* IO REQUEST X* S2io_Command SANA2CMD_UNTRACKTYPE X* S2io_PacketType Pointer to the packet type of interest. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* X* SEE ALSO X* sana2.device/SANA2CMD_TRACKTYPE, X* sana2.device/SANA2CMD_GETTYPESTATS X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_GETTYPESTATS *************************** X* X* NAME X* GetTypeStats -- Get accumulated type specific statistics. X* X* FUNCTION X* This command causes the device driver to retrieve various X* packet type specific runtime statistics for this network X* interface. The format of the data returned is as follows: X* X* struct Sana2TypeStatData X* { X* LONG PacketsSent; X* LONG PacketsReceived; X* LONG BytesSent; X* LONG BytesReceived; X* LONG PacketsDropped; X* }; X* X* IO REQUEST X* S2io_Command SANA2CMD_GETTYPESTATS X* S2io_PacketType Pointer to the packet type of interest. X* S2io_StatData Pointer to TypeStatData structure to fill in. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* Statistics for a particular packet type are only available X* while that packet type is being ``tracked''. X* X* SEE ALSO X* sana2.device/SANA2CMD_TRACKTYPE, X* sana2.device/SANA2CMD_UNTRACKTYPE X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_GETSPECIALSTATS ************************ X* X* NAME X* GetSpecialStats -- Get network type specific statistics. X* X* FUNCTION X* This function returns statistics which are specific to the X* type of network medium this driver controls. For example, this X* command could return statistics common to all Ethernets which X* are not common to all network mediums in general. X* X* The supplied Sana2SpecialStatData structure is given below: X* X* struct Sana2SpecialStatData X* { X* ULONG RecordCountMax; X* ULONG RecordCountSupplied; X* struct Sana2StatRecord[RecordCountMax]; X* }; X* X* The format of the data returned is: X* X* struct Sana2StatRecord X* { X* ULONG Type; /* commodore registered */ X* LONG Count; /* the stat itself */ X* char *String; /* null terminated */ X* }; X* X* The RecordCountMax field specifies the number of records that X* the caller is prepared to accomodate. X* X* RecordCountSupplied is the number of record actually supplied X* which will not exceed RecordCountMax. X* X* IO REQUEST X* S2io_Command SANA2CMD_GETSPECIALSTATS X* S2io_StatData Pointer to a Sana2SpecialStatData structure to X* fill. RecordCountMax must be initialized. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* Commodore shall maintain registered statistic Types. X* X* SEE ALSO X* sana2.device/SANA2CMD_GETGLOBALSTATS X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_GETGLOBALSTATS ************************* X* X* NAME X* GetGlobalStats -- Get interface accumulated statistics. X* X* FUNCTION X* This command causes the device driver to retrieve various X* global runtime statistics for this network interface. The X* format of the data returned is as follows: X* X* struct Sana2DeviceStats X* { X* LONG packets_received; X* LONG packets_sent; X* LONG framming_errors; X* LONG bad_data; X* LONG bytes_received; X* LONG bytes_sent; X* LONG hard_misses; X* LONG soft_misses; X* LONG unknown_types_received; X* LONG fifo_overruns; X* LONG fifo_underruns; X* LONG reconfigurations; X* timeval last_start; X* }; X* X* IO REQUEST X* S2io_Command SANA2CMD_GETGLOBALSTATS X* S2io_StatData Pointer to Sana2DeviceStats structure to fill. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* X* SEE ALSO X* sana2.device/SANA2CMD_GETSPECIALSTATS X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_ONEVENT ******************************** X* X* NAME X* OnEvent -- Return when specified event occures. X* X* FUNCTION X* This command returns when a particular event condition has X* occured on the network or this network interface. X* X* IO REQUEST X* S2io_Command SANA2CMD_ONEVENT X* S2io_Flags Supported flags are: X* SANA2IOB_QUICK X* S2io_WireError Event number to wait for. X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError Event number that occured. X* X* NOTES X* If this device driver does not understand the specified event X* condition then the command returns immediately with S2io_Error X* non-zero. A successful return will have S2io_Error set to zero X* S2io_WireError set to the event number. X* X* All pending requests for a particular event will be returned X* when that event occurs. X* X* All event types that cover a particular condition are returned X* when that condition occures. For instance, if an error is X* returned by NetBuff.library during receive processing, events X* of types S2EVENT_ERROR, S2EVENT_RX and S2EVENT_NETBUFF would X* be returned if pending. X* X* SEE ALSO X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_ONLINE ********************************* X* X* NAME X* Online -- Put a network interface back in service. X* X* FUNCTION X* This command places an offline network interface back into X* service. X* X* IO REQUEST X* S2io_Command SANA2CMD_ONLINE X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* This command is responsible for putting the network interface X* hardware back into a known state and resets the unit global X* and special statistics. X* X* SEE ALSO X* sana2.device/SANA2CMD_OFFLINE X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X******* sana2.device/SANA2CMD_OFFLINE ******************************** X* X* NAME X* Offline -- Remove interface from service. X* X* FUNCTION X* This command removes a network interface from service. X* X* IO REQUEST X* S2io_Command SANA2CMD_OFFLINE X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* S2io_WireError More specific error number. X* X* NOTES X* Aborts all pending reads and writes with S2io_Error set to X* SANA2ERROR_OUTOFSERVICE. X* X* While the interface is offline, all read, writes and any other X* command that touches interface hardware will be rejected with X* S2io_Error set to SANA2ERROR_OUTOFSERVICE. X* X* This command is intended to permit a network interface to be X* tested on an otherwise live system. X* X* SEE ALSO X* sana2.device/SANA2CMD_ONLINE X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X*****i* sana2.device/CMD_START *************************************** X* X* NAME X* Start -- Restart device operation. X* X* FUNCTION X* Does not apply to this class of device. X* X* IO REQUEST X* S2io_Command CMD_ONLINE X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* X* NOTES X* X* SEE ALSO X* sana2.device/CMD_STOP X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* Does not apply to this class of device. X* X X X*****i* sana2.device/CMD_STOP **************************************** X* X* NAME X* Stop -- Pause device operation. X* X* FUNCTION X* Does not apply to this class of device. X* X* IO REQUEST X* S2io_Command CMD_OFFLINE X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* X* NOTES X* X* SEE ALSO X* sana2.device/CMD_START X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* Does not apply to this class of device. X* X X X*****i* sana2.device/CMD_CLEAR *************************************** X* X* NAME X* Clear -- Clear internal network interface read buffers. X* X* FUNCTION X* Does not apply to this class of device. X* X* IO REQUEST X* S2io_Command CMD_CLEAR X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* X* NOTES X* X* SEE ALSO X* sana2.device/UPDATE, X* sana2.device/CLEAR X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* Does not apply to this class of device. X* X X X*****i* sana2.device/CMD_FLUSH *************************************** X* X* NAME X* Flush -- Clear internal network interface write buffers. X* X* FUNCTION X* Does not apply to this class of device. X* X* IO REQUEST X* S2io_Command CMD_FLUSH X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* X* NOTES X* X* SEE ALSO X* sana2.device/AbortIO(), X* sana2.device/CMD_UPDATE, X* sana2.device/CMD_CLEAR X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* Does not apply to this class of device. X* X X X*****i* sana2.device/CMD_INVALID ************************************* X* X* NAME X* Invalid -- Return with error IOERR_NOCMD. X* X* FUNCTION X* This command causes device driver to reply with an error X* IOERR_NOCMD as defined in exec/errors.h indicating the command X* is not supported. X* X* IO REQUEST X* S2io_Command CMD_INVALID X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* X* NOTES X* X* SEE ALSO X* X* BUGS X* Not known to be useful at this time. X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X X X*****i* sana2.device/CMD_RESET *************************************** X* X* NAME X* Reset -- Reset the network interface to initialized state. X* X* FUNCTION X* Does not apply to this class of device. X* X* IO REQUEST X* S2io_Command CMD_RESET X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* X* NOTES X* X* SEE ALSO X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* Does not apply to this class of device. X* X X X*****i* sana2.device/CMD_UPDATE ************************************** X* X* NAME X* Update -- Force packets out to device X* X* FUNCTION X* Does not apply to this class of device. X* X* IO REQUEST X* S2io_Command CMD_UPDATE X* X* RESULTS X* S2io_Error Zero if successful; non-zero otherwise. X* X* NOTES X* X* SEE ALSO X* sana2.device/CMD_CLEAR, X* sana2.device/CMD_FLUSH X* X* BUGS X* X********************************************************************** X* X* IMPLEMENTATION NOTES X* X* Does not apply to this class of device. X* X X END_OF_FILE if test 48321 -ne `wc -c <'sana2device.spec'`; then echo shar: \"'sana2device.spec'\" unpacked with wrong size! fi # end of 'sana2device.spec' fi echo shar: End of archive 3 \(of 3\). cp /dev/null ark3isdone MISSING="" for I in 1 2 3 ; do if test ! -f ark${I}isdone ; then MISSING="${MISSING} ${I}" fi done if test "${MISSING}" = "" ; then echo You have unpacked all 3 archives. rm -f ark[1-9]isdone else echo You still need to unpack the following archives: echo " " ${MISSING} fi ## End of shell archive. exit 0 -- Mail submissions (sources or binaries) to . Mail comments to the moderator at . Post requests for sources, and general discussion to comp.sys.amiga.misc.