Data Structures for Drivers ddideviceaccattr(9S)
NAME
ddideviceaccattr - data access attributes structure
SYNOPSIS
#include
#include
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
DESCRIPTION
The ddideviceaccattr structure describes the data access
characteristics and requirements of the device.
STRUCTURE MEMBERS
ushortt devaccattrversion;
uchart devaccattrendianflags;
uchart devaccattrdataorder;
uchart devaccattraccess;
The devaccattrversion member identifies the version number
of this structure. The current version number is
DIDEVICEATRV0.
The devaccattrendianflags member describes the endian
characteristics of the device. Specify one of the following
values:
DINEVERSWAPAC Data access with no byte swapping
DISTRUCTUREBEAC Structural data access in big-endian
format
DISTRUCTURELEAC Structural data access in little
endian format
DISTRUCTUREBEAC and DISTRUCTURELEAC describe the
endian characteristics of the device as big-endian or
little-endian, respectively. Although most of the devices
have the same endian characteristics as their buses, exam-
ples of devices that have opposite endian characteristics of
the buses do exist. When DISTRUCTUREBEAC or
DISTRUCTURELEAC is set, byte swapping is automatically
performed by the system if the host machine and the device
SunOS 5.11 Last change: 13 May 2007 1
Data Structures for Drivers ddideviceaccattr(9S)
data formats have opposite endian characteristics. The
implementation can take advantage of hardware platform byte
swapping capabilities.
When you specify DINEVERSWAPAC, byte swapping is not
invoked in the data access functions.
The devaccattrdataorder member describes the order in
which the CPU references data. Specify one of the following
values.
DISTRICTORDERAC Data references must be issued by
a CPU in program order. Strict
ordering is the default behavior.
DIUNORDEREDOKAC The CPU can reorder the data
references. This includes all
kinds of reordering. For example,
a load followed by a store might
be replaced by a store followed
by a load.
DIMERGINGOKAC The CPU can merge individual
stores to consecutive locations.
For example, the CPU can turn two
consecutive byte stores into one
half-word store. It can also
batch individual loads. For exam-
ple, the CPU might turn two con-
secutive byte loads into one
half-word load.
DIMERGINGOKAC also implies
reordering.
DILOADCACHINGOKAC The CPU can cache the data it
fetches and reuse it until
another store occurs. The default
behavior is to fetch new data on
every load.
DILOADCACHINGOKAC also
implies merging and reordering.
DISTORECACHINGOKAC The CPU can keep the data in the
cache and push it to the device,
perhaps with other data, at a
later time. The default behavior
SunOS 5.11 Last change: 13 May 2007 2
Data Structures for Drivers ddideviceaccattr(9S)
is to push the data right away.
DISTORECACHINGOKAC also
implies load caching, merging,
and reordering.
These values are advisory, not mandatory. For example, data
can be ordered without being merged, or cached, even though
a driver requests unordered, merged, and cached together.
The values defined for devaccattraccess are:
DIDEFAULTAC If an I/O fault occurs, the system will
take the default action, which might be
to panic.
DIFLAGERAC Using this value indicates that the
driver is hardened: able to cope with
the incorrect results of I/O operations
that might result from an I/O fault. The
value also indicates that the driver
will use ddifmaccerrget(9F) to check
access handles for faults on a regular
basis.
If possible, the system should not panic
on such an I/O fault, but should instead
mark the I/O handle through which the
access was made as having faulted.
This value is advisory: it tells the
system that the driver can continue in
the face of I/O faults. The value does
not guarantee that the system will not
panic, as that depends on the nature of
the fault and the capabilities of the
system. It is quite legitimate for an
implementation to ignore this flag and
panic anyway.
DICAUTIOUSAC This value indicates that an I/O fault
is anticipated and should be handled as
gracefully as possible. For example, the
framework should not print a console
message.
This value should be used when it is not
certain that a device is physically
SunOS 5.11 Last change: 13 May 2007 3
Data Structures for Drivers ddideviceaccattr(9S)
present: for example, when probing. As
such, it provides an alternative within
the DI access framework to the existing
peek/poke functions, which don't use
access handles and cannot be integrated
easily into a more general I/O fault
handling framework.
In order to guarantee safe recovery from
an I/O fault, it might be necessary to
acquire exclusive access to the parent
bus, for example, or to synchronize
across processors on an MP machine.
"Cautious" access can be quite expensive
and is only recommended for initial
probing and possibly for additional
fault-recovery code.
EXAMPLES
The following examples illustrate the use of device register
address mapping setup functions and different data access
functions.
Example 1 Using ddideviceaccattr() in
>ddiregsmapsetup(9F)
This example demonstrates the use of the
ddideviceaccattr() structure in ddiregsmapsetup(9F).
It also shows the use of ddigetw(9F) and ddiputw(9F)
functions in accessing the register contents.
devinfot *dip;
uintt rnumber;
ushortt *devaddr;
offsett offset;
offsett len;
ushortt devcommand;
ddideviceaccattrt devattr;
ddiacchandlet handle;
...
/*
* setup the device attribute structure for little endian,
* strict ordering and 16-bit word access.
*/
devattr.devaccattrversion = DIDEVICEATRV0;
devattr.devaccattrendianflags = DISTRUCTURELEAC;
devattr.devaccattrdataorder = DISTRICTORDERAC;
SunOS 5.11 Last change: 13 May 2007 4
Data Structures for Drivers ddideviceaccattr(9S)
/*
* set up the device registers address mapping
*/
ddiregsmapsetup(dip, rnumber, (caddrt *)&devaddr, offset, len,
&devattr, &handle);
/* read a 16-bit word command register from the device */
devcommand = ddigetw(handle, devaddr);
devcommand = DEVINTRENABLE;
/* store a new value back to the device command register */
ddiputw(handle, devaddr, devcommand);
Example 2 Accessing a Device with Different Apertures
The following example illustrates the steps used to access a
device with different apertures. Several apertures are
assumed to be grouped under one single "reg" entry. For
example, the sample device has four different apertures,
each 32 Kbyte in size. The apertures represent YUV little-
endian, YUV big-endian, RGB little-endian, and RGB big-
endian. This sample device uses entry 1 of the "reg" pro-
perty list for this purpose. The size of the address space
is 128 Kbyte with each 32 Kbyte range as a separate aper-
ture. In the register mapping setup function, the sample
driver uses the offset and len parameters to specify one of
the apertures.
ulongt *devaddr;
ddideviceaccattrt devattr;
ddiacchandlet handle;
uchart buf[256];
...
/*
* setup the device attribute structure for never swap,
* unordered and 32-bit word access.
*/
devattr.devaccattrversion = DIDEVICEATRV0;
devattr.devaccattrendianflags = DINEVERSWAPAC;
devattr.devaccattrdataorder = DIUNORDEREDOKAC;
/*
* map in the RGB big-endian aperture
* while running in a big endian machine
* - offset 96K and len 32K
*/
ddiregsmapsetup(dip, 1, (caddrt *)&devaddr, 96*1024, 32*1024,
SunOS 5.11 Last change: 13 May 2007 5
Data Structures for Drivers ddideviceaccattr(9S)
&devattr, &handle);
/*
* Write to the screen buffer
* first 1K bytes words, each size 4 bytes
*/
ddirepputl(handle, buf, devaddr, 256, DIDEVAUTOINCR);
Example 3 Functions That Call Out the Data Word Size
The following example illustrates the use of the functions
that explicitly call out the data word size to override the
data size in the device attribute structure.
struct deviceblk {
ushortt dcommand; /* command register */
ushortt dstatus; /* status register */
ulong ddata; /* data register */
} *devblkp;
devinfot *dip;
caddrt devaddr;
ddideviceaccattrt devattr;
ddiacchandlet handle;
uchart buf[256];
...
/*
* setup the device attribute structure for never swap,
* strict ordering and 32-bit word access.
*/
devattr.devaccattrversion = DIDEVICEATRV0;
devattr.devaccattrendianflags = DINEVERSWAPAC;
devattr.devaccattrdataorder= DISTRICTORDERAC;
ddiregsmapsetup(dip, 1, (caddrt *)&devblkp, 0, 0,
&devattr, &handle);
/* write command to the 16-bit command register */
ddiputw(handle, &devblkp->dcommand, STARTXFER);
/* Read the 16-bit status register */
status = ddigetw(handle, &devblkp->dstatus);
if (status & DATAREADY)
/* Read 1K bytes off the 32-bit data register */
ddirepgetl(handle, buf, &devblkp->ddata,
256, DIDEVNOAUTOINCR);
SunOS 5.11 Last change: 13 May 2007 6
Data Structures for Drivers ddideviceaccattr(9S)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
SEE ALSO
attributes(5), ddifmaccerrget(9F), ddigetw(9F),
ddiputw(9F), ddiregsmapsetup(9F)
Writing Device Drivers
SunOS 5.11 Last change: 13 May 2007 7
|
