.TH dma_mapalloc D3X
.SH NAME
\f4dma_mapalloc\f1 \- allocate a DMA map
.SH SYNOPSIS
.nf
\f4#include "sys/types.h"
#include "sys/sema.h"
#include "sys/dmamap.h"
.sp .8v
dmamap_t *dma_mapalloc(int \f1\f2type\f1\f4,\c
int \f1\f2adapter\f1\f4, int \f1\f2num_pages\f1\f4,\c
int \f1\f2flags\f1\f4);\f1
.fi
.SS Arguments
.TP
\f2type\f1
Must be either \f2DMA_A32VME\f1 or \f2DMA_A24VME\f1 depending on
the transfer desired.
(The \f2DMA_SCSI\f1 type is reserved for exclusive use
by the SCSI host adapter driver.)
.TP
\f2adapter\f1
Specifies the I/O adapter to use for setting up the mapping
This should be set to the I/O bus adapter
number to which the device doing DMA is attached to.
.TP
\f2num_pages\f1
Specifies the maximum number of mapping registers to allocate.
Mapping
registers are responsible for translating the addresses that appear
on the I/O bus to a format that could be used internally within a system.
On current Silicon Graphics systems, each mapping register is
capable of mapping a page of length 4096 bytes on the I/O
bus to a set of consecutive addresses on system memory.
This is true regardless of the system page size.
The number of bytes each mapping register is capable of mapping
could change in future systems.
In order to keep the device driver
platform independent, use of the macro \f4io_btoc\f1 is recommended to
calculate the \f2num_pages\f1 parameter for required length of mapping.
You need to allocate an extra page for non-page aligned
transfers-for example, a transfer of 4096 bytes starting at a
non-aligned address actually requires two mapping registers.
.TP
\f2flags\f1
Reserved for future development.
For now, you should always set it to 0.
.SH DESCRIPTION
\f4dma_mapalloc\f1 allocates DMA mapping registers on
multiprocessor models and returns a pointer to a structure,
of type \f2dmamap_t\f1,
for later use by the mapping routine \f4dma_map\f1.
You need DMA maps to access main memory through VME A24 space.
In addition, because DMA maps give you the ability to perform
transfers to non-contiguous physical memory,
you also want them for A32 access.
.P
Use \f4dma_mapfree\f1 to free the DMA mapping registers
and other resources associated with a given map.
.P
VME adapter number to which a device is attached is available at
edtinit time via \f2e_adap\f1 field in \f2edt\f1 structure.
It is also possible to get this number by using the function
\f4vme_adapter\f1(D3X).
.P
This call can block (it calls \f4psema\f1) if no maps are available,
so it must never be called at interrupt time.
.P
On Challenge and Onyx systems, the maximum amount of address space that can
be mapped for DMA by A32 VME devices is 64MB by default.
This can be changed by modifying the systune variable \f4nvme32_dma\f1.
The value of \f4nvme32_dma\f1 is the maximum amount of address space
(in megabytes) that may be allocated for A32 VME devices.
The default value for \f4nvme32_dma\f1 is 64 (corresponding to the standard
limit of 64MB of address space).
\f4nvme32_dma\f1 must be a power of 2 and may not exceed 512
(meaning 512MB).
If a value larger than 512 is specified, it will be forced back down to 512.
If the value is not a power of 2, it will be rounded up to the next higher
power of 2 (but not to exceed 512).
.SS "Return Values"
\f4dma_mapalloc\f1 returns a pointer to the DMA map
structure on models that support DMA maps.
On other models, \f4dma_mapalloc\f1 returns \-1 to indicate that
DMA mapping is not possible on that model.
.SS "See Also"
dma_map(D3X),
dma_mapaddr(D3X),
dma_mapfree(D3X),
vme_adapter(D3X).