1 '\" te
   2 .\" Copyright (c) 1999, Sun Microsystems, Inc.
   3 .\" All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH SBUS 4 "Dec 31, 1996"
   8 .SH NAME
   9 sbus \- configuration files for SBus device drivers
  10 .SH DESCRIPTION
  11 .sp
  12 .LP
  13 The \fBSBus\fR is a geographically addressed peripheral bus present on many
  14 \fBSPARC\fR hardware platforms. \fBSBus\fR devices are \fIself-identifying\fR
  15 \(em that is to say the \fBSBus\fR card itself provides information to the
  16 system so that it can identify the device driver that needs to be used. The
  17 device usually provides additional information to the system in the form of
  18 name-value pairs that can be retrieved using the \fBDDI\fR property interfaces.
  19 See \fBddi_prop_op\fR(9F) for details.
  20 .sp
  21 .LP
  22 The information is usually derived from a small Forth program stored in the
  23 \fBFCode\fR \fBPROM\fR on the card, so driver configuration files should be
  24 completely unnecessary for these devices. However, on some occasions, drivers
  25 for \fBSBus\fR devices may need to use driver configuration files to augment
  26 the information provided by the \fBSBus\fR card. See \fBdriver.conf\fR(4) for
  27 further details.
  28 .sp
  29 .LP
  30 When they are needed, configuration files for \fBSBus\fR device drivers should
  31 identify the parent bus driver implicitly using the \fIclass\fR keyword.  This
  32 removes the dependency on the particular bus driver involved since this may be
  33 named differently on different platforms.
  34 .sp
  35 .LP
  36 All bus drivers of class \fBsbus\fR recognise the following properties:
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fBreg\fR\fR
  41 .ad
  42 .RS 14n
  43 An arbitrary length array where each element of the array consists of a 3-tuple
  44 of integers.  Each array element describes a logically contiguous mappable
  45 resource on the \fBSBus.\fR
  46 .sp
  47 The first integer of each tuple specifies the slot number the card is plugged
  48 into. The second integer of each 3-tuple specifies the offset in the slot
  49 address space identified by the first element. The third integer of each
  50 3-tuple specifies the size in bytes of the mappable resource.
  51 .sp
  52 The driver can refer to the elements of this array by index, and construct
  53 kernel mappings to these addresses using \fBddi_map_regs\fR(9F). The index into
  54 the array is passed as the \fIrnumber\fR argument of \fBddi_map_regs()\fR.
  55 .sp
  56 You can use the \fBddi_get*\fR and \fBddi_put*\fR family of functions to access
  57 register space from a high-level interrupt context.
  58 .RE
  59 
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fBinterrupts\fR\fR
  64 .ad
  65 .RS 14n
  66 An arbitrary length array where each element of the array consists of a single
  67 integer. Each array element describes a possible \fBSBus\fR interrupt level
  68 that the device might generate.
  69 .sp
  70 The driver can refer to the elements of this array by index, and register
  71 interrupt handlers with the system using \fBddi_add_intr\fR(9F). The index into
  72 the array is passed as the \fIinumber\fR argument of \fBddi_add_intr()\fR.
  73 .RE
  74 
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBregisters\fR\fR
  79 .ad
  80 .RS 14n
  81 An arbitrary length array where each element of the array consists of a 3-tuple
  82 of integers.  Each array element describes a logically contiguous mappable
  83 resource on the \fBSBus.\fR
  84 .sp
  85 The first integer of each tuple should be set to \fB\(mi1\fR, specifying that
  86 any SBus slot may be matched. The second integer of each 3-tuple specifies the
  87 offset in the slot address space identified by the first element.  The third
  88 integer of each 3-tuple specifies the size in bytes of the mappable resoure.
  89 .sp
  90 The \fBregisters\fR property can only be used to augment an incompletely
  91 specified \fBreg\fR property with information from a driver configuration file.
  92 It may only be specified in a driver configuration file.
  93 .RE
  94 
  95 .sp
  96 .LP
  97 All \fBSBus\fR devices must provide \fBreg\fR properties to the system. The
  98 first two integer elements of the \fBreg\fR property are used to construct the
  99 address part of the device name under \fB/devices\fR.
 100 .sp
 101 .LP
 102 Only devices that generate interrupts need to provide \fBinterrupts\fR
 103 properties.
 104 .sp
 105 .LP
 106 Occasionally, it may be necessary to override or augment the configuration
 107 information supplied by the \fBSBus\fR device. This can be achieved by writing
 108 a driver configuration file that describes a prototype device information
 109 (devinfo) node specification, containing the additional properties required.
 110 .sp
 111 .LP
 112 For the system to merge the information, certain conditions must be met. First,
 113 the \fBname\fR property must be the same. Second, either the first two integers
 114 (slot number and offset) of the two \fBreg\fR properties must be the same, or
 115 the second integer (offset) of the \fBreg\fR and \fBregisters\fR properties
 116 must be the same.
 117 .sp
 118 .LP
 119 In the event that the \fBSBus\fR card has no \fBreg\fR property at all, the
 120 self-identifying information cannot be used, so all the details of the card
 121 must be specified in a driver configuration file.
 122 .SH EXAMPLES
 123 .LP
 124 \fBExample 1 \fRA sample configuration file.
 125 .sp
 126 .LP
 127 Here is a configuration file for an \fBSBus\fR card called \fBSUNW,netboard\fR.
 128 The card already has a simple \fBFCode\fR \fBPROM\fR that creates \fBname\fR
 129 and \fBreg\fR properties, and will have a complete set of properties for normal
 130 use once the driver and firmware is complete.
 131 
 132 .sp
 133 .LP
 134 In this example, we want to augment the properties given to us by the firmware.
 135 We use the same \fBname\fR property, and use the \fBregisters\fR property to
 136 match the firmware \fBreg\fR property. That way we don't have to worry about
 137 which slot the card is really plugged into.
 138 
 139 .sp
 140 .LP
 141 We want to add an \fBinterrupts\fR property while we are developing the
 142 firmware and driver so that we can start to experiment with interrupts. The
 143 device can generate interrupts at \fBSBus\fR level 3. Additionally, we want to
 144 set a \fBdebug-level\fR property to 4.
 145 
 146 .sp
 147 .in +2
 148 .nf
 149 #
 150 # Copyright (c) 1992, by Sun Microsystems, Inc.
 151 #ident  "@(#)SUNW,netboard.conf         1.4     92/03/10 SMI"
 152 #
 153 name="SUNW,netboard" class="sbus"
 154         registers=-1,0x40000,64,-1,0x80000,1024
 155         interrupts=3 debug-level=4;
 156 .fi
 157 .in -2
 158 .sp
 159 
 160 .SH ATTRIBUTES
 161 .sp
 162 .LP
 163 See \fBattributes\fR(5) for descriptions of the following attributes:
 164 .sp
 165 
 166 .sp
 167 .TS
 168 box;
 169 c | c
 170 l | l .
 171 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 172 _
 173 Architecture    SPARC
 174 .TE
 175 
 176 .SH SEE ALSO
 177 .sp
 178 .LP
 179 \fBdriver.conf\fR(4), \fBattributes\fR(5), \fBddi_add_intr\fR(9F),
 180 \fBddi_map_regs\fR(9F), \fBddi_prop_op\fR(9F)
 181 .sp
 182 .LP
 183 \fIWriting Device Drivers\fR
 184 .SH WARNINGS
 185 .sp
 186 .LP
 187 The wildcarding mechanism of the \fBregisters\fR property matches every
 188 instance of the particular device attached to the system. This may not always
 189 be what is wanted.