8472 Want docs for iports, tgtmaps, and friends

Reviewed by: Jason King <jason.king@joyent.com>
Reviewed by: Toomas Soome <tsoome@me.com>
Reviewed by: Yuri Pankov <yuri.pankov@nexenta.com>
Approved by: Richard Lowe <richlowe@richlowe.net>

16 files changed, 2618 insertions, 336 deletions

diff --git a/usr/src/man/man9/Makefile b/usr/src/man/man9/Makefile
index 66bd9e9a4c..103a1e6b28 100644
--- a/usr/src/man/man9/Makefile
+++ b/usr/src/man/man9/Makefile
@@ -18,12 +18,19 @@ include		$(SRC)/Makefile.master
 
 MANSECT= 	9
 MANFILES=	Intro.9	\
+		iport.9 \
 		vmem.9
 
 
-MANLINKS=	intro.9
+MANLINKS=	intro.9 \
+		iportmap.9 \
+		phymap.9 \
+		tgtmap.9
 
 intro.9		:= LINKSRC = Intro.9
+iportmap.9	:= LINKSRC = iport.9
+phymap.9	:= LINKSRC = iport.9
+tgtmap.9	:= LINKSRC = iport.9
 
 .KEEP_STATE:
 
diff --git a/usr/src/man/man9/iport.9 b/usr/src/man/man9/iport.9
new file mode 100644
index 0000000000..1bf8fcaef1
--- /dev/null
+++ b/usr/src/man/man9/iport.9
@@ -0,0 +1,332 @@
+.\"
+.\" 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 IPORT 9
+.Os
+.Sh NAME
+.Nm iport ,
+.Nm iportmap ,
+.Nm phymap ,
+.Nm tgtmap
+.Nd SCSI Device Management Concepts
+.Sh DESCRIPTION
+The
+.Sy iport ,
+.Sy iportmap ,
+.Sy phymap ,
+and
+.Sy tgtmap
+abstractions enable host bus adapter (HBA) drivers to represent the
+devices that they are responsible for enumerating, as well as the
+relationships between these devices.
+These interfaces simplify device drivers by taking care of the creation
+and destruction of device nodes in the devices tree for enumerated
+devices as well as performing some amount of hysteresis.
+.Pp
+These abstractions are used in tandem with SCSI complex addressing.
+A device driver that uses these interfaces generally passes both the
+.Dv SCSI_HBA_HBA
+flag and the
+.Dv SCSI_HBA_ADDR_COMPLEX
+in the
+.Fa hba_flags
+argument to
+.Xr scsi_hba_attach_setup 9F .
+.Ss iport
+The
+.Sy iport ,
+or initiator port, abstracts a collection of attached devices.
+One way to view an iport is that each iport maps to a phy on the HBA.
+A phy refers to a physical connector between the HBA and devices.
+A phy may be made up of individual lanes.
+A lane is connected to a device, for example a disk driver.
+Multiple lanes maybe plugged into the same device, for example, an
+expander.
+When a phy connects to a device with a single lane, this is often
+called a
+.Em narrow phy .
+When a phy connects to a device with multiple lanes, this is often
+called a
+.Em wide phy .
+.Pp
+Consider a device that has two physical ports, and thus two phys.
+Each phy has four lanes, thus we describe the phy as having a mask of
+0xf.
+Each bit in the mask corresponds to a specific lane.
+In this example, each phy would be represented in the system by an iport
+and may enumerate a different device for each lane of the phy.
+If an expander is attached to one or more of the lanes of a phy, then
+additional devices will be enumerated under the expander and be added to
+that phy's iport.
+.Pp
+Another example to consider is when each lane of a phy is directly
+connected to a single disk through a passive backplane.
+In this case, each lane may represent its own iport, since the
+management of each is independent, basically there are many devices each
+with a mask of 0x1.
+.Pp
+iports do not need to map to a physical phy.
+Some HBAs support a combination of both physical and virtual devices.
+In that case, the driver may create two different iports, one for the
+physical devices and one for the virtual devices.
+.Pp
+One property of iports is that they're attached separately from the main
+device and therefore have their own
+.Xr scsi_hba_tran 9S
+structure.
+As a result, that means that a driver can provide different
+entry points for each iport, especially if they represent different
+classes of resources, for example one iport for all physical devices and
+one for all virtual devices.
+This allows for a driver to return different capabilities, among other
+behaviors and entry points, for these different iports.
+One specific case of this is that while physical devices may provide a
+means to get to a SCSI WWN, virtual devices may not have a WWN and
+instead must use a different addressing format.
+.Pp
+iports are considered children of the device driver that attach them,
+but they are bound to the same driver.
+This means that when an iport is created, the
+.Xr attach 9E
+and
+.Xr probe 9E
+entry points of the parent driver (usually indicated by passing a
+.Vt dev_info
+structure) will be called.
+Similarly, when an iport is removed from the system, then the driver's
+.Xr detach 9E
+entry point will be called.
+A driver can determine whether an iport is being attached or not by
+calling the
+.Xr scsi_hba_iport_unit_address 9F
+function.
+The value will return
+.Dv NULL
+if the attaching device represents the driver.
+.Pp
+To manage iports, drivers have two different options.
+If the set of iport an HBA supports are static, then they should use the
+.Xr scsi_hba_iport_register 9F
+function to register an iport.
+.Pp
+If instead, the set of iports are dynamic and map to the coming and
+going of phys discovered by the driver (or some other dynamic source),
+then the driver should use the iportmap set of functions.
+See the section
+.Sx phymap and iportmap
+for more information.
+.Ss tgtmap
+The target map represents a set of devices that have been enumerated
+under an iport.
+Each device is represented by a string, which is an address of some
+kind.
+Usually a physical device's WWN is used.
+.Pp
+By using a target map, the operating system will take
+responsibility for notifying the driver when devices have come and gone
+from a target map, once it has settled, and it will also take
+responsibility for having device nodes come and go, meaning that the
+device driver does not need to know anything about the devices tree or
+worry about other parts of being a nexus driver.
+.Pp
+Target maps come in two forms which change how the HBA driver is
+responsible for reporting changes:
+.Bl -enum
+.It
+Full-set
+.It
+Per-address
+.El
+.Pp
+In the full-set mode, the driver always reports the full set of current
+devices that it sees.
+When the driver finishes the report, the operating system will inform
+the driver of addresses that were added and addresses that were removed.
+These addresses correspond to newly found devices and recently removed
+devices, respectively.
+The full-set mode allows for a simpler device driver, particularly if
+addition and removal notifications may be dropped by the hardware.
+.Pp
+When using the per-address mode of a target map, the HBA driver is
+responsible for indicating which addresses have come and gone from the
+system.
+.Pp
+In either mode, the driver will receive two callbacks, if they have been
+registered when the target map was created.
+The first callback fires before a target driver like sd, ses, etc. is
+attached.
+The second callback fires after the corresponding driver has been
+attached.
+These allow the HBA driver to perform any operations that are
+required on the devices.
+.Pp
+Each target map has two different sets of devices that it manages in
+this form.
+The devices are separated into the following groups:
+.Bl -enum
+.It
+SCSI Devices
+.It
+SMP (SCSI Management Protocol) devices
+.El
+.Pp
+All SATA, SCSI, SAS, SES, etc. devices all are considered part of the
+first category.
+.Pp
+Target maps can be created and destroyed with the
+.Xr scsi_hba_tgtmap_create 9F
+and
+.Xr scsi_hba_tgtmap_destroy 9F
+functions.
+.Pp
+The following functions are used to manage target maps operating in
+full-set mode:
+.Bl -dash
+.It
+.Xr scsi_hba_tgtmap_set_begin 9F
+.It
+.Xr scsi_hba_tgtmap_set_add 9F
+.It
+.Xr scsi_hba_tgtmap_set_end 9F
+.It
+.Xr scsi_hba_tgtmap_set_flush 9F
+.El
+.Pp
+The following functions are used to manage target maps operating in
+per-address mode:
+.Bl -dash
+.It
+.Xr scsi_hba_tgtmap_tgt_add 9F
+.It
+.Xr scsi_hba_tgtmap_tgt_remove 9F
+.El
+.Ss phymap and iportmap
+The phymap and iportmap are often used together to represent complex SAS
+topologies.
+The phymap provides a way to see what phys have been grouped together
+under the same SAS port.
+The SAS port is represented by the
+.Dq local
+and
+.Dq remote
+WWNs.
+When additional phys come online, if they end up referring to the
+same WWNs, then they'll map to the same port.
+.Pp
+The iportmap is used to maintain a dynamic set of iports related to a
+device.
+The iports are each identified by an address, which is generally
+a unit address string.
+For example, when a new phy is added to the phymap which represents a
+new SAS port being used, then a corresponding iport will be created and
+associated with that entry from the phymap.
+Once the iport has been created, a normal target map can be created on
+top of it to handle detected SCSI and SMP devices.
+.Pp
+Both the phymap and iportmap operate in a similar fashion to the
+per-address mode of a tgtmap.
+Entries can be added and removed through direct functions.
+The phymap provides callbacks similar to the tgtmap; however, the
+iportmap does not.
+This is because when an iport is added or removed, a new node is added
+to the devices tree and the driver's
+.Xr attach 9E
+entry point is called with a new
+.Vt dev_info_t
+structure representing the iport.
+.Pp
+During the phymap callback, the HBA driver should create a new iport
+with the unit address passed in from the callback function.
+This relationship is important when taking advantage of the ability to
+map between an iport and the set of phys that it represents.
+.Pp
+The following functions are used to manage iportmaps:
+.Bl -dash
+.It
+.Xr scsi_hba_iportmap_create 9F
+.It
+.Xr scsi_hba_iportmap_iport_add 9F
+.It
+.Xr scsi_hba_iportmap_iport_remove 9F
+.It
+.Xr scsi_hba_iportmap_destroy 9F
+.El
+.Pp
+The following functions are used to manage phymaps:
+.Bl -dash
+.It
+.Xr sas_phymap_create 9F
+.It
+.Xr sas_phymap_destroy 9F
+.It
+.Xr sas_phymap_phy_add 9F
+.It
+.Xr sas_phymap_phy_rem 9F
+.El
+.Ss SCSI Complex Addressing
+Traditionally, SCSI devices were represented by a simple structure, the
+.Xr scsi_address 9S .
+This represented devices by a simple target and lun number.
+While this interface is useful for simple devices and traditional
+parallel SCSI devices, it is not as useful for SAS-era devices where the
+SCSI bus is now a fabric.
+A driver may opt into such a complex addressing mode by setting the
+.Dv SCSI_HBA_ADDR_COMPLEX
+flag.
+.Pp
+When this flag is set, the HBA driver must treat the SCSI address
+as an opaque structure.
+Once in this mode, the driver may get and set a private data structure
+on the SCSI device.
+This is facilitated by the
+.Xr scsi_device_hba_private_set 9F
+and
+.Xr scsi_device_hba_private_get 9F
+functions.
+In addition, the system provides a means to map between the
+.Xr scsi_address 9S
+structure and the corresponding
+.Xr scsi_device 9S
+structure.
+This is performed by the
+.Xr scsi_device_unit_address 9F
+function.
+.Sh SEE ALSO
+.Xr attach 9E ,
+.Xr detach 9E ,
+.Xr sas_phymap_create 9F ,
+.Xr sas_phymap_destroy 9F ,
+.Xr sas_phymap_phy_add 9F ,
+.Xr sas_phymap_phy_rem 9F ,
+.Xr scsi_device_hba_private_get 9F ,
+.Xr scsi_device_hba_private_set 9F ,
+.Xr scsi_device_unit_address 9F ,
+.Xr scsi_hba_attach_setup 9F ,
+.Xr scsi_hba_iport_register 9F ,
+.Xr scsi_hba_iport_unit_address 9F ,
+.Xr scsi_hba_iportmap_create 9F ,
+.Xr scsi_hba_iportmap_destroy 9F ,
+.Xr scsi_hba_iportmap_iport_add 9F ,
+.Xr scsi_hba_iportmap_iport_remove 9F ,
+.Xr scsi_hba_tgtmap_create 9F ,
+.Xr scsi_hba_tgtmap_destroy 9F ,
+.Xr scsi_hba_tgtmap_set_add 9F ,
+.Xr scsi_hba_tgtmap_set_begin 9F ,
+.Xr scsi_hba_tgtmap_set_end 9F ,
+.Xr scsi_hba_tgtmap_set_flush 9F ,
+.Xr scsi_hba_tgtmap_tgt_add 9F ,
+.Xr scsi_hba_tgtmap_tgt_remove 9F ,
+.Xr scsi_address 9S ,
+.Xr scsi_device 9S ,
+.Xr scsi_hba_tran 9S
diff --git a/usr/src/man/man9f/Makefile b/usr/src/man/man9f/Makefile
index dcea9314f9..b2f4b32fac 100644
--- a/usr/src/man/man9f/Makefile
+++ b/usr/src/man/man9f/Makefile
@@ -442,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			\
@@ -455,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			\
@@ -476,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					\
@@ -1166,11 +1175,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					\
@@ -1184,6 +1216,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					\
@@ -2022,6 +2056,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
@@ -2036,8 +2086,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
@@ -2051,6 +2114,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/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..233a0bf782
--- /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_get
+function returns a data value registered via the
+.Fn scsi_device_hba_private_set
+function.
+If the
+.Fn scsi_device_hba_private_set
+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..8570013ca6
--- /dev/null
+++ b/usr/src/man/man9f/scsi_hba_iportmap_create.9f
@@ -0,0 +1,178 @@
+.\"
+.\" 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
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
diff --git a/usr/src/man/man9s/scsi_address.9s b/usr/src/man/man9s/scsi_address.9s
index 48b19e85f1..65fc9a017f 100644
--- a/usr/src/man/man9s/scsi_address.9s
+++ b/usr/src/man/man9s/scsi_address.9s
@@ -1,70 +1,111 @@
-'\" te
 .\"  Copyright (c) 2000, Sun Microsystems, Inc.,  All Rights Reserved
