share/man/man9f/ddi_dma_sync.9f

   1 '\" te
   2 .\"  Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DDI_DMA_SYNC 9F "Jan 16, 2006"
   7 .SH NAME
   8 ddi_dma_sync \- synchronize CPU and I/O views of memory
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15 \fBint\fR \fBddi_dma_sync\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBoff_t\fR \fIoffset\fR,
  16      \fBsize_t\fR \fIlength\fR, \fBuint_t\fR \fItype\fR);
  17 .fi
  18
  19 .SH INTERFACE LEVEL
  20 .sp
  21 .LP
  22 Solaris DDI specific (Solaris DDI).
  23 .SH PARAMETERS
  24 .sp
  25 .ne 2
  26 .na
  27 \fB\fIhandle\fR\fR
  28 .ad
  29 .RS 10n
  30 The \fIhandle\fR filled in by a call to \fBddi_dma_alloc_handle\fR(9F).
  31 .RE
  32
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIoffset\fR\fR
  37 .ad
  38 .RS 10n
  39 The offset into the object described by the \fIhandle\fR.
  40 .RE
  41
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fIlength\fR\fR
  46 .ad
  47 .RS 10n
  48 The length, in bytes, of the area to synchronize. When \fIlength\fR is zero,
  49 the entire range starting from \fIoffset\fR to the end of the object has the
  50 requested operation applied to it.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fItype\fR\fR
  57 .ad
  58 .RS 10n
  59 Indicates the caller's desire about what view of the memory object to
  60 synchronize. The possible values are \fBDDI_DMA_SYNC_FORDEV\fR,
  61 \fBDDI_DMA_SYNC_FORCPU\fR and \fBDDI_DMA_SYNC_FORKERNEL\fR.
  62 .RE
  63
  64 .SH DESCRIPTION
  65 .sp
  66 .LP
  67 The \fBddi_dma_sync()\fR function is used to selectively synchronize either a
  68 \fBDMA\fR device's or a \fBCPU\fR's view of a memory object that has \fBDMA\fR
  69 resources allocated for I/O . This may involve operations such as flushes of
  70 \fBCPU\fR or I/O caches, as well as other more complex operations such as
  71 stalling until hardware write buffers have drained.
  72 .sp
  73 .LP
  74 This function need only be called under certain circumstances. When resources
  75 are allocated for \fBDMA\fR using  \fBddi_dma_addr_bind_handle()\fR or
  76 \fBddi_dma_buf_bind_handle()\fR, an implicit \fBddi_dma_sync()\fR is done. When
  77 \fBDMA\fR resources are deallocated using \fBddi_dma_unbind_handle\fR(9F), an
  78 implicit \fBddi_dma_sync()\fR is done. However, at any time between  \fBDMA\fR
  79 resource allocation and deallocation, if the memory object has been modified by
  80 either the \fBDMA\fR device or a \fBCPU\fR and you wish to ensure that the
  81 change is noticed by the party that did \fBnot\fR do the modifying, a call to
  82 \fBddi_dma_sync()\fR is required. This is true independent of any attributes of
  83 the memory object including, but not limited to, whether or not the memory was
  84 allocated for consistent mode I/O (see \fBddi_dma_mem_alloc\fR(9F)) or whether
  85 or not  \fBDMA\fR resources have been allocated for consistent mode I/O (see
  86 \fBddi_dma_addr_bind_handle\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F)).
  87 .sp
  88 .LP
  89 If a consistent view of the memory object must be ensured between the time
  90 \fBDMA\fR resources are allocated for the object and the time they are
  91 deallocated, you \fBmust\fR call \fBddi_dma_sync()\fR to ensure that either a
  92 \fBCPU\fR or a \fBDMA\fR device has such a consistent view.
  93 .sp
  94 .LP
  95 What to set \fBtype\fR to depends on the view you are trying to ensure
  96 consistency for. If the memory object is modified by a \fBCPU\fR, and the
  97 object is going to be \fBread\fR by the \fBDMA\fR engine of the device, use
  98 \fBDDI_DMA_SYNC_FORDEV\fR. This ensures that the device's \fBDMA\fR engine sees
  99 any changes that a \fBCPU\fR has made to the memory object. If the \fBDMA\fR
 100 engine for the device has \fBwritten\fR to the memory object, and you are going
 101 to \fBread\fR (with a \fBCPU\fR) the object (using an extant virtual address
 102 mapping that you have to the memory object), use \fBDDI_DMA_SYNC_FORCPU\fR.
 103 This ensures that a \fBCPU\fR's view of the memory object includes any changes
 104 made to the object by the device's \fBDMA\fR engine. If you are only interested
 105 in the kernel's view (kernel-space part of the \fBCPU\fR's view) you may use
 106 \fBDDI_DMA_SYNC_FORKERNEL\fR. This gives a hint to the system\(emthat is, if it
 107 is more economical to synchronize the kernel's view only, then do so;
 108 otherwise, synchronize for \fBCPU\fR.
 109 .SH RETURN VALUES
 110 .sp
 111 .LP
 112 The \fBddi_dma_sync()\fR function returns:
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBDDI_SUCCESS\fR\fR
 117 .ad
 118 .RS 15n
 119 Caches are successfully flushed.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBDDI_FAILURE\fR\fR
 126 .ad
 127 .RS 15n
 128 The address range to be flushed is out of the address range established by
 129 \fBddi_dma_addr_bind_handle\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F).
 130 .RE
 131
 132 .SH CONTEXT
 133 .sp
 134 .LP
 135 The \fBddi_dma_sync()\fR function can be called from user, interrupt, or kernel
 136 context.
 137 .SH SEE ALSO
 138 .sp
 139 .LP
 140 \fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F),
 141 \fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_mem_alloc\fR(9F),
 142 \fBddi_dma_unbind_handle\fR(9F)
 143 .sp
 144 .LP
 145 \fIWriting Device Drivers\fR