path: root/private/ntos/ndis/madge/driver/head_def/ftk_user.h

/****************************************************************************/
/****************************************************************************/
/*                                                                          */
/*      THE USER DEFINITIONS                                                */
/*      ====================                                                */
/*                                                                          */
/*      FTK_USER.H : Part of the FASTMAC TOOL-KIT (FTK)                     */
/*                                                                          */
/*      Copyright (c) Madge Networks Ltd. 1991-1994                         */
/*      Developed by MF                                                     */
/*      CONFIDENTIAL                                                        */
/*                                                                          */
/*                                                                          */
/****************************************************************************/
/*                                                                          */
/* This header file contains ALL the definitions and structures required by */
/* any  user  of the FTK driver. Any user of the FTK need only include this */
/* definitions header file in order to use the FTK.                         */
/*                                                                          */
/* IMPORTANT : Some structures used within the FTK  need to  be  packed  in */
/* order to work correctly. This means sizeof(STRUCTURE) will give the real */
/* size  in bytes, and if a structure contains sub-structures there will be */
/* no spaces between the sub-structures.                                    */
/*                                                                          */
/****************************************************************************/

/****************************************************************************/
/*                                                                          */
/* VERSION_NUMBER of FTK to which this FTK_USER.H belongs :                 */
/*                                                                          */

#define FTK_VERSION_NUMBER_FTK_USER_H 221


/****************************************************************************/
/*                                                                          */
/* TYPEDEFs for all structures defined within this header file :            */
/*                                                                          */

typedef struct STRUCT_NODE_ADDRESS              NODE_ADDRESS;
typedef union  UNION_MULTI_ADDRESS              MULTI_ADDRESS;
typedef struct STRUCT_STATUS_INFORMATION        STATUS_INFORMATION;
typedef struct STRUCT_ERROR_LOG                 ERROR_LOG;
typedef struct STRUCT_PROBE                     PROBE;
typedef struct STRUCT_PREPARE_ARGS              PREPARE_ARGS, *PPREPARE_ARGS;
typedef struct STRUCT_START_ARGS                START_ARGS, *PSTART_ARGS;
typedef struct STRUCT_TR_OPEN_DATA              TR_OPEN_DATA, *PTR_OPEN_DATA;


/****************************************************************************/
/*                                                                          */
/* Function declarations                                                    */
/*                                                                          */
/* Routines  in the FTK are either local to a module, or they are exported. */
/* Exported routines are entry points to the  user  of  a  module  and  the */
/* routine  has  an  'extern' definition in an appropriate header file (see */
/* FTK_INTR.H and FTK_EXTR.H). A user of the FTK may wish  to  follow  this */
/* method of function declarations using the following definitions.         */
/*                                                                          */

#define local   static
#define export


/****************************************************************************/
/*                                                                          */
/* Basic types : BYTE, WORD, DWORD and BOOLEAN                              */
/*                                                                          */
/* The basic types used throughout the FTK, and for passing  parameters  to */
/* it,  are  BYTE  (8  bit unsigned), WORD (16 bit unsigned), DWORD (32 bit */
/* unsigned) and BOOLEAN (16 bit unsigned). A BOOLEAN variable should  take */
/* the value TRUE or FALSE.                                                 */
/*                                                                          */
/* Note  that  none  of  the FTK code makes an explicit check for the value */
/* TRUE (it only checks for FALSE which must be zero) and  hence  TRUE  can */
/* have any non-zero value.                                                 */
/*                                                                          */

typedef unsigned char           BYTE;           /* 8 bits                   */

typedef unsigned short int      WORD;           /* 16 bits                  */

typedef unsigned long int       DWORD;          /* 32 bits                  */

typedef unsigned long int       ULONG;

typedef WORD                    WBOOLEAN;

typedef unsigned int            UINT;

#define	VOID			void

#define FALSE                   0
#define TRUE                    1