+.\" 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_ADDRESS 9S "Aug 30, 1995"
-.SH NAME
-scsi_address \- SCSI address structure
-.SH SYNOPSIS
-.LP
-.nf
-#include <sys/scsi/scsi.h>
-.fi
-
-.SH INTERFACE LEVEL
-.sp
-.LP
-Solaris architecture specific (Solaris DDI)
-.SH DESCRIPTION
-.sp
-.LP
-A \fBscsi_address\fR structure defines the addressing components for a
-\fBSCSI\fR target device. The address of the target device is separated into
-two components: target number and logical unit number. The two addressing
-components are used to uniquely identify any type of \fBSCSI\fR device;
-however, most devices can be addressed with the target component of the
+.Dd Apr 23, 2017
+.Dt SCSI_ADDRESS 9S
+.Os
+.Sh NAME
+.Nm scsi_address
+.Nd SCSI address structure
+.Sh SYNOPSIS
+.In sys/scsi/scsi.h
+.Sh INTERFACE LEVEL
+illumos architecture specific (illumos DDI)
+.Sh DESCRIPTION
+A
+.Vt scsi_address
+structure defines the addressing components for a
+.Sy SCSI
+target device.
+The address of the target device is separated into two components:
+target number and logical unit number.
+The two addressing components are used to uniquely identify any type of
+.Sy SCSI
+device; however, most devices can be addressed with the target component of the
 address.
