1ddi_dma_sync(9F) Kernel Functions for Drivers ddi_dma_sync(9F)
2
6 ddi_dma_sync - synchronize CPU and I/O views of memory
7
9 #include <sys/ddi.h>
10 #include <sys/sunddi.h>
11 int ddi_dma_sync(ddi_dma_handle_t handle, off_t offset,
13 size_t length, uint_t type);
14
17 Solaris DDI specific (Solaris DDI).
18
20 handle The handle filled in by a call to ddi_dma_alloc_handle(9F).
21 offset The offset into the object described by the handle.
24 length The length, in bytes, of the area to synchronize. When length
27 is zero, the entire range starting from offset to the end of
28 the object has the requested operation applied to it.
29 type Indicates the caller's desire about what view of the memory
32 object to synchronize. The possible values are
33 DDI_DMA_SYNC_FORDEV, DDI_DMA_SYNC_FORCPU and
34 DDI_DMA_SYNC_FORKERNEL.
35
38 The ddi_dma_sync() function is used to selectively synchronize either a
39 DMA device's or a CPU's view of a memory object that has DMA resources
40 allocated for I/O . This may involve operations such as flushes of CPU
41 or I/O caches, as well as other more complex operations such as
42 stalling until hardware write buffers have drained.
43 This function need only be called under certain circumstances. When
46 resources are allocated for DMA using ddi_dma_addr_bind_handle() or
47 ddi_dma_buf_bind_handle(), an implicit ddi_dma_sync() is done. When DMA
48 resources are deallocated using ddi_dma_unbind_handle(9F), an implicit
49 ddi_dma_sync() is done. However, at any time between DMA resource
50 allocation and deallocation, if the memory object has been modified by
51 either the DMA device or a CPU and you wish to ensure that the change
52 is noticed by the party that did not do the modifying, a call to
53 ddi_dma_sync() is required. This is true independent of any attributes
54 of the memory object including, but not limited to, whether or not the
55 memory was allocated for consistent mode I/O (see
56 ddi_dma_mem_alloc(9F)) or whether or not DMA resources have been allo‐
57 cated for consistent mode I/O (see ddi_dma_addr_bind_handle(9F) or
58 ddi_dma_buf_bind_handle(9F)).
59 If a consistent view of the memory object must be ensured between the
62 time DMA resources are allocated for the object and the time they are
63 deallocated, you must call ddi_dma_sync() to ensure that either a CPU
64 or a DMA device has such a consistent view.
65 What to set type to depends on the view you are trying to ensure con‐
68 sistency for. If the memory object is modified by a CPU, and the object
69 is going to be read by the DMA engine of the device, use
70 DDI_DMA_SYNC_FORDEV. This ensures that the device's DMA engine sees any
71 changes that a CPU has made to the memory object. If the DMA engine for
72 the device has written to the memory object, and you are going to read
73 (with a CPU) the object (using an extant virtual address mapping that
74 you have to the memory object), use DDI_DMA_SYNC_FORCPU. This ensures
75 that a CPU's view of the memory object includes any changes made to the
76 object by the device's DMA engine. If you are only interested in the
77 kernel's view (kernel-space part of the CPU's view) you may use
78 DDI_DMA_SYNC_FORKERNEL. This gives a hint to the system—that is, if it
79 is more economical to synchronize the kernel's view only, then do so;
80 otherwise, synchronize for CPU.
81
83 The ddi_dma_sync() function returns:
84 DDI_SUCCESS Caches are successfully flushed.
86 DDI_FAILURE The address range to be flushed is out of the address
89 range established by ddi_dma_addr_bind_handle(9F) or
90 ddi_dma_buf_bind_handle(9F).
91
94 The ddi_dma_sync() function can be called from user, interrupt, or ker‐
95 nel context.
96
98 ddi_dma_addr_bind_handle(9F), ddi_dma_alloc_handle(9F),
99 ddi_dma_buf_bind_handle(9F), ddi_dma_mem_alloc(9F), ddi_dma_unbind_han‐
100 dle(9F)
101 Writing Device Drivers
104SunOS 5.11 16 Jan 2006 ddi_dma_sync(9F)