Date: Mon, 7 Jul 97 13:28:58 PDT
From: wmb@FirmWorks.COM (Mitch Bradley)
Subject: Item #410: Proposal for "dma-ranges" property

P1275 Openboot Working Group Proposal -- Proposal #:410 Ver 1

Title:          Standard "dma-ranges" Property

Author:         Mitch Bradley

Date:           26-Jun-97

Ed/Tech:        Technical

Synopsis:       Create standard definition for "dma-ranges" S

Doc & Version:  Core Doc, Recommended Practice

Scope:          Recommended practice to all implementations

Problem:        There is no property to describe the DMA structure
                of a system.

Proposal:

Create a recommended practice, standardizing the following property name:

"dma-ranges"                                              S

   Standard *property name* to describe the DMA structure of a device.

   Memory-mapped-busses supporting direct memory access (DMA) require a way
   to define the relationship between the physical address spaces of the
   parent and child nodes.  The "dma-ranges" property provides that
   capability.  The property can appear in any node for a memory-mapped bus
   that has DMA capability.  

   The value of the "dma-ranges" property describes the correspondence
   between the physical address space defined by a memory-mapped-bus node
   (the "child address space") and the physical address space of that bus
   node's parent (the "parent address space").  The "dma-ranges" property
   value is a sequence of 

	child-address  parent-address  child-size

   specifications.  Each such specification describes a contiguous DMA
   address range, giving the base addresses of the range in both the child
   and parent address spaces and the length of the range, which is expressed
   in the child's size format.

   Each "child-address" is a physical address, encoded as with encode-phys,
   within the child address space (as with all such physical addresses, the
   number of cells therein is bus-dependent, and can be determined from the
   "#address-cells" property of the node that defines the address space,
   which in this case is the node that contains the "dma-ranges" property).

   Each "parent-address" is a physical address, encoded as with encode-phys,
   within the parent address space (as with all such physical addresses, the
   number of cells therein is bus-dependent, and can be determined from the
   "#address-cells" property of the node that defines the address space,
   which in this case is the node that is the parent of the node that
   contains the "dma-ranges" property).

   Each "child-size" is a sequence of integers, each encoded as with
   encode-int.  The number of integers is the same as for the "size"
   component of a "reg" property entry for a child device (it can be
   determined from the "#size-cells" property of the node that contains
   the "dma-ranges" property).

   As a special case, a "dma-ranges" property may be present in the
   root node of the device tree.  In this case, the property value
   describes the ranges of DMA addresses that the system bus can
   accept.  In this case, the length of the parent-address portion
   of each entry in the property value is 0 (because the root node
   has no parent), so the format reduces to:

	child-address child-size

   See also: "#address-cells", "#size-cells".

Discussion:

The convention that "#address-cells" is 0 for the non-existent parent
of the root node is new; this is the first appearance of that convention.





[ P1275 Item #410 -- Received: Mon Jul  7 13:24:07 PDT 1997 ]