1 SBUS(4) File Formats and Configurations SBUS(4) 2 3 4 5 NAME 6 sbus - configuration files for SBus device drivers 7 8 DESCRIPTION 9 The SBus is a geographically addressed peripheral bus present on many 10 SPARC hardware platforms. SBus devices are self-identifying -- that is 11 to say the SBus card itself provides information to the system so that 12 it can identify the device driver that needs to be used. The device 13 usually provides additional information to the system in the form of 14 name-value pairs that can be retrieved using the DDI property 15 interfaces. See ddi_prop_op(9F) for details. 16 17 18 The information is usually derived from a small Forth program stored in 19 the FCode PROM on the card, so driver configuration files should be 20 completely unnecessary for these devices. However, on some occasions, 21 drivers for SBus devices may need to use driver configuration files to 22 augment the information provided by the SBus card. See driver.conf(4) 23 for further details. 24 25 26 When they are needed, configuration files for SBus device drivers 27 should identify the parent bus driver implicitly using the class 28 keyword. This removes the dependency on the particular bus driver 29 involved since this may be named differently on different platforms. 30 31 32 All bus drivers of class sbus recognise the following properties: 33 34 reg 35 An arbitrary length array where each element of the array 36 consists of a 3-tuple of integers. Each array element 37 describes a logically contiguous mappable resource on the 38 SBus. 39 40 The first integer of each tuple specifies the slot number 41 the card is plugged into. The second integer of each 42 3-tuple specifies the offset in the slot address space 43 identified by the first element. The third integer of 44 each 3-tuple specifies the size in bytes of the mappable 45 resource. 46 47 The driver can refer to the elements of this array by 48 index, and construct kernel mappings to these addresses 49 using ddi_map_regs(9F). The index into the array is 50 passed as the rnumber argument of ddi_map_regs(). 51 52 You can use the ddi_get* and ddi_put* family of functions 53 to access register space from a high-level interrupt 54 context. 55 56 57 interrupts 58 An arbitrary length array where each element of the array 59 consists of a single integer. Each array element 60 describes a possible SBus interrupt level that the device 61 might generate. 62 63 The driver can refer to the elements of this array by 64 index, and register interrupt handlers with the system 65 using ddi_add_intr(9F). The index into the array is 66 passed as the inumber argument of ddi_add_intr(). 67 68 69 registers 70 An arbitrary length array where each element of the array 71 consists of a 3-tuple of integers. Each array element 72 describes a logically contiguous mappable resource on the 73 SBus. 74 75 The first integer of each tuple should be set to -1, 76 specifying that any SBus slot may be matched. The second 77 integer of each 3-tuple specifies the offset in the slot 78 address space identified by the first element. The third 79 integer of each 3-tuple specifies the size in bytes of 80 the mappable resource. 81 82 The registers property can only be used to augment an 83 incompletely specified reg property with information from 84 a driver configuration file. It may only be specified in 85 a driver configuration file. 86 87 88 89 All SBus devices must provide reg properties to the system. The first 90 two integer elements of the reg property are used to construct the 91 address part of the device name under /devices. 92 93 94 Only devices that generate interrupts need to provide interrupts 95 properties. 96 97 98 Occasionally, it may be necessary to override or augment the 99 configuration information supplied by the SBus device. This can be 100 achieved by writing a driver configuration file that describes a 101 prototype device information (devinfo) node specification, containing 102 the additional properties required. 103 104 105 For the system to merge the information, certain conditions must be 106 met. First, the name property must be the same. Second, either the 107 first two integers (slot number and offset) of the two reg properties 108 must be the same, or the second integer (offset) of the reg and 109 registers properties must be the same. 110 111 112 In the event that the SBus card has no reg property at all, the self- 113 identifying information cannot be used, so all the details of the card 114 must be specified in a driver configuration file. 115 116 EXAMPLES 117 Example 1 A sample configuration file. 118 119 120 Here is a configuration file for an SBus card called SUNW,netboard. 121 The card already has a simple FCode PROM that creates name and reg 122 properties, and will have a complete set of properties for normal use 123 once the driver and firmware is complete. 124 125 126 127 In this example, we want to augment the properties given to us by the 128 firmware. We use the same name property, and use the registers 129 property to match the firmware reg property. That way we don't have to 130 worry about which slot the card is really plugged into. 131 132 133 134 We want to add an interrupts property while we are developing the 135 firmware and driver so that we can start to experiment with interrupts. 136 The device can generate interrupts at SBus level 3. Additionally, we 137 want to set a debug-level property to 4. 138 139 140 # 141 # Copyright (c) 1992, by Sun Microsystems, Inc. 142 #ident "@(#)SUNW,netboard.conf 1.4 92/03/10 SMI" 143 # 144 name="SUNW,netboard" class="sbus" 145 registers=-1,0x40000,64,-1,0x80000,1024 146 interrupts=3 debug-level=4; 147 148 149 150 ATTRIBUTES 151 See attributes(5) for descriptions of the following attributes: 152 153 154 155 156 +---------------+-----------------+ 157 |ATTRIBUTE TYPE | ATTRIBUTE VALUE | 158 +---------------+-----------------+ 159 |Architecture | SPARC | 160 +---------------+-----------------+ 161 162 SEE ALSO 163 driver.conf(4), attributes(5), ddi_add_intr(9F), ddi_map_regs(9F), 164 ddi_prop_op(9F) 165 166 167 Writing Device Drivers 168 169 WARNINGS 170 The wildcarding mechanism of the registers property matches every 171 instance of the particular device attached to the system. This may not 172 always be what is wanted. 173 174 175 176 December 31, 1996 SBUS(4)