From c19a4c78bfe710ff3831ac57a03fc1eb686d4398 Mon Sep 17 00:00:00 2001 From: jhb Date: Fri, 28 Sep 2018 17:40:06 +0000 Subject: [PATCH] MFC 337673: Add an overview section to bus_dma.9. Describe the role of tags and mapping objects as abstractions. Describe static vs dynamic transaction types and give a brief overview of the set of functions and object life cycles used for static vs dynamic. While here, fix a few other typos and expand a bit on parent tags. git-svn-id: svn://svn.freebsd.org/base/stable/10@339003 ccf9f872-aa2e-dd11-9fc8-001c23d0bc1f --- share/man/man9/bus_dma.9 | 156 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 149 insertions(+), 7 deletions(-) diff --git a/share/man/man9/bus_dma.9 b/share/man/man9/bus_dma.9 index fa23fbff2..22ed951d9 100644 --- a/share/man/man9/bus_dma.9 +++ b/share/man/man9/bus_dma.9 @@ -53,7 +53,7 @@ .\" $FreeBSD$ .\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ .\" -.Dd July 17, 2013 +.Dd August 11, 2018 .Dt BUS_DMA 9 .Os .Sh NAME @@ -135,11 +135,149 @@ It provides the client with flexibility and simplicity by abstracting machine dependent issues like setting up DMA mappings, handling cache issues, bus specific features and limitations. +.Sh OVERVIEW +A tag structure +.Vt ( bus_dma_tag_t ) +is used to describe the properties of a group of related DMA +transactions. +One way to view this is that a tag describes the limitations of a DMA engine. +For example, if a DMA engine in a device is limited to 32-bit addresses, +that limitation is specified by a parameter when creating the tag +for that device. +Similarly, a tag can be marked as requiring buffers whose addresses are +aligned to a specific boundary. +.Pp +Some devices may require multiple tags to describe DMA +transactions with differing properties. +For example, a device might require 16-byte alignment of its descriptor ring +while permitting arbitrary alignment of I/O buffers. +In this case, +the driver must create one tag for the descriptor ring and a separate tag for +I/O buffers. +If a device has restrictions that are common to all DMA transactions +in addition to restrictions that differ between unrelated groups of +transactions, +the driver can first create a +.Dq parent +tag that decribes the common restrictions. +The per-group tags can then inherit these restrictions from this +.Dq parent +tag rather than having to list them explicitly when creating the per-group tags. +.Pp +A mapping structure +.Vt ( bus_dmamap_t ) +represents a mapping of a memory region for DMA. +On systems with I/O MMUs, +the mapping structure tracks any I/O MMU entries used by a request. +For DMA requests that require bounce pages, +the mapping tracks the bounce pages used. +.Pp +To prepare for one or more DMA transactions, +a mapping must be bound to a memory region by calling one of the +.Fn bus_dmamap_load +functions. +These functions configure the mapping which can include programming entries +in an I/O MMU and/or allocating bounce pages. +An output of these functions +(either directly or indirectly by invoking a callback routine) +is the list of scatter/gather address ranges a consumer can pass to a DMA +engine to access the memory region. +When a mapping is no longer needed, +the mapping must be unloaded via +.Fn bus_dmamap_unload . +.Pp +Before and after each DMA transaction, +.Fn bus_dmamap_sync +must be used to ensure that the correct data is used by the DMA engine and +the CPU. +If a mapping uses bounce pages, +the sync operations copy data between the bounce pages and the memory region +bound to the mapping. +Sync operations also handle architecture-specific details such as CPU cache +flushing and CPU memory operation ordering. +.Sh STATIC VS DYNAMIC +.Nm +handles two types of DMA transactions: static and dynamic. +Static transactions are used with a long-lived memory region that is reused +for many transactions such as a descriptor ring. +Dynamic transactions are used for transfers to or from transient buffers +such as I/O buffers holding a network packet or disk block. +Each transaction type uses a different subset of the +.Nm +API. +.Ss Static Transactions +Static transactions use memory regions allocated by +.Nm . +Each static memory region is allocated by calling +.Fn bus_dmamem_alloc . +This function requires a valid tag describing the properties of the +DMA transactions to this region such as alignment or address restrictions. +Multiple regions can share a single tag if they share the same restrictions. +.Pp +.Fn bus_dmamem_alloc +allocates a memory region along with a mapping object. +The associated tag, memory region, and mapping object must then be passed to +.Fn bus_dmamap_load +to bind the mapping to the allocated region and obtain the +scatter/gather list. +.Pp +It is expected that +.Fn bus_dmamem_alloc +will attempt to allocate memory requiring less expensive sync operations +(for example, implementations should not allocate regions requiring bounce +pages), +but sync operations should still be used. +For example, a driver should use +.Fn bus_dmamap_sync +in an interrupt handler before reading descriptor ring entries written by the +device prior to the interrupt. +.Pp +When a consumer is finished with a memory region, +it should unload the mapping via +.Fn bus_dmamap_unload +and then release the memory region and mapping object via +.Fn bus_dmamem_free . +.Ss Dynamic Transactions +Dynamic transactions map memory regions provided by other parts of the system. +A tag must be created via +.Fn bus_dma_tag_create +to describe the DMA transactions to and from these memory regions, +and a pool of mapping objects must be allocated via +.Fn bus_dmamap_create +to track the mappings of any in-flight transactions. +.Pp +When a consumer wishes to schedule a transaction for a memory region, +the consumer must first obtain an unused mapping object from its pool +of mapping objects. +The memory region must be bound to the mapping object via one of the +.Fn bus_dmamap_load +functions. +Before scheduling the transaction, +the consumer should sync the memory region via +.Fn bus_dmamap_sync +with one or more of the +.Dq PRE +flags. +After the transaction has completed, +the consumer should sync the memory region via +.Fn bus_dmamap_sync +with one or more of the +.Dq POST +flags. +The mapping can then be unloaded via +.Fn bus_dmamap_unload , +and the mapping object can be returned to the pool of unused mapping objects. +.Pp +When a consumer is no longer scheduling DMA transactions, +the mapping objects should be freed via +.Fn bus_dmamap_destroy , +and the tag should be freed via +.Fn bus_dma_tag_destroy . .Sh STRUCTURES AND TYPES .Bl -tag -width indent .It Vt bus_dma_tag_t A machine-dependent (MD) opaque type that describes the -characteristics of DMA transactions. +characteristics of a group of DMA transactions. DMA tags are organized into a hierarchy, with each child tag inheriting the restrictions of its parent. This allows all devices along the path of DMA transactions @@ -340,14 +478,18 @@ Releases and/or unlocks the client locking primitive. .It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ "highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ "flags" "lockfunc" "lockfuncarg" "*dmat" -Allocates a device specific DMA tag, and initializes it according to +Allocates a DMA tag, and initializes it according to the arguments provided: .Bl -tag -width ".Fa filtfuncarg" .It Fa parent -Indicates restrictions between the parent bridge, CPU memory, and the +A parent tag from which to inherit restrictions. +The restrictions passed in other arguments can only further tighten the +restrictions inherited from the parent tag. +.Pp +All tags created by a device driver must inherit from the tag returned by +.Fn bus_get_dma_tag +to honor restrictions between the parent bridge, CPU memory, and the device. -Each device must use a master parent tag by calling -.Fn bus_get_dma_tag . .It Fa alignment Alignment constraint, in bytes, of any mappings created using this tag. The alignment must be a power of 2. @@ -391,7 +533,7 @@ and a .Fa lowaddr of .Dv BUS_SPACE_MAXADDR_24BIT . -Some implementations requires that some region of device visible +Some implementations require that some region of device visible address space, overlapping available host memory, be outside the window. This area of -- 2.42.0