-.sp
-.LP
+.Pp
 In the case where only the target component is used to address the device, the
-logical unit should be set to  \fB0\fR. If the \fBSCSI\fR target device
-supports logical units, then the \fBHBA\fR must interpret the logical units
-field of the data structure.
-.sp
-.LP
-The \fBpkt_address\fR member of a \fBscsi_pkt\fR(9S) is initialized by
-\fBscsi_init_pkt\fR(9F).
-.SH STRUCTURE MEMBERS
-.sp
-.in +2
-.nf
+logical unit should be set to
+.Sy 0 . If the
+.Sy SCSI
+target device supports logical units, then the HBA must interpret the
+logical units field of the data structure.
+.Pp
+The
+.Sy pkt_address
+member of a
+.Xr scsi_pkt 9S
+is initialized by
+.Xr scsi_init_pkt 9F .
+.Ss Complex Addressing
+Drivers may set the flag
+.Dv SCSI_HBA_ADDR_COMPLEX
+in the
+.Fa hba_flags
+argument to
+.Xr scsi_hba_attach_setup 9F .
+When the flag is set, this structure must be treated as opaque.
+Instead of storing a traditional target and LUN, the address is treated
+as the string form of a unit address.
+In addition, rather than storing a pointer to the
+.Xr scsi_hba_tran 9S
+structure, the address structure can store any arbitrary pointer through
+the
+.Xr scsi_device_hba_private_get 9F
+and
+.Xr scsi_device_hba_private_set 9F
+functions.
+.Sh STRUCTURE MEMBERS
+.Bd -literal
 scsi_hba_tran_t   *a_hba_tran;  /* Transport vectors for the SCSI bus */
 ushort_t          a_target;     /* SCSI target id */
 uchar_t           a_lun;        /* SCSI logical unit */