#if !defined(max)
#define max(a,b) ((a) < (b) ? (b) : (a))
#endif

#if !defined(min)
#define min(a,b) ((a) < (b) ? (a) : (b))
#endif


#ifdef FMPLUS

/****************************************************************************/
/*                                                                          */
/* Variables : Fmplus download image                                       */
/*                                                                          */
/* The following variables are exported  by  FMPLUS.C  which  contains  the */
/* binary image for FastmacPlus in a 'C' format BYTE array. These variables */
/* will  be  needed  by  a  user  of  the  FTK in order to download Fastmac */
/* Plus  (fmplus_image),   display  the  Fastmac  Plus version  number  and */
/* copyright  message  (fmplus_version  and fmplus_copyright_msg) and check */
/* that  the   FTK   version   number   is   that   required   by   Fastmac */
/* (ftk_version_for_fmplus).  The variables  concerned with the size of the */
/* Fastmac Plus binary (sizeof_fmplus_array and recorded_size_fmplus_array) */
/* can  be  used  to  check  for corruption of the Fasmtac image array. The */
/* checksum byte (fmplus_checksum) can also be used for this purpose.       */
/*                                                                          */

extern BYTE fmplus_image[];

extern char fmplus_version[];

extern char fmplus_copyright_msg[];

extern WORD ftk_version_for_fmplus;

extern WORD sizeof_fmplus_array;

extern WORD recorded_size_fmplus_array;

extern BYTE fmplus_checksum;

#else

/****************************************************************************/
/*                                                                          */
/* Variables : Fastmac download image                                       */
/*                                                                          */
/* The following variables are exported by  FASTMAC.C  which  contains  the */
/* binary image for Fastmac in a 'C' format  BYTE  array.  These  variables */
/* will  be  needed  by  a  user  of  the  FTK in order to download Fastmac */
/* (fastmac_image),  display  the  Fastmac  version  number  and  copyright */
/* message  (fastmac_version  and fastmac_copyright_msg) and check that the */
/* FTK    version    number     is     that     required     by     Fastmac */
/* (ftk_version_for_fastmac).  The variables concerned with the size of the */
/* Fastmac binary  (sizeof_fastmac_array  and  recorded_size_fastmac_array) */
/* can  be  used  to  check  for corruption of the Fasmtac image array. The */
/* checksum byte (fastmac_checksum) can also be used for this purpose.      */
/*                                                                          */

extern BYTE fastmac_image[];

extern WORD fastmac_version;

extern char fastmac_copyright_msg[];

extern WORD ftk_version_for_fastmac;

extern WORD sizeof_fastmac_array;

extern WORD recorded_size_fastmac_array;

extern BYTE fastmac_checksum;

#endif

/****************************************************************************/
/*                                                                          */
/* Values : Pointers                                                        */
/*                                                                          */
/* For a near pointer, (one that points to a location in DGROUP), the value */
/* NULL  (must equal 0) is used to specify that it is yet to be assigned or */
/* an attempt to assign to it was unsuccessful.  For example, an attempt to */
/* allocate memory via a system specific call to which a near pointer is to */
/* point, eg. sys_alloc_init_block, should  return  NULL  if  unsuccessful. */
/* Similarly,  when  a  DWORD  is  used  as  a pointer to a 32 bit physical */
/* address pointer, the value NULL_PHYSADDR (must equal 0L)  is  used.   It */
/* should be returned by sys_alloc fastmac buffer routines if unsuccessful. */
/*                                                                          */

#if !defined(NULL)
#define NULL                    0
#endif

#define NULL_PHYSADDR           0L


/****************************************************************************/
/*                                                                          */
/* Type : ADAPTER_HANDLE                                                    */
/*                                                                          */
/* An element of this type is returned by driver_prepare_adapter  in  order */
/* to  identify a particular adapter for all subsequent calls to the driver */
/* module of the FTK.                                                       */
/*                                                                          */

typedef WORD                    ADAPTER_HANDLE;


