udi_dma_limits(3udi)

---

Platform-specific allocation and access limits

SYNOPSIS

#include <udi.h>

typedef struct {

	udi_size_t max_legal_contig_alloc;

	udi_size_t max_safe_contig_alloc;

	udi_size_t cache_line_size;

} udi_dma_limits_t;
 
void udi_dma_limits (

	udi_dma_limits_t *dma_limits );
 
/* Guaranteed Minimum Allocation Size */
 

#define  UDI_DMA_MIN_ALLOC_LIMIT				4000
 

MEMBERS max_legal_contig_alloc is the maximum legal size of a single DMA-able memory element (one element in a udi_scgth_t scatter/gather list) that can be requested from udi_dma_mem_alloc or udi_dma_buf_map. Any request for a larger size will produce indeterminate results, which could include termination of the driver or region, or even a complete system abort.

max_safe_contig_alloc is the maximum size of a single DMA-able memory element that should be requested from udi_dma_mem_alloc or udi_dma_buf_map without being prepared to cancel an unsuccessful allocation.

cache_line_size is the size, in bytes, of the largest cache line that affects DMA-able memory.

DESCRIPTION udi_dma_limits_t reflects the DMA memory allocation limits available on a particular system, for a particular region. These limits may vary from region to region, but will remain constant for the life of a region.

The udi_dma_limits_t structure is passed back to a driver by a call to udi_dma_limits.

Since UDI can be implemented on a wide variety of systems from small embedded systems to large server systems, the ability to provide contiguous DMA-able memory through udi_dma_mem_alloc and udi_dma_buf_map can vary widely. udi_dma_limits allows drivers to adjust their allocation algorithms to best fit their environment.

There are two types of allocation limits: legal limits and safe limits. Legal limits represent the absolute upper bound on a single allocation. Drivers must not make requests that would exceed the legal limits.

Safe limits represent the maximum amount that a driver may safely request without arranging to deal with unsuccessful allocations. For any size greater than the safe limit (but not exceeding the legal limit), drivers must cancel the request (using udi_cancel) after a reasonable amount of time has expired. To do this, they must set a timer using udi_timer_start or udi_timer_start_repeating. Drivers may also cancel allocations below the safe limit, but they are not expected to do so.

The max_legal_contig_alloc and max_safe_contig_alloc limits affect the size of a DMA-able memory element (one element in a udi_scgth_t scatter/gather list), which must be contiguous in bus address space. In most cases, DMA constraints allow the environment sufficient flexibility to use smaller pieces; in such cases, these limits wouldn't matter. However, the following DMA and transfer constraints attributes could force the environment to use larger element sizes:

UDI_DMA_ELEMENT_GRANULARITY_BITS

UDI_DMA_SCGTH_MAX_ELEMENTS

UDI_DMA_NO_PARTIAL

UDI_XFER_GRANULARITY

All of the above allocation limits are guaranteed to be greater than or equal to UDI_DMA_MIN_ALLOC_LIMIT (4000 bytes). This means drivers don't need to check these limits for requests that don't exceed 4000 bytes.

The cache_line_size value may be used to set appropriate DMA constraints for devices that need data or "slop" aligned on cache line boundaries.

REFERENCES udi_limits_t, udi_dma_mem_alloc, udi_dma_buf_map, udi_cancel