-.fi
-.in -2
-
-.sp
-.LP
-\fBa_hba_tran\fR is a pointer to the controlling \fBHBA\fR's transport vector
-structure. The \fBSCSA\fR interface uses this field to pass any transport
-requests from the \fBSCSI\fR target device drivers to the \fBHBA\fR driver.
-.sp
-.LP
-\fBa_target\fR is the target component of the \fBSCSI\fR address.
-.sp
-.LP
-\fBa_lun\fR is the logical unit component of the \fBSCSI\fR address. The
-logical unit is used to further distinguish a \fBSCSI\fR target device that
-supports multiple logical units from one that does not. The \fBmakecom\fR(9F)
-family of functions use the \fBa_lun\fR field to set the logical unit field in
-the \fBSCSI\fR \fBCDB\fR, for compatibility with \fBSCSI-1\fR.
-.SH SEE ALSO
-.sp
-.LP
-\fBmakecom\fR(9F), \fBscsi_init_pkt\fR(9F), \fBscsi_hba_tran\fR(9S),
-\fBscsi_pkt\fR(9S)
-.sp
-.LP
-\fIWriting Device Drivers\fR
+.Ed
+.Pp
+.Fa a_hba_tran
+is a pointer to the controlling
+.Sy HBA 's
+transport vector
+structure.
+The
+.Sy SCSA
+interface uses this field to pass any transport
+requests from the
+.Sy SCSI
+target device drivers to the
+.Sy HBA
+driver.
+.Pp
+.Fa a_target
+is the target component of the
+.Sy SCSI
+address
+.Pp
+.Fa a_lun
+is the logical unit component of the
+.Sy SCSI
+address.
+The logical unit is used to further distinguish a
+.Sy SCSI
+target device that
+supports multiple logical units from one that does not.
+.Pp
+If the flag,
+.Dv SCSI_HBA_ADDR_COMPLEX
+was set, then the driver
+.Em must not
+dereference any of these fields, the structure contents will have
+changed and should be considered opaque.
+.Sh SEE ALSO
+.Xr scsi_device_hba_private_get 9F ,
+.Xr scsi_device_hba_private_set 9F ,
+.Xr scsi_hba_attach_setup 9F ,
+.Xr scsi_init_pkt 9F ,
+.Xr scsi_hba_tran 9S ,
+.Xr scsi_pkt 9S
+.Pp
+.Rs
+.%T Writing Device Drivers
+.Re
diff --git a/usr/src/pkg/manifests/system-kernel.man9.inc b/usr/src/pkg/manifests/system-kernel.man9.inc
index 9fa1b9eb3d..cd1d8b6bdb 100644
--- a/usr/src/pkg/manifests/system-kernel.man9.inc
+++ b/usr/src/pkg/manifests/system-kernel.man9.inc
@@ -14,5 +14,9 @@
 # Copyright 2012 Nexenta Systems, Inc. All rights reserved.
 #
 file path=usr/share/man/man9/Intro.9
