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