| blob | ff48e71a97e20818e7eaf411d92fe408b4e04f7c |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH DDI_DEVICE_ACC_ATTR 9S "May 13, 2007"
7 .SH NAME
8 ddi_device_acc_attr \- data access attributes structure
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/ddi.h>
13 #include <sys/sunddi.h>
14 .fi
16 .SH INTERFACE LEVEL
17 .sp
18 .LP
19 Solaris DDI specific (Solaris DDI)
20 .SH DESCRIPTION
21 .sp
22 .LP
23 The \fBddi_device_acc_attr\fR structure describes the data access
24 characteristics and requirements of the device.
25 .SH STRUCTURE MEMBERS
26 .sp
27 .in +2
28 .nf
29 ushort_t devacc_attr_version;
30 uchar_t devacc_attr_endian_flags;
31 uchar_t devacc_attr_dataorder;
32 uchar_t devacc_attr_access;
33 .fi
34 .in -2
36 .sp
37 .LP
38 The \fBdevacc_attr_version\fR member identifies the version number of this
39 structure. The current version number is \fBDDI_DEVICE_ATTR_V0\fR.
40 .sp
41 .LP
42 The \fBdevacc_attr_endian_flags\fR member describes the endian characteristics
43 of the device. Specify one of the following values:
44 .sp
45 .ne 2
46 .na
47 \fB\fBDDI_NEVERSWAP_ACC\fR\fR
48 .ad
49 .RS 24n
50 Data access with no byte swapping
51 .RE
53 .sp
54 .ne 2
55 .na
56 \fB\fBDDI_STRUCTURE_BE_ACC\fR\fR
57 .ad
58 .RS 24n
59 Structural data access in big-endian format
60 .RE
62 .sp
63 .ne 2
64 .na
65 \fB\fBDDI_STRUCTURE_LE_ACC\fR\fR
66 .ad
67 .RS 24n
68 Structural data access in little endian format
69 .RE
71 .sp
72 .LP
73 \fBDDI_STRUCTURE_BE_ACC\fR and \fBDDI_STRUCTURE_LE_ACC\fR describe the endian
74 characteristics of the device as big-endian or little-endian, respectively.
75 Although most of the devices have the same endian characteristics as their
76 buses, examples of devices that have opposite endian characteristics of the
77 buses do exist. When \fBDDI_STRUCTURE_BE_ACC\fR or \fBDDI_STRUCTURE_LE_ACC\fR
78 is set, byte swapping is automatically performed by the system if the host
79 machine and the device data formats have opposite endian characteristics. The
80 implementation can take advantage of hardware platform byte swapping
81 capabilities.
82 .sp
83 .LP
84 When you specify \fBDDI_NEVERSWAP_ACC\fR, byte swapping is not invoked in the
85 data access functions.
86 .sp
87 .LP
88 The \fBdevacc_attr_dataorder\fR member describes the order in which the
89 \fBCPU\fR references data. Specify one of the following values.
90 .sp
91 .ne 2
92 .na
93 \fB\fBDDI_STRICTORDER_ACC\fR\fR
94 .ad
95 .RS 27n
96 Data references must be issued by a \fBCPU\fR in program order. Strict ordering
97 is the default behavior.
98 .RE
100 .sp
101 .ne 2
102 .na
103 \fB\fBDDI_UNORDERED_OK_ACC\fR\fR
104 .ad
105 .RS 27n
106 The \fBCPU\fR can reorder the data references. This includes all kinds of
107 reordering. For example, a load followed by a store might be replaced by a
108 store followed by a load.
109 .RE
111 .sp
112 .ne 2
113 .na
114 \fB\fBDDI_MERGING_OK_ACC\fR\fR
115 .ad
116 .RS 27n
117 The \fBCPU\fR can merge individual stores to consecutive locations. For
118 example, the \fBCPU\fR can turn two consecutive byte stores into one half-word
119 store. It can also batch individual loads. For example, the \fBCPU\fR might
120 turn two consecutive byte loads into one half-word load.
121 \fBDDI_MERGING_OK_ACC\fR also implies reordering.
122 .RE
124 .sp
125 .ne 2
126 .na
127 \fB\fBDDI_LOADCACHING_OK_ACC\fR\fR
128 .ad
129 .RS 27n
130 The \fBCPU\fR can cache the data it fetches and reuse it until another store
131 occurs. The default behavior is to fetch new data on every load.
132 \fBDDI_LOADCACHING_OK_ACC\fR also implies merging and reordering.
133 .RE
135 .sp
136 .ne 2
137 .na
138 \fB\fBDDI_STORECACHING_OK_ACC\fR\fR
139 .ad
140 .RS 27n
141 The \fBCPU\fR can keep the data in the cache and push it to the device, perhaps
142 with other data, at a later time. The default behavior is to push the data
143 right away. \fBDDI_STORECACHING_OK_ACC\fR also implies load caching, merging,
144 and reordering.
145 .RE
147 .sp
148 .LP
149 These values are advisory, not mandatory. For example, data can be ordered
150 without being merged, or cached, even though a driver requests unordered,
151 merged, and cached together.
152 .sp
153 .LP
154 The values defined for \fBdevacc_attr_access\fR are:
155 .sp
156 .ne 2
157 .na
158 \fB\fBDDI_DEFAULT_ACC\fR\fR
159 .ad
160 .RS 20n
161 If an \fBI/O\fR fault occurs, the system will take the default action, which
162 might be to panic.
163 .RE
165 .sp
166 .ne 2
167 .na
168 \fB\fBDDI_FLAGERR_ACC\fR\fR
169 .ad
170 .RS 20n
171 Using this value indicates that the driver is hardened: able to cope with the
172 incorrect results of \fBI/O\fR operations that might result from an \fBI/O\fR
173 fault. The value also indicates that the driver will use
174 \fBddi_fm_acc_err_get\fR(9F) to check access handles for faults on a regular
175 basis.
176 .sp
177 If possible, the system should not panic on such an \fBI/O\fR fault, but should
178 instead mark the \fBI/O\fR handle through which the access was made as having
179 faulted.
180 .sp
181 This value is advisory: it tells the system that the driver can continue in the
182 face of \fBI/O\fR faults. The value does not guarantee that the system will not
183 panic, as that depends on the nature of the fault and the capabilities of the
184 system. It is quite legitimate for an implementation to ignore this flag and
185 panic anyway.
186 .RE
188 .sp
189 .ne 2
190 .na
191 \fB\fBDDI_CAUTIOUS_ACC\fR\fR
192 .ad
193 .RS 20n
194 This value indicates that an \fBI/O\fR fault is anticipated and should be
195 handled as gracefully as possible. For example, the framework should not print
196 a console message.
197 .sp
198 This value should be used when it is not certain that a device is physically
199 present: for example, when probing. As such, it provides an alternative within
200 the \fBDDI\fR access framework to the existing peek/poke functions, which don't
201 use access handles and cannot be integrated easily into a more general
202 \fBI/O\fR fault handling framework.
203 .sp
204 In order to guarantee safe recovery from an \fBI/O\fR fault, it might be
205 necessary to acquire exclusive access to the parent bus, for example, or to
206 synchronize across processors on an \fBMP\fR machine. "Cautious" access can be
207 quite expensive and is only recommended for initial probing and possibly for
208 additional fault-recovery code.
209 .RE
211 .SH EXAMPLES
212 .sp
213 .LP
214 The following examples illustrate the use of device register address mapping
215 setup functions and different data access functions.
216 .LP
217 \fBExample 1 \fRUsing \fBddi_device_acc_attr()\fR in
218 \fBddi_regs_map_setup\fR(9F)
219 .sp
220 .LP
221 This example demonstrates the use of the \fBddi_device_acc_attr()\fR structure
222 in \fBddi_regs_map_setup\fR(9F). It also shows the use of \fBddi_getw\fR(9F)
223 and \fBddi_putw\fR(9F) functions in accessing the register contents.
225 .sp
226 .in +2
227 .nf
228 dev_info_t *dip;
229 uint_t rnumber;
230 ushort_t *dev_addr;
231 offset_t offset;
232 offset_t len;
233 ushort_t dev_command;
234 ddi_device_acc_attr_t dev_attr;
235 ddi_acc_handle_t handle;
237 \&.\|.\|.
239 /*
240 * setup the device attribute structure for little endian,
241 * strict ordering and 16-bit word access.
242 */
243 dev_attr.devacc_attr_version = DDI_DEVICE_ATTR_V0;
244 dev_attr.devacc_attr_endian_flags = DDI_STRUCTURE_LE_ACC;
245 dev_attr.devacc_attr_dataorder = DDI_STRICTORDER_ACC;
247 /*
248 * set up the device registers address mapping
249 */
250 ddi_regs_map_setup(dip, rnumber, (caddr_t *)&dev_addr, offset, len,
251 &dev_attr, &handle);
253 /* read a 16-bit word command register from the device */
254 dev_command = ddi_getw(handle, dev_addr);
256 dev_command |= DEV_INTR_ENABLE;
257 /* store a new value back to the device command register */
258 ddi_putw(handle, dev_addr, dev_command);
259 .fi
260 .in -2
262 .LP
263 \fBExample 2 \fRAccessing a Device with Different Apertures
264 .sp
265 .LP
266 The following example illustrates the steps used to access a device with
267 different apertures. Several apertures are assumed to be grouped under one
268 single "reg" entry. For example, the sample device has four different
269 apertures, each 32 Kbyte in size. The apertures represent \fBYUV\fR
270 little-endian, \fBYUV\fR big-endian, \fBRGB\fR little-endian, and \fBRGB\fR
271 big-endian. This sample device uses entry \fB1\fR of the "reg" property list
272 for this purpose. The size of the address space is 128 Kbyte with each 32 Kbyte
273 range as a separate aperture. In the register mapping setup function, the
274 sample driver uses the \fIoffset\fR and \fIlen\fR parameters to specify one of
275 the apertures.
277 .sp
278 .in +2
279 .nf
280 ulong_t *dev_addr;
281 ddi_device_acc_attr_t dev_attr;
282 ddi_acc_handle_t handle;
283 uchar_t buf[256];
285 \&.\|.\|.
287 /*
288 * setup the device attribute structure for never swap,
289 * unordered and 32-bit word access.
290 */
291 dev_attr.devacc_attr_version = DDI_DEVICE_ATTR_V0;
292 dev_attr.devacc_attr_endian_flags = DDI_NEVERSWAP_ACC;
293 dev_attr.devacc_attr_dataorder = DDI_UNORDERED_OK_ACC;
295 /*
296 * map in the RGB big-endian aperture
297 * while running in a big endian machine
298 * - offset 96K and len 32K
299 */
300 ddi_regs_map_setup(dip, 1, (caddr_t *)&dev_addr, 96*1024, 32*1024,
301 &dev_attr, &handle);
303 /*
304 * Write to the screen buffer
305 * first 1K bytes words, each size 4 bytes
306 */
307 ddi_rep_putl(handle, buf, dev_addr, 256, DDI_DEV_AUTOINCR);
308 .fi
309 .in -2
311 .LP
312 \fBExample 3 \fRFunctions That Call Out the Data Word Size
313 .sp
314 .LP
315 The following example illustrates the use of the functions that explicitly call
316 out the data word size to override the data size in the device attribute
317 structure.
319 .sp
320 .in +2
321 .nf
322 struct device_blk {
323 ushort_t d_command; /* command register */
324 ushort_t d_status; /* status register */
325 ulong d_data; /* data register */
326 } *dev_blkp;
327 dev_info_t *dip;
328 caddr_t dev_addr;
329 ddi_device_acc_attr_t dev_attr;
330 ddi_acc_handle_t handle;
331 uchar_t buf[256];
333 \&.\|.\|.
335 /*
336 * setup the device attribute structure for never swap,
337 * strict ordering and 32-bit word access.
338 */
339 dev_attr.devacc_attr_version = DDI_DEVICE_ATTR_V0;
340 dev_attr.devacc_attr_endian_flags = DDI_NEVERSWAP_ACC;
341 dev_attr.devacc_attr_dataorder= DDI_STRICTORDER_ACC;
343 ddi_regs_map_setup(dip, 1, (caddr_t *)&dev_blkp, 0, 0,
344 &dev_attr, &handle);
346 /* write command to the 16-bit command register */
347 ddi_putw(handle, &dev_blkp->d_command, START_XFER);
349 /* Read the 16-bit status register */
350 status = ddi_getw(handle, &dev_blkp->d_status);
352 if (status & DATA_READY)
353 /* Read 1K bytes off the 32-bit data register */
354 ddi_rep_getl(handle, buf, &dev_blkp->d_data,
355 256, DDI_DEV_NO_AUTOINCR);
356 .fi
357 .in -2
359 .SH ATTRIBUTES
360 .sp
361 .LP
362 See \fBattributes\fR(5) for descriptions of the following attributes:
363 .sp
365 .sp
366 .TS
367 box;
368 c | c
369 l | l .
370 ATTRIBUTE TYPE ATTRIBUTE VALUE
371 _
372 Interface Stability Committed
373 .TE
375 .SH SEE ALSO
376 .sp
377 .LP
378 \fBattributes\fR(5), \fBddi_fm_acc_err_get\fR(9F), \fBddi_getw\fR(9F),
379 \fBddi_putw\fR(9F), \fBddi_regs_map_setup\fR(9F)
380 .sp
381 .LP
382 \fIWriting Device Drivers\fR