Kernel Functions for Drivers ddidmae(9F)
NAME
ddidmae, ddidmaealloc, ddidmaerelease, ddidmaeprog,
ddidmaedisable, ddidmaeenable, ddidmaestop,
ddidmaegetcnt, ddidmae1stparty, ddidmaegetlim,
ddidmaegetattr - system DMA engine functions
SYNOPSIS
int ddidmaealloc(devinfot *dip, int chnl, int (*callback) (caddrt),
caddrt arg);
int ddidmaerelease(devinfot *dip, int chnl);
int ddidmaeprog(devinfot *dip, struct ddidmaereq *dmaereqp,
ddidmacookiet *cookiep, int chnl);
int ddidmaedisable(devinfot *dip, int chnl);
int ddidmaeenable(devinfot *dip, int chnl);
int ddidmaestop(devinfot *dip, int chnl);
int ddidmaegetcnt(devinfot *dip, int chnl, int *countp);
int ddidmae1stparty(devinfot *dip, int chnl);
int ddidmaegetlim(devinfot *dip, ddidmalimt *limitsp);
int ddidmaegetattr(devinfot *dip, ddidmaattrt *attrp);
INTERFACE LEVEL
Solaris DI specific (Solaris DI). The ddidmaegetlim()
interface, described below, is obsolete. Use
ddidmaegetattr(), also described below, to replace it.
PARAMETERS
dip A devinfo pointer that identifies the device.
chnl A DMA channel number. On ISA buses this number
must be 0, 1, 2, 3, 5, 6, or 7.
SunOS 5.11 Last change: 04 Apr 2006 1
Kernel Functions for Drivers ddidmae(9F)
callback The address of a function to call back later if
resources are not currently available. The fol-
lowing 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 the callback function,
if specified.
dmaereqp A pointer to a DMA engine request structure. See
ddidmaereq(9S).
cookiep A pointer to a ddidmacookie(9S) object,
obtained from ddidmasegtocookie(9F), which
contains the address and count.
countp A pointer to an integer that will receive the
count of the number of bytes not yet transferred
upon completion of a DMA operation.
limitsp A pointer to a DMA limit structure. See
ddidmalimx86(9S).
attrp A pointer to a DMA attribute structure. See
ddidmaattr(9S).
DESCRIPTION
There are three possible ways that a device can perform DMA
engine functions:
Bus master DMA If the device is capable of acting as a
true bus master, then the driver should
program the device's DMA registers
directly and not make use of the DMA
engine functions described here. The
driver should obtain the DMA address and
count from ddidmasegtocookie(9F). See
SunOS 5.11 Last change: 04 Apr 2006 2
Kernel Functions for Drivers ddidmae(9F)
ddidmacookie(9S) for a description of a
DMA cookie.
Third-party DMA This method uses the system DMA engine
that is resident on the main system
board. In this model, the device
cooperates with the system's DMA engine
to effect the data transfers between the
device and memory. The driver uses the
functions documented here, except
ddidmae1stparty(), to initialize and
program the DMA engine. For each DMA data
transfer, the driver programs the DMA
engine and then gives the device a com-
mand to initiate the transfer in coopera-
tion with that engine.
First-party DMA Using this method, the device uses its
own DMA bus cycles, but requires a chan-
nel from the system's DMA engine. After
allocating the DMA channel, the
ddidmae1stparty() function may be used
to perform whatever configuration is
necessary to enable this mode.
ddidmaealloc()
The ddidmaealloc() function is used to acquire a DMA chan-
nel of the system DMA engine. ddidmaealloc() allows only
one device at a time to have a particular DMA channel allo-
cated. It must be called prior to any other system DMA
engine function on a channel. If the device allows the chan-
nel to be shared with other devices, it must be freed using
ddidmaerelease() after completion of the DMA operation. In
any case, the channel must be released before the driver
successfully detaches. See detach(9E). No other driver may
acquire the DMA channel until it is released.
If the requested channel is not immediately available, the
value of callback determines what action will be taken. If
the value of callback is DIDMADONTWAIT, ddidmaealloc()
will return immediately. The value DIDMASLEP will cause
the thread to sleep and not return until the channel has
been acquired. Any other value is assumed to be a callback
function address. In that case, ddidmaealloc() returns
immediately, and when resources might have become available,
the callback function is called (with the argument arg) from
interrupt context. When the callback function is called, it
should attempt to allocate the DMA channel again. If it
SunOS 5.11 Last change: 04 Apr 2006 3
Kernel Functions for Drivers ddidmae(9F)
succeeds or no longer needs the channel, it must return the
value DIDMACALBACKDONE. If it tries to allocate the
channel but fails to do so, it must return the value
DIDMACALBACKRUNOUT. In this case, the callback function
is put back on a list to be called again later.
ddidmaeprog()
The ddidmaeprog() function programs the DMA channel for a
DMA transfer. The ddidmaereq structure contains all the
information necessary to set up the channel, except for the
memory address and count. Once the channel has been pro-
grammed, subsequent calls to ddidmaeprog() may specify a
value of NUL for dmaereqp if no changes to the programming
are required other than the address and count values. It
disables the channel prior to setup, and enables the channel
before returning. The DMA address and count are specified by
passing ddidmaeprog() a cookie obtained from
ddidmasegtocookie(9F). Other DMA engine parameters are
specified by the DMA engine request structure passed in
through dmaereqp. The fields of that structure are docu-
mented in ddidmaereq(9S).
Before using ddidmaeprog(), you must allocate system DMA
resources using DMA setup functions such as
ddidmabufsetup(9F). ddidmasegtocookie(9F) can then be
used to retrieve a cookie which contains the address and
count. Then this cookie is passed to ddidmaeprog().
ddidmaedisable()
The ddidmaedisable() function disables the DMA channel so
that it no longer responds to a device's DMA service
requests.
ddidmaeenable()
The ddidmaeenable() function enables the DMA channel for
operation. This may be used to re-enable the channel after a
call to ddidmaedisable(). The channel is automatically
enabled after successful programming by ddidmaeprog().
ddidmaestop()
The ddidmaestop() function disables the channel and ter-
minates any active operation.
ddidmaegetcnt()
The ddidmaegetcnt() function examines the count register
of the DMA channel and sets *countp to the number of bytes
remaining to be transferred. The channel is assumed to be
stopped.
ddidmae1stparty()
SunOS 5.11 Last change: 04 Apr 2006 4
Kernel Functions for Drivers ddidmae(9F)
In the case of ISA buses, ddidmae1stparty() configures a
channel in the system's DMA engine to operate in a ``slave''
(``cascade'') mode.
When operating in ddidmae1stparty() mode, the DMA channel
must first be allocated using ddidmaealloc() and then con-
figured using ddidmae1stparty(). The driver then programs
the device to perform the I/O, including the necessary DMA
address and count values obtained from
ddidmasegtocookie(9F).
ddidmaegetlim()
This function is obsolete. Use ddidmaegetattr(), described
below, instead.
The ddidmaegetlim() function fills in the DMA limit struc-
ture, pointed to by limitsp, with the DMA limits of the sys-
tem DMA engine. Drivers for devices that perform their own
bus mastering or use first-party DMA must create and ini-
tialize their own DMA limit structures; they should not use
ddidmaegetlim(). The DMA limit structure must be passed to
the DMA setup routines so that they will know how to break
the DMA request into windows and segments (see
ddidmanextseg(9F) and ddidmanextwin(9F)). If the device
has any particular restrictions on transfer size or granu-
larity (such as the size of disk sector), the driver should
further restrict the values in the structure members before
passing them to the DMA setup routines. The driver must not
relax any of the restrictions embodied in the structure
after it is filled in by ddidmaegetlim(). After calling
ddidmaegetlim(), a driver must examine, and possibly set,
the size of the DMA engine's scatter/gather list to deter-
mine whether DMA chaining will be used. See
ddidmalimx86(9S) and ddidmaereq(9S) for additional
information on scatter/gather DMA.
ddidmaegetattr()
The ddidmaegetattr() function fills in the DMA attribute
structure, pointed to by attrp, with the DMA attributes of
the system DMA engine. Drivers for devices that perform
their own bus mastering or use first-party DMA must create
and initialize their own DMA attribute structures; they
should not use ddidmaegetattr(). The DMA attribute struc-
ture must be passed to the DMA resource allocation functions
to provide the information necessary to break the DMA
request into DMA windows and DMA cookies. See
ddidmanextcookie(9F) and ddidmagetwin(9F).
RETURN VALUES
SunOS 5.11 Last change: 04 Apr 2006 5
Kernel Functions for Drivers ddidmae(9F)
DISUCES Upon success, for all of these rou-
tines.
DIFAILURE May be returned due to invalid argu-
ments.
DIDMANORESOURCES May be returned by ddidmaealloc()
if the requested resources are not
available and the value of
dmaewaitfp is not DIDMASLEP.
CONTEXT
If ddidmaealloc() is called from interrupt context, then
its dmaewaitfp argument and the callback function must not
have the value DIDMASLEP. Otherwise, all these routines
can be called from user, interrupt, or kernel context.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture x86
SEE ALSO
isa(4), attributes(5), ddidmabufsetup(9F),
ddidmagetwin(9F), ddidmanextcookie(9F),
ddidmanextseg(9F), ddidmanextwin(9F),
ddidmasegtocookie(9F), ddidmasetup(9F),
ddidmaattr(9S), ddidmacookie(9S), ddidmalimx86(9S),
ddidmareq(9S), ddidmaereq(9S)
SunOS 5.11 Last change: 04 Apr 2006 6
|
