docs/53271: the bus_dma man page fails to document alignment restrictions

[harti at FreeBSD.org]

>Number:         53271
>Category:       docs
>Synopsis:       the bus_dma man page fails to document alignment restrictions
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Jun 13 02:00:30 PDT 2003
>Closed-Date:
>Last-Modified:
>Originator:     Hartmut Brandt
>Release:        FreeBSD 5.1-CURRENT i386
>Organization:
Fraunhofer Fokus
>Environment:
System: FreeBSD beagle.fokus.fraunhofer.de 5.1-CURRENT FreeBSD 5.1-CURRENT #0: Thu Jun 12 11:30:16 CEST 2003 hbb at beagle.fokus.fraunhofer.de:/opt/obj/usr/src/sys/BEAGLE i386


	
>Description:

While it is possible to specify an alignment to the bus_dma_tag_create
function this alignment is ignored in many (if not most cases). For i386
it is only effective if the tag is used to allocate memory via
bus_dmamem_alloc() and that memory is larger than PAGE_SIZE. For sparc64
the minimum alignment that may be specified seems to be a IO_PAGE_SIZE.
Other architectures probably have equivalent restrictions.

Many io devices need buffers that are aligned to 4-byte or other boundaries.
In these cases specifying an alignment does NOT help.

This should be documented as an implementation limitation, because it can
cause driver developers much grief searching for the problem.

	
>How-To-Repeat:

look at sys/i386/i386/bus_machdep.c, sys/sparc64/sparc64/{bus_machdep,iommu}.c

	
>Fix:

Add something like the following to either the paragraph about
bus_dma_tag_create or into a BUGS or IMPLEMENTATION NOTES section:

The alignment argument to bus_dma_tag_create cannot be used to enforce
alignments that are lesser than a PAGE_SIZE. Generally it should be assumed that
the argument is ignored by the bus_dma code.
	


>Release-Note:
>Audit-Trail:
>Unformatted: