physreq(D4)
physreq --
physical alignment requirements structure
Syntax
#include <sys/types.h>
#include <sys/kmem.h>
#include <sys/ddi.h>
Description
The physreq structure is used by routines to indicate
physical address alignment and contiguity constraints on memory.
Usage
Whenever memory is allocated that will be made accessible to
hardware devices via
DMA,
one of the interfaces that allows physical requirements
to be specified using a physreq_t structure should be used.
Before this structure can be passed to any other routine,
other than
physreq_free(D3),
it first must be passed to
physreq_prep(D3).
Note that the
bcb_prep(D3)
function will also prep an associated physreq structure,
although a separate call to
physreq_prep( )
is legal.
After calling physreq_prep,
no members in this structure should be changed
unless
physreq_prep( )
is called again.
Always allocate physreq structures by calling
physreq_alloc(D3).
Never create these structures statically.
Structure definitions
The physreq structure includes the following members:
paddr_t phys_align;
paddr_t phys_boundary;
uchar_t phys_dmasize;
uchar_t phys_max_scgth;
uchar_t phys_flags;
Structure members
phys_align
-
Specifies the constraint on the alignment
of the starting physical address, if any.
The starting address of any buffer will be a multiple of
phys_align.
phys_align must be a power of 2.
phys_boundary
-
specifies an optional boundary constraint.
If it is non-zero, buffers will not span any addresses that are
multiples of
phys_boundary
.
If non-zero, phys_boundary
must be a power of 2.
phys_dmasize
-
Number of address bits used for DMA.
Specifies DMA-ability requirements, if any.
If it is non-zero, buffers will be allocated
in regions suitable for DMA access
with
phys_dmasize
bits of address.
phys_dmasize
should be set
to the number of bits in addresses
generated by the DMA controller
or device to be used for I/O.
Typically, phys_dmasize
is set to
the following values:
0-
DMA is not used.
24-
for ISA devices.
31-
Allocate memory below the physical 2GB boundary.
32-
for PCI, EISA, and MCA devices.
64-
For devices that support access to 64-bit physical memory space.
Do not use this value unless the hardware controller
supports 64-bit addresses.
Setting this member to a value more than
what the hardware supports can cause memory corruption.
The driver must set this parameter either directly
or by using the
dma_physreq(D3)
function.
dma_physreq( )
is used only with ISA and
EISA motherboard DMA.
It is not for use when the DMA engine
is part of the adapter
as it is with bus master devices.
For ISA and EISA devices,
phys_dmasize
should always be set to non-zero
(and physreq allocations should be used)
whenever the memory is to be accessed
by hardware devices other than the CPU.
This is true even for devices
that generate ``full'' addresses
(addresses with at least as many bits
as the memory bus interconnect).
In this way, drivers can be moved to other systems
with enhanced CPUs and/or memory subsystems
that allow for larger memory addresses.
phys_max_scgth
-
Maximum length of the scatter/gather list.
This field is used only by
buf_breakup(D3)
in the BA_SCGTH case
and by the
msgscgth(D3str)
function.
phys_flags
-
contains flags describing additional physical
properties of the memory.
This includes flags that are used only by the operating system
as well as flags that are exported to the driver.
At present, the only valid flag for the driver to set is
PREQ_PHYSCONTIG, indicating a physical contiguity constraint.
Applicable hardware
All
Version applicability
ddi:
1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp
Difference between versions
The phys_dmasize
member
cannot be set to values greater than 32
in drivers written for DDI versions prior to version 8.
References
buf_breakup(D3),
kmem_alloc_physreq(D3),
kmem_zalloc_physreq(D3),
physreq_alloc(D3),
physreq_free(D3),
physreq_prep(D3)
``DMA'' in HDK Technical Reference.
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005