diff options
Diffstat (limited to 'usr/src/man/man9f')
| -rw-r--r-- | usr/src/man/man9f/Makefile | 77 | ||||
| -rw-r--r-- | usr/src/man/man9f/ddi_ffs.9f | 157 | ||||
| -rw-r--r-- | usr/src/man/man9f/kmem_alloc.9f | 7 | ||||
| -rw-r--r-- | usr/src/man/man9f/mac_transceiver_info.9f | 95 | ||||
| -rw-r--r-- | usr/src/man/man9f/sas_phymap_create.9f | 307 | ||||
| -rw-r--r-- | usr/src/man/man9f/sas_phymap_lookup_ua.9f | 213 | ||||
| -rw-r--r-- | usr/src/man/man9f/scsi_address_device.9f | 169 | ||||
| -rw-r--r-- | usr/src/man/man9f/scsi_hba_attach_setup.9f | 529 | ||||
| -rw-r--r-- | usr/src/man/man9f/scsi_hba_iport_exist.9f | 98 | ||||
| -rw-r--r-- | usr/src/man/man9f/scsi_hba_iport_register.9f | 88 | ||||
| -rw-r--r-- | usr/src/man/man9f/scsi_hba_iport_unit_address.9f | 74 | ||||
| -rw-r--r-- | usr/src/man/man9f/scsi_hba_iportmap_create.9f | 179 | ||||
| -rw-r--r-- | usr/src/man/man9f/scsi_hba_tgtmap_create.9f | 489 | ||||
| -rw-r--r-- | usr/src/man/man9f/scsi_wwnstr_to_wwn.9f | 169 |
14 files changed, 2311 insertions, 340 deletions
diff --git a/usr/src/man/man9f/Makefile b/usr/src/man/man9f/Makefile index 30c1d87148..3d02d6e075 100644 --- a/usr/src/man/man9f/Makefile +++ b/usr/src/man/man9f/Makefile @@ -332,6 +332,7 @@ MANFILES= ASSERT.9f \ mac_prop_info.9f \ mac_register.9f \ mac_rx.9f \ + mac_transceiver_info.9f \ mac_tx_update.9f \ makecom.9f \ makedevice.9f \ @@ -441,7 +442,10 @@ MANFILES= ASSERT.9f \ rmvb.9f \ rmvq.9f \ rwlock.9f \ + sas_phymap_create.9f \ + sas_phymap_lookup_ua.9f \ scsi_abort.9f \ + scsi_address_device.9f \ scsi_alloc_consistent_buf.9f \ scsi_cname.9f \ scsi_destroy_pkt.9f \ @@ -454,10 +458,15 @@ MANFILES= ASSERT.9f \ scsi_get_device_type_string.9f \ scsi_hba_attach_setup.9f \ scsi_hba_init.9f \ + scsi_hba_iport_exist.9f \ + scsi_hba_iport_register.9f \ + scsi_hba_iport_unit_address.9f \ + scsi_hba_iportmap_create.9f \ scsi_hba_lookup_capstr.9f \ scsi_hba_pkt_alloc.9f \ scsi_hba_pkt_comp.9f \ scsi_hba_probe.9f \ + scsi_hba_tgtmap_create.9f \ scsi_hba_tran_alloc.9f \ scsi_ifgetcap.9f \ scsi_init_pkt.9f \ @@ -475,6 +484,7 @@ MANFILES= ASSERT.9f \ scsi_unprobe.9f \ scsi_validate_sense.9f \ scsi_vu_errmsg.9f \ + scsi_wwnstr_to_wwn.9f \ semaphore.9f \ sprintf.9f \ stoi.9f \ @@ -745,7 +755,9 @@ MANLINKS= AVL_NEXT.9f \ ddi_dmae_release.9f \ ddi_dmae_stop.9f \ ddi_exit_critical.9f \ + ddi_ffsll.9f \ ddi_fls.9f \ + ddi_flsll.9f \ ddi_fm_capable.9f \ ddi_fm_dma_err_clear.9f \ ddi_fm_dma_err_get.9f \ @@ -999,6 +1011,8 @@ MANLINKS= AVL_NEXT.9f \ mac_prop_info_set_default_uint8.9f \ mac_prop_info_set_perm.9f \ mac_prop_info_set_range_uint32.9f \ + mac_transceiver_info_set_present.9f \ + mac_transceiver_info_set_usable.9f \ mac_unregister.9f \ makecom_g0.9f \ makecom_g0_s.9f \ @@ -1163,11 +1177,34 @@ MANLINKS= AVL_NEXT.9f \ rw_tryenter.9f \ rw_tryupgrade.9f \ samestr.9f \ + sas_phymap_destroy.9f \ + sas_phymap_lookup_uapriv.9f \ + sas_phymap_phy_add.9f \ + sas_phymap_phy_rem.9f \ + sas_phymap_phy2ua.9f \ + sas_phymap_phys_free.9f \ + sas_phymap_phys_next.9f \ + sas_phymap_ua_free.9f \ + sas_phymap_ua2phys.9f \ + sas_phymap_uahasphys.9f \ + scsi_device_unit_address.9f \ + scsi_device_hba_private_get.9f \ + scsi_device_hba_private_set.9f \ scsi_dmafree.9f \ scsi_dname.9f \ scsi_hba_detach.9f \ scsi_hba_fini.9f \ + scsi_hba_iport_find.9f \ + scsi_hba_iportmap_destroy.9f \ + scsi_hba_iportmap_iport_add.9f \ + scsi_hba_iportmap_iport_remove.9f \ scsi_hba_pkt_free.9f \ + scsi_hba_tgtmap_set_begin.9f \ + scsi_hba_tgtmap_set_add.9f \ + scsi_hba_tgtmap_set_end.9f \ + scsi_hba_tgtmap_set_flush.9f \ + scsi_hba_tgtmap_tgt_add.9f \ + scsi_hba_tgtmap_tgt_remove.9f \ scsi_hba_tran_free.9f \ scsi_ifsetcap.9f \ scsi_mname.9f \ @@ -1181,6 +1218,8 @@ MANLINKS= AVL_NEXT.9f \ scsi_sense_info_uint64.9f \ scsi_sname.9f \ scsi_unslave.9f \ + scsi_wwn_to_wwnstr.9f \ + scsi_free_wwnstr.9f \ sema_destroy.9f \ sema_init.9f \ sema_p.9f \ @@ -1519,7 +1558,9 @@ ddi_dmae_stop.9f := LINKSRC = ddi_dmae.9f ddi_exit_critical.9f := LINKSRC = ddi_enter_critical.9f +ddi_ffsll.9f := LINKSRC = ddi_ffs.9f ddi_fls.9f := LINKSRC = ddi_ffs.9f +ddi_flsll.9f := LINKSRC = ddi_ffs.9f ddi_fm_dma_err_clear.9f := LINKSRC = ddi_fm_acc_err_clear.9f @@ -1828,6 +1869,10 @@ mac_prop_info_set_default_uint32.9f := LINKSRC = mac_prop_info.9f mac_prop_info_set_default_uint64.9f := LINKSRC = mac_prop_info.9f mac_prop_info_set_perm.9f := LINKSRC = mac_prop_info.9f mac_prop_info_set_range_uint32.9f := LINKSRC = mac_prop_info.9f + +mac_transceiver_info_set_present.9f := LINKSRC = mac_transceiver_info.9f +mac_transceiver_info_set_usable.9f := LINKSRC = mac_transceiver_info.9f + mac_unregister.9f := LINKSRC = mac_register.9f makecom_g0.9f := LINKSRC = makecom.9f @@ -2015,6 +2060,22 @@ rw_read_locked.9f := LINKSRC = rwlock.9f rw_tryenter.9f := LINKSRC = rwlock.9f rw_tryupgrade.9f := LINKSRC = rwlock.9f +sas_phymap_destroy.9f := LINKSRC = sas_phymap_create.9f +sas_phymap_phy_add.9f := LINKSRC = sas_phymap_create.9f +sas_phymap_phy_rem.9f := LINKSRC = sas_phymap_create.9f + +sas_phymap_lookup_uapriv.9f := LINKSRC = sas_phymap_lookup_ua.9f +sas_phymap_phy2ua.9f := LINKSRC = sas_phymap_lookup_ua.9f +sas_phymap_ua_free.9f := LINKSRC = sas_phymap_lookup_ua.9f +sas_phymap_uahasphys.9f := LINKSRC = sas_phymap_lookup_ua.9f +sas_phymap_ua2phys.9f := LINKSRC = sas_phymap_lookup_ua.9f +sas_phymap_phys_next.9f := LINKSRC = sas_phymap_lookup_ua.9f +sas_phymap_phys_free.9f := LINKSRC = sas_phymap_lookup_ua.9f + +scsi_device_unit_address.9f := LINKSRC = scsi_address_device.9f +scsi_device_hba_private_get.9f := LINKSRC = scsi_address_device.9f +scsi_device_hba_private_set.9f := LINKSRC = scsi_address_device.9f + scsi_dname.9f := LINKSRC = scsi_cname.9f scsi_mname.9f := LINKSRC = scsi_cname.9f scsi_rname.9f := LINKSRC = scsi_cname.9f @@ -2029,8 +2090,21 @@ scsi_hba_detach.9f := LINKSRC = scsi_hba_attach_setup.9f scsi_hba_fini.9f := LINKSRC = scsi_hba_init.9f +scsi_hba_iportmap_destroy.9f := LINKSRC = scsi_hba_iportmap_create.9f +scsi_hba_iportmap_iport_add.9f := LINKSRC = scsi_hba_iportmap_create.9f +scsi_hba_iportmap_iport_remove.9f := LINKSRC = scsi_hba_iportmap_create.9f + +scsi_hba_iport_find.9f := LINKSRC = scsi_hba_iport_exist.9f + scsi_hba_pkt_free.9f := LINKSRC = scsi_hba_pkt_alloc.9f +scsi_hba_tgtmap_set_begin.9f := LINKSRC = scsi_hba_tgtmap_create.9f +scsi_hba_tgtmap_set_add.9f := LINKSRC = scsi_hba_tgtmap_create.9f +scsi_hba_tgtmap_set_end.9f := LINKSRC = scsi_hba_tgtmap_create.9f +scsi_hba_tgtmap_set_flush.9f := LINKSRC = scsi_hba_tgtmap_create.9f +scsi_hba_tgtmap_tgt_add.9f := LINKSRC = scsi_hba_tgtmap_create.9f +scsi_hba_tgtmap_tgt_remove.9f := LINKSRC = scsi_hba_tgtmap_create.9f + scsi_hba_tran_free.9f := LINKSRC = scsi_hba_tran_alloc.9f scsi_ifsetcap.9f := LINKSRC = scsi_ifgetcap.9f @@ -2044,6 +2118,9 @@ scsi_sense_ascq.9f := LINKSRC = scsi_sense_key.9f scsi_unslave.9f := LINKSRC = scsi_unprobe.9f +scsi_wwn_to_wwnstr.9f := LINKSRC = scsi_wwnstr_to_wwn.9f +scsi_free_wwnstr.9f := LINKSRC = scsi_wwnstr_to_wwn.9f + sema_destroy.9f := LINKSRC = semaphore.9f sema_init.9f := LINKSRC = semaphore.9f sema_p.9f := LINKSRC = semaphore.9f diff --git a/usr/src/man/man9f/ddi_ffs.9f b/usr/src/man/man9f/ddi_ffs.9f index afd1e13dbd..e6d5c1dfe2 100644 --- a/usr/src/man/man9f/ddi_ffs.9f +++ b/usr/src/man/man9f/ddi_ffs.9f @@ -3,74 +3,95 @@ .\" 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] -.TH DDI_FFS 9F "Jun 5, 2013" -.SH NAME -ddi_ffs, ddi_fls \- find first (last) bit set in a long integer -.SH SYNOPSIS -.LP -.nf -#include <sys/conf.h> -#include <sys/ddi.h> -#include <sys/sunddi.h> - - - -\fBint\fR \fBddi_ffs\fR(\fBlong\fR \fImask\fR); -.fi - -.LP -.nf -\fBint\fR \fBddi_fls\fR(\fBlong\fR \fImask\fR); -.fi - -.SH INTERFACE LEVEL -.sp -.LP +.Dd July 14, 2017 +.Dt DDI_FFS 9F +.Os +.Sh NAME +.Nm ddi_ffs, ddi_ffsll, ddi_fls, ddi_flsll +.Nd find first (last) bit set in a long (long) integer +.Sh SYNOPSIS +.In sys/conf.h +.In sys/ddi.h +.In sys/sunddi.h +.Ft int +.Fo "ddi_ffs" +.Fa "long mask" +.Fc +.Ft int +.Fo "ddi_fls" +.Fa "long mask" +.Fc +.Ft int +.Fo "ddi_ffs" +.Fa "long long mask" +.Fc +.Ft int +.Fo "ddi_fls" +.Fa "long long mask" +.Fc +.Sh INTERFACE LEVEL Solaris DDI specific (Solaris DDI). -.SH PARAMETERS -.sp -.ne 2 -.na -\fB\fImask\fR\fR -.ad -.RS 8n -A 32-bit argument value to search through. -.RE - -.SH DESCRIPTION -.sp -.LP -The function \fBddi_ffs()\fR takes its argument and returns the shift count -that the first (least significant) bit set in the argument corresponds to. The -function \fBddi_fls()\fR does the same, only it returns the shift count for the -last (most significant) bit set in the argument. -.SH RETURN VALUES -.sp -.ne 2 -.na -\fB\fB0\fR\fR -.ad -.RS 5n +.Sh PARAMETERS +.Bl -tag -width Va +.It Fa mask +A 32-bit or 64-bit argument value to search through. +.El +.Sh DESCRIPTION +The functions +.Fn ddi_ffs +and +.Fn ddi_ffsll +take their argument and return the shift count that the first (least +significant) bit set in the argument corresponds to. +The functions +.Fn ddi_fls +and +.Fn ddi_flsll +do the same, only they returns the shift count for the last (most +significant) bit set in the argument. +.Fn ddi_ffs +and +.Fn ddi_fls +operate on 32-bit values, while +.Fn ddi_ffsll +and +.Fn ddi_flsll +operate on 64-bit values. +.Sh CONTEXT +These functions can be called from user, interrupt, or kernel context. +.Sh RETURN VALUES +.Bl -tag -width Va +.It 0 No bits are set in mask. -.RE - -.sp -.ne 2 -.na -\fB\fIN\fR\fR -.ad -.RS 5n -Bit \fIN\fR is the least significant (\fBddi_ffs\fR) or most significant -(\fBddi_fls\fR) bit set in mask. Bits are numbered from \fB1\fR to \fB32\fR, -with bit \fB1\fR being the least significant bit position and bit \fB32\fR the -most significant position. -.RE - -.SH CONTEXT -.sp -.LP -This function can be called from user, interrupt, or kernel context. -.SH SEE ALSO -.sp -.LP +.It N +Bit +.Em N +is the least significant +.Po +.Fn ddi_ffs , +.Fn ddi_ffsll +.Pc +or most significant +.Po +.Fn ddi_fls , +.Fn ddi_flsll +.Pc +bit set in +.Fa mask . +Bits are numbered from +.Em 1 +to +.Em 32 +or +.Em 64 , +with bit +.Em 1 +being the least significant bit position and bit +.Em 32 +or +.Em 64 +the most significant position, depending on the variant of the +functions used. +.El +.Sh SEE ALSO \fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/kmem_alloc.9f b/usr/src/man/man9f/kmem_alloc.9f index 9c4f8ccb0c..201544b57c 100644 --- a/usr/src/man/man9f/kmem_alloc.9f +++ b/usr/src/man/man9f/kmem_alloc.9f @@ -129,5 +129,8 @@ uninitialized kernel memory should be handled carefully. For example, never .SH NOTES .sp .LP -\fBkmem_alloc(0\fR, \fIflag\fR\fB)\fR always returns \fINULL\fR. -\fBkmem_free(NULL, 0)\fR is legal. +\fBkmem_alloc(0\fR, \fIflag\fR\fB)\fR always returns \fINULL\fR, but +if \fBKM_SLEEP\fR is set, this behavior is considered to be deprecated; +the system may be configured to explicitly panic in this case in lieu +of returning \fINULL\fR. +\fBkmem_free(NULL, 0)\fR is legal, however. diff --git a/usr/src/man/man9f/mac_transceiver_info.9f b/usr/src/man/man9f/mac_transceiver_info.9f new file mode 100644 index 0000000000..9b04ab3a9d --- /dev/null +++ b/usr/src/man/man9f/mac_transceiver_info.9f @@ -0,0 +1,95 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2017, Joyent, Inc. +.\" +.Dd Feb 21, 2017 +.Dt MAC_TRANSCEIVER_INFO 9F +.Os +.Sh NAME +.Nm mac_transceiver_info , +.Nm mac_transceiver_info_set_present , +.Nm mac_transceiver_info_set_usable +.Nd set MAC transceiver property information +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft void +.Fo mac_transceiver_info_set_present +.Fa "mac_transceiver_info_t *infop" +.Fa "boolean_t present" +.Fc +.Ft void +.Fo mac_transceiver_info_set_usable +.Fa "mac_transceiver_info_t *infop" +.Fa "boolean_t usable" +.Fc +.Sh INTERFACE LEVEL +.Sy Volatile - +This interface is still evolving in illumos. +API and ABI stability is +not guaranteed. +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa infop +A pointer to an opaque structure obtained as an argument to the +.Xr mct_info 9E +entry point. +.It Fa present +A boolean that indicates whether the transceiver is present. +.It Fa usable +A boolean that indicates whether the transceiver is usable. +.El +.Sh DESCRIPTION +The +.Fn mac_transceiver_set_present +and +.Fn mac_transceiver_set_usable +functions are used to set information about a transceiver as part of the +.Xr mct_info 9E +entry point to obtain information about a MAC transceiver. +For more information and background, see the +.Sy Transceiver Information Functions +section of +.Xr mac_capab_transceiver 9E . +.Pp +The +.Fn mct_transceiver_set_present +function sets whether or not the transceiver is present and plugged into +the system. +If the transceiver is not plugged in, then the function +should be called with +.Fa present set to +.Dv B_FALSE , +otehrwise it should use +.Dv B_TRUE . +.Pp +The +.Fn mct_transceiver_set_usable +function determines whether or not the device can use the transceiver. +If the device cannot use the transceiver, then it should call the +function with +.Fa usable +set to +.Dv B_FALSE . +Otherwise, it should use +.Dv B_TRUE . +If the transceiver is not present, then this function should not be +called. +.Sh CONTEXT +These functions should be called in response to handling the +.Fn mct_info 9E +entry point for transceivers in +.Sy kernel +context. +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_capab_transceiver 9E , +.Xr mct_info 9E diff --git a/usr/src/man/man9f/sas_phymap_create.9f b/usr/src/man/man9f/sas_phymap_create.9f new file mode 100644 index 0000000000..97b5515946 --- /dev/null +++ b/usr/src/man/man9f/sas_phymap_create.9f @@ -0,0 +1,307 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2017, Joyent, Inc. +.\" +.Dd Apr 20, 2017 +.Dt SAS_PHYMAP_CREATE 9F +.Os +.Sh NAME +.Nm sas_phymap_create , +.Nm sas_phymap_destroy , +.Nm sas_phymap_phy_add , +.Nm sas_phymap_phy_rem +.Nd SAS PHY map functions +.Sh SYNOPSIS +.In sys/scsi/scsi.h +.Ft int +.Fo sas_phymap_create +.Fa "dev_info_t *dip" +.Fa "int settle_usec" +.Fa "sas_phymap_mode_t mode" +.Fa "void *mode_argument" +.Fa "void *phymap_priv" +.Fa "sas_phymap_activate_cb_t activate_cb" +.Fa "sas_phymap_deactivate_cb_t deactivate_cb" +.Fa "sas_phymap_t **phymapout" +.Fc +.Ft void +.Fo sas_phymap_destroy +.Fa "sas_phymap_t *phymap" +.Fc +.Ft int +.Fo sas_phymap_phy_add +.Fa "sas_phymap_t *phymap" +.Fa "int phy" +.Fa "uint64_t local" +.Fa "uint64_t remote" +.Fc +.Ft int +.Fo sas_phymap_phy_rem +.Fa "sas_phymap_t *phymap" +.Fa "int phy" +.Fc +.Ft void +.Fo (*sas_phymap_activate_cb_t) +.Fa "void *phymap_priv" +.Fa "char *ua" +.Fa "void **ua_privp" +.Fc +.Ft void +.Fo (*sas_phymap_deactivate_cb_t) +.Fa "void *phymap_priv" +.Fa "char *ua" +.Fa "void *ua_priv" +.Fc +.Sh INTERFACE LEVEL +.Sy Evolving - +This interface is still evolving in illumos. +API and ABI stability is +not guaranteed. +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa dip +Pointer to +.Vt dev_info +structure. +.It Fa settle_usec +A time in microseconds. +.It Fa mode +Mode of operation for the phy map. +Should be set to +.Dv PHYMAP_MODE_SIMPLE . +.It Fa mode_priv +Drivers should pass +.Dv NULL . +.It Fa phymap_priv +A private argument to be used in callback functions. +.It Fa activate_cb +An optional callback that will be called when a new phy is being +added to the system. +.It Fa deactivate_cb +An optional callback that will be called when an existing phys is +removed from the system. +.It Fa phymapout +Pointer where the phy map is stored. +.It Fa phymap +Pointer to an allocated phy map. +.It Fa phy +A non-negative integer that uniquely identifies a phy on a device. +.It Fa local +The World Wide Number (WWN) of the HBA-owned side of the phy. +.It Fa remote +The World Wide Number (WWN) of the device that is plugged into the phy. +.It Fa ua +A character string that indicates the system generated unit address for +the logical port. +.It Fa ua_privp +A private value that can be stored for the corresponding unit address. +.It Fa ua_priv +A private value for the unit address stored into +.Fa ua_privp . +.El +.Sh DESCRIPTION +The +.Fn sas_phymap_create +and +.Fn sas_phymap_destroy +functions create and destroy phymaps which are used to manage a set of +potentially-active SAS phys and the attached devices. +For more background, see +.Xr phymap 9 . +If the driver in question is not a SAS HBA or a similar fabric-like +device, then do not use this interface. +.Pp +The phy map maps one or more phys to a logical port-like construct that +is represented based on the WWNs in question. +This logical SAS port has a unit address derived from the two WWNs. +When the first phy is noted as using these WWNs, then the phymap will +call any registered callbacks as the port is created. +If additional phys come online in service of the +same port, then a new port will not be created. +.Pp +To facilitate the mapping between a PHY and the corresponding port unit +address, the +.Xr sas_phymap_phy2ua 9F +and +.Xr sas_phymap_lookup_ua 9F +functions are available. +.Pp +To create a phy map, the driver uses the +.Fn sas_phymap_create +function. +The resulting phy map will be stored in the +.Fa phymapout +argument. +The value in +.Fa settle_usec +indicates the amount of time that the system should wait to quiesce all +changes and consider the resulting system stable. +Changes will not be reported until after +.Fa settle_usec +have passed. +.Pp +If a driver places a function pointer for either the +.Fa activate_cb +or +.Fa deactivate cb +then those functions will be called when phys are added and removed from +the phy map. +.Pp +The value placed in the +.Fa phymap_priv +argument will be passed to both callback functions. +.Pp +To destroy a phymap, the driver should call the +.Fn sas_phymap_destroy +function. +A side effect of this is that all existing entries in the phy +map will be removed and their deactivate callbacks will fire. +.Ss Callbacks +The phymap provides a means for receiving callbacks when the addition of +a phy causes a new logical port to be created or when the phy being +removed is the last phy that is a member of the port. +Unlike with the +.Xr tgtmap 9 , +there is no system managed driver that is attached with the phymap. +For the phymap to be useful to drivers, the callbacks should generally +be registered. +.Pp +It's important to emphasize that the callbacks do not represent phys, +but instead the logical port that they are bound to. +This is different +from the +.Xr tgtmap 9 +and +.Xr iportmap 9 . +Calls to the +.Fn sas_phymap_phy_add +and +.Fn sas_phymap_phy_rem +functions may not result in anything being created in the system. +.Pp +The +.Fa activate_cb +callback occurs whenever a new logical port is created because the first +phy that references that pair of WWNs has been created. +The +.Fa phymap_priv +argument corresponds to the value passed in the +.Fn sas_phymap_create +function. +.Pp +The +.Fa ua +argument is a unit-address string that the system constructs based on +the WWNs passed in the +.Fa local +and +.Fa remote +arguments to the +.Fn sas_phymap_phy_add +function. +If this is being used together with an +.Xr iportmap 9 +then the +.Fa ua +should be the name of the added iport. +.Pp +The +.Fa ua_privp +argument allows for data to be correlated with the unit-address. +This data is accessible throughout the lifetime of the unit-address +through the +.Xr sas_phymap_lookup_uapriv 9F +function and is also made available during the deactivate callback. +.Pp +The +.Fa deactivate_cb +callback occurs when the logical port is being removed, because the last +associated phy has been removed. +The arguments to this are the same as to the activate callback, with the +exception that the +.Fa ua_priv +argument is the value that was stored in the +.Fa ua_privp +argument of the activate callback. +.Ss Adding and Removing PHYs +To add a phy to the system, the driver should call the +.Fn sas_phymap_phy_add +function. +The +.Fa phy +argument should indicate the phy identifier of the phy that has come up. +The +.Fa local +WWN generally corresponds to the SAS port on the controller, while the +.Fa remote +WWN is whatever device is on the other side of the phy. +The system enforces that a given phy only maps to a single port at any +time. +.Pp +When a phy goes offline, then the driver should call the +.Fn sas_phymap_phy_rem +function using the same phy identifier that it used when adding the phy. +If this is the last phy that was used for this logical port, then the +corresponding logical port will be removed and the deactivate callback +function, if registered, will be called. +.Sh CONTEXT +The +.Fn sas_phymap_create +and +.Fn sas_phymap_destroy +functions are generally called during an HBA driver's +.Xr attach 9E +and +.Xr detach 9E +entry points, though may be called by a driver from +.Sy user +or +.Sy kernel +context. +.Pp +The optional +.Fn activate_cb +and +.Fn deactivate_cb +functions for a phymap will be called into the driver from +.Sy kernel +context. +.Pp +The +.Fn sas_phymap_phy_add +and +.Fn sas_phymap_phy_rem +functions may be called from +.Sy user +or +.Sy kernel +context. +.Sh RETURN VALUES +Upon successful completion, the +.Fn sas_phymap_create , +.Fn sas_phymap_phy_add , +and +.Fn sas_phymap_phy_rem +functions return +.Dv DDI_SUCCESS . +Otherwise, +.Dv DDI_FAILURE +is returned to indicate failure. +.Sh SEE ALSO +.Xr iportmap 9 , +.Xr phymap 9 , +.Xr tgtmap 9 , +.Xr attach 9E , +.Xr detach 9E , +.Xr sas_phymap_lookup_ua 9F , +.Xr sas_phymap_lookup_uapriv 9F , +.Xr sas_phymap_phy2ua 9F diff --git a/usr/src/man/man9f/sas_phymap_lookup_ua.9f b/usr/src/man/man9f/sas_phymap_lookup_ua.9f new file mode 100644 index 0000000000..5255f49632 --- /dev/null +++ b/usr/src/man/man9f/sas_phymap_lookup_ua.9f @@ -0,0 +1,213 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2017, Joyent, Inc. +.\" +.Dd Apr 20, 2017 +.Dt SAS_PHYMAP_LOOKUP_UA 9F +.Os +.Sh NAME +.Nm sas_phymap_lookup_ua , +.Nm sas_phymap_lookup_uapriv , +.Nm sas_phymap_phy2ua , +.Nm sas_phymap_ua_free , +.Nm sas_phymap_uahasphys , +.Nm sas_phymap_ua2phys , +.Nm sas_phymap_phys_next , +.Nm sas_phymap_phys_free +.Nd SAS phymap utility functions +.Sh SYNOPSIS +.In sys/scsi/scsi.h +.Ft "char *" +.Fo sas_phymap_lookup_ua +.Fa "sas_phymap_t *phymap" +.Fa "uint64_t local" +.Fa "uint64_t remote" +.Fc +.Ft "void *" +.Fo sas_phymap_lookup_uapriv +.Fa "sas_phymap_t *phymap" +.Fa "char *ua" +.Fc +.Ft int +.Fo sas_phymap_uahasphys +.Fa "sas_phymap_t *phymap" +.Fa "char *ua" +.Fc +.Ft "char *" +.Fo sas_phymap_phy2ua +.Fa "sas_phymap_t *phymap" +.Fa "int phy" +.Fc +.Ft void +.Fo sas_phymap_ua_free +.Fa "char *ua" +.Fc +.Ft "sas_phymap_phys_t *" +.Fo sas_phymap_ua2phys +.Fa "sas_phymap_t *phymap" +.Fa "char *ua" +.Fc +.Ft int +.Fo sas_phymap_phys_next +.Fa "sas_phymap_phys_t *phys" +.Fc +.Ft void +.Fo sas_phymap_phys_free +.Fa "sas_phymap_phys_t *phys" +.Fc +.Sh INTERFACE LEVEL +.Sy Evolving - +This interface is still evolving in illumos. +API and ABI stability is +not guaranteed. +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa phymap +Pointer to an allocated phy map. +.It Fa local +The World Wide Number (WWN) of the HBA-owned side of the phy. +.It Fa remote +The World Wide Number (WWN) of the device that is plugged into the phy. +.It Fa ua +A character string that indicates the system generated unit address for +the logical port. +.It Fa phy +A non-negative integer that uniquely identifies a phy on a device. +.It Fa phys +An opaque structure that represents a collection of phys on a port. +.El +.Sh DESCRIPTION +The functions described here are all utility functions for operating on +a phymap and the entities it creates. + For more information on phymaps, +see +.Xr phymap 9 +and +.Xr sas_phymap_create 9F . +.Pp +The +.Fn sas_phymap_lookup_ua +function finds the unit address of the logical port that corresponds to +the tuple of the +.Fa local +and +.Fa remote +WWN. +If a logical port exists for that tuple, then a pointer to its +system generated unit-address is returned. +This string is managed by the system and it must not be modified or freed. +If it cannot be found, then +.Dv NULL +is returned. +.Pp +The +.Fn sas_phymap_lookup_uapriv +function returns the private value that was stored during the activate +callback of the logical port represented by the unit address +.Fa ua +that is a part of the phymap +.Fa phymap . +.Pp +The +.Fn sas_phymap_uahasphys +function is used to determine whether or not the logical port +represented by the unit address specified in +.Fa ua +that is a part of the phymap +.Fa phymap +has any phys. +If phys are found, then the function returns +.Sy 1 . +.Pp +The +.Fn sas_phymap_phy2ua +function attempts to map a given phy specified by +.Fa phy +to its unit-address in the map +.Fa phymap . +This function will allocate memory for the character string, thus it can +be modified. +The caller must call the +.Fa sas_phymap_ua_free +function to release the memory that was allocated. +The +.Fa sas_phymap_ua_free +function should not be used with the string returned from the +.Fn sas_phymap_lookup_ua +function. +.Pp +The +.Fn sas_phymap_ua2phys +function creates a collection of phys that exist on a given logical port +represented by the unit-address +.Fa ua +in the map +.Fa phymap . +This set can be iterated by calling the +.Fn sas_phyap_phys_next +function. +Each time the function is called, an entry is returned. +When the value +.Sy -1 +is returned it indicates that the set is empty. +Regardless of whether or not the set has been iterated over, the caller +must call the +.Fn sas_phymap_phys_free +function to release the memory associated with the set. +.Sh CONTEXT +All functions may be used in +.Sy user , +.Sy kernel , +and +.Sy interrupt +context. +.Sh RETURN VALUES +Upon successful completion, the +.Fn sas_phymap_lookup_ua +and +.Fn sas_phymap_phy2ua +function returns a pointer to the unit-address. +If the port or phy could not be found or another error occurred, then +the function returns +.Dv NULL . +.Pp +Upon successful completion, the +.Fn sas_phymap_lookup_uapriv +function returns a pointer to the port's private data, if any exists. +Otherwise, if the port could not be found or another error occurred, then +the function returns +.Dv NULL . +Upon successful completion, the +.Fn sas_phymap_uahasphys +returns +.Sy 1 +to indicate that the unit-address has phys. +If the unit-address has no phys, then it returns +.Sy 0 . +If an error occurred or the port doesn't exist, then the function returns +.Sy 0 . +.Pp +Upon successful completion, the +.Fn sas_phymap_ua2phys +function returns a pointer to an allocated phy set. +Otherwise, it returns +.Dv NULL . +.Pp +The +.Fn sas_phymap_phys_next +function returns a non-negative integer indicating a present phy or it +returns +.Sy -1 +to indicate that no values remain. +.Sh SEE ALSO +.Xr phymap 9 , +.Xr sas_phymap_create 9F diff --git a/usr/src/man/man9f/scsi_address_device.9f b/usr/src/man/man9f/scsi_address_device.9f new file mode 100644 index 0000000000..f550d5d324 --- /dev/null +++ b/usr/src/man/man9f/scsi_address_device.9f @@ -0,0 +1,169 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2017, Joyent, Inc. +.\" +.Dd Apr 20, 2017 +.Dt SCSI_ADDRESS_DEVICE 9F +.Os +.Sh NAME +.Nm scsi_address_device , +.Nm scsi_device_unit_address , +.Nm scsi_device_hba_private_get , +.Nm scsi_device_hba_private_set +.Nd SCSI Complex addressing utility functions +.Sh SYNOPSIS +.In sys/scsi/scsi.h +.Ft "struct scsi_device *" +.Fo scsi_address_device +.Fa "struct scsi_address *sa" +.Fc +.Ft "void *" +.Fo scsi_device_hba_private_get +.Fa "struct scsi_device *sd" +.Fc +.Ft void +.Fo scsi_device_hba_private_set +.Fa "struct scsi_device *sd" +.Fa "void *data" +.Fc +.Ft "char *" +.Fo scsi_device_unit_address +.Fa "struct scsi_device *sd" +.Fc +.Sh INTERFACE LEVEL +.Sy Evolving - +This interface is still evolving in illumos. +API and ABI stability is +not guaranteed. +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa sa +Pointer to a +.Xr scsi_address 9S +structure. +.It Fa sd +Pointer to a +.Xr scsi_device 9S +structure. +.It Fa data +A private value that the driver can get and set. +.El +.Sh DESCRIPTION +These functions provide useful services for SCSI HBA drivers that use +complex addressing. +In complex addressing mode, the +.Xr scsi_address 9S +structure is treated as an opaque structure and is not a simple target +and LUN. +To use these functions, the driver must have enabled complex addressing +by passing the +.Dv SCSI_HBA_ADDR_COMPLEX +flag into the +.Fa hba_flags +argument of the +.Xr scsi_hba_attach_setup 9F +function. +If the +.Dv SCSI_HBA_ADDR_COMPLEX +flag was not passed, then the driver must not call the +.Fn scsi_device_hba_private_get , +.Fn scsi_device_hba_private_set , +or +.Fn scsi_device_unit_address +functions. +.Pp +The +.Fn scsi_address_device +function maps the +.Xr scsi_address 9S +function back to its corresponding +.Xr scsi_device 9S +structure. +If the +.Dv SCSI_HBA_ADDR_COMPLEX +flag has not been set, then the function will return +.Dv NULL . +This can be used as a way to check if the flag has been set on the +device. +.Pp +The +.Fn scsi_device_hba_private_set +function, allows a driver to set a private data value on the +.Xr scsi_device 9S +structure, which it can later retrieve through the +.Fn scsi_device_hba_private_get +function. +Most drivers will set a value during the +.Xr tran_start 9E +entry point and then reference the data structure later on. +This is designed to simplify the management of mapping between driver +data structures and the corresponding system objects. +.Pp +The +.Fn scsi_device_unit_address +function returns the unit address of the +.Xr scsi_device 9S +structure. +The returned string should not be modified by the device driver. +The unit address string comes from values that are passed when +the device is enumerated, generally through an instance of an +.Xr iport 9 . +.Sh CONTEXT +These functions may be used in +.Sy user , +.Sy kernel , +and +.Sy interrupt +context. +.Sh RETURN VALUES +Upon successful completion, the +.Fn scsi_address_device +function returns a pointer to the +.Xr scsi_device 9S +structure. +Otherwise, if an error occurred +.Dv NULL +is returned. +.Pp +The +.Fn scsi_device_hba_private_set +function returns a data value registered via the +.Fn scsi_device_hba_private_get +function. +If the +.Fn scsi_device_hba_private_get +was never called, +.Dv NULL +is returned. +.Pp +Upon successful completion, the +.Fn scsi_device_unit_address +returns a pointer to a character string with the device's unit address. +Otherwise, +.Dv NULL +is returned. +.Pp +If the +.Dv SCSI_HBA_ADDR_COMPLEX +flag has not been set for the HBA structure or iport, then the +.Fn scsi_address_device , +.Fn scsi_device_hba_private_get , +and +.Fn scsi_device_unit_address +functions return +.Dv NULL . +.Sh SEE ALSO +.Xr iport 9 , +.Xr tran_start 9E , +.Xr scsi_hba_attach_setup 9F , +.Xr scsi_address 9S , +.Xr scsi_device 9S diff --git a/usr/src/man/man9f/scsi_hba_attach_setup.9f b/usr/src/man/man9f/scsi_hba_attach_setup.9f index dfe56db9f4..45a72a06ca 100644 --- a/usr/src/man/man9f/scsi_hba_attach_setup.9f +++ b/usr/src/man/man9f/scsi_hba_attach_setup.9f @@ -1,292 +1,281 @@ -'\" te .\" Copyright (c) 2006 Sun Microsystems, Inc., All Rights Reserved .\" Copyright 2014 Garrett D'Amore <garrett@damore.org> +.\" Copyright (c) 2017, Joyent, Inc. .\" 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] -.TH SCSI_HBA_ATTACH_SETUP 9F "May 24, 2014" -.SH NAME -scsi_hba_attach_setup, scsi_hba_detach \- SCSI HBA attach and -detach routines -.SH SYNOPSIS -.LP -.nf -#include <sys/scsi/scsi.h> - - - -\fBint\fR \fBscsi_hba_attach_setup\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_attr_t *\fR\fIhba_dma_attr\fR, - \fBscsi_hba_tran_t *\fR\fIhba_tran\fR, \fBint\fR \fIhba_flags\fR); -.fi - -.LP -.nf -\fBint\fR \fBscsi_hba_detach\fR(\fBdev_info_t *\fR\fIdip\fR); -.fi - -.SH INTERFACE LEVEL -.sp -.LP -Solaris architecture specific (Solaris DDI). -.SH PARAMETERS -.sp -.ne 2 -.na -\fB\fIdip\fR\fR -.ad -.RS 16n -Pointer to the \fBdev_info_t\fR structure that refers to the instance of the -HBA device. -.RE - -.sp -.ne 2 -.na -\fB\fIhba_tran\fR\fR -.ad -.RS 16n -Pointer to a \fBscsi_hba_tran\fR(9S) structure. -.RE - -.sp -.ne 2 -.na -\fB\fIhba_flags\fR\fR -.ad -.RS 16n -Flag modifiers. The defined flag values are \fBSCSI_HBA_TRAN_CLONE\fR, -\fBSCSI_HBA_TRAN_SCB\fR, and \fBSCSI_HBA_TRAN_CDB\fR. -.RE - -.sp -.ne 2 -.na -\fB\fIhba_options\fR\fR -.ad -.RS 16n -Optional features provided by the HBA driver for future extensions; must be -\fINULL\fR. -.RE - -.sp -.ne 2 -.na -\fB\fIhba_dma_attr\fR\fR -.ad -.RS 16n -Pointer to a \fBddi_dma_attr\fR(9S) structure. -.RE - -.SH DESCRIPTION -.sp -.SS "scsi_hba_attach_setup(\|)" -.sp -.LP -The \fBscsi_hba_attach_setup()\fR function registers the -\fIhba_dma_attr\fR DMA attributes and the \fIhba_tran\fR transport vectors of -each instance of the HBA device defined by \fIdip\fR. The HBA driver can pass -different DMA attributes and the transport vectors for each -instance of the device to support any constraints imposed by the HBA itself. -.sp -.LP -The \fBscsi_hba_attach_setup()\fR function uses the -\fBdev_bus_ops\fR field in the \fBdev_ops\fR(9S) structure. The HBA driver -should initialize this field to \fINULL\fR before calling -\fBscsi_hba_attach_setup()\fR. -.sp -.LP -If \fBSCSI_HBA_TRAN_CLONE\fR is requested in \fIhba_flags\fR, the -\fBhba_tran\fR structure is cloned once for each target that is attached to the -HBA. The structure is cloned before the \fBtran_tgt_init\fR(9E) entry point is -called to initialize a target. At all subsequent HBA entry points, including -\fBtran_tgt_init\fR(9E), the \fBscsi_hba_tran_t\fR structure passed as an -argument or found in a \fBscsi_address\fR structure is the cloned -\fBscsi_hba_tran_t\fR structure,which allows the HBA to use the -\fBtran_tgt_private\fR field in the \fBscsi_hba_tran_t\fR structure to point to -per-target data. The HBA should free only the same \fBscsi_hba_tran_t\fR -structure allocated when the HBA detaches. All cloned \fBscsi_hba_tran_t\fR +.Dd Apr 23, 2017 +.Dt SCSI_HBA_ATTACH_SETUP 9F +.Os +.Sh NAME +.Nm scsi_hba_attach_setup , +.Nm scsi_hba_detach +.Nd SCSI HBA attach and detach routines +.Sh SYNOPSIS +.In sys/scsi/scsi.h +.Ft int +.Fo scsi_hba_attach_setup +.Fa "dev_info_t *dip" +.Fa "ddi_dma_attr_t *hba_dma_attr" +.Fa "scsi_hba_tran_t *hba_tran" +.Fa "int hba_flags" +.Fc +.Ft int +.Fo scsi_hba_detach +.Fa "dev_info_t *dip" +.Fc +.Sh INTERFACE LEVEL +illumos architecture specific (illumos DDI). +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa dip +Pointer to the +.Vt dev_info_t +structure that refers to the instance of the HBA device. +.It Fa hba_tran +Pointer to a +.Xr scsi_hba_tran 9S +structure. +.It Fa hba_flags +Flag modifiers. +The defined flag values are +.Dv SCSI_HBA_TRAN_CLONE , +.Dv SCSI_HBA_TRAN_SCB , +.Dv SCSI_HBA_TRAN_CDB , +.Dv SCSI_HBA_HBA , +and +.Dv SCSI_HBA_ADDR_COMPLEX . +.It Fa hba_dma_attr +Pointer to a +.Xr ddi_dma_attr 9S +structure. +.El +.Sh DESCRIPTION +.Ss Fn scsi_hba_attach_setup +The +.Fn scsi_hba_attach_setup +function registers the +.Fa hba_dma_attr +DMA attributes and the +.Fa hba_tran +transport vectors of each instance of the HBA device defined by +.Fa dip . +The HBA driver can pass different DMA attributes and the transport +vectors for each instance of the device to support any constraints +imposed by the HBA itself. +.Pp +The +.Fn scsi_hba_attach_setup +function uses the +.Vt dev_bus_ops +field in the +.Xr dev_ops 9S +structure. +The HBA driver should initialize this field to +.Dv NULL +before calling +.Fn scsi_hba_attach_setup . +.Pp +If +.Dv SCSI_HBA_TRAN_CLONE +is requested in +.Fa hba_flags , +the +Fa hba_tran +structure is cloned once for each target that is attached to the +HBA. +The use of this flag is deprecated, drivers should instead use +.Dv SCSI_HBA_ADDR_COMPLEX +for per-target data. +.Pp +The structure is cloned before the +.Xr tran_tgt_init 9E +entry point is called to initialize a target. +At all subsequent HBA +entry points, including +.Xr tran_tgt_init 9E , +the +.Vt scsi_hba_tran_t +structure passed as an +argument or found in a +.Xr scsi_address 9S +structure is the cloned +.Vt scsi_hba_tran_t +structure, which allows the HBA to use the +.Vt tran_tgt_private +field in the +.Vt scsi_hba_tran_t +structure to point to per-target data. +The HBA should free only the same +.Vt scsi_hba_tran_t +structure allocated when the HBA detaches. +All cloned +.Vt scsi_hba_tran_t structures that are allocated by the system are freed by the system. -.sp -.LP -The flags \fBSCSI_HBA_TRAN_CDB\fR and \fBSCSI_HBA_TRAN_SCB\fR are only valid -when \fBtran_setup_pkt()\fR is used. See \fBtran_setup_pkt\fR(9E) for -information on using these flags. -.sp -.LP -The \fBscsi_hba_attach_setup()\fR function attaches -a number of integer-valued properties to \fIdip\fR, unless properties of the -same name are already attached to the node. An HBA driver should retrieve these -configuration parameters via \fBddi_prop_get_int\fR(9F), and respect any -settings for features provided the HBA. -.sp -.ne 2 -.na -\fB\fBscsi-options\fR\fR -.ad -.RS 26n -\fBOptional\fR \fBSCSI\fR \fBconfiguration bits\fR -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_DR\fR\fR -.ad -.RS 26n +.Pp +The flags +.Dv SCSI_HBA_TRAN_CDB +and +.Dv SCSI_HBA_TRAN_SCB +are only valid +when +.Fn tran_setup_pkt +is used. +See +.Xr tran_setup_pkt 9E +for information on using these flags. +.Pp +The flag +.Dv SCSI_HBA_ADDR_COMPLEX +indicates to the system that this device handles more complex SCSI +topologies, such as SAS. +When this flag is set, the +.Xr scsi_address 9S +structure becomes opaque. +The driver must not check it for the traditional target and LUN values. +Instead, a target and LUN are identified by a unit address which can be +retrieved using the +.Xr scsi_device_unit_address 9F +function. +.Pp +When operating with the flag +.Dv SCSI_HBA_ADDR COMPLEX , +the driver may associate private data with the +.Xr scsi_device 9S +structure. +This obviates the need and complexity around using +.Dv SCSI_HBA_TRAN_CLONE +flag. +To get and set private data, the driver can use the +.Xr scsi_device_hba_private_get 9F +and +.Xr scsi_device_hba_private_set 9F +functions. +Notably, the +.Fn scsi_device_hba_private_set +function should be used during the +.Xr tran_tgt_init 9E +entry point. +The +.Fn scsi_device_hba_private_get +function should then be used during other SCSI HBA entry points. +In addition, the +.Xr scsi_address_device 9F +function now becomes available to the driver to map between the +.Xr scsi_device 9S +and +.Xr scsi_address 9S +structures. +.Pp +The +.Dv SCSI_HBA_HBA +flag indicates that the HBA driver will only enumerate direct children +which are +.Xr iport 9 +instances. +This mode of operation is recommended for device drivers as +it simplifies the management of discovered devices. +This flag is often used in tandem with +.Dv SCSI_HBA_ADDR_COMPLEX +and is recommended for all new SAS-based HBA drivers. +For more information on the management of iports and the use of target +maps, please see +.Xr iport 9 . +.Pp +The +.Fn scsi_hba_attach_setup +function attaches a number of integer-valued properties to +.Fa dip , +unless properties of the same name are already attached to the node. +An HBA driver should retrieve these configuration parameters via +.Xr ddi_prop_get_int 9F , +and respect any settings for features provided the HBA. +.Bl -tag -width Sy +.It Sy scsi-options +.Sy Optional SCSI configuration bits . +The following values may be bitwise-inclusive-ORed together. +.Bl -tag -width Dv +.It Dv SCSI_OPTIONS_DR If not set, the HBA should not grant Disconnect privileges to target devices. -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_TAG\fR\fR -.ad -.RS 26n +.It Dv SCSI_OPTIONS_TAG If not set, the HBA should not operate in Command Tagged Queueing mode. -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_PARITY\fR\fR -.ad -.RS 26n +.It Dv SCSI_OPTIONS_PARITY If not set, the HBA should not operate in parity mode. -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_QAS\fR\fR -.ad -.RS 26n +.It Dv SCSI_OPTIONS_QAS If not set, the HBA should not make use of the Quick Arbitration Select -feature. Consult your Sun hardware documentation to determine whether your +feature. +Consult your hardware documentation to determine whether your machine supports QAS. -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_FAST\fR\fR -.ad -.RS 26n +.It Dv SCSI_OPTIONS_FAST If not set, the HBA should not operate the bus in FAST SCSI mode. -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_FAST20\fR\fR -.ad -.RS 26n +.It Dv SCSI_OPTIONS_FAST20 If not set, the HBA should not operate the bus in FAST20 SCSI mode. -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_FAST40\fR\fR -.ad -.RS 26n +.It Dv SCSI_OPTIONS_FAST40 If not set, the HBA should not operate the bus in FAST40 SCSI mode. -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_FAST80\fR\fR -.ad -.RS 26n +.It Dv SCSI_OPTIONS_FAST80 If not set, the HBA should not operate the bus in FAST80 SCSI mode. -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_FAST160\fR\fR -.ad -.RS 26n +.It Dv SCSI_OPTIONS_FAST160 If not set, the HBA should not operate the bus in FAST160 SCSI mode. -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_FAST320\fR\fR -.ad -.RS 26n +.It Dv SCSI_OPTIONS_FAST320 If not set, the HBA should not operate the bus in FAST320 SCSI mode. -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_WIDE\fR\fR -.ad -.RS 26n +.It Dv SCSI_OPTIONS_WIDE If not set, the HBA should not operate the bus in WIDE SCSI mode. -.RE - -.sp -.ne 2 -.na -\fB\fBSCSI_OPTIONS_SYNC\fR\fR -.ad -.RS 26n +.It Dv SCSI_OPTIONS_SYNC If not set, the HBA should not operate the bus in synchronous transfer mode. -.RE - -.sp -.ne 2 -.na -\fB\fBscsi-reset-delay\fR\fR -.ad -.RS 26n +.El +.It Sy scsi-reset-delay SCSI bus or device reset recovery time, in milliseconds. -.RE - -.sp -.ne 2 -.na -\fB\fBscsi-selection-timeout\fR\fR -.ad -.RS 26n -Default SCSI selection phase timeout value, in milliseconds. Please refer to -individual HBA man pages for any HBA-specific information -.RE - -.SS "scsi_hba_detach(\|)" -.sp -.LP -The \fBscsi_hba_detach()\fR function removes the reference to the DMA -attributes structure and the transport vector for the given instance of an HBA -driver. -.SH RETURN VALUES -.sp -.LP -The \fBscsi_hba_attach_setup()\fR and -\fBscsi_hba_detach()\fR functions return \fBDDI_SUCCESS\fR if the function call -succeeds, and return \fBDDI_FAILURE\fR on failure. -.SH CONTEXT -.sp -.LP -The \fBscsi_hba_attach_setup()\fR function should -be called from \fBattach\fR(9E). The \fBscsi_hba_detach()\fR function should be -called from \fBdetach\fR(9E). -.SH SEE ALSO -.sp -.LP -\fBattach\fR(9E), \fBdetach\fR(9E), \fBtran_setup_pkt\fR(9E), -\fBtran_tgt_init\fR(9E), \fBddi_prop_get_int\fR(9F), \fBddi_dma_attr\fR(9S), -\fBdev_ops\fR(9S), \fBscsi_address\fR(9S), -\fBscsi_hba_tran\fR(9S) -.sp -.LP -\fIWriting Device Drivers\fR -.SH NOTES -.sp -.LP +.It Sy scsi-selection-timeout +Default SCSI selection phase timeout value, in milliseconds. +Please refer to individual HBA man pages for any HBA-specific +information +.El +.Ss Fn scsi_hba_detach +The +.Fn scsi_hba_detach +function removes the reference to the DMA attributes structure and the +transport vector for the given instance of an HBA driver. +.Sh CONTEXT +The +.Fn scsi_hba_attach_setup +function should be called from +.Xr attach 9E . +The +.Fn scsi_hba_detach +function should be called from +.Xr detach 9E . +.Sh RETURN VALUES +The +.Fn scsi_hba_attach_setup +and +.Fn scsi_hba_detach +functions return +.Dv DDI_SUCCESS +if the function call succeeds, and return +.Dv DDI_FAILURE +on failure. +.Sh SEE ALSO +.Xr iport 9 , +.Xr attach 9E , +.Xr detach 9E , +.Xr tran_setup_pkt 9E , +.Xr tran_tgt_init 9E , +.Xr ddi_prop_get_int 9F , +.Xr scsi_address_device 9F , +.Xr scsi_device_hba_private_get 9F , +.Xr scsi_device_hba_private_set 9F , +.Xr scsi_device_unit_address 9F , +.Xr ddi_dma_attr 9S , +.Xr dev_ops 9S , +.Xr scsi_address 9S , +.Xr scsi_device 9S , +.Xr scsi_hba_tran 9S +.Pp +.Rs +.%T Writing Device Drivers +.Re +.Sh NOTES It is the HBA driver's responsibility to ensure that no more transport requests will be taken on behalf of any SCSI target device driver after -\fBscsi_hba_detach()\fR is called. +.Fn scsi_hba_detach +is called. diff --git a/usr/src/man/man9f/scsi_hba_iport_exist.9f b/usr/src/man/man9f/scsi_hba_iport_exist.9f new file mode 100644 index 0000000000..2f059bc1a7 --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_iport_exist.9f @@ -0,0 +1,98 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2017, Joyent, Inc. +.\" +.Dd Apr 18, 2017 +.Dt SCSI_HBA_IPORT_EXIST 9F +.Os +.Sh NAME +.Nm scsi_hba_iport_exist , +.Nm scsi_hba_iport_find +.Nd find and check if an iport exists +.Sh SYNOPSIS +.In sys/scsi/scsi.h +.Ft int +.Fo scsi_hba_iport_exist +.Fa "dev_info_t *dip" +.Fc +.Ft "dev_info_t *" +.Fo scsi_hba_iport_find +.Fa "dev_info_t *dip" +.Fa "char *ua" +.Fc +.Sh INTERFACE LEVEL +.Sy Evolving - +This interface is still evolving in illumos. +API and ABI stability is not guaranteed. +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa dip +Pointer to +.Vt dev_info +structure. +.It Fa ua +The unit address of the iport being searched for. +.El +.Sh DESCRIPTION +The +.Fn scsi_hba_iport_exists +function is used to determine whether or not +.Fa dip +has any child devices that are iports which have been added through +.Xr scsi_hba_iport_register 9F +or +.Xr scsi_hba_iportmap_iport_add 9F . +For more information on iports, see +.Xr iport 9 . +.Pp +The +.Fn scsi_hba_iport_find +function attempts to find a child iport and return its +.Vt dev_info +structure if it exists. +The iport is searched for by its unit address, which is passed in the +.Fa ua +argument. +The unit address for an iport is established when the iport is created. +.Sh CONTEXT +The +.Fn scsi_hba_iport_exist +and +.Fn scsi_hba_iport_find +functions may be called in either +.Sy user +or +.Sy kernel +context. +.Sh RETURN VALUES +The +.Fn scsi_hba_iport_exists +function returns +.Sy 1 +when there is a child iport of +.Fa dip . +Otherwise, it returns +.Sy 0. +.Pp +The +.Fn scsi_hba_iport_find +function returns a pointer to the iport's +.Vt dev_info +structure, if found. +Otherwise, +.Dv NULL +is returned. +.Sh SEE ALSO +.Xr iport 9 , +.Xr iportmap 9 , +.Xr scsi_hba_iport_register 9F , +.Xr scsi_hba_iportmap_iport_add 9F diff --git a/usr/src/man/man9f/scsi_hba_iport_register.9f b/usr/src/man/man9f/scsi_hba_iport_register.9f new file mode 100644 index 0000000000..085c88f3a0 --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_iport_register.9f @@ -0,0 +1,88 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2017, Joyent, Inc. +.\" +.Dd Apr 18, 2017 +.Dt SCSI_HBA_IPORT_REGISTER 9F +.Os +.Sh NAME +.Nm scsi_hba_iport_register +.Nd register a new iport +.Sh SYNOPSIS +.In sys/scsi/scsi.h +.Ft int +.Fo scsi_hba_iport_register +.Fa "dev_info_t *dip" +.Fa "char *port" +.Fc +.Sh INTERFACE LEVEL +.Sy Evolving - +This interface is still evolving in illumos. +API and ABI stability is +not guaranteed. +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa dip +Pointer to +.Vt dev_info +structure. +.It Fa port +The name of the iport to add. +.El +.Sh DESCRIPTION +The +.Fn scsi_hba_iport_register +function is used to create a new iport. +For more information on iports and their uses, see +.Xr iport 9 . +This interface is generally used then there are a fixed, static set of +iports that exist in the system. +If the set of iports is dynamic or related to phys coming online and +offline, then the driver should instead consider using the +.Xr iportmap 9 +abstraction. +.Pp +The iport will be created as a child of the device represented by +.Fa dip . +The iport will be bound to the same driver. +To distinguish nodes, the driver should use the +.Xr scsi_hba_iport_unit_address 9F +function. +.Pp +The name of the iport, specified by +.Fa port , +must be unique for a given parent. +The iport will not be created if the name is already in use. +While names generally are based on unit addresses, they may be synthetic +names. +.Sh CONTEXT +The +.Fn scsi_hba_iport_register +function is generally called during the +.Xr attach 9E +entry point and may be called from +.Sy user +or +.Sy kernel +context. +.Sh RETURN VALUES +Upon successful completion, the +.Fn scsi_hba_iport_register +function returns +.Dv DDI_SUCCESS . +Otherwise, +.Dv DDI_FAILURE +is returned. +.Sh SEE ALSO +.Xr iport 9 , +.Xr iportmap 9 , +.Xr scsi_hba_iportmap_iport_add 9F diff --git a/usr/src/man/man9f/scsi_hba_iport_unit_address.9f b/usr/src/man/man9f/scsi_hba_iport_unit_address.9f new file mode 100644 index 0000000000..94b11d84c2 --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_iport_unit_address.9f @@ -0,0 +1,74 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2017, Joyent, Inc. +.\" +.Dd Apr 18, 2017 +.Dt SCSI_HBA_IPORT_UNIT_ADDRESS 9F +.Os +.Sh NAME +.Nm scsi_hba_iport_unit_address +.Nd Get the unit address of an iport +.Sh SYNOPSIS +.In sys/scsi/scsi.h +.Ft "char *" +.Fo scsi_hba_iport_unit_address +.Fa "dev_info_t *dip" +.Fc +.Sh INTERFACE LEVEL +.Sy Evolving - +This interface is still evolving in illumos. +API and ABI stability is +not guaranteed. +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa dip +Pointer to +.Vt dev_info +structure. +.El +.Sh DESCRIPTION +The +.Fn scsi_hba_iport_unit_address +function is used to obtain the unit address of an iport. +For more information on iports, see +.Xr iport 9 . +.Pp +This function can be used to determine whether or not a device node in +the tree is an iport. +If the device node corresponds to an iport, then +the unit address used when it was created either through +.Xr scsi_hba_iport_register 9F +or +.Xr scsi_hba_iportmap_iport_add 9F +will be returned. +.Sh CONTEXT +The +.Fn scsi_hba_iport_unit_address +function may be called in +.Sy user , +.Sy kernel , +or +.Sy interrupt +context. +.Sh RETURN VALUES +If +.Fa dip +is an iport, then the unit address string the device was registered with +is returned. +Otherwise, +.Dv NULL +is returned. +.Sh SEE ALSO +.Xr iport 9 , +.Xr iportmap 9 , +.Xr scsi_hba_iport_register 9F , +.Xr scsi_hba_iportmap_iport_add 9F diff --git a/usr/src/man/man9f/scsi_hba_iportmap_create.9f b/usr/src/man/man9f/scsi_hba_iportmap_create.9f new file mode 100644 index 0000000000..8c7e127160 --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_iportmap_create.9f @@ -0,0 +1,179 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2017, Joyent, Inc. +.\" +.Dd Apr 18, 2017 +.Dt SCSI_HBA_IPORTMAP_CREATE 9F +.Os +.Sh NAME +.Nm scsi_hba_iportmap_create , +.Nm scsi_hba_iportmap_destroy , +.Nm scsi_hba_iportmap_iport_add , +.Nm scsi_hba_iportmap_iport_remove +.Nd create and manage an iportmap +.Sh SYNOPSIS +.In sys/scsi/scsi.h +.Ft int +.Fo scsi_hba_iportmap_create +.Fa "dev_info_t *dip" +.Fa "int csync_usec" +.Fa "int settle_usec" +.Fa "scsi_hba_iportmap_t **iportmapout" +.Fc +.Ft void +.Fo scsi_hba_iportmap_destroy +.Fa "scsi_hba_iportmap_t *iportmap" +.Fc +.Ft int +.Fo scsi_hba_iportmap_iport_add +.Fa "scsi_hba_iportmap_t *iportmap" +.Fa "char *ua" +.Fa "void *priv" +.Fc +.Ft int +.Fo scsi_hba_iportmap_iport_remove +.Fa "scsi_hba_iportmap_t *iportmap" +.Fa "char *ua" +.Fc +.Sh INTERFACE LEVEL +.Sy Evolving - +This interface is still evolving in illumos. +API and ABI stability is not guaranteed. +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa dip +Pointer to +.Vt dev_info +structure. +.It Fa csync_usec +A time in microseconds. +.It Fa settle_usec +A time in microseconds. +.It Fa iportmap +An allocated iportmap. +.It Fa iportmapout +Pointer where the iportmap is stored. +.It Fa ua +A character string that represents a unit address for an iport. +.It Fa priv +Drivers should pass +.Dv NULL +for this field. +.El +.Sh DESCRIPTION +The +.Fn scsi_hba_iportmap_create +and +.Fn scsi_hba_iportmap_destroy +functions are used by HBA drivers to create and destroy an iportmap. +For more information on an iportmap and its purpose, see +.Xr iportmap 9 . +.Pp +The +.Fa csync_usec +and +.Fa settle_usec +are both times measured in microseconds that control two different +properties of the iportmap and how it behaves. +The value in +.Fa settle_usec +indicates the amount of time that the system should wait to quiesce all +changes and consider the resulting system stable. +Changes will not be reported until after +.Fa settle_usec +have passed. +.Fa csync_usec +indicates how much time needs to elapse after creation before an initial +enumeration has been completed. +.Pp +The +.Vt dev_info +structure passed into +.Fa dip +is usually the HBA driver's +.Vt dev_info +structure. +.Pp +When the +.Fn scsi_hba_iportmap_iport +function returns, +.Fa iportmapout +will be populated with a pointer to an iportmap that can be used to add +and remove iports. +.Pp +To destroy the iportmap, drivers should use the +.Fn scsi_hba_iportmap_destroy +function. +As part of destroying the iportmap, all associated iports will +be detached from the system by having the driver's +.Xr detach 9E +entry point called. +.Pp +When the driver needs to add an iport to the system, generally in +response to a hotplug event, then the driver should call the +.Fn scsi_hba_iportmap_iport_add +function. +The value of +.Fa ua +should be a character string that uniquely identifies the device. +If the driver is using a phymap, then this unit address should be the +same one as the phymap's callback provided. +Otherwise, the driver sets +.Fa ua +to a unique string which is generally the iport's WWN. +.Pp +When the corresponding iport needs to be removed, then the driver should +call the +.Fn scsi_hba_iportmap_remove +function. +The iport to remove is indicated by the +.Fa ua +argument, which should match the value passed into the +.Fn scsi_hba_iportmap_add +function. +.Sh CONTEXT +The +.Fn scsi_hba_iportmap_create +function is generally called during a driver's +.Xr attach 9E +entry point. +.Pp +The +.Fn scsi_hba_iportmap_destroy +function is generally called during a driver's +.Xr detach 9E +entry point. +.Pp +The +.Fn scsi_hba_iportmap_iport_add +and +.Fn scsi_hba_iportmap_iport_remove +functions should be called from +.Sy kernel +context. +.Sh RETURN VALUES +Upon successful completion, the +.Fn scsi_hba_iportmap_create , +.Fn scsi_hba_iportmap_iport_add , +and +.Fn scsi_hba_iportmap_iport_remove +functions return +.Dv DDI_SUCCESS. +Otherwise, +.Dv DDI_FAILURE +is returned. +.Sh SEE ALSO +.Xr iport 9 , +.Xr iportmap 9 , +.Xr attach 9E , +.Xr detach 9E , +.Xr detach 9E diff --git a/usr/src/man/man9f/scsi_hba_tgtmap_create.9f b/usr/src/man/man9f/scsi_hba_tgtmap_create.9f new file mode 100644 index 0000000000..3f5a393cf1 --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_tgtmap_create.9f @@ -0,0 +1,489 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2017, Joyent, Inc. +.\" +.Dd Apr 18, 2017 +.Dt SCSI_HBA_TGTMAP_CREATE 9F +.Os +.Sh NAME +.Nm scsi_hba_tgtmap_create , +.Nm scsi_hba_tgtmap_destroy , +.Nm scsi_hba_tgtmap_set_begin , +.Nm scsi_hba_tgtmap_set_add , +.Nm scsi_hba_tgtmap_set_end , +.Nm scsi_hba_tgtmap_set_flush , +.Nm scsi_hba_tgtmap_tgt_add , +.Nm scsi_hba_tgtmap_tgt_remove +.Nd SCSI target map functions +.Sh SYNOPSIS +.In sys/scsi/scsi.h +.Ft int +.Fo scsi_hba_tgtmap_create +.Fa "dev_info_t *dip" +.Fa "scsi_tgtmap_mode_t mode" +.Fa "int csync_usec" +.Fa "int settle_usec" +.Fa "void *tgtmap_priv" +.Fa "scsi_tgt_activate_cb_t activate_cb" +.Fa "scsi_tgt_deactivate_cb_t deactivate_cb" +.Fa "scsi_hba_tgtmap_t *tgtmapout" +.Fc +.Ft void +.Fo scsi_hba_tgtmap_destroy +.Fa "scsi_hba_tgtmap_t *tgtmap" +.Fc +.Ft void +.Fo (*scsi_tgt_activate_cb_t) +.Fa "void *tgtmap_priv" +.Fa "char *tgt_addr" +.Fa "scsi_tgtmap_tgt_type_t type" +.Fa "void **tgt_privp" +.Fc +.Ft boolean_t +.Fo (*scsi_tgt_deactivate_cb_t) +.Fa "void *tgtmap_priv" +.Fa "char *tgt_addr" +.Fa "scsi_tgtmap_tgt_type_t type" +.Fa "void *tgt_priv" +.Fa "scsi_tgtmap_deact_rsn_t deact" +.Fc +.Ft int +.Fo scsi_hba_tgtmap_set_begin +.Fa "scsi_hba_tgtmap_t *map" +.Fc +.Ft int +.Fo scsi_hba_tgtmap_set_add +.Fa "scsi_hba_tgtmap_t *tgtmap" +.Fa "scsi_tgtmap_tgt_type_t type" +.Fa "char *tgt_addr" +.Fa "void *tgt_priv" +.Fc +.Ft int +.Fo scsi_hba_tgtmap_set_end +.Fa "scsi_hba_tgtmap_t *map" +.Fc +.Ft int +.Fo scsi_hba_tgtmap_set_flush +.Fa "scsi_hba_tgtmap_t *map" +.Fc +.Ft int +.Fo scsi_hba_tgtmap_tgt_add +.Fa "scsi_hba_tgtmap_t *tgtmap" +.Fa "scsi_tgtmap_tgt_type_t type" +.Fa "char *tgt_addr" +.Fa "void *tgt_priv" +.Fc +.Ft int +.Fo scsi_hba_tgtmap_tgt_remove +.Fa "scsi_hba_tgtmap_t *tgtmap" +.Fa "scsi_tgtmap_tgt_type_t type" +.Fa "char *tgt_addr" +.Fc +.Sh INTERFACE LEVEL +.Sy Evolving - +This interface is still evolving in illumos. +API and ABI stability is +not guaranteed. +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa dip +Pointer to +.Vt dev_info +structure. +.It Fa mode +One of the following values: +.Bl -tag -width Dv +.It Dv SCSI_TM_FULLSET +The target map operates by full-set reporting. +.It Dv SCSI_TM_PERADDR +The target map operates by per-address reporting. +.El +.It Fa csync_usec +A time in microseconds. +.It Fa settle_usec +A time in microseconds. +.It Fa tgtmap_priv +A private value to be passed to callback functions. +.It Fa activate_cb +An optional callback that will be called when a new device is being +added to the system. +.It Fa deactivate_cb +An optional callback that will be called when an existing devices is +removed from the system. +.It Fa tgtmapout +Pointer where the target map is stored. +.It Fa tgtmap +Pointer to an allocated target map. +.It Fa tgt_addr +The address of the target map entry the callback is acting upon. +.It Fa type +One of the following values, indicating the type of the target: +.Bl -tag -width Dv +.It Dv SCSI_TGT_SCSI_DEVICE +The target is some form of SCSI device such as a parallel SCSI, SATA, +SAS, SES, etc. +.It Dv SCSI_TGT_SMP_DEVICE +The target is a SCSI Management Protocol device. +.El +.It Fa deact +One of the following values, indicating why the target is being removed: +.Bl -tag -width Dv +.It Dv SCSI_TGT_DEACT_RSN_GONE +The device is being deactivated because it is gone. +.It Dv SCSI_TGT_DEACT_RSN_CFG_FAIL +The device is being deactivated because the configuration callback +failed. +.It Dv SCSI_TGT_DEACT_RSN_UNSTBL +The device is being deactivated because it was added and removed during +the stabilization period and therefore is considered unstable. +.El +.El +.Sh DESCRIPTION +The +.Fn scsi_hba_tgtmap_create +and +.Fn scsi_hba_tgtmap_destroy +functions are used to create and destroy target maps. +A target map is used to manage SCSI and SMP (SCSI Management Protocol) +devices. +For more background on target maps, see +.Xr tgtmap 9 . +.Pp +To create a target map, the driver should call the +.Fn scsi_hba_tgtmap_create +function. +Upon successful completion, a pointer to the target map will be placed +in the +.Fa tgtmapout +argument. +.Pp +The +.Fa dip +argument should correspond to the HBA driver's device node or one of its +iports. +.Pp +The +.Fa mode +argument describes how addresses are reported into the target map and +the functions used to add and remove devices. +If +.Fa mode +is +.Dv SCSI_TM_FULLSET +then the driver must always report all the devices that are in the set +and will be told when the corresponding devices have been removed. +See +the section +.Sx Full-Set Reporting +for more information. +.Pp +Otherwise, the driver should set the +.Fa mode +argument to +.Dv SCSI_TM_PERADDR +and use the +.Fn scsi_hba_tgtmap_tgt_add +and +.Fn scsi_hba_tgtmap_tgt_destroy +functions. +See the section +.Sx Per-Address Reporting +for more information. +.Pp +The +.Fa csync_usec +and +.Fa settle_usec +are both times measured in microseconds that control two different +properties of the target map and how it behaves. +The value in +.Fa settle_usec +indicates the amount of time that the system should wait to quiesce all +changes and consider the resulting system stable. +Changes will not be reported until after +.Fa settle_usec +have passed. +.Fa csync_usec +indicates how much time needs to elapse after creation before an initial +enumeration has been completed. +.Pp +The +.Fa activate_cb +and +.Fa deactivate_cb +arguments are optional function pointers that will be run in the context +of devices being added and removed from the system. +This allows the HBA driver to perform any required operations prior to +the system attaching a target driver such as +.Xr sd 7D +or +.Xr ses 7D +in the activate case and after the system has detached the driver, in +the removal case. +.Pp +To destroy a target map, a caller should use the +.Fn scsi_hba_tgtmap_destroy +function. +Destroying a target map causes all currently present devices +to be deactivated, as though they were removed, prior to the +final destruction of the target map. +.Ss Callbacks +Target maps allow for callbacks to be registered and called when +devices are being added and removed from the system. +A driver specifies these when the target map is created by passing in +function pointers to +the +.Fn activate_cb +and +.Fn deactivate_cb +arguments. +.Pp +When a new address is registered in a target map and the driver has +specified a function in the +.Fa activate_cb +argument, the driver will eventually have their activation function +called. +This call will be asynchronous with respect to the adding and +removing of entries, regardless of whether the target map is using +per-address or full-set reporting. +This call will occur before any driver is bound to the discovered +address. +.Pp +The +.Fa tgtmap_priv +argument will point to the optional, private argument that was passed +to the +.Fn scsi_hba_tgtmap_create +function when the target map was created. +The +.Fa tgt_addr +and +.Fa tgt_type +will describe the address and type of the new device and will correspond +with the values passed into either the +.Fn scsi_hba_tgtmap_set_add +or +.Fn scsi_hba_tgtmap_tgt_add +functions. +.Pp +The +.Fa tgt_privp +argument is a modifiable private value. +Initially, +.Fa tgt_privp +points to the value passed in as +.Fa tgt_priv +to either the +.Fn scsi_hba_tgtmap_set_add +or +.Fn scsi_hba_tgtmap_tgt_add +functions. +The driver may change the value as needed. +It will receive the value stored in +.Fa tgt_privp +during the deactivate callback. +.Pp +When a target map has been updated to indicate that a device has been +removed, then the driver will receive a deactivation callback if it +registered one. +The deactivate callback will occur after a driver has +been detached from the corresponding device. +.Pp +The +.Fa tgtmap_priv , +.Fa tgt_addr , +and +.Fa type +arguments to the callback function are the same as for the activate +case. +The +.Fa tgt_priv +pointer will be set to the value that was passed when the device was +added and will reflect any updates made during an activate callback, if +present. +.Pp +The +.Fa deact +argument gives the driver some amount of information as to why device +was being removed. +The deactivation reason provides the driver +more information about why the address was being removed from the target +map which can be useful in the cases that it itself did not issue it. +.Pp +The return value indicates whether or not some amount of rediscovery of +the address is desired or not. +This is only meaningful in the case where the +.Fa deact +argument was +.Dv SCSI_TGT_DEACT_RSN_CFG_FAIL . +If the driver does wish to attempt rediscovery, then it should return +.Dv B_TRUE . +Otherwise, the driver should return +.Dv B_FALSE . +If in doubt, use the return value +.Dv B_FALSE . +Note, even if the driver returns +.Dv B_TRUE , +no action may be taken by the system. +.Ss Full-Set Reporting +Full-Set reporting is one way of managing a target map. +In full-set reporting, whenever an update is being made, the entire data +set is reported to the target map. +The target map then determines which +addresses are new, which have been removed, and which have stayed the +same and updates the system state appropriately. +If devices have been added or removed from the system, then any activate +and deactivate endpoints will be called. +.Pp +To begin a new report, the driver should call the +.Fn scsi_hba_tgtmap_set_begin +function. +Once the report has begun, the driver should add devices by calling the +.Fn scsi_hba_tgtmap_set_add +function. +Once all devices have been added, the driver should call the +.Fn scsi_hba_tgtmap_set_end +function to indicate that the target map processing has ended. +If driver wishes to discard a report that has begun, but not yet +terminated, then the driver should call the +.Fn scsi_hba_tgtmap_set_flush +function. +.Pp +When adding entries, the driver should indicate the address of the +device in +.Fa tgt_addr . +This will generally be a world wide number (WWN) in a unit-addressable +form. +However, the driver may use its own synthetic numbering. +This address will be passed to the activate callbacks and will also be +used as the address of the +.Xr scsi_device 9S +in the +.Xr tran_start 9E +entry point. +.Pp +The +.Fa type +argument indicates how the kernel will interpret the type of device. +At this time, devices are broken into two broad categories. +Things which are some kind of SCSI device, whether parallel, SCSI, SATA +behind a SATL, SES, etc. should use the type +.Dv SCSI_TGT_SCSI_DEVICE . +The other group, +.Dv SCSI_TGT_SMP_DEVICE , +is for SCSI Management Protocol (SMP) devices. +.Pp +The +.Fa tgt_priv +argument will be passed to the activate and deactivate callbacks, +allowing the driver to pass around data corresponding to this address. +.Ss Per-Address Reporting +When using a target map with per-address reporting, the driver is +responsible for indicating what devices have been added and removed. +This is useful for various hardware configurations where all entries and +removals are processes in a highly-reliable fashion where hardware +cannot drop entries. +.Pp +To add a new device, the driver should call the +.Fa scsi_hba_tgtmap_tgt_add +function. +The +.Fa tgt_addr +and +.Fa type +arguments describe the address and what kind of device the address +corresponds to. +For more information, see the previous section, +.Sx Full-Address Reporting . +The +.Fa tgt_priv +argument will be passed along to the activate and deactivate functions, +allowing the driver to associate a value with the address in question. +.Pp +When a device has been removed, the driver should call the +.Fn scsi_hba_tgtmap_tgt_remove +function, ensuring that both the +.Fa tgt_addr +and +.Fa type +arguments match those that were used when calling the +.Fn scsi_hba_tgtmap_tgt_add +function. +.Sh CONTEXT +The +.Fn scsi_hba_tgtmap_create +and +.Fn scsi_hba_tgtmap_destroy +functions are generally called from the context of the +.Xr attach 9E +and +.Xr detach 9E +entry points of HBA drivers and their iports, though may also be called +from +.Sy user +or +.Sy kernel +context. +.Pp +The optional +.Fn activate_cb +and +.Fn deactivate_cb +functions for a target map will be called into the driver from +.Sy kernel +context. +.Pp +The +.Fn scsi_hba_tgtmap_set_begin , +.Fn scsi_hba_tgtmap_set_add , +.Fn scsi_hba_tgtmap_set_end , +.Fn scsi_hba_tgtmap_set_flush , +.Fn scsi_hba_tgtmap_tgt_add , +and +.Fn scsi_hba_tgtmap_tgt_remove +functions may be called from +.Sy user +or +.Sy kernel +context. +It is recommended that device drivers do not call these functions from +.Sy interrupt +context and instead should schedule deferred work with a task queue +or with +.Xr timeout 9F +if they receive notifications during an interrupt that causes them to +need to call these functions. +.Sh RETURN VALUES +Upon successful completion, the +.Fn scsi_hba_tgtmap_create , +.Fn scsi_hba_tgtmap_destroy , +.Fn scsi_hba_tgtmap_set_begin , +.Fn scsi_hba_tgtmap_set_add , +.Fn scsi_hba_tgtmap_set_end , +.Fn scsi_hba_tgtmap_set_flush , +.Fn scsi_hba_tgtmap_tgt_add , +and +.Fn scsi_hba_tgtmap_tgt_remove +functions return +.Dv DDI_SUCCESS . +Otherwise, +.Dv DDI_FAILURE +is returned. +.Sh SEE ALSO +.Xr sd 7D , +.Xr ses 7D , +.Xr tgtmap 9 , +.Xr attach 9E , +.Xr detach 9E , +.Xr tran_start 9E , +.Xr timeout 9F , +.Xr scsi_device 9S diff --git a/usr/src/man/man9f/scsi_wwnstr_to_wwn.9f b/usr/src/man/man9f/scsi_wwnstr_to_wwn.9f new file mode 100644 index 0000000000..3ff8694050 --- /dev/null +++ b/usr/src/man/man9f/scsi_wwnstr_to_wwn.9f @@ -0,0 +1,169 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2017, Joyent, Inc. +.\" +.Dd Feb 28, 2017 +.Dt SCSI_WWNSTR_TO_WWN 9F +.Os +.Sh NAME +.Nm scsi_wwnstr_to_wwn , +.Nm scsi_wwn_to_wwnstr , +.Nm scsi_free_wwnstr +.Nd SCSI World Wide Name string conversion functions +.Sh SYNOPSIS +.In sys/scsi/scsi.h +.Ft int +.Fo scsi_wwnstr_to_wwn +.Fa "const char *wwwnstr" +.Fa "uint64_t *wwnp" +.Fc +.Ft "char *" +.Fo scsi_wwn_to_wwnstr +.Fa "uint64_t wwn" +.Fa "int ua_form" +.Fa "char *wwnstr" +.Fc +.Ft void +.Fo scsi_free_wwnstr +.Fa "char *wwnstr" +.Fc +.Sh INTERFACE LEVEL +.Sy Evolving - +This interface is still evolving in illumos. +API and ABI stability is not guaranteed. +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa wwn +A 64-bit world wide number. +.It Fa wwnstr +A string representation of a world wide number. +.It Fa wwnp +A pointer to a 64-bit value that will store a world wide number. +.It Fa ua_form +An integer indicating whether or not the unit address form should be +used. +.El +.Sh DESCRIPTION +The +.Fn scsi_wwnstr_to_wwn +and +.Fn scsi_wwn_to_wwnstr +functions convert an 8-byte world wide number to and from a string +representation. +.Pp +World wide numbers are unique identifiers that are used in storage +technologies, particularly ATA, SAS, and FC. +The format of a WWN is defined by the IEEE and generally come in 8 and +16 byte forms. +These interfaces only operate on the 8 byte forms. +.Pp +When the WWN is represented as a string, it is represented as a 16 +character hexadecimal string. +This character string may either use uppercase or lowercase hexadecimal +characters. +The character string may be preceded by a +.Sq w +character. +When this is present, this is called the +.Em unit-address form . +If the string is not 16 ASCII character long or 17, when using the +unit-address form, the string is considered invalid. +The following macros are provided to help deal with these lengths: +.Bl -tag -width Dv +.It Dv SCSI_WWN_STRLEN +The number of bytes, excluding a terminating nul character, for a world +wide number to be represented when not in the unit-address form. +.It Dv SCSI_WWN_UA_STRLEN +The number of bytes, excluding a terminating nul character, for a world +wide number to be represented in the unit-address form. +.It Dv SCSI_WWN_BUFLEN +A number of bytes that is guaranteed to be sufficient to hold any form +of a world wide number and a nul terminator. +.El +.Pp +The +.Fn scsi_wwnstr_to_wwn +function parses the string form of the WWN +.Fa wwnstr +and converts it to a 64-bit representation. +The string form may either be in unit-address form or not. +The string must have a nul terminator. +If the string is successfully parsed, the world wide number is stored in +.Fa wwnp . +.Pp +The +.Fn scsi_wwn_to_wwnstr +converts the world wide number in +.Fa wwn +into a human-readable string as described above. +If the +.Fa ua_form +is non-zero then the unit-address form is used and a leading +.Sq w +is placed. +.Pp +If the +.Fa wwnstr +argument is supplied by the user, then it must be large enough to +contain both the string form of the world wide number and a nul +character. +The +.Dv SCSI_WWN_BUFLEN +macro is recommended. +It will always ensure that a buffer is large +enough to hold any supported string representation of a world wide +number. +.Pp +If the +.Fa wwnstr +argument is instead +.Dv NULL , +then a character string of sufficient size will be allocated by the +system. +Note, this allocation will block until memory is available. +If memory is allocated in this way, then the caller should free this +memory with the +.Fn scsi_free_wwnstr +function. +.Sh CONTEXT +The +.Fn scsi_wwnstr_to_wwn , +.Fn scsi_wwn_to_wwnstr , +and +.Fn scsi_free_wwnstr +functions may be used in +.Sy user , +.Sy kernel , +and +.Sy interrupt +context. +.Sh RETURN VALUES +Upon successful completion, the +.Fn scsi_wwnstr_to_wwn +function returns +.Dv DDI_SUCCESS +and fills in +.Fa wwnp +with the WWN. +Otherwise, +.Dv DDI_FAILURE +is returned, indicating an invalid argument or a malformed string in +.Fa wwnstr . +.Pp +Upon successful completion, the +.Fn scsi_wwn_to_wwnstr +function returns a pointer to the start of the world wide number. +Otherwise +.Dv NULL +is returned to indicate that the conversion failed. +.Sh SEE ALSO +.Xr scsi_hba_iport_unit_address 9F |