/****************************************************************************/
/*                                                                          */
/* Type : DOWNLOAD_IMAGE                                                    */
/*                                                                          */
/* A pointer  to  a  download  image  must  be  supplied  by  the  user  to */
/* driver_prepare_adapter. This download image should be Fastmac.           */
/*                                                                          */

typedef BYTE                    DOWNLOAD_IMAGE;


/****************************************************************************/
/*                                                                          */
/* The following structures represent data strcutures on the adapter and    */
/* must be byte packed.                                                     */
/*                                                                          */

#pragma pack(1)


/****************************************************************************/
/*                                                                          */
/* Structure type : NODE_ADDRESS                                            */
/*                                                                          */
/* A node address may be supplied  by the user to driver_prepare_adapter or */
/* driver_open_adapter.  The  permanent  node  address  of  the  adapter is */
/* returned by driver_start_adapter. A node address is a 6 byte value.  For */
/* Madge adapters the bytes would be 0x00, 0x00, 0xF6, ... etc.             */
/*                                                                          */

struct STRUCT_NODE_ADDRESS
    {
    BYTE        byte[6];
    };


/****************************************************************************/
/*                                                                          */
/* Union type : MULTI_ADDRESS                                               */
/*                                                                          */
/* A   multicast   address   may   be   supplied    by    the    user    to */
/* driver_set_group_address    or    driver_set_functional_address.     The */
/* multicast address is the final 4 bytes of a 6  byte  node  address.  The */
/* first  2  bytes  are  determined  by  whether it is a group address or a */
/* functional address.                                                      */
/*                                                                          */

union UNION_MULTI_ADDRESS
    {
    DWORD       all;
    BYTE        byte[4];
    };


/****************************************************************************/
/*                                                                          */
/* Type : LONG_ADDRESS                                                      */
/*                                                                          */
/* A LONG_ADDRESS is a 64 bit address. Some architectures (e.g. Alpha) use  */
/* 64 bit physical addresses.                                               */
/*                                                                          */

union STRUCT_LONG_ADDRESS
    {
    BYTE  bytes[8];
    WORD  words[4];
    DWORD dwords[2];
    };

typedef union STRUCT_LONG_ADDRESS LONG_ADDRESS;


/****************************************************************************/
/*                                                                          */
/* Structure type : TR_OPEN_DATA                                            */
/*                                                                          */
/* The TR_OPEN_DATA structure is used to pass  to  the  Open SRB and to the */
/* driver_start_adapter  functions  all  the  addressing details that could */
/* usefully set. This  is  especially  useful  for  restoring the card to a */
/* prior state after a reset.                                               */
/*                                                                          */

typedef struct STRUCT_TR_OPEN_DATA
    {
    WORD                                open_options;
    NODE_ADDRESS                        opening_node_address;
    ULONG                               group_address;
    ULONG                               functional_address;
    };


/****************************************************************************/
/*                                                                          */
/* Structure type : ERROR_LOG                                               */
/*                                                                          */
/* This  is   part   of   the   information   returned   by   a   call   to */
/* driver_get_adapter_status. The error log contains the information from a */
/* READ_ERROR_LOG  SRB  call. All the MAC level error counters are reset to */
/* zero after they are read.                                                */
/*                                                                          */
/* REFERENCE : The TMS 380 Second-Generation Token_Ring User's Guide        */
/*             by Texas Instruments                                         */
/*             4-112 MAC 000A READ.ERROR.LOG Command                        */
/*                                                                          */

struct STRUCT_ERROR_LOG
    {
    BYTE        line_errors;
    BYTE        reserved_1;
    BYTE        burst_errors;
    BYTE        ari_fci_errors;
    BYTE        reserved_2;
    BYTE        reserved_3;
    BYTE        lost_frame_errors;
    BYTE        congestion_errors;
    BYTE        frame_copied_errors;
    BYTE        reserved_4;
    BYTE        token_errors;
    BYTE        reserved_5;
    BYTE        dma_bus_errors;
    BYTE        dma_parity_errors;
    };