+file path=usr/share/man/man9/iport.9
 file path=usr/share/man/man9/vmem.9
 link path=usr/share/man/man9/intro.9 target=Intro.9
+link path=usr/share/man/man9/iportmap.9 target=iport.9
+link path=usr/share/man/man9/phymap.9 target=iport.9
+link path=usr/share/man/man9/tgtmap.9 target=iport.9
diff --git a/usr/src/pkg/manifests/system-kernel.man9f.inc b/usr/src/pkg/manifests/system-kernel.man9f.inc
index 31b6644aa9..8d705ffe5d 100644
--- a/usr/src/pkg/manifests/system-kernel.man9f.inc
+++ b/usr/src/pkg/manifests/system-kernel.man9f.inc
@@ -437,7 +437,10 @@ file path=usr/share/man/man9f/rmfree.9f
 file path=usr/share/man/man9f/rmvb.9f
 file path=usr/share/man/man9f/rmvq.9f
 file path=usr/share/man/man9f/rwlock.9f
+file path=usr/share/man/man9f/sas_phymap_create.9f
+file path=usr/share/man/man9f/sas_phymap_lookup_ua.9f
 file path=usr/share/man/man9f/scsi_abort.9f
+file path=usr/share/man/man9f/scsi_address_device.9f
 file path=usr/share/man/man9f/scsi_alloc_consistent_buf.9f
 file path=usr/share/man/man9f/scsi_cname.9f
 file path=usr/share/man/man9f/scsi_destroy_pkt.9f
