Data Structures for Drivers ddidmaattr(9S)
NAME
ddidmaattr - DMA attributes structure
SYNOPSIS
#include
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
DESCRIPTION
A ddidmaattrt structure describes device- and DMA
engine-specific attributes necessary to allocate DMA
resources for a device. The driver might have to extend the
attributes with bus-specific information, depending on the
bus to which the device is connected.
STRUCTURE MEMBERS
uintt dmaattrversion; /* version number */
uint64t dmaattraddrlo; /* low DMA address range */
uint64t dmaattraddrhi; /* high DMA address range */
uint64t dmaattrcountmax; /* DMA counter register */
uint64t dmaattralign; /* DMA address alignment */
uintt dmaattrburstsizes; /* DMA burstsizes */
uint32t dmaattrminxfer; /* min effective DMA size */
uint64t dmaattrmaxxfer; /* max DMA xfer size */
uint64t dmaattrseg; /* segment boundary */
int dmaattrsgllen; /* s/g list length */
uint32t dmaattrgranular; /* granularity of device */
uintt dmaattrflags; /* DMA transfer flags */
The dmaattrversion stores the version number of this DMA
attribute structure. It should be set to DMATRV0.
The dmaattraddrlo and dmaattraddrhi fields specify the
address range the device's DMA engine can access. The
dmaattraddrlo field describes the inclusive lower 64-bit
boundary. The dmaattraddrhi describes the inclusive upper
64-bit boundary. The system ensures that allocated DMA
resources are within the range specified. See
ddidmacookie(9S).
The dmaattrcountmax describes an inclusive upper bound
for the device's DMA counter register. For example, 0xF
would describe a DMA engine with a 24-bit counter register.
DMA resource allocation functions have to break up a DMA
object into multiple DMA cookies if the size of the object
SunOS 5.11 Last change: 12 Feb 2009 1
Data Structures for Drivers ddidmaattr(9S)
exceeds the size of the DMA counter register.
The dmaattralign specifies alignment requirements for
allocated DMA resources. This field can be used to force
more restrictive alignment than imposed by
dmaattrburstsizes or dmaattrminxfer, such as alignment
at a page boundary. Most drivers set this field to 1, indi-
cating byte alignment.
The dmaattralign only specifies alignment requirements for
allocated DMA resources. The buffer passed to
ddidmaaddrbindhandle(9F) or ddidmabufbindhandle(9F)
must have an equally restrictive alignment (see
ddidmamemalloc(9F)).
The dmaattrburstsizes field describes the possible burst
sizes the DMA engine of a device can accept. The format of
the data sizes is binary, encoded in terms of powers of two.
When DMA resources are allocated, the system can modify the
burstsizes value to reflect the system limits. The driver
must use the allowable burstsizes to program the DMA engine.
See ddidmaburstsizes(9F).
The dmaattrminxfer field describes the minimum effective
DMA access size in units of bytes. DMA resources can be
modified, depending on the presence and use of I/O caches
and write buffers between the DMA engine and the memory
object. This field is used to determine alignment and pad-
ding requirements for ddidmamemalloc(9F).
The dmaattrmaxxfer field describes the maximum effective
DMA access size in units of bytes.
The dmaattrseg field specifies segment boundary restric-
tions for allocated DMA resources. The system allocates DMA
resources for the device so that the object does not span
the segment boundary specified by dmaattrseg. For example,
a value of 0xF means DMA resources must not cross a 64-
Kbyte boundary. DMA resource allocation functions might have
to break up a DMA object into multiple DMA cookies to
enforce segment boundary restrictions. In this case, the
transfer must be performed using scatter-gather I/O or mul-
tiple DMA windows.
SunOS 5.11 Last change: 12 Feb 2009 2
Data Structures for Drivers ddidmaattr(9S)
The dmaattrsgllen field describes the length of the DMA
scatter/gather list of a device. Possible values are as fol-
lows:
< 0 Device DMA engine is not constrained by the size, for
example, withDMA chaining.
= 0 Reserved.
= 1 Device DMA engine does not support scatter/gather
such as third party DMA.
> 1 Device DMA engine uses scatter/gather. The
dmaattrsgllen value is the maximum number of
entries in the list.
The dmaattrgranular field describes the granularity of the
device transfer size in units of bytes. When the system
allocates DMA resources, the size of a single segment is a
multiple of the device granularity. If dmaattrsgllen is
larger than 1 within a window, the sum of the sizes for a
subgroup of segments is a multiple of the device granular-
ity.
All driver requests for DMA resources must be a multiple of
the granularity of the device transfer size.
The dmaattrflags field can be set to a combination of:
DIDMAFORCEPHYSICAL
Some platforms, such as SPARC systems, support what is
called Direct Virtual Memory Access (DVMA). On these
platforms, the device is provided with a virtual address
by the system in order to perform the transfer. In this
case, the underlying platform provides an IOMU, which
translates accesses to these virtual addresses into the
proper physical addresses. Some of these platforms also
support DMA. DIDMAFORCEPHYSICAL indicates that the
system should return physical rather than virtual I/O
addresses if the system supports both. If the system
does not support physical DMA, the return value from
ddidmaallochandle(9F) is DIDMABADATR. In this
case, the driver has to clear DIDMAFORCEPHYSICAL and
retry the operation.
SunOS 5.11 Last change: 12 Feb 2009 3
Data Structures for Drivers ddidmaattr(9S)
DIDMAFLAGER
Using this value indicates that the driver is hardened:
able to cope with the incorrect results of DMA opera-
tions that might result from an I/O fault. The value
also indicates that the driver will use
ddifmdmaerrget(9F) to check DMA handles for faults
on a regular basis.
If a DMA error is detected during a DMA access to an
area mapped by such a handle, the system should not
panic if possible, but should instead mark the DMA han-
dle as having faulted.
This value is advisory: it tells the system that the
driver can continue in the face of I/O faults. It 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 implementa-
tion to ignore this flag and panic anyway.
DIDMARELAXEDORDERING
This optional flag can be set if the DMA transactions
associated with this handle are not required to observe
strong DMA write ordering among themselves, nor with DMA
write transactions of other handles.
The flag allows the host bridge to transfer data to and
from memory more efficiently and might result in better
DMA performance on some platforms.
Drivers for devices with hardware support, such as mark-
ing the bus transactions relaxed ordered, should not use
this flag. Such drivers should use the hardware capabil-
ity instead.
EXAMPLES
Example 1 Initializing the ddidmaattrt Structure
Assume a device has the following DMA characteristics:
o Full 32-bit range addressable
o 24-bit DMA counter register
o Byte alignment
o 4- and 8-byte burst sizes support
SunOS 5.11 Last change: 12 Feb 2009 4
Data Structures for Drivers ddidmaattr(9S)
o Minimum effective transfer size of 1 bytes
o 64 Mbyte minus 1 (26-bit) maximum transfer size
limit
o Maximum segment size of 32 Kbyte
o 17 scatter/gather list elements
o 512-byte device transfer size granularity
The corresponding ddidmaattrt structure is initialized as
follows:
static ddidmaattrt dmaattrs = {
DMATRV0 /* version number */
(uint64t)0x0, /* low address */
(uint64t)0xffffffff, /* high address */
(uint64t)0xffffff, /* DMA counter max */
(uint64t)0x1 /* alignment */
0x0c, /* burst sizes */
0x1, /* minimum transfer size */
(uint64t)0x3ffffff, /* maximum transfer size */
(uint64t)0x7fff, /* maximum segment size */
17, /* scatter/gather list lgth */
512 /* granularity */
0 /* DMA flags */
};
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
SEE ALSO
attributes(5), ddidmaaddrbindhandle(9F),
ddidmaallochandle(9F), ddidmabufbindhandle(9F),
ddidmaburstsizes(9F), ddidmamemalloc(9F),
ddidmanextcookie(9F), ddifmdmaerrget(9F),
ddidmacookie(9S)
SunOS 5.11 Last change: 12 Feb 2009 5
Data Structures for Drivers ddidmaattr(9S)
Writing Device Drivers
SunOS 5.11 Last change: 12 Feb 2009 6
|