/****************************************************************************/
/*                                                                          */
/* Structure type : STATUS_INFORMATION                                      */
/*                                                                          */
/* The status information returned by a call  to  driver_get_status         */
/* includes  whether the adapter is currently open, the current ring status */
/* and the MAC level error log information.                                 */
/*                                                                          */

struct STRUCT_STATUS_INFORMATION
    {
    WBOOLEAN            adapter_open;
    WORD                ring_status;
    ERROR_LOG           error_log;
    };


/****************************************************************************/
/*                                                                          */
/* Values : STATUS_INFORMATION - WORD ring_status                           */
/*                                                                          */
/* These are the  possible  ring  status  values  returned  by  a  call  to */
/* driver_get_adapter_status.                                               */
/*                                                                          */
/* REFERENCE : The TMS 380 Second-Generation Token_Ring User's Guide        */
/*             by Texas Instruments                                         */
/*             4-61 4.12.2 RING.STATUS                                      */
/*                                                                          */

#define RING_STATUS_SIGNAL_LOSS         0x8000
#define RING_STATUS_HARD_ERROR          0x4000
#define RING_STATUS_SOFT_ERROR          0x2000
#define RING_STATUS_TRANSMIT_BEACON     0x1000
#define RING_STATUS_LOBE_FAULT          0x0800
#define RING_STATUS_AUTO_REMOVAL        0x0400
#define RING_STATUS_REMOVE_RECEIVED     0x0100
#define RING_STATUS_COUNTER_OVERFLOW    0x0080
#define RING_STATUS_SINGLE_STATION      0x0040
#define RING_STATUS_RING_RECOVERY       0x0020


/****************************************************************************/
/*                                                                          */
/* Values : WORD open_options                                               */
/*                                                                          */
/* The     open_options    parameter    to    driver_prepare_adapter    and */
/* driver_open_adapter has the following bit fields defined.                */
/*                                                                          */
/* WARNING : The FORCE_OPEN option is a special Fastmac  option  that  will */
/* open  an  adapter  onto any ring - even if the adapter and ring speed do */
/* not match! Use it with caution.                                          */
/*                                                                          */
/* REFERENCE : The Madge Fastmac Interface Specification                    */
/*             - SRB Interface : Open Adapter SRB                           */
/*                                                                          */
/* REFERENCE : The TMS 380 Second-Generation Token_Ring User's Guide        */
/*             by Texas Instruments                                         */
/*             4-71 MAC 0003 OPEN command                                   */
/*                                                                          */

#define OPEN_OPT_WRAP_INTERFACE                 0x8000
#define OPEN_OPT_DISABLE_SOFT_ERROR             0x4000
#define OPEN_OPT_DISABLE_HARD_ERROR             0x2000
#define OPEN_OPT_PASS_ADAPTER_MACS              0x1000
#define OPEN_OPT_PASS_ATTENTION_MACS            0x0800
#define OPEN_OPT_FORCE_OPEN                     0x0400      /* Fastmac only */
#define OPEN_OPT_CONTENDER                      0x0100
#define OPEN_OPT_PASS_BEACON_MACS               0x0080
#define OPEN_OPT_EARLY_TOKEN_RELEASE            0x0010
#define OPEN_OPT_COPY_ALL_MACS                  0x0004
#define OPEN_OPT_COPY_ALL_LLCS                  0x0002


/****************************************************************************/
/*                                                                          */
/* Values : WORD adapter_card_bus_type                                      */
/*                                                                          */
/* The  following  adapter  card bus types are defined and can be passed to */
/* driver_start_adapter.  Different  adapter  card  bus  types   apply   to */
/* different adapter cards :                                                */
/*                                                                          */
/* ADAPTER_CARD_ISA_BUS_TYPE    16/4 PC or 16/4 AT                          */
/* ADAPTER_CARD_MC_BUS_TYPE     16/4 MC or 16/4 MC 32                       */
/* ADAPTER_CARD_EISA_BUS_TYPE   16/4 EISA mk1 or mk2                        */
/*                                                                          */

