Kernel Functions for Drivers ddidmaallochandle(9F)
NAME
ddidmaallochandle - allocate DMA handle
SYNOPSIS
#include
#include
int ddidmaallochandle(devinfot *dip, ddidmaattrt *attr,
int (*callback) (caddrt), caddrt arg, ddidmahandlet *handlep);
INTERFACE LEVEL
Solaris DI specific (Solaris DI).
PARAMETERS
dip Pointer to the device's devinfo structure.
attr Pointer to a DMA attribute structure for this
device (see ddidmaattr(9S)).
callback The address of a function to call back later if
resources aren't available now. The following
special function addresses may also be used.
DIDMASLEP Wait until resources are
available.
DIDMADONTWAIT Do not wait until resources
are available and do not
schedule a callback.
arg Argument to be passed to a callback function, if
such a function is specified.
handlep Pointer to the DMA handle to be initialized.
DESCRIPTION
ddidmaallochandle() allocates a new DMA handle. A DMA
handle is an opaque object used as a reference to subse-
quently allocated DMA resources. ddidmaallochandle()
accepts as parameters the device information referred to by
dip and the device's DMA attributes described by a
ddidmaattr(9S) structure. A successful call to
SunOS 5.11 Last change: 22 Sep 1996 1
Kernel Functions for Drivers ddidmaallochandle(9F)
ddidmaallochandle() fills in the value pointed to by
handlep. A DMA handle must only be used by the device for
which it was allocated and is only valid for one I/O tran-
saction at a time.
The callback function, callback, indicates how a caller
wants to handle the possibility of resources not being
available. If callback is set to DIDMADONTWAIT, then the
caller does not care if the allocation fails, and can handle
an allocation failure appropriately. If callback is set to
DIDMASLEP, then the caller wishes to have the allocation
routines wait for resources to become available. If any
other value is set, and a DMA resource allocation fails,
this value is assumed to be a function to call at a later
time when resources may become available. When the specified
function is called, it is passed arg as an argument. The
specified callback function must return either
DIDMACALBACKRUNOUT or DIDMACALBACKDONE.
DIDMACALBACKRUNOUT indicates that the callback routine
attempted to allocate DMA resources but failed to do so, in
which case the callback function is put back on a list to be
called again later. DIDMACALBACKDONE indicates either
success at allocating DMA resources or the driver no longer
wishes to retry.
The callback function is called in interrupt context. There-
fore, only system functions that are accessible from inter-
rupt context is available. The callback function must take
whatever steps necessary to protect its critical resources,
data structures, queues, and so forth.
When a DMA handle is no longer needed,
ddidmafreehandle(9F) must be called to free the handle.
RETURN VALUES
ddidmaallochandle() returns:
DISUCES Successfully allocated a new DMA han-
dle.
DIDMABADATR The attributes specified in the
ddidmaattr(9S) structure make it
impossible for the system to allocate
potential DMA resources.
DIDMANORESOURCES No resources are available.
SunOS 5.11 Last change: 22 Sep 1996 2
Kernel Functions for Drivers ddidmaallochandle(9F)
CONTEXT
ddidmaallochandle() can be called from user, kernel, or
interrupt context, except when callback is set to
DIDMASLEP, in which case it can be called from user or
kernel context only.
SEE ALSO
ddidmaaddrbindhandle(9F), ddidmabufbindhandle(9F),
ddidmaburstsizes(9F), ddidmafreehandle(9F),
ddidmaunbindhandle(9F), ddidmaattr(9S)
Writing Device Drivers
SunOS 5.11 Last change: 22 Sep 1996 3
|
