home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilss / sockets / include / h / xcb < prev   
Encoding:
Text File  |  1995-01-11  |  14.7 KB  |  364 lines
  1. /*
  2.  * $Header: /ax/networking:include/xcb.h:networking  1.1  $
  3.  * $Source: /ax/networking:include/xcb.h: $
  4.  *
  5.  * Copyright (c) 1989 Acorn Computers Ltd., Cambridge, England
  6.  *
  7.  * $Log:    xcb.h,v $
  8.  * Revision 1.1  95/01/11  10:21:43  kwelton
  9.  * Initial revision
  10.  * 
  11.  * Revision 1.1  89/04/28  14:57:01  mark
  12.  * Initial revision
  13.  * 
  14.  */
  15. /* xcb.h
  16.  *
  17.  * Definitions for expansion card bus (XCB, formerly known
  18.  * as "podule") device access.
  19.  */
  20. #ifndef  _XCB_
  21. #define  _XCB_
  22.  
  23. typedef struct
  24. {
  25.     unsigned char id0,          _pad0[3];
  26.     unsigned char flags,        _pad1[3];
  27.     unsigned char unused,       _pad2[3];
  28.     unsigned char product_lo,   _pad3[3];
  29.     unsigned char product_hi,   _pad4[3];
  30.     unsigned char company_lo,   _pad5[3];
  31.     unsigned char company_hi,   _pad6[3];
  32.     unsigned char country,      _pad7[3];
  33.     union
  34.     {
  35.         char            d_char[4];
  36.         unsigned char   d_uchar[4];
  37.         short           d_short[2];
  38.         unsigned short  d_ushort[2];
  39.         int             d_int;
  40.         unsigned int    d_uint;
  41.     } data[1024-8];
  42. } XCBID, *XCBIDRef;
  43. /* bits in c_id0 field: */
  44. #define XCB_ID0_IRQ             (1 << 0)        /* set if IRQ outstanding */
  45. #define XCB_ID0_NOT_PRESENT     (1 << 1)        /* pull-up gives 1 if slot empty */
  46. #define XCB_ID0_FIQ             (1 << 2)        /* set if FIQ outstanding */
  47. #define XCB_ID0_EXTRA           (0xF8)          /* remaining 5 bits should be 0 */
  48.  
  49.  
  50. /* expansion card source country codes */
  51.  
  52. #define XCB_COUNTRY_UK  0
  53. #define XCB_COUNTRY_ITALY       4
  54. #define XCB_COUNTRY_SPAIN       5
  55. #define XCB_COUNTRY_FRANCE      6
  56. #define XCB_COUNTRY_GERMANY     7
  57. #define XCB_COUNTRY_PORTUGAL    8
  58. #define XCB_COUNTRY_GREECE      10
  59. #define XCB_COUNTRY_SWEDEN      11
  60. #define XCB_COUNTRY_FINLAND     12
  61. #define XCB_COUNTRY_DENMARK     14
  62. #define XCB_COUNTRY_NORWAY      15
  63. #define XCB_COUNTRY_ICELAND     16
  64. #define XCB_COUNTRY_CANADA      17
  65. #define XCB_COUNTRY_TURKEY      20
  66.  
  67. /* expansion card manufacturing company codes */
  68.  
  69. #define XCB_COMPANY_ACORNUK                     0
  70. #define XCB_COMPANY_ACORNUSA                    1
  71. #define XCB_COMPANY_OLIVETTI                    2
  72. #define XCB_COMPANY_WATFORD                     3
  73. #define XCB_COMPANY_COMPUTERCONCEPTS            4
  74. #define XCB_COMPANY_INTELIGENTINTERFACES        5
  75. #define XCB_COMPANY_CAMAN                       6
  76. #define XCB_COMPANY_ARMADILLO                   7
  77. #define XCB_COMPANY_SOFTOPTION                  8
  78. #define XCB_COMPANY_WILDVISION                  9
  79. #define XCB_COMPANY_ANGLOCOMPUTERS              10
  80. #define XCB_COMPANY_RESOURCE                    11
  81.  
  82. /* expansion card product type codes */
  83. #define XCB_PRODUCT_HOSTTUBE                    0 /* To a BBC */
  84. #define XCB_PRODUCT_PARASITETUBE                1 /* To a second processor */
  85. #define XCB_PRODUCT_SCSI                        2
  86. #define XCB_PRODUCT_ETHERNET                    3
  87. #define XCB_PRODUCT_IBMDISC                     4
  88. #define XCB_PRODUCT_RAMROM                      5
  89. #define XCB_PRODUCT_BBCIO                       6
  90. #define XCB_PRODUCT_MODEM                       7
  91. #define XCB_PRODUCT_TELETEXT                    8
  92. #define XCB_PRODUCT_CDROM                       9
  93. #define XCB_PRODUCT_IEEE488                     10
  94. #define XCB_PRODUCT_WINCHESTER                  11
  95. #define XCB_PRODUCT_ESDI                        12
  96. #define XCB_PRODUCT_SMD                         13
  97. #define XCB_PRODUCT_LASERPRINTER                14
  98. #define XCB_PRODUCT_SCANNER                     15
  99. #define XCB_PRODUCT_FASTRING                    16
  100. #define XCB_PRODUCT_VMEBUS                      17
  101. #define XCB_PRODUCT_PROMPROGRAMMER              18
  102. #define XCB_PRODUCT_MIDI                        19
  103. #define XCB_PRODUCT_MONOVPU                     20
  104. #define XCB_PRODUCT_FRAMEGRABBER                21
  105. #define XCB_PRODUCT_SOUNDSAMPLER                22
  106. #define XCB_PRODUCT_VIDEODIGITISER              23
  107. #define XCB_PRODUCT_GENLOCK                     24
  108. #define XCB_PRODUCT_CODECSAMPLER                25
  109. #define XCB_PRODUCT_IMAGEANALYSER               26
  110. #define XCB_PRODUCT_ANALOGUEINPUT               27
  111. #define XCB_PRODUCT_CDSOUNDSAMPLER              28
  112. #define XCB_PRODUCT_6MIPSSIGPROC                29
  113. #define XCB_PRODUCT_12MIPSSIGPROC               30
  114. #define XCB_PRODUCT_33MIPSSIGPROC               31
  115. #define XCB_PRODUCT_TOUCHSCREEN                 32
  116. #define XCB_PRODUCT_TRANSPUTERLINK              33
  117.  
  118. /* Hardware addressing (via IOC) */
  119.  
  120. #define XCB_SPEED_SLOW          0
  121. #define XCB_SPEED_MEDIUM        1
  122. #define XCB_SPEED_FAST          2
  123. #define XCB_SPEED_SYNC          3               /* slowest of all...(!) */              
  124. #define SLOW   0
  125. #define MEDIUM 1
  126. #define FAST   2
  127. #define SYNC   3
  128. #define XCB_SPEED(speed) (speed)
  129.  
  130. #define XCB_SLOT_OFF(slot)      ((slot) << 14)
  131. #define XCB_ADDRESS(speed, slot) \
  132.         (0x03240000 + (XCB_SPEED(speed) << 19) + \
  133.          XCB_SLOT_OFF(slot))
  134.  
  135. #define XCB_IDx(speed, slot) ((XCBIDRef)(XCB_ADDRESS (speed, slot)))
  136. #define XCB_ID(slot)         XCB_IDx (SYNC, slot)       /* recommended speed */
  137.  
  138.  
  139. /* XCB manager interface details */
  140.  
  141. #define XCB_SLOTS       4
  142. #define XCB_MAX_ETHERNET_CARDS 2
  143.  
  144.  
  145. /*
  146.  * The XCBInfo structure contains card-identification information, as 
  147.  * stored in ARM memory.  Each expansion card must also contain these
  148.  * codes, in a standard format and location, so that the XCB manager 
  149.  * can read the card ID and hence match cards to drivers.
  150.  */
  151. typedef struct xcb_info
  152. {
  153.     unsigned short product, company;
  154.     unsigned char  country;
  155. } XCBInfo, *XCBInfoRef;
  156.  
  157. #ifdef NOT_YET
  158. typedef struct xcb_io_mem
  159. {
  160.     struct xcb_io_mem  *next;                   /* in access-def list */
  161.     int flags;                                  /* b/w, r/w, speed, multi etc */
  162.     unsigned short offset, len;                 /* area loc/len in words  */
  163. } XCIOMem, *XCIOMemRef;
  164. /*
  165.  * Flags bits: 
  166.  *      0..1:   I/O cycle speed use XCB_SPEED_xxx 
  167.  *      2:      memc-space address (speed ignored)
  168.  *      3:      readable
  169.  *      4       writable
  170.  *      5:      byte-wide (0 => halfword-wide) access
  171.  *      6:      can use ldm/stm access as appropriate in this area
  172.  *      7:      is multi-mapped fifo register (requires bit 6 also)
  173.  */
  174. #define XCIO_SPEED__MASK        (3 << 0)        /*  */
  175. #endif 
  176.  
  177.     
  178. /*
  179.  * Expansion Card type record.  This is the means whereby an XCB
  180.  * device driver is linked with the XCB manager, in a fashion
  181.  * analogous to the normal cdevsw and bdevsw tables (note that most
  182.  * expansion card drivers will also have entries in one or both of
  183.  * those tables).  The file "xcbconf.c" in the kernel build directory
  184.  * contains a table, xcb_type[], of expansion card type structures,
  185.  * one for each supported card type; the count of entries is set in
  186.  * the external int nxcb_type.  Adding an XCB device driver requires
  187.  * the inclusion in xcb_type of an entry for the card type.  At boot
  188.  * time, the expansion card bus is scanned for expansion cards; the ID
  189.  * of each installed card is determined by reading the first few bytes
  190.  * of XCB ID space for the slot the card resides in.  Only those cards
  191.  * with IDs matching entries in xcb_type will be considered valid as
  192.  * far as RISC iX is concerned.  For all valid cards, a sequence of
  193.  * initialisation is then performed, as follows:
  194.  * 
  195.  *    {cpu priority level still at MAX_SPL}
  196.  *    for each valid card               {round 1}
  197.  *       if (card_type->init_high != NULL)
  198.  *           (*card_type->init_high) (card_slot);
  199.  *
  200.  *    {cpu priority reduced to 0, but xcb interrupts disabled}
  201.  *    for each valid card               {round 2}
  202.  *       if (card_type->init_low != NULL)
  203.  *           (*card_type->init_low) (card_slot, 0);
  204.  *    enable interrupts from expansion card bus
  205.  *    for each valid card               {round 3}
  206.  *       if (card_type->init_low != NULL)
  207.  *           (*card_type->init_low) (card_slot, 1);
  208.  * 
  209.  * The first round of calls is designed to allow a driver to bring its
  210.  * hardware to a stable, non-interrupting, initialised state, before the
  211.  * processor interrupt priority is dropped from its initial maximum
  212.  * and interrupts are allowed in.  The "init_high" function must not
  213.  * reduce the processor priority.
  214.  *
  215.  * The second round of calls, via the "init_low" field, permits
  216.  * further initialisation if required, with general interrupts
  217.  * enabled, but no interrupts from expansion cards (marked by the
  218.  * second parameter being 0).  The standard Ethernet card uses this
  219.  * call to perform a test routine during which each configured card is
  220.  * checked for correct functionality: if the card is OK then it is
  221.  * added to the driver's tables and an interrupt handler is declared
  222.  * for it using the function decl_xcb_interrupt().
  223.  *
  224.  * During either of the first two initialisation calls to a driver,
  225.  * the driver may call the function decl_xcb_interrupt(), to declare
  226.  * to the interrupt manager the existence of an interrupt handler for
  227.  * IRQs from a specific card.  At most one call may be made, for each
  228.  * slot in which a valid card has been found.  In the case that the
  229.  * hardware configuration does not include a full-spec backplane, as
  230.  * indicated by (xcb_regs == (XCBRegsRef)0), any call to this function
  231.  * (and to the function decl_xcb_irq_sense, for non-standard card
  232.  * interrupt indication) MUST happen at this time: an attempt to call
  233.  * it later will cause a panic.
  234.  *
  235.  * The third and last round of initialisation calls uses the same
  236.  * entry point as the second round, but with a second parameter of 1,
  237.  * marking the fact that by this point interrupts from expansion cards
  238.  * have been enabled, and all declared xcb interrupt handlers can
  239.  * potentially be called.  Again the processor priority level is 0.
  240.  * The Ethernet driver uses this call to perform final setup for each
  241.  * configured working Ethernet card, during which time the Ethernet
  242.  * interrupt handler is functioning normally.
  243.  *
  244.  * During the second and third calls, the driver may raise and lower
  245.  * priority as required, using the normal splnnn calls, but should
  246.  * return with the SPL restored to 0.
  247.  *
  248.  * The finally xcb driver entry point is used when the system reboot
  249.  * or halt mechanism is invoked (e.g. via the "reboot" or "halt"
  250.  * programs); the function specified in the shutdown field will be
  251.  * called, as follows:
  252.  *
  253.  *    {cpu priority at maximum}
  254.  *    foreach valid card:
  255.  *       if (card_type->shutdown != NULL)
  256.  *           (*card_type->shutdown) (card_slot);
  257.  *
  258.  * This function should arrange to close off any activity on the
  259.  * device and bring the card to a stable quiescent state such that
  260.  * when the kernel passes control to RISC OS, the card (a) will not
  261.  * generate any interrupts, and (b) is in a condition equivalent to
  262.  * the hardware reset state, such that the ID bytes used to identify
  263.  * the card are readable at the standard address.
  264.  *
  265.  * In all cases, the called function is passed the physical slot
  266.  * number of the expansion card as its first only parameter; from this
  267.  * the device address may be derived.  Multiple instances of the same
  268.  * card type on the bus will cause multiple calls on the function, one
  269.  * for each slot in which a card of the given type is found.
  270.  */
  271.  
  272. typedef struct xcb_type
  273. {
  274.     XCBInfo id;                                 /* ROM ID values */
  275.     int flags;                                  /* for various purposes */
  276. #ifdef NOTYET
  277.     XCIOMemRef io_mem;                          /* for user access */
  278. #endif 
  279.     void (*init_high) (/*int slot*/);           /* init function 1, max prio */
  280.     void (*init_low) (/*int slot*/);            /* init function 2, prio 0 */
  281.     void (*shutdown) (/*int slot*/);            /* reboot shutdown function */
  282. } XCBType, *XCBTypeRef;
  283.  
  284.  
  285. #ifdef KERNEL
  286. extern XCBType xcb_type[];
  287. extern int nxcb_type;
  288. #endif
  289.  
  290.  
  291.  
  292. #ifdef KERNEL
  293. /*
  294.  * decl_xcb_interrupt
  295.  *
  296.  * The parameters to decl_xcb_interrupt have the following meanings:
  297.  *
  298.  * slot:        0..(XCB_SLOTS-1) - the card's physical slot number.
  299.  * handler:     the address of a statically allocated interrupt handler
  300.  *              record.  The ih_fn field should be set to the address of
  301.  *              the interrupt handling function, and the ih_farg field 
  302.  *              should contain a value to be passed to this function on
  303.  *              interrupt; the ih_mask and ih_next fields must be left 
  304.  *              entirely alone by the driver.
  305.  * priority:    the interrupt level at which IRQs from the expansion card
  306.  *              should be serviced (i.e. a PRIO_xxxx value).  Normally,
  307.  *              interrupts from the slot will actually arrive at this spl;
  308.  *              however on those few systems configured without a proper
  309.  *              backplane but with multiple expansion cards running at 
  310.  *              different priorities, the lowest specified priority will
  311.  *              be used for the single hardware interrupt level, but the
  312.  *              handler function will be called with the spl level set to
  313.  *              the requested level.
  314.  *
  315.  * This requests that whenever an expansion card in the specified slot
  316.  * generates an IRQ, handler->ih_fn will be called, with argument
  317.  * handler->ih_farg, with spl set to priority.
  318.  */
  319.  
  320. extern void decl_xcb_interrupt (/* int slot, 
  321.                                    struct int_hndlr *handler,
  322.                                    int priority */);
  323. #endif 
  324.  
  325. /*
  326.  * Structure describing the way in which an interrupt from a non-
  327.  * standard expansion card may be detected by the XCB manager.  On
  328.  * systems with a proper backplane this mechanism is not used: the
  329.  * backplane registers give indication of individual XCB interrupts.
  330.  * On systems (regretably there still are a number) without a proper
  331.  * backplane, we need to cope with XCB devices where the "standard"
  332.  * IRQ flag is not used (ID byte 0, bit 0, positive logic).  Such
  333.  * devices include the winchester expansion card (which has a separate
  334.  * register) and early (pre-issue 1) ethernet cards, where the ID byte
  335.  * must be read at FAST speed as opposed to SYNC.  This mechanism
  336.  * assumes that an interrupting card may be identified by reading a
  337.  * flag word from a (slot-adjusted) address and testing it against a
  338.  * mask, the result indicating IRQ presence (!=0) or absence (==0).
  339.  */
  340. typedef struct xcb_irq_sense
  341. {
  342.     int *flag;          /* Note: slot address bits set by xcb manager */
  343.     int mask;
  344. } XCBIRQSense, *XCBIRQSenseRef;
  345.  
  346. #ifdef KERNEL
  347. /*
  348.  * decl_xcb_irq_sense need be called only for non-standard cards
  349.  * in systems where the full-spec backplane hardware is not fitted.
  350.  * This can be tested by checking the contents of the external
  351.  * variable xcb_regs (see xcbregs.h).  See the comment above about
  352.  * the meaning of the XCBIRQSense structure.  Note that the slot-
  353.  * specific part of the device address (bits 14,15) is controlled
  354.  * by the XCB manager, and should be left 0 in the flag field of
  355.  * the structure passed in.
  356.  */
  357. extern void decl_xcb_irq_sense (/*int slot, XCBIRQSenseRef sense*/);
  358. #endif 
  359.  
  360.  
  361. #endif 
  362.  
  363. /* EOF xcb.h */
  364.