#define ADAPTER_CARD_ATULA_BUS_TYPE                 1
#define ADAPTER_CARD_MC_BUS_TYPE                    2
#define ADAPTER_CARD_EISA_BUS_TYPE                  3
#define ADAPTER_CARD_PCI_BUS_TYPE                   4
#define ADAPTER_CARD_SMART16_BUS_TYPE               5
#define ADAPTER_CARD_PCMCIA_BUS_TYPE                6
#define ADAPTER_CARD_PNP_BUS_TYPE                   7
#define ADAPTER_CARD_TI_PCI_BUS_TYPE                8
#define ADAPTER_CARD_PCI2_BUS_TYPE                  9


/****************************************************************************/
/*                                                                          */
/* Values : WORD transfer_mode, WORD interrupt_number                       */
/*                                                                          */
/* If  POLLING_INTERRUPTS_MODE  is  given  as  the  interrupt   number   to */
/* driver_start_adapter, then polling is assumed to be used.                */
/*                                                                          */
/* NOTE  :  If  using  the DOS example system specific code, then note that */
/* PIO_DATA_TRANSFER_MODE is defined in SYS_IRQ.ASM and  SYS_DMA.ASM        */
/* resepctively.  The  value used here must be, and is, identical.          */
/*                                                                          */

#define PIO_DATA_TRANSFER_MODE          0
#define DMA_DATA_TRANSFER_MODE          1
#define MMIO_DATA_TRANSFER_MODE         2
#define POLLING_INTERRUPTS_MODE         0


/****************************************************************************/
/*                                                                          */
/* Values : Returned from driver_transmit_frame (or some such)              */
/*                                                                          */
/* The value returned by driver_transmit_frame  indicates  how far the code */
/* got with transmitting  the  frame.  FAIL  and  SUCCEED are obvious, WAIT */
/* means  that  the caller should not assume the frame has been transmitted */
/* until some later indication.                                             */
/*                                                                          */

#define DRIVER_TRANSMIT_FAIL 0
#define DRIVER_TRANSMIT_WAIT 1
#define DRIVER_TRANSMIT_SUCCEED 2


/****************************************************************************/
/*                                                                          */
/* Values : Returned from user_receive_frame                                */
/*                                                                          */
/* The value returned by a call to the user_receive_frame routine indicates */
/* whether  the  user wishes to keep the frame in the Fastmac buffer or has */
/* dealt with it (decided it can be thrown away or copied it elsewhere). In */
/* the latter case the frame  can  be  removed  from  the  Fastmac  receive */
/* buffer.                                                                  */
/*                                                                          */

#define DO_NOT_KEEP_FRAME       0
#define KEEP_FRAME              1


/****************************************************************************/
/*                                                                          */
/* Type : card_t                                                            */
/*                                                                          */
/* To support large model compilation,   certain type casts have to be made */
/* to evade compilation errors. The card_t type is used to convert pointers */
/* to  structures  on  the adapter card into unsigned integers so that they */
/* can be truncated to 16 bits without warnings.                            */
/*                                                                          */
/*                                                                          */

typedef DWORD card_t;


/****************************************************************************/
/*                                                                          */
/* The following structures do not need to be byte packed.                  */
/*                                                                          */

#pragma pack()


/****************************************************************************/
/*                                                                          */
/* Values : PROBE_FAILURE                                                   */
/*                                                                          */
/* This value is returned by the driver_probe_adapter function if an error  */
/* occurs.                                                                  */
/*                                                                          */

#define PROBE_FAILURE           0xffff


/****************************************************************************/
/*                                                                          */
/* Values : FTK_UNDEFINED                                                   */
/*                                                                          */
/* This value means that a value is not defined or not used.                */
/*                                                                          */

