Lines Matching +full:memory +full:- +full:to +full:- +full:memory

10 .\" 2. The name of the author may not be used to endorse or promote products
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
28 .\" This code is derived from software contributed to The NetBSD Foundation
43 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
46 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
163 Direct Memory Access (DMA) is a method of transferring data
165 A DMA transaction can be achieved between device to memory,
166 device to device, or memory to memory.
170 API is a bus, device, and machine-independent (MI) interface to
179 is used to describe the properties of a group of related DMA
181 One way to view this is that a tag describes the limitations of a DMA engine.
182 For example, if a DMA engine in a device is limited to 32-bit addresses,
186 aligned to a specific boundary.
188 Some devices may require multiple tags to describe DMA
190 For example, a device might require 16-byte alignment of its descriptor ring
195 If a device has restrictions that are common to all DMA transactions
196 in addition to restrictions that differ between unrelated groups of
201 The per-group tags can then inherit these restrictions from this
203 tag rather than having to list them explicitly when creating the per-group tags.
207 represents a mapping of a memory region for DMA.
214 a mapping must be bound to a memory region by calling one of the
221 is the list of scatter/gather address ranges a consumer can pass to a DMA
222 engine to access the memory region.
229 must be used to ensure that the correct data is used by the DMA engine and
232 the sync operations copy data between the bounce pages and the memory region
233 bound to the mapping.
234 Sync operations also handle architecture-specific details such as CPU cache
235 flushing and CPU memory operation ordering.
239 Static transactions are used with a long-lived memory region that is reused
241 Dynamic transactions are used for transfers to or from transient buffers
247 Static transactions use memory regions allocated by
249 Each static memory region is allocated by calling
252 DMA transactions to this region such as alignment or address restrictions.
256 allocates a memory region along with a mapping object.
257 The associated tag, memory region, and mapping object must then be passed to
259 to bind the mapping to the allocated region and obtain the
264 will attempt to allocate memory requiring less expensive sync operations
271 device prior to the interrupt.
273 When a consumer is finished with a memory region,
276 and then release the memory region and mapping object via
279 Dynamic transactions map memory regions provided by other parts of the system.
282 to describe the DMA transactions to and from these memory regions,
285 to track the mappings of any in-flight transactions.
287 When a consumer wishes to schedule a transaction for a memory region,
290 The memory region must be bound to the mapping object via one of the
294 the consumer should sync the memory region via
300 the consumer should sync the memory region via
307 and the mapping object can be returned to the pool of unused mapping objects.
315 .Bl -tag -width indent
317 A machine-dependent (MD) opaque type that describes the
322 to contribute to the constraints of those transactions.
329 a driver can over-ride individual fields to suit its needs.
331 .Bd -literal
353 .Bl -tag -width indent
358 Address filters can be specified during tag creation to allow
363 argument is specified by the client during tag creation to be passed to all
371 .Ql trunc_page(testaddr) + PAGE_SIZE - 1 ,
374 can be accommodated by the device and non-zero otherwise.
378 A machine-dependent type that describes individual
381 .Bd -literal
391 Although the DMA segments returned by a mapping call will adhere to
393 (e.g.\& a conversion from host byte order to the device's byte order) is
394 almost always required when presenting segment information to the device.
396 A machine-dependent opaque type describing an individual mapping.
397 One map is used for each memory allocation that will be loaded.
400 While the value of the map may evaluate to
418 .Bl -tag -width indent
426 is the callback argument passed to dmamap load functions.
450 .Bl -tag -width indent
461 Memory synchronization operation specifier.
462 Bus DMA requires explicit synchronization of memory with its device
463 visible mapping in order to guarantee memory coherency.
467 to be communicated to the system so that the correct coherency measures
470 though it only makes sense to combine PRE flags or POST flags, not both.
473 description below for more details on how to use these operations.
475 All operations specified below are performed from the host memory point of view,
476 where a read implies data coming from the device to the host memory, and a write
477 implies data going from the host memory to the device.
479 where reading a network packet or storage sector corresponds to a read operation
482 .Bl -tag -width ".Dv BUS_DMASYNC_POSTWRITE"
484 Perform any synchronization required prior to an update of host memory by the
487 Perform any synchronization required after an update of host memory by the CPU
488 and prior to device access to host memory.
490 Perform any synchronization required after an update of host memory by the
491 device and prior to CPU access to host memory.
493 Perform any synchronization required after device access to host memory.
498 within busdma whenever a client lock needs to be manipulated.
504 If the load operation does not need to be deferred, then it
508 .Bl -tag -width indent
515 argument is specified by the client during tag creation to be passed to all
519 argument specifies the lock operation to perform.
537 Operations to be performed by the client-specified
539 .Bl -tag -width ".Dv BUS_DMA_UNLOCK"
547 .Bl -tag -width indent
551 Allocates a DMA tag, and initializes it according to
553 .Bl -tag -width ".Fa filtfuncarg"
555 A parent tag from which to inherit restrictions.
561 to honor restrictions between the parent bridge, CPU memory, and the
569 Hardware requiring DMA transfers to start on a multiple of 4K
573 Boundary constraint, in bytes, of the target DMA memory region.
587 and less than or equal to
597 Similarly a device that can only perform DMA to addresses below
607 address space, overlapping available host memory, be outside the
610 .Ql safe memory
611 is used to bounce requests that would otherwise conflict with
631 .Bl -tag -width ".Dv BUS_DMA_ALLOCNOW"
633 Pre-allocate enough resources to handle at least one map load operation on
641 Also, due to resource sharing with other tags, this flag does not guarantee
645 Indicate that the DMA engine and CPU are cache-coherent.
646 Cached memory may be used to back allocations created by
658 needs to manipulate a lock on behalf of the client.
665 Optional argument to be passed to the function specified by
668 Pointer to a bus_dma_tag_t where the resulting DMA tag will
674 if sufficient memory is not available for tag creation
703 argument is non-NULL, this parent tag is associated with the template and
713 All return values are identical to
718 Copies the fields from an existing tag to a template.
719 The template does not need to be initialized first.
728 This is not meant to be called directly, use
733 key-value parameters.
735 it into a key-value structure that is directly usable as a parameter argument.
737 .Bd -literal
753 .Bl -tag -width ".Fa nsegments"
758 .Bl -tag -width ".Dv BUS_DMA_COHERENT"
760 Attempt to map the memory loaded with this map such that cache sync
762 This flag is typically set on maps when the memory loaded with these will
764 and as opposed to streamable data such as receive and transmit buffers.
770 Pointer to a
777 if sufficient memory is not available for creating the
782 .Bl -tag -width ".Fa dmat"
784 DMA tag used to allocate
787 The DMA map to destroy.
804 .Bl -tag -width ".Fa buflen"
806 DMA tag used to allocate
811 A kernel virtual address pointer to a contiguous (in KVA) buffer, to be
820 later, but the load operation will still return immediately to the caller.
822 load returns, and code should be structured appropriately to handle this.
826 .Bl -tag -width ".Dv BUS_DMA_NOWAIT"
831 The generated transactions to and from the virtual page are non-cacheable.
835 Return values to the caller are as follows:
836 .Bl -tag -width ".Er EINPROGRESS"
839 The status of the mapping has been delivered to the callback.
847 This may result in out-of-order processing of requests.
848 If the caller requires the order of requests to be preserved,
849 then the caller is required to stall subsequent requests until a pending
852 The load request has failed due to insufficient resources, and the caller
869 argument used to create the dma tag
876 .Bl -tag -width ".Er EINPROGRESS"
891 which maps buffers pointed to by
895 may point to either a mapped or unmapped buffer.
899 which maps data pointed to by
905 .Bl -tag -width ".Er CAM_DATA_SG_PADDR"
917 attached to the CCB.
923 .Bl -item -offset indent -compact
934 which maps the input buffer pointed to by
944 which maps the crypto data buffer pointed to by
958 argument is also passed to the callback routine, which
964 Mbuf chains are assumed to be in kernel virtual address space.
987 which maps buffers pointed to by
992 argument is also passed to the callback routine, which contains the size of
995 .Fa uio->uio_resid .
1003 .Fa uio->uio_segflg
1009 .Fa "uio->uio_td->td_proc" Ns 's
1011 User space memory must be in-core and wired prior to attempting a map
1018 .Bl -tag -width ".Fa dmam"
1020 DMA tag used to allocate
1023 The DMA map that is to be unloaded.
1028 This must be done explicitly by a call to
1030 prior to unloading the map.
1033 memory referenced by that mapping.
1035 .Bl -tag -width ".Fa dmat"
1037 DMA tag used to allocate
1040 The DMA mapping to be synchronized.
1042 Type of synchronization operation to perform.
1052 is the method used to ensure that CPU's and device's direct
1053 memory access (DMA) to shared
1054 memory is coherent.
1055 For example, the CPU might be used to set up the contents of a buffer
1056 that is to be made available to a device.
1058 memory, the buffer must be loaded and a DMA sync operation of
1066 Conversely, suppose a device updates memory that is to be read by a CPU.
1070 The CPU will only be able to see the results of this memory update
1078 Allocates memory that is mapped into KVA at the address returned
1086 .Bl -tag -width ".Fa alignment"
1090 Pointer to a pointer that will hold the returned KVA mapping of
1094 .Bl -tag -width ".Dv BUS_DMA_NOWAIT"
1098 The routine is not allowed to wait for resources.
1103 Attempt to map this memory in a coherent fashion.
1113 Causes the allocated memory to be set to all zeros.
1115 The allocated memory will not be cached in the processor caches.
1116 All memory accesses appear on the bus and are executed
1123 Strong Uncacheable PAT to be set for the allocated virtual address range.
1126 Pointer to a
1131 The size of memory to be allocated is
1133 as specified in the call to
1142 An initial load operation is required to obtain the bus address of the allocated
1143 memory, and an unload operation is required before freeing the memory, as
1149 Although an explicit load is not required for each access to the memory
1153 section still apply and should be used to achieve portability on architectures
1158 if sufficient memory is not available for completing
1161 Frees memory previously allocated by
1166 .Bl -tag -width ".Fa vaddr"
1170 Kernel virtual address of the memory.
1172 DMA map to be invalidated.
1176 Behavior is undefined if invalid arguments are passed to
1194 The first is a private global lock that is used to synchronize access to the
1196 This lock is strictly a leaf lock that is only used internally to
1198 and is not exposed to clients of the API.
1204 the most efficient way to protect the tag resources is through the lock that
1220 .Bl -item -offset indent -compact
1239 There is one exception to this rule.
1240 It is common practice to call some of these functions during driver start-up
1243 different threads during this operation, it is safe to not hold a lock for
1250 due to memory or resource allocation.
1252 called with any non-sleepable locks held:
1254 .Bl -item -offset indent -compact
1274 .%T "A Machine-Independent DMA Framework for NetBSD"
1290 The alterations to the original API were aimed to remove the need for
1295 while allowing callers to queue up on scarce resources.
1305 .An -nosplit