Kernel Functions for Drivers ddidmamemalloc(9F)
NAME
ddidmamemalloc - allocate memory for DMA transfer
SYNOPSIS
#include
#include
int ddidmamemalloc(ddidmahandlet handle, sizet length,
ddideviceaccattrt *accattrp, uintt flags,
int (*waitfp) (caddrt), caddrt arg, caddrt *kaddrp,
sizet *reallength, ddiacchandlet *handlep);
INTERFACE LEVEL
Solaris DI specific (Solaris DI).
PARAMETERS
handle The DMA handle previously allocated by a call
to ddidmaallochandle(9F).
length The length in bytes of the desired alloca-
tion.
accattrp Pointer to a ddideviceaccattr() structure
of the device. See ddideviceaccattr(9S).
The value in devaccattrdataorder is ignored
in the current release. The value in
devaccattrendianflags is meaningful on the
SPARC architecture only.
flags Used to determine the data transfer mode
and/or the cache attribute.
Possible values of the data transfer are:
DIDMASTREAMING Sequential, unidirec-
tional, block-sized,
and block-aligned
transfers.
DIDMACONSISTENT Nonsequential transfers
of small objects.
Possible values of the cache attribute are:
SunOS 5.11 Last change: 05 Jun 2006 1
Kernel Functions for Drivers ddidmamemalloc(9F)
IOMEMDATACACHED The CPU can cache
the data it
fetches and push
it to memory at a
later time. This
is the default
attribute that is
used if no cache
attributes are
specified.
IOMEMDATAUCWRCOMBINE The CPU never
caches the data,
but writes can
occur out of
order or can be
combined. Reord-
ering is implied.
If
IOMEMDATAUCWRCOMBINE
is specified but
not supported,
IOMEMDATAUNCACHED
is used instead.
IOMEMDATAUNCACHED The CPU never
caches data, but
has uncacheable
access to memory.
Strict ordering
is implied.
The cache attributes are mutually exclusive.
Any combination of the values leads to a
failure. On the SPARC architecture, only
IOMEMDATACACHED is meaningful. Others lead
to a failure.
waitfp The address of a function to call back later
if resources are not available now. The call-
back function indicates how a caller wants to
handle the possibility of resources not being
available. If callback is set to
DIDMADONTWAIT, the caller does not care if
the allocation fails, and can handle an allo-
cation failure appropriately. If callback is
set to DIDMASLEP, the caller wishes to
have the allocation routines wait for
SunOS 5.11 Last change: 05 Jun 2006 2
Kernel Functions for Drivers ddidmamemalloc(9F)
resources to become available. If any other
value is set and a DMA resource allocation
fails, this value is assumed to be the
address of a function to be called when
resources become available. When the speci-
fied function is called, arg is passed to it
as an argument. The specified callback func-
tion must return either
DIDMACALBACKRUNOUT or
DIDMACALBACKDONE.
DIDMACALBACKRUNOUT indicates that the
callback function attempted to allocate DMA
resources but failed. In this case, the call-
back function is put back on a list to be
called again later. DIDMACALBACKDONE
indicates that either the allocation of DMA
resources was successful or the driver no
longer wishes to retry. The callback function
is called in interrupt context. Therefore,
only system functions accessible from inter-
rupt context are available.
The callback function must take whatever
steps are necessary to protect its critical
resources, data structures, queues, and so
on.
arg Argument to be passed to the callback func-
tion, if such a function is specified.
kaddrp On successful return, kaddrp points to the
allocated memory.
reallength The amount of memory, in bytes, allocated.
Alignment and padding requirements may
require ddidmamemalloc() to allocate more
memory than requested in length.
handlep Pointer to a data access handle.
DESCRIPTION
The ddidmamemalloc() function allocates memory for DMA
transfers to or from a device. The allocation will obey the
alignment, padding constraints and device granularity as
specified by the DMA attributes (see ddidmaattr(9S))
passed to ddidmaallochandle(9F) and the more restrictive
attributes imposed by the system.
SunOS 5.11 Last change: 05 Jun 2006 3
Kernel Functions for Drivers ddidmamemalloc(9F)
The flags parameter should be set to DIDMASTREAMING if
the device is doing sequential, unidirectional, block-sized,
and block-aligned transfers to or from memory. The alignment
and padding constraints specified by the minxfer and burst-
sizes fields in the DMA attribute structure,
ddidmaattr(9S) (see ddidmaallochandle(9F)) will be used
to allocate the most effective hardware support for large
transfers. For example, if an I/O transfer can be sped up by
using an I/O cache, which has a minimum transfer of one
cache line, ddidmamemalloc() will align the memory at a
cache line boundary and it will round up reallength to a
multiple of the cache line size.
The flags parameter should be set to DIDMACONSISTENT if
the device accesses memory randomly, or if synchronization
steps using ddidmasync(9F) need to be as efficient as pos-
sible. I/O parameter blocks used for communication between a
device and a driver should be allocated using
DIDMACONSISTENT.
The device access attributes are specified in the location
pointed by the accattrp argument (see
ddideviceaccattr(9S)).
The data access handle is returned in handlep. handlep is
opaque - drivers may not attempt to interpret its value. To
access the data content, the driver must invoke ddiget8(9F)
or ddiput8(9F) (depending on the data transfer direction)
with the data access handle.
DMA resources must be established before performing a DMA
transfer by passing kaddrp and reallength as returned from
ddidmamemalloc() and the flag DIDMASTREAMING or
DIDMACONSISTENT to ddidmaaddrbindhandle(9F). In addi-
tion, to ensure the consistency of a memory object shared
between the CPU and the device after a DMA transfer, expli-
cit synchronization steps using ddidmasync(9F) or
ddidmaunbindhandle(9F) are required.
RETURN VALUES
The ddidmamemalloc() function returns:
DISUCES Memory successfully allocated.
DIFAILURE Memory allocation failed.
SunOS 5.11 Last change: 05 Jun 2006 4
Kernel Functions for Drivers ddidmamemalloc(9F)
CONTEXT
The ddidmamemalloc() function can be called from user,
interrupt, or kernel context except when waitfp is set to
DIDMASLEP, in which case it cannot be called from inter-
rupt context.
SEE ALSO
ddidmaaddrbindhandle(9F), ddidmaallochandle(9F),
ddidmamemfree(9F), ddidmasync(9F),
ddidmaunbindhandle(9F), ddiget8(9F), ddiput8(9F),
ddideviceaccattr(9S), ddidmaattr(9S)
Writing Device Drivers
WARNINGS
If DINEVERSWAPAC is specified, memory can be used for
any purpose; but if either endian mode is specified, you
must use ddiget/put* and never anything else.
SunOS 5.11 Last change: 05 Jun 2006 5
|
