Hallo, dies ist ein Test.

PWD: /www/data-lst1/unixsoft/unixsoft/kaempfer/.public_html

Running in File Mode
Relative path: ./../../../../../../usr/man/man9e/tran_init_pkt.9e
Real path: /usr/share/man/man9e/tran_init_pkt.9e
Zurück

'\" te .\" Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved. .TH tran_init_pkt 9E "7 Apr 2020" "Oracle Solaris 11.4" "Driver Entry Points" .SH NAME tran_init_pkt, tran_destroy_pkt \- SCSI HBA packet preparation and deallocation .SH SYNOPSIS .LP .nf #include <sys/scsi/scsi.h> \fBstruct scsi_pkt *prefix\fR\fBtran_init_pkt\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBstruct scsi_pkt *\fR\fIpkt\fR, \fBstruct buf *\fR\fIbp\fR, \fBint\fR \fIcmdlen\fR, \fBint\fR \fIstatuslen\fR, \fBint\fR \fItgtlen\fR, \fBint\fR\fIflags\fR, \fBint (*\fR\fIcallback\fR)(caddr_t), \fBcaddr_t\fR \fIarg\fR); .fi .LP .nf \fBvoid prefix\fR\fBtran_destroy_pkt\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBstruct scsi_pkt *\fR\fIpkt\fR); .fi .SH INTERFACE LEVEL .sp .LP Solaris architecture specific (Solaris DDI). .SH PARAMETERS .sp .ne 2 .mk .na \fB\fIap\fR\fR .ad .RS 13n .rt Pointer to a \fBscsi_address\fR(9S) structure. .RE .sp .ne 2 .mk .na \fB\fIpkt\fR\fR .ad .RS 13n .rt Pointer to a \fBscsi_pkt\fR(9S) structure allocated in an earlier call, or \fINULL\fR. .RE .sp .ne 2 .mk .na \fB\fIbp\fR\fR .ad .RS 13n .rt Pointer to a \fBbuf\fR(9S) structure if \fBDMA \fRresources are to be allocated for the \fIpkt\fR, or \fINULL\fR. .RE .sp .ne 2 .mk .na \fB\fIcmdlen\fR\fR .ad .RS 13n .rt The required length for the \fBSCSI \fRcommand descriptor block (\fBCDB\fR) in bytes. .RE .sp .ne 2 .mk .na \fB\fIstatuslen\fR\fR .ad .RS 13n .rt The required length for the \fBSCSI \fRstatus completion block (\fBSCB\fR) in bytes. .RE .sp .ne 2 .mk .na \fB\fItgtlen\fR\fR .ad .RS 13n .rt The length of the packet private area within the \fBscsi_pkt\fR to be allocated on behalf of the \fBSCSI \fRtarget driver. .RE .sp .ne 2 .mk .na \fB\fIflags\fR\fR .ad .RS 13n .rt Flags for creating the packet. .RE .sp .ne 2 .mk .na \fB\fIcallback\fR\fR .ad .RS 13n .rt Pointer to either \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR. .RE .sp .ne 2 .mk .na \fB\fIarg\fR\fR .ad .RS 13n .rt Always \fINULL\fR. .RE .SH DESCRIPTION .sp .LP The \fBtran_init_pkt()\fR and \fBtran_destroy_pkt()\fR vectors in the \fBscsi_hba_tran\fR structure must be initialized during the \fBHBA \fRdriver's \fBattach\fR(9E) to point to \fBHBA \fRentry points to be called when a target driver calls \fBscsi_init_pkt\fR(9F) and \fBscsi_destroy_pkt\fR(9F). .SS "\fBtran_init_pkt()\fR" .sp .LP \fBtran_init_pkt()\fR is the entry point into the \fBHBA \fRwhich is used to allocate and initialize a \fBscsi_pkt\fR structure on behalf of a \fBSCSI \fRtarget driver. If \fIpkt\fR is \fINULL,\fR the \fBHBA \fRdriver must use \fBscsi_hba_pkt_alloc\fR(9F) to allocate a new \fBscsi_pkt\fR structure. .sp .LP If \fIbp\fR is non-\fINULL\fR, the \fBHBA \fRdriver must allocate appropriate \fBDMA \fRresources for the \fIpkt\fR, for example, through \fBddi_dma_buf_setup\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F). .sp .LP If the \fBPKT_CONSISTENT\fR bit is set in \fIflags\fR, the buffer was allocated by \fBscsi_alloc_consistent_buf\fR(9F). For packets marked with \fBPKT_CONSISTENT,\fR the \fBHBA \fRdriver must synchronize any cached data transfers before calling the target driver's command completion callback. .sp .LP If the \fBPKT_DMA_PARTIAL\fR bit is set in \fIflags\fR, the \fBHBA \fRdriver should set up partial data transfers, such as setting the \fBDDI_DMA_PARTIAL\fR bit in the \fIflags\fR argument if interfaces such as \fBddi_dma_buf_setup\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F) are used. .sp .LP If only partial \fBDMA \fRresources are available, \fBtran_init_pkt()\fR must return in the \fBpkt_resid\fR field of \fIpkt\fR the number of bytes of \fBDMA \fRresources not allocated. .sp .LP If both \fIpkt\fR and \fIbp\fR are non-\fINULL\fR, if the \fBPKT_DMA_PARTIAL\fR bit is set in \fIflags\fR, and if \fBDMA \fRresources have already been allocated for the pkt with a previous call to \fBtran_init_pkt()\fR that returned a non-zero \fBpkt_resid\fR field, this request is to move the \fBDMA \fRresources for the subsequent piece of the transfer. .sp .LP The contents of \fBscsi_address\fR(9S) pointed to by \fIap\fR are copied into the \fBpkt_address\fR field of the \fBscsi_pkt\fR(9S) by \fBscsi_hba_pkt_alloc\fR(9F). .sp .LP \fItgtlen\fR is the length of the packet private area in the \fBscsi_pkt\fR structure to be allocated on behalf of the \fBSCSI \fRtarget driver. .sp .LP \fIstatuslen\fR is the required length for the \fBSCSI \fRstatus completion block. If the requested status length is greater than or equal to \fBsizeof(struct scsi_arq_status)\fR and the \fBauto_rqsense\fR capability has been set, automatic request sense (\fBARS\fR) is enabled for this packet. If the status length is less than \fBsizeof(struct scsi_arq_status)\fR, automatic request sense must be disabled for this \fIpkt\fR. .sp .LP If the \fBHBA\fR driver is not capable of disabling \fBARQ\fR on a per-packet basis and \fBtran_init_pkt()\fR is called with a \fIstatuslen\fR that is less than \fBsizeof(struct scsi_arq_status)\fR, the driver's \fBtran_init_pkt\fR routine should allocate at least \fBsizeof(struct scsi_arq_status)\fR. If an \fBARS\fR is needed, upon successful \fBARS\fR done by the \fBHBA\fR driver, the driver must copy the sense data over and set \fBSTAT_ARQ_DONE\fR in \fBpkt_state\fR. .sp .LP \fIcmdlen\fR is the required length for the \fBSCSI \fRcommand descriptor block. .sp .LP Note: \fItgtlen\fR, \fIstatuslen\fR, and \fIcmdlen\fR are used only when the \fBHBA \fRdriver allocates the \fBscsi_pkt\fR(9S), in other words, when \fIpkt\fR is \fINULL\fR. .sp .LP \fIcallback\fR indicates what the allocator routines should do when resources are not available: .sp .ne 2 .mk .na \fB\fBNULL_FUNC\fR\fR .ad .RS 14n .rt Do not wait for resources. Return a \fINULL\fR pointer. .RE .sp .ne 2 .mk .na \fB\fBSLEEP_FUNC\fR\fR .ad .RS 14n .rt Wait indefinitely for resources. .RE .SS "tran_destroy_pkt()" .sp .LP \fBtran_destroy_pkt()\fR is the entry point into the \fBHBA \fRthat must free all of the resources that were allocated to the \fBscsi_pkt\fR(9S) structure during \fBtran_init_pkt()\fR. .SH RETURN VALUES .sp .LP \fBtran_init_pkt()\fR must return a pointer to a \fBscsi_pkt\fR(9S) structure on success, or \fINULL\fR on failure. .sp .LP If \fIpkt\fR is \fINULL\fR on entry, and \fBtran_init_pkt()\fR allocated a packet through \fBscsi_hba_pkt_alloc\fR(9F) but was unable to allocate \fBDMA \fRresources, \fBtran_init_pkt()\fR must free the packet through \fBscsi_hba_pkt_free\fR(9F) before returning \fINULL\fR. .SH SEE ALSO .sp .LP \fBattach\fR(9E), \fBtran_setup_pkt\fR(9E), \fBtran_sync_pkt\fR(9E), \fBbiodone\fR(9F), \fBbioerror\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_buf_setup\fR(9F), \fBkmem_cache_create\fR(9F), \fBscsi_alloc_consistent_buf\fR(9F), \fBscsi_destroy_pkt\fR(9F), \fBscsi_hba_attach\fR(9F), \fBscsi_hba_pkt_alloc\fR(9F), \fBscsi_hba_pkt_free\fR(9F), \fBscsi_init_pkt\fR(9F), \fBbuf\fR(9S), \fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S), \fBscsi_pkt\fR(9S) .sp .LP \fIWriting Device Drivers in Oracle Solaris 11.4\fR .SH NOTES .sp .LP If a \fBDMA\fR allocation request fails with \fBDDI_DMA_NOMAPPING\fR, indicate the error by calling \fBbioerror\fR(9F) with \fIbp\fR and an error code of \fBEFAULT\fR. .sp .LP If a \fBDMA \fRallocation request fails with \fBDDI_DMA_TOOBIG,\fR indicate the error by calling \fBbioerror\fR(9F) with \fIbp\fR and an error code of \fBEINVAL\fR. .sp .LP For increased performance, an HBA driver may want to provide a cache for \fBscsi_pkt\fR(9S) allocation. This cache should be implemented by the HBA driver providing a \fBtran_setup_pkt\fR(9E) implementation. Implementing this cache by direct use of \fBkmem_cache_create\fR(9F) adds a compile-time dependency on \fBscsi_pkt()\fR size, which is illegal.