 |
Index for
Section 9 |
|
 |
Alphabetical
listing for V |
|
 |
Bottom of
page |
|
vba_set_dma_addr(9r)
NAME
vba_set_dma_addr - VMEbus: Specifies a VMEbus address and DMA flags
SYNOPSIS
unsigned int vba_set_dma_addr(
struct controller *ctlr,
vme_atype_t flags,
vme_addr_t vme_address );
ARGUMENTS
ctlr
Specifies a pointer to the VMEbus device's controller data structure.
flags
A bit encoded argument that specifies DMA flags, including the address
space, transfer size, access mode, and swap mode of the VMEbus address.
A table of valid bits appears in the DESCRIPTION section.
vme_address
Specifies the VMEbus address for the start of the address translation.
DESCRIPTION
The vba_set_dma_addr() routine allows VMEbus device drivers to pass a
specific VMEbus address and direct memory access (DMA) flags to the
dma_map_alloc() and dma_map_load() routines.
The vba_set_dma_addr() routine provides a mechanism to select the VMEbus
adapter's DMA engine to perform master block transfers. (See the
description of master block transfers with local DMA in the System
Configuration Supplement: OEM Platforms for a description and examples.)
This is the recommended use of the vba_set_dma_addr() routine. See the
NOTES section for a more detailed discussion on the use of
vba_set_dma_addr().
The vba_set_dma_addr() routine also provides a mechanism to map to a
specific VMEbus address versus the dynamic allocation normally performed by
dma_map_alloc() or dma_map_load(). The routine mimics the functionality
that was available in the obsolete routines vballoc() and vbasetup(). We
recommend that you not use the vba_set_dma_addr() routine in this way
unless you understand all of the issues related to the way the obsolete
routines worked. See the NOTES section for a discussion about the issues
for this type of mapping.
The vba_set_dma_addr() routine searches an internal data structure for a
free resource and then does the following:
· Marks the resource as being used
· Fills in the DMA flags
· Fills in the VMEbus address
· Returns a special value to the caller
The caller passes this return value to the flags argument of
dma_map_alloc() or dma_map_load().
When the VMEbus adapter's DMA allocation routine detects the special value,
it calls vba_get_dma_addr() to retrieve the DMA flags and VMEbus address.
As the description for the flags argument states, you can specify atype as
the bitwise inclusive OR of the valid bits in the following table. The
<io/dec/vme/vbareg.h> header file defines these and other bits.
_________________________________________________________________
Bit Category Value Meaning
_________________________________________________________________
Swap mode bits VME_BS_NOSWAP Specifies no byte swapping.
VME_BS_BYTE
Specifies byte swapping in
bytes.
VME_BS_WORD
Specifies byte swapping in
words.
VME_BS_LWORD
Specifies byte swapping in
longwords.
VME_BS_QUAD
Specifies byte swapping in
quadwords.
Address space bits VME_A16
Specifies a request for the
16-bit address space.
VME_A24
Specifies a request for the
24-bit address space.
VME_A32
Specifies a request for the
32-bit address space.
Transfer size bits VME_D08
Specifies a request for the
8-bit data size.
VME_D16
Specifies a request for the
16-bit data size.
VME_D32
Specifies a request for the
32-bit data size.
VME_D64
Specifies a request for the
64-bit data size.
Access mode bits VME_UDATA Specifies user data.
VME_UPROG Specifies a user program.
VME_SDATA Specifies supervisory data.
VME_SPROG
Specifies a supervisory
program.
_________________________________________________________________
Table Notes
·
Not all bus adapters support hardware byte swapping.
·
The VMEbus adapter's master block transfer DMA engine may not
support all data transport sizes. See the description of master
block transfers with local DMA in the System Configuration
Supplement: OEM Platforms or the documentation that comes with your
adapter for block mode restrictions.
You can pass the bitwise inclusive OR of the following special condition
bits defined in the <io/common/devdriver.h> header file:
____________________________________________________________________
Value Meaning
____________________________________________________________________
DMA_GUARD_UPPER
Allocates additional resources so that contiguous
data overruns are captured by the system map error
functions. This bit is probably most useful during
device driver development and debugging.
DMA_GUARD_LOWER
Allocates additional resources so that contiguous
data underruns are captured by the system map
error functions. This bit is probably most useful
during device driver development and debugging.
DMA_SLEEP
Puts the process to sleep if the system cannot
allocate the necessary resources to perform a data
transfer of size byte_count at the time the driver
calls the routine.
DMA_IN
Selects the VMEbus adapter's DMA engine to perform
master block transfers to DMA data from the
specified VMEbus address into system memory.
DMA_OUT
Selects the VMEbus adapter's DMA engine to perform
master block transfers to DMA data from the system
memory to specified VMEbus address.
DMA_ALL
Returns a nonzero value, only if the system can
satisfy a DMA transfer of size byte_count.
____________________________________________________________________
NOTES
To select the VMEbus adapter's master block transfer DMA engine for DMA
transfer, specify either DMA_IN or DMA_OUT in the flags argument in the
call to the vba_set_dma_addr() routine. In addition, specify the bitwise
inclusive OR of the VMEbus flag bits from the first table listed in the
DESCRIPTION section. You also specify the starting VMEbus address of the
transfer in the vme_address argument. You must then pass the return value
from vba_set_dma_addr() to either dma_map_alloc() or dma_map_load(). If you
call both these routines, then you must pass the return value to both.
To perform the actual master block mode DMA transfer, call the vba_dma()
routine. When the transfer has completed, the VMEbus device driver can call
vba_dma() again to transfer the same buffer again. If the device driver
needs to provide a different buffer, call dma_map_load() and vba_dma() to
transfer the next buffer. This reloading of the buffer works providing the
size of the buffer does not exceed the byte count passed to dma_map_alloc()
or to dma_map_load(). When the master block transfer with local DMA engine
is no longer needed, call dma_map_unload() and dma_map_dealloc() to return
master block transfer DMA page map register resources back to the VMEbus
adapter.
You can also use the vba_set_dma_addr() routine to pass a specific VMEbus
address to dma_map_alloc() or dma_map_load(). The purpose of doing this is
to request the VMEbus adapter's allocation routine to map its system memory
at a specific VMEbus address rather than the dynamic allocation that
normally occurs when you call dma_map_alloc() or dma_map_load(). You cause
this mapping by not specifying DMA_IN or DMA_OUT in the flags argument.
You pass the return value from the vba_set_dma_addr() routine to
dma_map_alloc() or dma_map_load(). If the VMEbus adapter's allocation
routine has not already allocated the VMEbus address space to another
VMEbus device driver, and if there are enough page map registers available
to handle the requested mapping size specified by the byte_count argument
of dma_map_alloc() or dma_map_load(), the VMEbus adapter's DMA allocation
routine will reserve the resources and return successfully. If you call
dma_map_load(), the system memory is mapped to the VMEbus upon successful
allocation. If the DMA resources were previously allocated, then
dma_map_alloc() or dma_map_load() returns an error condition.
Upon successful completion of dma_map_load(), the VMEbus device driver
should call dma_get_curr_sgentry() to obtain the actual address mapped to
the VMEbus. The address returned by the call to dma_get_curr_sgentry() may
not be the specified address requested by vba_set_dma_addr(). However, the
address will be within the VMEbus window associated with the page map
register representing the VMEbus address. The reason is that the VMEbus
address consists of two parts. The first part is a VMEbus address that
corresponds to a particular resource (page map register). This part of the
address is a multiple of the bus window that the page map register
represents (typically an Alpha page size). The second part of the VMEbus
address is the page offset of the system memory buffer from the start of an
Alpha page. You pass the system memory buffer to the virt_addr argument of
the dma_map_load() routine.
It is possible that the requested VMEbus address will not be mapped to
memory or only partially mapped. This can occur in three cases:
· If the page offset of the system memory buffer is greater then the
page offset of the VMEbus address
· If the page offset of the system memory buffer plus the byte count
specified in dma_map_load() is less than the page offset of the VMEbus
address
· If the page offset of the VMEbus address is greater then the page
offset of the memory buffer but the requested byte count plus the
specified VMEbus address exceeds the memory buffer
To guard against the previously described problems, ensure that the
specified system memory buffer and VMEbus address are aligned to an Alpha
page boundary. The memory buffer allocated should be large enough to
encompass the page offset of the required VMEbus address. You should pass
the byte count of the memory buffer to the byte_count argument of the
dma_map_alloc() or dma_map_load() routine. To get to the desired VMEbus
address, add the correct page offset to the system memory buffer and to the
VMEbus address returned in the call to dma_get_curr_sgentry().
RETURN VALUES
The vba_set_dma_addr() can return one of the following values:
________________________________________________________________
Value Meaning
________________________________________________________________
The value zero (0)
The system could not allocate internal
resources.
A nonzero value
The system could allocate internal
resources and fill in the internal data
structure with DMA flags and the VMEbus
address. Pass this return value to the
flags argument of dma_map_alloc() or
dma_map_load().
________________________________________________________________
SEE ALSO
Kernel Routines: vba_dma(9r), vba_get_dma_addr(9r)
VMEbus Master Block Transfers with Local DMA: System Configuration
Supplement: OEM Platforms
|
Index for
Section 9 |
|
|
Alphabetical
listing for V |
|
 |
Top of
page |
|