@@ -450,10 +453,15 @@ file path=usr/share/man/man9f/scsi_get_device_type_scsi_options.9f
 file path=usr/share/man/man9f/scsi_get_device_type_string.9f
 file path=usr/share/man/man9f/scsi_hba_attach_setup.9f
 file path=usr/share/man/man9f/scsi_hba_init.9f
+file path=usr/share/man/man9f/scsi_hba_iport_exist.9f
+file path=usr/share/man/man9f/scsi_hba_iport_register.9f
+file path=usr/share/man/man9f/scsi_hba_iport_unit_address.9f
+file path=usr/share/man/man9f/scsi_hba_iportmap_create.9f
 file path=usr/share/man/man9f/scsi_hba_lookup_capstr.9f
 file path=usr/share/man/man9f/scsi_hba_pkt_alloc.9f
 file path=usr/share/man/man9f/scsi_hba_pkt_comp.9f
 file path=usr/share/man/man9f/scsi_hba_probe.9f
+file path=usr/share/man/man9f/scsi_hba_tgtmap_create.9f
 file path=usr/share/man/man9f/scsi_hba_tran_alloc.9f
 file path=usr/share/man/man9f/scsi_ifgetcap.9f
 file path=usr/share/man/man9f/scsi_init_pkt.9f
@@ -471,6 +479,7 @@ file path=usr/share/man/man9f/scsi_transport.9f
 file path=usr/share/man/man9f/scsi_unprobe.9f
 file path=usr/share/man/man9f/scsi_validate_sense.9f
 file path=usr/share/man/man9f/scsi_vu_errmsg.9f
+file path=usr/share/man/man9f/scsi_wwnstr_to_wwn.9f
 file path=usr/share/man/man9f/semaphore.9f
 file path=usr/share/man/man9f/sprintf.9f
 file path=usr/share/man/man9f/stoi.9f
@@ -1255,13 +1264,60 @@ link path=usr/share/man/man9f/rw_read_locked.9f target=rwlock.9f
 link path=usr/share/man/man9f/rw_tryenter.9f target=rwlock.9f
 link path=usr/share/man/man9f/rw_tryupgrade.9f target=rwlock.9f
 link path=usr/share/man/man9f/samestr.9f target=SAMESTR.9f
+link path=usr/share/man/man9f/sas_phymap_destroy.9f \
+    target=sas_phymap_create.9f
+link path=usr/share/man/man9f/sas_phymap_lookup_uapriv.9f \
+    target=sas_phymap_lookup_ua.9f
+link path=usr/share/man/man9f/sas_phymap_phy2ua.9f \
+    target=sas_phymap_lookup_ua.9f
+link path=usr/share/man/man9f/sas_phymap_phy_add.9f \
+    target=sas_phymap_create.9f
+link path=usr/share/man/man9f/sas_phymap_phy_rem.9f \
+    target=sas_phymap_create.9f
+link path=usr/share/man/man9f/sas_phymap_phys_free.9f \
+    target=sas_phymap_lookup_ua.9f
+link path=usr/share/man/man9f/sas_phymap_phys_next.9f \
+    target=sas_phymap_lookup_ua.9f
+link path=usr/share/man/man9f/sas_phymap_ua2phys.9f \
+    target=sas_phymap_lookup_ua.9f
+link path=usr/share/man/man9f/sas_phymap_ua_free.9f \
+    target=sas_phymap_lookup_ua.9f
+link path=usr/share/man/man9f/sas_phymap_uahasphys.9f \
+    target=sas_phymap_lookup_ua.9f
+link path=usr/share/man/man9f/scsi_device_hba_private_get.9f \
+    target=scsi_address_device.9f
+link path=usr/share/man/man9f/scsi_device_hba_private_set.9f \
+    target=scsi_address_device.9f
+link path=usr/share/man/man9f/scsi_device_unit_address.9f \
+    target=scsi_address_device.9f
 link path=usr/share/man/man9f/scsi_dmafree.9f target=scsi_dmaget.9f
 link path=usr/share/man/man9f/scsi_dname.9f target=scsi_cname.9f
