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.