xref: /illumos-gate/usr/src/man/man9f/scsi_hba_pkt_alloc.9f (revision dd72704bd9e794056c558153663c739e2012d721) 
 te
 Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
 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.
 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.
 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]
 SCSI_HBA_PKT_ALLOC 9F "Dec 11, 2006"
 NAME
scsi_hba_pkt_alloc, scsi_hba_pkt_free - allocate and free a scsi_pkt structure

 SYNOPSIS
#include <sys/scsi/scsi.h>



struct scsi_pkt *scsi_hba_pkt_alloc(dev_info_t *dip,
 struct scsi_address *ap, int cmdlen, int statuslen,
 int tgtlen, int hbalen,
 int (*callback)(caddr_t arg), caddr_t arg);






void scsi_hba_pkt_free(struct scsi_address *ap, struct scsi_pkt *pkt);




 INTERFACE LEVEL
illumos architecture specific (illumos DDI).

 PARAMETERS
dip


Pointer to a dev_info_t structure, defining the HBA driver
instance.



ap


Pointer to a scsi_address(9S) structure, defining the target instance.



cmdlen


Length in bytes to be allocated for the SCSI command descriptor block
(CDB).



statuslen


Length in bytes to be allocated for the SCSI status completion block
(SCB).



tgtlen


Length in bytes to be allocated for a private data area for the target driver's
exclusive use.



hbalen


Length in bytes to be allocated for a private data area for the HBA
driver's exclusive use.



callback


Indicates what scsi_hba_pkt_alloc() should do when resources are not
available:
NULL_FUNC


Do not wait for resources. Return a NULL pointer.



SLEEP_FUNC


Wait indefinitely for resources.






arg


Must be NULL.



pkt


A pointer to a scsi_pkt(9S) structure.




 DESCRIPTION
For scsi_hba_pkt_alloc():


The scsi_hba_pkt_alloc() function allocates space for a scsi_pkt
structure. HBA drivers must use this interface when allocating a
scsi_pkt from their tran_init_pkt(9E) entry point.


If callback is NULL_FUNC, scsi_hba_pkt_alloc() may not sleep
when allocating resources, and callers should be prepared to deal with
allocation failures.


The scsi_hba_pkt_alloc() function copies the scsi_address(9S)
structure pointed to by ap to the pkt_address field in the
scsi_pkt(9S).


The scsi_hba_pkt_alloc() function also allocates memory for these
scsi_pkt(9S) data areas, and sets these fields to point to the allocated
memory:
pkt_ha_private


HBA private data area.



pkt_private


Target driver private data area.



pkt_scbp


SCSI status completion block.



pkt_cdbp


SCSI command descriptor block.





For scsi_hba_pkt_free():


The scsi_hba_pkt_free() function frees the space allocated for the
scsi_pkt(9S) structure.

 RETURN VALUES
The scsi_hba_pkt_alloc() function returns a pointer to the scsi_pkt
structure, or NULL if no space is available.

 CONTEXT
The scsi_hba_pkt_alloc() function can be called from user, interrupt, or
kernel context. Drivers must not allow scsi_hba_pkt_alloc() to sleep if
called from an interrupt routine.


The scsi_hba_pkt_free() function can be called from user, interrupt, or
kernel context.

 SEE ALSO
 tran_init_pkt (9E),  scsi_address (9S),  scsi_pkt (9S) 

Writing Device Drivers