+link path=usr/share/man/man9f/scsi_free_wwnstr.9f target=scsi_wwnstr_to_wwn.9f
 link path=usr/share/man/man9f/scsi_hba_detach.9f \
     target=scsi_hba_attach_setup.9f
 link path=usr/share/man/man9f/scsi_hba_fini.9f target=scsi_hba_init.9f
+link path=usr/share/man/man9f/scsi_hba_iport_find.9f \
+    target=scsi_hba_iport_exist.9f
+link path=usr/share/man/man9f/scsi_hba_iportmap_destroy.9f \
+    target=scsi_hba_iportmap_create.9f
+link path=usr/share/man/man9f/scsi_hba_iportmap_iport_add.9f \
+    target=scsi_hba_iportmap_create.9f
+link path=usr/share/man/man9f/scsi_hba_iportmap_iport_remove.9f \
+    target=scsi_hba_iportmap_create.9f
 link path=usr/share/man/man9f/scsi_hba_pkt_free.9f \
     target=scsi_hba_pkt_alloc.9f
+link path=usr/share/man/man9f/scsi_hba_tgtmap_set_add.9f \
+    target=scsi_hba_tgtmap_create.9f
+link path=usr/share/man/man9f/scsi_hba_tgtmap_set_begin.9f \
+    target=scsi_hba_tgtmap_create.9f
+link path=usr/share/man/man9f/scsi_hba_tgtmap_set_end.9f \
+    target=scsi_hba_tgtmap_create.9f
+link path=usr/share/man/man9f/scsi_hba_tgtmap_set_flush.9f \
+    target=scsi_hba_tgtmap_create.9f
+link path=usr/share/man/man9f/scsi_hba_tgtmap_tgt_add.9f \
+    target=scsi_hba_tgtmap_create.9f
+link path=usr/share/man/man9f/scsi_hba_tgtmap_tgt_remove.9f \
+    target=scsi_hba_tgtmap_create.9f
 link path=usr/share/man/man9f/scsi_hba_tran_free.9f \
     target=scsi_hba_tran_alloc.9f
 link path=usr/share/man/man9f/scsi_ifsetcap.9f target=scsi_ifgetcap.9f
@@ -1278,6 +1334,8 @@ link path=usr/share/man/man9f/scsi_sense_info_uint64.9f \
     target=scsi_ext_sense_fields.9f
 link path=usr/share/man/man9f/scsi_sname.9f target=scsi_cname.9f
 link path=usr/share/man/man9f/scsi_unslave.9f target=scsi_unprobe.9f
+link path=usr/share/man/man9f/scsi_wwn_to_wwnstr.9f \
+    target=scsi_wwnstr_to_wwn.9f
 link path=usr/share/man/man9f/sema_destroy.9f target=semaphore.9f
 link path=usr/share/man/man9f/sema_init.9f target=semaphore.9f
 link path=usr/share/man/man9f/sema_p.9f target=semaphore.9f
@@ -1313,12 +1371,12 @@ link path=usr/share/man/man9f/va_copy.9f target=va_arg.9f
 link path=usr/share/man/man9f/va_end.9f target=va_arg.9f
 link path=usr/share/man/man9f/va_start.9f target=va_arg.9f
 link path=usr/share/man/man9f/vcmn_err.9f target=cmn_err.9f
-link path=usr/share/man/man9f/vmem_xalloc.9f target=vmem_alloc.9f
-link path=usr/share/man/man9f/vmem_free.9f target=vmem_alloc.9f
-link path=usr/share/man/man9f/vmem_xfree.9f target=vmem_alloc.9f
-link path=usr/share/man/man9f/vmem_xcreate.9f target=vmem_create.9f
 link path=usr/share/man/man9f/vmem_destroy.9f target=vmem_create.9f
+link path=usr/share/man/man9f/vmem_free.9f target=vmem_alloc.9f
 link path=usr/share/man/man9f/vmem_size.9f target=vmem_walk.9f
+link path=usr/share/man/man9f/vmem_xalloc.9f target=vmem_alloc.9f
+link path=usr/share/man/man9f/vmem_xcreate.9f target=vmem_create.9f
+link path=usr/share/man/man9f/vmem_xfree.9f target=vmem_alloc.9f
 link path=usr/share/man/man9f/vsnprintf.9f target=sprintf.9f
 link path=usr/share/man/man9f/vsprintf.9f target=sprintf.9f
 link path=usr/share/man/man9f/vzcmn_err.9f target=cmn_err.9f