#define FTK_UNDEFINED           0xeeff


/****************************************************************************/
/*                                                                          */
/* Structure type : PROBE                                                   */
/*                                                                          */
/* The probe structure can be filled in with card details by a call to      */
/* driver_probe_adapter. This is the way the user of the FTK should obtain  */
/* hardware resource information (DMA channel, IRQ number etc) about an     */
/* adapter before calling driver_prepare_adapter and driver_start_adapter.  */
/*                                                                          */

struct STRUCT_PROBE
{
    WORD                   socket;
    UINT                   adapter_card_bus_type;
    UINT                   adapter_card_type;
    UINT                   adapter_card_revision;
    UINT                   adapter_ram_size; 
    WORD                   io_location;
    WORD                   interrupt_number;
    WORD                   dma_channel; 
    UINT                   transfer_mode;
    DWORD                  mmio_base_address;
    DWORD                  pci_handle;
}; 


/****************************************************************************/
/*                                                                          */
/* Types : PREPARE_ARGS                                                     */
/*                                                                          */
/* The driver_prepare_adapter function takes a collection of arguments. An  */
/* instance of this structure is used to pass the arguments.                */ 
/*                                                                          */

typedef struct STRUCT_PREPARE_ARGS
{
    /* User's private information, not interpreted by the FTK. */

    void           * user_information;
                        
#ifdef FMPLUS

    /* Number of FastMAC Plus receive and transmit slots. */

    WORD             number_of_rx_slots;
    WORD             number_of_tx_slots;

#else

    /* Size of the FastMAC receive and transmit buffers. */

    WORD             receive_buffer_byte_size;
    WORD             transmit_buffer_byte_size;

#endif

    /* Requested maximum frame size. */

    WORD             max_frame_size;

}; 


/****************************************************************************/
/*                                                                          */
/* Types : START_ARGS                                                       */
/*                                                                          */
/* The driver_start_adapter function takes a collection of arguments. An    */
/* instance of this structure is used to pass the arguments. Note that some */ 
/* of the structure fields are filled in on return from                     */
/* driver_start_adapter.                                                    */
/*                                                                          */

typedef struct STRUCT_START_ARGS
{
    /* Adapter family. */

    UINT             adapter_card_bus_type;

    /* Hardware resource details. */

#ifdef PCMCIA_POINT_ENABLE
    UINT             socket;
#endif
    WORD             io_location;
    WORD             dma_channel;
    UINT             transfer_mode; 
    WORD             interrupt_number;

    /* Override DMA/IRQ values on soft programmable adapters? */

    WBOOLEAN         set_dma_channel;
    WBOOLEAN         set_interrupt_number;

    /* Force ring speed to this if possible. 4, 16 or 0 for default. */

    UINT             set_ring_speed;

    /* Base Address for MMIO */

    DWORD            mmio_base_address;

    /*
     * Used for the Ti PCI ASIC which in hwi_install needs to access PCI
     * Config space.
     */

    DWORD            pci_handle;

    /* Actual maximum frame size. Set on return. */

    WORD             max_frame_size;

    /* Auto open the adapter? */

    WBOOLEAN         auto_open_option;

    /* Open options and addresses for auto open mode. If 
       opening_node_address == 000000000000 the the BIA address 
       is used. */

    WORD             open_options;

    NODE_ADDRESS     opening_node_address;
    ULONG            opening_group_address;
    ULONG            opening_functional_address;

    /* Pointer to the adapter download image. */

    DOWNLOAD_IMAGE * code;

    /* The open status of the adapter on return. */

    UINT             open_status;

#ifdef FMPLUS

    /* Size of the RX/TX buffers on the adapter. */

    WORD             rx_tx_buffer_size;

#endif

};


/*                                                                          */
/*                                                                          */
/************** End of FTK_USER.H file **************************************/
/*                                                                          */
/*                                                                          */