Hallo, dies ist ein Test.
PWD: /www/data-lst1/unixsoft/unixsoft/kaempfer/.public_html
Running in File Mode
Relative path: ././../../../../../../usr/man/man9s/ddi_dma_attr.9s
Real path: /usr/share/man/man9s/ddi_dma_attr.9s
Zurück
'\" te .\" Copyright (c) 2009, 2014, Oracle and/or its affiliates. All rights reserved. .TH ddi_dma_attr 9S "9 Sep 2014" "Oracle Solaris 11.4" "Kernel & Driver Data Structures" .SH NAME ddi_dma_attr \- DMA attributes structure .SH SYNOPSIS .LP .nf #include <sys/ddidmareq.h> .fi .SH INTERFACE LEVEL .sp .LP Solaris DDI specific (Solaris DDI) .SH DESCRIPTION .sp .LP A \fBddi_dma_attr_t\fR structure describes device- and \fBDMA\fR engine-specific attributes necessary to allocate \fBDMA\fR resources for a device. The driver might have to extend the attributes with bus-specific information, depending on the bus to which the device is connected. .SH STRUCTURE MEMBERS .sp .in +2 .nf uint_t dma_attr_version; /* version number */ uint64_t dma_attr_addr_lo; /* low DMA address range */ uint64_t dma_attr_addr_hi; /* high DMA address range */ uint64_t dma_attr_count_max; /* DMA counter register */ uint64_t dma_attr_align; /* DMA address alignment */ uint_t dma_attr_burstsizes; /* DMA burstsizes */ uint32_t dma_attr_minxfer; /* min effective DMA size */ uint64_t dma_attr_maxxfer; /* max DMA xfer size */ uint64_t dma_attr_seg; /* segment boundary */ int dma_attr_sgllen; /* s/g list length */ uint32_t dma_attr_granular; /* granularity of device */ uint_t dma_attr_flags; /* DMA transfer flags */ \fI\fR .fi .in -2 .sp .sp .LP The \fBdma_attr_version\fR stores the version number of this \fBDMA\fR attribute structure. It should be set to \fBDMA_ATTR_V0\fR. .sp .LP The \fBdma_attr_addr_lo\fR and \fBdma_attr_addr_hi\fR fields specify the address range the device's \fBDMA\fR engine can access. The \fBdma_attr_addr_lo\fR field describes the inclusive lower 64-bit boundary. The \fBdma_attr_addr_hi\fR describes the inclusive upper 64-bit boundary. The system ensures that allocated \fBDMA\fR resources are within the range specified. See \fBddi_dma_cookie\fR(9S). .sp .LP The \fBdma_attr_count_max\fR describes an inclusive upper bound for the device's \fBDMA\fR counter register. For example, \fB0xFFFFFF\fR would describe a \fBDMA\fR engine with a 24-bit counter register. \fBDMA\fR resource allocation functions have to break up a \fBDMA\fR object into multiple \fBDMA\fR cookies if the size of the object exceeds the size of the \fBDMA\fR counter register. .sp .LP The \fBdma_attr_align\fR specifies alignment requirements for allocated \fBDMA\fR resources. This field can be used to force more restrictive alignment than imposed by \fBdma_attr_burstsizes\fR or \fBdma_attr_minxfer\fR, such as alignment at a page boundary. Most drivers set this field to 1, indicating byte alignment. .sp .LP The \fBdma_attr_align\fR only specifies alignment requirements for allocated \fBDMA\fR resources. The buffer passed to \fBddi_dma_addr_bind_handle\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F) must have an equally restrictive alignment (see \fBddi_dma_mem_alloc\fR(9F)). .sp .LP The \fBdma_attr_burstsizes\fR field describes the possible burst sizes the \fBDMA\fR engine of a device can accept. The format of the data sizes is binary, encoded in terms of powers of two. When \fBDMA\fR resources are allocated, the system can modify the \fBburstsizes\fR value to reflect the system limits. The driver must use the allowable \fBburstsizes\fR to program the \fBDMA\fR engine. See \fBddi_dma_burstsizes\fR(9F). .sp .LP The \fBdma_attr_minxfer\fR field describes the minimum effective \fBDMA\fR access size in units of bytes. \fBDMA\fR resources can be modified, depending on the presence and use of \fBI/O\fR caches and write buffers between the \fBDMA\fR engine and the memory object. This field is used to determine alignment and padding requirements for \fBddi_dma_mem_alloc\fR(9F). .sp .LP The \fBdma_attr_maxxfer\fR field describes the maximum effective \fBDMA\fR access size in units of bytes. .sp .LP The \fBdma_attr_seg\fR field specifies segment boundary restrictions for allocated \fBDMA\fR resources. The system allocates \fBDMA\fR resources for the device so that the object does not span the segment boundary specified by \fBdma_attr_seg\fR. For example, a value of \fB0xFFFF\fR means a \fBDMA\fR cookie must not cross a 64-Kbyte boundary. \fBDMA\fR resource allocation functions might have to break up a \fBDMA\fR object into multiple \fBDMA\fR cookies to enforce segment boundary restrictions. In this case, the transfer must be performed using scatter-gather \fBI/O\fR or multiple \fBDMA\fR windows. .sp .LP The \fBdma_attr_sgllen\fR field describes the length of the \fBDMA\fR scatter/gather list of a device. Possible values are as follows: .sp .ne 2 .mk .na \fB\fB< 0\fR\fR .ad .RS 7n .rt Device \fBDMA\fR engine is not constrained by the size, for example, with\fBDMA\fR chaining. .RE .sp .ne 2 .mk .na \fB\fB= 0\fR\fR .ad .RS 7n .rt Reserved. .RE .sp .ne 2 .mk .na \fB\fB= 1\fR\fR .ad .RS 7n .rt Device \fBDMA\fR engine does not support scatter/gather such as third party \fBDMA\fR. .RE .sp .ne 2 .mk .na \fB\fB> 1\fR\fR .ad .RS 7n .rt Device \fBDMA\fR engine uses scatter/gather. The \fBdma_attr_sgllen\fR value is the maximum number of entries in the list. .RE .sp .LP The \fBdma_attr_granular\fR field gives the granularity in bytes of the \fBDMA\fR transfer ability of the device. This value can be used to specify the sector size of a mass storage device. When a bind operation requires a partial mapping, this field is used to ensure that the sum of the sizes of the cookies in every \fBDMA\fR window, except the last one, is a whole multiple of granularity. However, if the device does not have a scatter-gather capability, it is impossible for the DDI to ensure the granularity. In this case, the value of the \fBdma_attr_granular\fR field should be \fB1\fR. .sp .LP The \fBdma_attr_flags\fR field can be set to a combination of: .sp .ne 2 .mk .na \fB\fBDDI_DMA_FORCE_PHYSICAL\fR\fR .ad .br .sp .6 .RS 4n Some platforms, such as SPARC systems, support what is called Direct Virtual Memory Access (\fBDVMA\fR). On these platforms, the device is provided with a virtual address by the system in order to perform the transfer. In this case, the underlying platform provides an \fIIOMMU\fR, which translates accesses to these virtual addresses into the proper physical addresses. Some of these platforms also support \fBDMA.\fR \fBDDI_DMA_FORCE_PHYSICAL\fR indicates that the system should return physical rather than virtual \fBI/O\fR addresses if the system supports both. If the system does not support physical \fBDMA\fR, the return value from \fBddi_dma_alloc_handle\fR(9F) is \fBDDI_DMA_BADATTR.\fR In this case, the driver has to clear \fBDDI_DMA_FORCE_PHYSICAL\fR and retry the operation. .RE .sp .ne 2 .mk .na \fB\fBDDI_DMA_FLAGERR\fR\fR .ad .br .sp .6 .RS 4n Using this value indicates that the driver is hardened: able to cope with the incorrect results of \fBDMA\fR operations that might result from an \fBI/O\fR fault. The value also indicates that the driver will use \fBddi_fm_dma_err_get\fR(9F) to check \fBDMA\fR handles for faults on a regular basis. .sp If a \fBDMA\fR error is detected during a \fBDMA\fR access to an area mapped by such a handle, the system should not panic if possible, but should instead mark the \fBDMA\fR handle as having faulted. .sp This value is advisory: it tells the system that the driver can continue in the face of \fBI/O\fR faults. It does not guarantee that the system will not panic, as that depends on the nature of the fault and the capabilities of the system. It is quite legitimate for an implementation to ignore this flag and panic anyway. .RE .sp .ne 2 .mk .na \fB\fBDDI_DMA_RELAXED_ORDERING\fR\fR .ad .br .sp .6 .RS 4n This optional flag can be set if the \fBDMA\fR transactions associated with this handle are not required to observe strong \fBDMA\fR write ordering among themselves, nor with \fBDMA\fR write transactions of other handles. .sp The flag allows the host bridge to transfer data to and from memory more efficiently and might result in better \fBDMA\fR performance on some platforms. .sp Drivers for devices with hardware support, such as marking the bus transactions relaxed ordered, should not use this flag. Such drivers should use the hardware capability instead. .RE .SH EXAMPLES .LP \fBExample 1\fR Initializing the \fBddi_dma_attr_t\fR Structure .sp .LP Assume a device has the following \fBDMA\fR characteristics: .RS +4 .TP .ie t \(bu .el o Full 32-bit range addressable .RE .RS +4 .TP .ie t \(bu .el o 24-bit DMA counter register .RE .RS +4 .TP .ie t \(bu .el o Byte alignment .RE .RS +4 .TP .ie t \(bu .el o 4- and 8-byte burst sizes support .RE .RS +4 .TP .ie t \(bu .el o Minimum effective transfer size of 1 bytes .RE .RS +4 .TP .ie t \(bu .el o 64 Mbyte minus 1 (26-bit) maximum transfer size limit .RE .RS +4 .TP .ie t \(bu .el o Maximum segment size of 32 Kbyte .RE .RS +4 .TP .ie t \(bu .el o 17 scatter/gather list elements .RE .RS +4 .TP .ie t \(bu .el o 512-byte device transfer size granularity .RE .sp .LP The corresponding \fBddi_dma_attr_t\fR structure is initialized as follows: .sp .in +2 .nf static ddi_dma_attr_t dma_attrs = { DMA_ATTR_V0 /* version number */ (uint64_t)0x0, /* low address */ (uint64_t)0xffffffff, /* high address */ (uint64_t)0xffffff, /* DMA counter max */ (uint64_t)0x1 /* alignment */ 0x0c, /* burst sizes */ 0x1, /* minimum transfer size */ (uint64_t)0x3ffffff, /* maximum transfer size */ (uint64_t)0x7fff, /* maximum segment size */ 17, /* scatter/gather list lgth */ 512 /* granularity */ 0 /* DMA flags */ }; .fi .in -2 .sp .SH ATTRIBUTES .sp .LP See \fBattributes\fR(7) for descriptions of the following attributes: .sp .TS tab( ) box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Interface Stability Committed .TE .sp .SH SEE ALSO .sp .LP \fBattributes\fR(7), \fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_burstsizes\fR(9F), \fBddi_dma_mem_alloc\fR(9F), \fBddi_dma_nextcookie\fR(9F), \fBddi_fm_dma_err_get\fR(9F), \fBddi_dma_cookie\fR(9S) .sp .LP \fIWriting Device Drivers in Oracle Solaris 11.4\fR