home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / tcp / Networking / Sana-II / spar372.lha / docs / sana2device.doc < prev    next >
Text File  |  1993-10-07  |  28KB  |  993 lines
  1. TABLE OF CONTENTS
  2.  
  3. sana2.device/AbortIO
  4. sana2.device/CloseDevice
  5. sana2.device/CMD_CLEAR
  6. sana2.device/CMD_FLUSH
  7. sana2.device/CMD_INVALID
  8. sana2.device/CMD_READ
  9. sana2.device/CMD_RESET
  10. sana2.device/CMD_START
  11. sana2.device/CMD_STOP
  12. sana2.device/CMD_UPDATE
  13. sana2.device/CMD_WRITE
  14. sana2.device/OpenDevice
  15. sana2.device/S2_ADDMULTICASTADDRESS
  16. sana2.device/S2_BROADCAST
  17. sana2.device/S2_CONFIGINTERFACE
  18. sana2.device/S2_DELMULTICASTADDRESS
  19. sana2.device/S2_DEVICEQUERY
  20. sana2.device/S2_GETGLOBALSTATS
  21. sana2.device/S2_GETSPECIALSTATS
  22. sana2.device/S2_GETSTATIONADDRESS
  23. sana2.device/S2_GETTYPESTATS
  24. sana2.device/S2_MULTICAST
  25. sana2.device/S2_OFFLINE
  26. sana2.device/S2_ONEVENT
  27. sana2.device/S2_ONLINE
  28. sana2.device/S2_READORPHAN
  29. sana2.device/S2_TRACKTYPE
  30. sana2.device/S2_UNTRACKTYPE
  31. sana2.device/AbortIO                                     sana2.device/AbortIO
  32.  
  33.    NAME
  34.     AbortIO -- Remove an existing device request.
  35.  
  36.    SYNOPSIS
  37.     error = AbortIO(Sana2Req)
  38.     D0              A1
  39.  
  40.     LONG AbortIO(struct IOSana2Req *);
  41.  
  42.    FUNCTION
  43.     This is an exec.library call.
  44.  
  45.     This function aborts an ioRequest. If the request is active, it may or
  46.     may not be aborted. If the request is queued it is removed. The
  47.     request will be returned in the same way as if it had normally
  48.     completed.  You must WaitIO() after AbortIO() for the request to
  49.     return.
  50.  
  51.    INPUTS
  52.     Sana2Req    - Sana2Req to be aborted.
  53.  
  54.    RESULTS
  55.     error        - Zero if the request was aborted, non-zero otherwise.
  56.               io_Error in Sana2Req will be set to IOERR_ABORTED
  57.               if it was aborted.
  58.  
  59.    NOTES
  60.  
  61.    SEE ALSO
  62.     exec.library/AbortIO(), exec.library/WaitIO()
  63.  
  64.    BUGS
  65.  
  66. sana2.device/CloseDevice                             sana2.device/CloseDevice
  67.  
  68.    NAME
  69.     CloseDevice -- Close the device.
  70.  
  71.    SYNOPSIS
  72.     CloseDevice(Sana2Req)
  73.             A1
  74.  
  75.     void CloseDevice(struct IOSana2Req *);
  76.  
  77.    FUNCTION
  78.     This function is called by exec.library CloseDevice().
  79.  
  80.     This function performs whatever cleanup is required at device closes.
  81.  
  82.     Note that all IORequests MUST be complete before closing. If any are
  83.     pending, your program must AbortIO() then WaitIO() each outstanding
  84.     IORequest to complete them.
  85.  
  86.    INPUTS
  87.     Sana2Req    - Pointer to IOSana2Req initialized by OpenDevice().
  88.  
  89.    NOTES
  90.  
  91.    SEE ALSO
  92.     exec.library/CloseDevice(), exec.library/OpenDevice()
  93.  
  94.    BUGS
  95.  
  96. sana2.device/CMD_CLEAR                                 sana2.device/CMD_CLEAR
  97.  
  98.    NAME
  99.     Clear -- Clear internal network interface read buffers.
  100.  
  101.    FUNCTION
  102.     There are no device internal buffers, so CMD_CLEAR does not apply to
  103.     this class of device.
  104.  
  105.    IO REQUEST
  106.     ios2_Command    - CMD_CLEAR.
  107.  
  108.    RESULTS
  109.     ios2_Error    - IOERR_NOCMD.
  110.  
  111.    NOTES
  112.  
  113.    SEE ALSO
  114.  
  115.    BUGS
  116.  
  117. sana2.device/CMD_FLUSH                                 sana2.device/CMD_FLUSH
  118.  
  119.    NAME
  120.     Flush -- Clear all queued I/O requests for the SANA-II device.
  121.  
  122.    FUNCTION
  123.     This command aborts all I/O requests in both the read and write
  124.     request queues of the device.  All pending I/O requests are
  125.     returned with an error message (IOERR_ABORTED).  CMD_FLUSH does not
  126.     affect active requests.
  127.  
  128.    IO REQUEST
  129.     ios2_Command    - CMD_FLUSH.
  130.  
  131.    RESULTS
  132.     ios2_Error    - Zero if successful; non-zero otherwise.
  133.  
  134.    NOTES
  135.  
  136.    SEE ALSO
  137.  
  138.    BUGS
  139.  
  140. sana2.device/CMD_INVALID                             sana2.device/CMD_INVALID
  141.  
  142.    NAME
  143.     Invalid -- Return with error IOERR_NOCMD.
  144.  
  145.    FUNCTION
  146.     This command causes device driver to reply with an error IOERR_NOCMD
  147.     as defined in <exec/errors.h> indicating the command is not supported.
  148.  
  149.    IO REQUEST
  150.     ios2_Command    - CMD_INVALID.
  151.  
  152.    RESULTS
  153.     ios2_Error    - IOERR_NOCMD.
  154.  
  155.    NOTES
  156.  
  157.    SEE ALSO
  158.  
  159.    BUGS
  160.     Not known to be useful.
  161.  
  162. sana2.device/CMD_READ                                   sana2.device/CMD_READ
  163.  
  164.    NAME
  165.     Read -- Get a packet from the network.
  166.  
  167.    FUNCTION
  168.     Get the next packet available of the requested packet type. The data
  169.     copied (via a call to the requestor-provided CopyToBuffer function)
  170.     into ios2_Data is normally the Data Link Layer packet data only. If
  171.     bit SANA2IOB_RAW is set in ios2_Flags, then the entire physical frame
  172.     will be returned.
  173.  
  174.     Unlike most Exec devices, SANA-II device drivers do not have internal
  175.     buffers.  If you wish to read data from a SANA-II device you should
  176.     have multiple CMD_READ requests pending at any given time.  The
  177.     functions provided by you the requestor will be used for any incoming
  178.     packets of the type you've requested.  If no read requests are
  179.     outstanding for a type which comes in and no read_orphan requests are
  180.     outstanding, the packet will be lost.
  181.  
  182.    IO REQUEST
  183.     ios2_Command    - CMD_READ
  184.     ios2_Flags    - Supported flags are:
  185.                         SANA2IOB_RAW
  186.                         SANA2IOB_QUICK
  187.     ios2_PacketType    - Packet type desired.
  188.     ios2_Data    - Abstract data structure to hold packet data.
  189.  
  190.    RESULTS
  191.     ios2_Error    - Zero if successful; non-zero otherwise.
  192.     ios2_WireError    - More specific error number.
  193.     ios2_Flags    - The following flags may be returned:
  194.                         SANA2IOB_RAW
  195.                         SANA2IOB_BCAST
  196.                         SANA2IOB_MCAST
  197.     ios2_SrcAddr    - Source interface address of packet.
  198.     ios2_DstAddr    - Destination interface address of packet.
  199.     ios2_DataLength    - Length of packet data.
  200.     ios2_Data    - Abstract data structure which packet data is
  201.               contained in.
  202.  
  203.    NOTES
  204.     The driver may not directly examine or modify anything pointed to by
  205.     ios2_Data.  It *must* use the requester-provided functions to access
  206.     this data.
  207.  
  208.    SEE ALSO
  209.     S2_READORPHAN, CMD_WRITE, any_protocol/CopyToBuffer
  210.  
  211.    BUGS
  212.  
  213. sana2.device/CMD_RESET                                 sana2.device/CMD_RESET
  214.  
  215.    NAME
  216.     Reset -- Reset the network interface to initialized state.
  217.  
  218.    FUNCTION
  219.     Currently, SANA-II devices can only be configured once (with
  220.     CMD_CONFIGINTERFACE) and cannot be re-configured, hence,
  221.     CMD_RESET does not apply to this class of device.
  222.  
  223.    IO REQUEST
  224.     ios2_Command    - CMD_RESET.
  225.  
  226.    RESULTS
  227.     ios2_Error    - IOERR_NOCMD.
  228.  
  229.    NOTES
  230.  
  231.    SEE ALSO
  232.  
  233.    BUGS
  234.  
  235. sana2.device/CMD_START                                 sana2.device/CMD_START
  236.  
  237.    NAME
  238.     Start -- Restart device operation.
  239.  
  240.    FUNCTION
  241.     There is no way for the driver to keep queuing requests without
  242.     servicing them, so CMD_STOP does not apply to this class of device.
  243.     S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
  244.     and CMD_START
  245.  
  246.    IO REQUEST
  247.     ios2_Command    - CMD_START.
  248.  
  249.    RESULTS
  250.     ios2_Error    - IOERR_NOCMD.
  251.  
  252.    NOTES
  253.  
  254.    SEE ALSO
  255.     S2_ONLINE, S2_OFFLINE
  256.  
  257.    BUGS
  258.  
  259. sana2.device/CMD_STOP                                   sana2.device/CMD_STOP
  260.  
  261.    NAME
  262.     Stop -- Pause device operation.
  263.  
  264.    FUNCTION
  265.     There is no way for the driver to keep queuing requests without
  266.     servicing them, so CMD_STOP does not apply to this class of device.
  267.     S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
  268.     and CMD_START
  269.  
  270.    IO REQUEST
  271.     ios2_Command    - CMD_STOP.
  272.  
  273.    RESULTS
  274.     ios2_Error    - IOERR_NOCMD.
  275.  
  276.    NOTES
  277.  
  278.    SEE ALSO
  279.     S2_ONLINE, S2_OFFLINE
  280.  
  281.    BUGS
  282.  
  283. sana2.device/CMD_UPDATE                               sana2.device/CMD_UPDATE
  284.  
  285.    NAME
  286.     Update -- Force packets out to device.
  287.  
  288.    FUNCTION
  289.     Since there are no device internal buffers, CMD_UPDATE does not
  290.     apply to this class of device.
  291.  
  292.    IO REQUEST
  293.     ios2_Command    - CMD_UPDATE.
  294.  
  295.    RESULTS
  296.     ios2_Error    - IOERR_NOCMD.
  297.  
  298.    NOTES
  299.  
  300.    SEE ALSO
  301.  
  302.    BUGS
  303.  
  304. sana2.device/CMD_WRITE                                 sana2.device/CMD_WRITE
  305.  
  306.    NAME
  307.     Write -- Send packet to the network.
  308.  
  309.    FUNCTION
  310.     This command causes the packet to be sent to the specified network
  311.     interface. Normally, appropriate packet header and trailer information
  312.     will be added to the packet data when it is sent.  If bit SANA2IOB_RAW
  313.     is set in io_Flags, then the ios2_Data is assumed to contain an entire
  314.     physical frame and will be sent (copied to the wire via
  315.     CopyFromBuffer() unmodified.
  316.  
  317.     Note that the device should not check to see if the destination
  318.     address is on the local hardware.  Network protocols should realize
  319.     that the packet has a local destination long before it gets to a
  320.     SANA-II driver.
  321.  
  322.    IO REQUEST
  323.     ios2_Command    - CMD_WRITE.
  324.     ios2_Flags    - Supported flags are:
  325.                         SANA2IOB_RAW
  326.                         SANA2IOB_QUICK
  327.     ios2_PacketType    - Packet type to send.
  328.     ios2_DstAddr    - Destination interface address for this packet.
  329.     ios2_DataLength    - Length of the Data to be sent.
  330.     ios2_Data    - Abstract data structure which packet data is
  331.               contained in.
  332.  
  333.    RESULTS
  334.     ios2_Error    - Zero if successful; non-zero otherwise.
  335.     ios2_WireError    - More specific error number.
  336.  
  337.    NOTES
  338.     The driver may not directly examine or modify anything pointed to by
  339.     ios2_Data.  It *must* use the requester-provided functions to access
  340.     this data.
  341.  
  342.    SEE ALSO
  343.     CMD_READ, S2_BROADCAST, S2_MULTICAST, any_protocol/CopyFromBuffer
  344.  
  345.    BUGS
  346.  
  347. sana2.device/OpenDevice                               sana2.device/OpenDevice
  348.  
  349.    NAME
  350.     Open -- Request an opening of the network device.
  351.  
  352.    SYNOPSIS
  353.     error = OpenDevice(unit, IOSana2Req, flags)
  354.     D0           D0    A1          D1
  355.  
  356.     BYTE OpenDevice(ULONG, struct IOSana2Req *, ULONG);
  357.  
  358.    FUNCTION
  359.     This function is called by exec.library OpenDevice().
  360.  
  361.     This function performs whatever initialization is required per
  362.     device open and initializes the Sana2Req for use by the
  363.     device.
  364.  
  365.    INPUTS
  366.     unit        - Device unit to open.
  367.     Sana2Req    - Pointer to IOSana2Req structure to be initialized by
  368.               the sana2.device.
  369.     flags        - Supported flags are:
  370.                 SANA2OPB_MINE
  371.                 SANA2OPB_PROM
  372.     ios2_BufferManagement    - A pointer to a tag list containing
  373.                   pointers to buffer management functions.
  374.  
  375.    RESULTS
  376.     error        - same as io_Error
  377.     io_Error    - Zero if successful; non-zero otherwise.
  378.     io_Device    - A pointer to whatever device will handle the calls
  379.               for this unit.  This pointer may be different
  380.               depending on what unit is requested.
  381.     ios2_BufferManagement    - A pointer to device internal information
  382.                   used to call buffer management functions.
  383.  
  384.    NOTES
  385.  
  386.    SEE ALSO
  387.     exec.library/OpenDevice(), exec.library/CloseDevice()
  388.  
  389.    BUGS
  390.  
  391. sana2.device/S2_ADDMULTICASTADDRESS       sana2.device/S2_ADDMULTICASTADDRESS
  392.  
  393.    NAME
  394.     AddMulticastAddress -- Enable an interface multicast address.
  395.  
  396.    FUNCTION
  397.     This command causes the device driver to enable multicast packet
  398.     reception for the requested address.
  399.  
  400.    IO REQUEST
  401.     ios2_Command    - S2_ADDMULTICASTADDRESS.
  402.     ios2_SrcAddr    - Multicast address to enable.
  403.  
  404.    RESULTS
  405.     ios2_Error    - Zero if successful; non-zero otherwise.
  406.     ios2_WireError    - More specific error number.
  407.  
  408.    NOTES
  409.     Multicast addresses are added globally -- anyone using the device
  410.     may receive packets as a result of any multicast address which has
  411.     been added for the device.
  412.  
  413.     Since multicast addresses are not "bound" to a particular packet type,
  414.     each enabled multicast address has an "enabled" count associated with
  415.     it so that if two protocols add the same multicast address and later
  416.     one removes it, it is still enabled until the second removes it.
  417.  
  418.    SEE ALSO
  419.     S2_MULTICAST, S2_DELMULTICASTADDRESS
  420.  
  421.    BUGS
  422.  
  423. sana2.device/S2_BROADCAST                           sana2.device/S2_BROADCAST
  424.  
  425.    NAME
  426.     Broadcast -- Broadcast a packet on network.
  427.  
  428.    FUNCTION
  429.     This command works the same as CMD_WRITE except that it also performs
  430.     whatever special processing of the packet is required to do a
  431.     broadcast send. The actual broadcast mechanism is neccessarily
  432.     network/interface/device specific.
  433.  
  434.    IO REQUEST
  435.     ios2_Command    - S2_BROADCAST.
  436.     ios2_Flags    - Supported flags are:
  437.                 SANA2IOB_RAW
  438.                 SANA2IOB_QUICK
  439.     ios2_PacketType    - Packet type to send.
  440.     ios2_DataLength    - Length of the Data to be sent.
  441.     ios2_Data    - Abstract data structure which packet data is
  442.               contained in.
  443.  
  444.    RESULTS
  445.     ios2_DstAddr    - The contents of this field are to be
  446.               considered trash upon return of the IOReq.
  447.     ios2_Error    - Zero if successful; non-zero otherwise.
  448.                       This command can fail for many reasons and
  449.                       is not supported by all networks and/or
  450.                       network interfaces.
  451.     ios2_WireError    - More specific error number.
  452.  
  453.    NOTES
  454.     The DstAddr field may be trashed by the driver because this function
  455.     may be implemented by filling DstAddr with a broadcast address and
  456.     internally calling CMD_WRITE.
  457.  
  458.    SEE ALSO
  459.     CMD_WRITE, S2_MULTICAST
  460.  
  461.    BUGS
  462.  
  463. sana2.device/S2_CONFIGINTERFACE               sana2.device/S2_CONFIGINTERFACE
  464.  
  465.    NAME
  466.     ConfigInterface -- Configure the network interface.
  467.  
  468.    FUNCTION
  469.     This command causes the device driver to initialize the interface
  470.     hardware and to set the network interface address to the address in
  471.     ios2_SrcAddr. This command can only be executed once and, if
  472.     successful, will leave the driver and network interface fully
  473.     operational and the network interface in ios2_SrcAddr.
  474.  
  475.     To set the interface address to the factory address, the network
  476.     management software must use GetStationAddress first and then call
  477.     ConfigInterface with the result. If there is no factory address then
  478.     the network software must pick an address to use.
  479.  
  480.     Until this command is executed the device will not listen for any
  481.     packets on the hardware.
  482.  
  483.    IO REQUEST
  484.     ios2_Command    - S2_CONFIGINTERFACE.
  485.     ios2_Flags      - Supported flags are:
  486.                 SANA2IOB_QUICK
  487.     ios2_SrcAddr    - Address for this interface.
  488.  
  489.    RESULTS
  490.     ios2_Error    - Zero if successful; non-zero otherwise.
  491.     ios2_WireError    - More specific error number.
  492.     ios2_SrcAddr    - Address of this interface as configured.
  493.  
  494.    NOTES
  495.     Some networks have the interfaces choose a currently unused interface
  496.     address each time the interface is initialized. The caller must check
  497.     ios2_SrcAddr for the actual interface address after configuring the
  498.     interface.
  499.  
  500.    SEE ALSO
  501.     S2_GETSTATIONADDRESS
  502.  
  503.    BUGS
  504.  
  505. sana2.device/S2_DELMULTICASTADDRESS       sana2.device/S2_DELMULTICASTADDRESS
  506.  
  507.    NAME
  508.     DelMultiCastAddress -- Disable an interface multicast address.
  509.  
  510.    FUNCTION
  511.     This command causes device driver to disable multicast packet
  512.     reception for the requested address.
  513.  
  514.     It is an error to disable a multicast address that is not enabled.
  515.  
  516.    IO REQUEST
  517.     ios2_Command    - S2_DELMULTICASTADDRESS
  518.     ios2_SrcAddr    - Multicast address to disable.
  519.  
  520.    RESULTS
  521.     ios2_Error    - Zero if successful; non-zero otherwise.
  522.     ios2_WireError    - More specific error number.
  523.  
  524.    NOTES
  525.     Multicast addresses are added globally -- anyone using the device
  526.     may receive packets as a result of any multicast address which has
  527.     been added for the device.
  528.  
  529.     Since multicast addresses are not "bound" to a particular packet type,
  530.     each enabled multicast address has an "enabled" count associated with
  531.     it so that if two protocols add the same multicast address and later
  532.     one removes it, it is still enabled until the second removes it.
  533.  
  534.    SEE ALSO
  535.     S2_ADDMULTICASTADDRESS
  536.  
  537.    BUGS
  538.  
  539. sana2.device/S2_DEVICEQUERY                       sana2.device/S2_DEVICEQUERY
  540.  
  541.    NAME
  542.     DeviceQuery -- Return parameters for this network interface.
  543.  
  544.    FUNCTION
  545.     This command causes the device driver to report information about the
  546.     device. Up to SizeAvailable bytes of the information is copied
  547.     into a buffer pointed to by ios2_StatData. The format of the data is
  548.     as follows:
  549.  
  550.         struct Sana2DeviceQuery
  551.         {
  552.         /*
  553.         ** Standard information
  554.         */
  555.             ULONG SizeAvailable;    /* bytes available */
  556.             ULONG SizeSupplied;     /* bytes supplied */
  557.             LONG  DevQueryFormat;   /* this is type 0 */
  558.             LONG  DeviceLevel;      /* this document is level 0 */
  559.  
  560.         /*
  561.         ** Common information
  562.         */
  563.             UWORD AddrFieldSize;    /* address size in bits */
  564.             ULONG MTU;              /* maximum packet data size */
  565.             LONG  BPS;              /* line rate (bits/sec) */
  566.             LONG  HardwareType;     /* what the wire is */
  567.  
  568.         /*
  569.         ** Format specific information
  570.         */
  571.         };
  572.  
  573.     The SizeAvailable specifies the number of bytes that the caller
  574.     is prepared to accomodate, including the standard information fields.
  575.  
  576.     SizeSupplied is the number of bytes actually supplied,
  577.     including the standard information fields, which will not exceed
  578.     SizeAvailable.
  579.  
  580.     <devices/sana2.h> includes constants for these values.  If your
  581.     hardware does not have a number assigned to it, you must contact
  582.     CATS to get a hardware number.
  583.  
  584.    IO REQUEST
  585.     ios2_Command    - S2_DEVICEQUERY.
  586.     ios2_StatData    - Pointer to Sana2DeviceQuery structure to fill in.
  587.  
  588.    RESULTS
  589.     ios2_Error    - Zero if successful; non-zero otherwise.
  590.     ios2_WireError    - More specific error number.
  591.  
  592.    NOTES
  593.  
  594.    SEE ALSO
  595.  
  596.    BUGS
  597.  
  598. sana2.device/S2_GETGLOBALSTATS                 sana2.device/S2_GETGLOBALSTATS
  599.  
  600.    NAME
  601.     GetGlobalStats -- Get interface accumulated statistics.
  602.  
  603.    FUNCTION
  604.     This command causes the device driver to retrieve various global
  605.     runtime statistics for this network interface. The format of the
  606.     data returned is as follows:
  607.  
  608.         struct Sana2DeviceStats
  609.         {
  610.             ULONG PacketsReceived;
  611.             ULONG PacketsSent;
  612.             ULONG BadData;
  613.             ULONG Overruns;
  614.             ULONG UnknownTypesReceived;
  615.             ULONG Reconfigurations;
  616.             timeval LastStart;
  617.         };
  618.  
  619.    IO REQUEST
  620.     ios2_Command    - S2_GETGLOBALSTATS.
  621.     ios2_StatData    - Pointer to Sana2DeviceStats structure to fill.
  622.  
  623.    RESULTS
  624.     ios2_Error    - Zero if successful; non-zero otherwise.
  625.     ios2_WireError    - More specific error number.
  626.  
  627.    NOTES
  628.  
  629.    SEE ALSO
  630.     S2_GETSPECIALSTATS
  631.  
  632.    BUGS
  633.  
  634. sana2.device/S2_GETSPECIALSTATS               sana2.device/S2_GETSPECIALSTATS
  635.  
  636.    NAME
  637.     GetSpecialStats -- Get network type specific statistics.
  638.  
  639.    FUNCTION
  640.     This function returns statistics which are specific to the type of
  641.     network medium this driver controls. For example, this command could
  642.     return statistics common to all Ethernets which are not common to all
  643.     network mediums in general.
  644.  
  645.     The supplied Sana2SpecialStatData structure is given below:
  646.  
  647.         struct Sana2SpecialStatData
  648.         {
  649.             ULONG RecordCountMax;
  650.             ULONG RecordCountSupplied;
  651.             struct Sana2StatRecord[RecordCountMax];
  652.         };
  653.  
  654.     The format of the data returned is:
  655.  
  656.         struct Sana2StatRecord
  657.         {
  658.             ULONG Type;     /* commodore registered */
  659.             LONG Count;     /* the stat itself */
  660.             char *String;   /* null terminated */
  661.         };
  662.  
  663.     The RecordCountMax field specifies the number of records that the
  664.     caller is prepared to accomodate.
  665.  
  666.     RecordCountSupplied is the number of record actually supplied which
  667.     will not exceed RecordCountMax.
  668.  
  669.    IO REQUEST
  670.     ios2_Command    - S2_GETSPECIALSTATS.
  671.     ios2_StatData    - Pointer to a Sana2SpecialStatData structure to fill.
  672.               RecordCountMax must be initialized.
  673.  
  674.    RESULTS
  675.     ios2_Error    - Zero if successful; non-zero otherwise.
  676.     ios2_WireError    - More specific error number.
  677.  
  678.    NOTES
  679.     Commodore will maintain registered statistic Types.
  680.  
  681.    SEE ALSO
  682.     S2_GETGLOBALSTATS, <devices/sana2specialstats.h>
  683.  
  684.    BUGS
  685.  
  686. sana2.device/S2_GETSTATIONADDRESS           sana2.device/S2_GETSTATIONADDRESS
  687.  
  688.    NAME
  689.     GetStationAddress -- Get default and interface address.
  690.  
  691.    FUNCTION
  692.     This command causes the device driver to copy the current interface
  693.     address into ios2_SrcAddr, and to copy the factory default station
  694.     address (if any) into ios2_DstAddr.
  695.  
  696.    IO REQUEST
  697.     ios2_Command    - S2_GETSTATIONADDRESS.
  698.  
  699.    RESULTS
  700.     ios2_Error    - Zero if successful; non-zero otherwise.
  701.     ios2_WireError    - More specific error number.
  702.     ios2_SrcAddr    - Current interface address.
  703.     ios2_DstAddr    - Default interface address (if any).
  704.  
  705.    NOTES
  706.  
  707.    SEE ALSO
  708.     S2_CONFIGINTERFACE
  709.  
  710.    BUGS
  711.  
  712. sana2.device/S2_GETTYPESTATS                     sana2.device/S2_GETTYPESTATS
  713.  
  714.    NAME
  715.     GetTypeStats -- Get accumulated type specific statistics.
  716.  
  717.    FUNCTION
  718.     This command causes the device driver to retrieve various packet type
  719.     specific runtime statistics for this network interface. The format of
  720.     the data returned is as follows:
  721.  
  722.         struct Sana2PacketTypeStats
  723.         {
  724.             LONG PacketsSent;            /* transmitted count            */
  725.             LONG PacketsReceived;        /* received count               */
  726.             LONG BytesSent;              /* bytes transmitted count      */
  727.             LONG BytesReceived;          /* bytes received count         */
  728.             LONG PacketsDropped;         /* packets dropped count        */
  729.         };
  730.  
  731.    IO REQUEST
  732.     ios2_Command    - S2_GETTYPESTATS.
  733.     ios2_PacketType    - Packet type of interest.
  734.     ios2_StatData    - Pointer to TypeStats structure to fill in.
  735.  
  736.    RESULTS
  737.     ios2_Error    - Zero if successful; non-zero otherwise.
  738.     ios2_WireError    - More specific error number.
  739.  
  740.    NOTES
  741.     Statistics for a particular packet type are only available while that
  742.     packet type is being ``tracked''.
  743.  
  744.    SEE ALSO
  745.     S2_TRACKTYPE, S2_UNTRACKTYPE
  746.  
  747.    BUGS
  748.  
  749. sana2.device/S2_MULTICAST                           sana2.device/S2_MULTICAST
  750.  
  751.    NAME
  752.     Multicast -- Multicast a packet on network.
  753.  
  754.    FUNCTION
  755.     This command works the same as CMD_WRITE except that it also performs
  756.     whatever special processing of the packet is required to do a
  757.     multicast send. The actual multicast mechanism is neccessarily
  758.     network/interface/device specific.
  759.  
  760.    IO REQUEST
  761.     ios2_Command    - S2_MULTICAST.
  762.     ios2_Flags    - Supported flags are:
  763.                 SANA2IOB_RAW
  764.                 SANA2IOB_QUICK
  765.     ios2_PacketType    - Packet type to send.
  766.     ios2_DstAddr    - Destination interface address for this packet.
  767.     ios2_DataLength    - Length of the Data to be sent.
  768.     ios2_Data    - Abstract data structure which packet data is
  769.               contained in.
  770.  
  771.    RESULTS
  772.     ios2_Error    - Zero if successful; non-zero otherwise.
  773.                       This command can fail for many reasons and
  774.                       is not supported by all networks and/or
  775.                       network interfaces.
  776.     ios2_WireError    - More specific error number.
  777.  
  778.    NOTES
  779.     The address supplied in ios2_DstAddr will be sanity checked (if
  780.     possible) by the driver. If the supplied address fails this sanity
  781.     check, the multicast request will fail immediately with ios2_Error
  782.     set to S2WERR_BAD_MULTICAST.
  783.  
  784.     Another Amiga will not receive a multicast packet unless it has had
  785.     the particular multicast address being used S2_ADDMULTICASTADRESS'd.
  786.  
  787.    SEE ALSO
  788.     CMD_WRITE, S2_BROADCAST, S2_ADDMULTICASTADDRESS
  789.  
  790.    BUGS
  791.  
  792. sana2.device/S2_OFFLINE                               sana2.device/S2_OFFLINE
  793.  
  794.    NAME
  795.     Offline -- Remove interface from service.
  796.  
  797.    FUNCTION
  798.     This command removes a network interface from service.
  799.  
  800.    IO REQUEST
  801.     ios2_Command    - S2_OFFLINE.
  802.  
  803.    RESULTS
  804.     ios2_Error    - Zero if successful; non-zero otherwise.
  805.     ios2_WireError    - More specific error number.
  806.  
  807.    NOTES
  808.     Aborts all pending reads and writes with ios2_Error set to
  809.     S2ERR_OUTOFSERVICE.
  810.  
  811.     While the interface is offline, all read, writes and any other
  812.     command that touches interface hardware will be rejected with
  813.     ios2_Error set to S2ERR_OUTOFSERVICE.
  814.  
  815.     This command is intended to permit a network interface to be
  816.     tested on an otherwise live system.
  817.  
  818.    SEE ALSO
  819.     S2_ONLINE
  820.  
  821.    BUGS
  822.  
  823. sana2.device/S2_ONEVENT                               sana2.device/S2_ONEVENT
  824.  
  825.    NAME
  826.     OnEvent -- Return when specified event occures.
  827.  
  828.    FUNCTION
  829.     This command returns when a particular event condition has occured
  830.     on the network or this network interface.
  831.  
  832.    IO REQUEST
  833.     ios2_Command    - S2_ONEVENT.
  834.     ios2_Flags    - Supported flags are:
  835.                 SANA2IOB_QUICK
  836.     ios2_WireError    - Mask of event(s) to wait for
  837.               (from <devices/sana2.h>).
  838.  
  839.    RESULTS
  840.     ios2_Error    - Zero if successful; non-zero otherwise.
  841.     ios2_WireError    - Mask of events that occured.
  842.  
  843.    NOTES
  844.     If this device driver does not understand the specified event
  845.     condition(s) then the command returns immediately with
  846.     ios2_Req.io_Error set to S2_ERR_NOT_SUPPORTED and ios2_WireError
  847.     S2WERR_BAD_EVENT.  A successful return will have ios2_Error set to
  848.     zero ios2_WireError set to the event number.
  849.  
  850.     All pending requests for a particular event will be returned when
  851.     that event occurs.
  852.  
  853.     All event types that cover a particular condition are returned when
  854.     that condition occures. For instance, if an error is returned by
  855.     a buffer management function during receive processing, events of
  856.     types S2EVENT_ERROR, S2EVENT_RX and S2EVENT_BUFF would be returned if
  857.     pending.
  858.  
  859.     Types ONLINE and OFFLINE return immediately if the device is
  860.     already in the state to be waited for.
  861.  
  862.    SEE ALSO
  863.  
  864.    BUGS
  865.  
  866. sana2.device/S2_ONLINE                                 sana2.device/S2_ONLINE
  867.  
  868.    NAME
  869.     Online -- Put a network interface back in service.
  870.  
  871.    FUNCTION
  872.     This command places an offline network interface back into service.
  873.  
  874.    IO REQUEST
  875.     ios2_Command    - S2_ONLINE.
  876.  
  877.    RESULTS
  878.     ios2_Error    - Zero if successful; non-zero otherwise.
  879.     ios2_WireError    - More specific error number.
  880.  
  881.    NOTES
  882.     This command is responsible for putting the network interface
  883.     hardware back into a known state (as close as possible to the
  884.     state before S2_OFFLINE) and resets the unit global and special
  885.     statistics.
  886.  
  887.    SEE ALSO
  888.     S2_OFFLINE
  889.  
  890.    BUGS
  891.  
  892. sana2.device/S2_READORPHAN                         sana2.device/S2_READORPHAN
  893.  
  894.    NAME
  895.     ReadOrphan -- Get a packet for which there is no reader.
  896.  
  897.    FUNCTION
  898.     Get the next packet available that does not satisfy any    then-pending
  899.     CMD_READ requests. The data returned in the ios2_Data structure is
  900.     normally the Data Link Layer packet type field and the packet data. If
  901.     bit SANA2IOB_RAW is set in ios2_Flags, then the entire Data Link Layer
  902.     packet, including both header and trailer information, will be
  903.     returned.
  904.  
  905.    IO REQUEST
  906.     ios2_Command    - CMD_READORPHAN.
  907.     ios2_Flags    - Supported flags are:
  908.                 SANA2IOB_RAW
  909.                 SANA2IOB_QUICK
  910.     ios2_DataLength    - Length of the Data to be sent.
  911.     ios2_Data    - Abstract data structure which packet data is
  912.               contained in.
  913.  
  914.    RESULTS
  915.     ios2_Error    - Zero if successful; non-zero otherwise.
  916.     ios2_WireError    - More specific error number.
  917.     ios2_Flags    - The following flags may be returned:
  918.                 SANA2IOB_RAW
  919.                 SANA2IOB_BCAST
  920.                 SANA2IOB_MCAST
  921.     ios2_SrcAddr    - Source interface address of packet.
  922.     ios2_DstAddr    - Destination interface address of packet.
  923.     ios2_DataLength    - Length of the Data to be sent.
  924.     ios2_Data    - Abstract data structure which packet data is
  925.               contained in.
  926.  
  927.    NOTES
  928.     This is intended for debugging and management tools.  Protocols should
  929.     not use this.
  930.  
  931.     As with 802.3 packets on an ethernet, to determine which protocol
  932.     family the returned packet belongs to you may have to specify
  933.     SANA2IOB_RAW to get the entire data link layer wrapper (which is where
  934.     the protocol type may be kept). Notice this necessarily means that
  935.     this cannot be done in a network interface independent fashion.  The
  936.     driver will, however, fill in the PacketType field to the best of its
  937.     ability.
  938.  
  939.    SEE ALSO
  940.     CMD_READ, CMD_WRITE
  941.  
  942.    BUGS
  943.  
  944. sana2.device/S2_TRACKTYPE                           sana2.device/S2_TRACKTYPE
  945.  
  946.    NAME
  947.     TrackType -- Accumulate statistics about a packet type.
  948.  
  949.    FUNCTION
  950.     This command causes the device driver to accumulate statistics about
  951.     a particular packet type. Packet type statistics, for the particular
  952.     packet type, are zeroed by this command.
  953.  
  954.    IO REQUEST
  955.     ios2_Command    - S2_TRACKTYPE.
  956.     ios2_PacketType    - Packet type of interest.
  957.  
  958.    RESULTS
  959.     ios2_Error    - Zero if successful; non-zero otherwise.
  960.     ios2_WireError    - More specific error number.
  961.  
  962.    NOTES
  963.  
  964.    SEE ALSO
  965.     S2_UNTRACKTYPE, S2_GETTYPESTATS
  966.  
  967.    BUGS
  968.  
  969. sana2.device/S2_UNTRACKTYPE                       sana2.device/S2_UNTRACKTYPE
  970.  
  971.    NAME
  972.     UntrackType -- End statistics about a packet type.
  973.  
  974.    FUNCTION
  975.     This command causes the device driver to stop accumulating
  976.     statistics about a particular packet type.
  977.  
  978.    IO REQUEST
  979.     ios2_Command    - S2_UNTRACKTYPE.
  980.     ios2_PacketType    - Packet type of interest.
  981.  
  982.    RESULTS
  983.     ios2_Error    - Zero if successful; non-zero otherwise.
  984.     ios2_WireError    - More specific error number.
  985.  
  986.    NOTES
  987.  
  988.    SEE ALSO
  989.     S2_TRACKTYPE, S2_GETTYPESTATS
  990.  
  991.    BUGS
  992.  
  993.