14784 Desire scsi_hba_tgtmap_scan_luns

Reviewed by: Robert Mustacchi <rm+illumos@fingolfin.org>
Reviewed by: Toomas Soome <tsoome@me.com>
Reviewed by: Hans Rosenfeld <rosenfeld@grumpf.hope-2000.org>
Approved by: Gordon Ross <gordon.w.ross@gmail.com>

2 files changed, 28 insertions, 4 deletions

diff --git a/usr/src/man/man9f/Makefile b/usr/src/man/man9f/Makefile
index 267d9f4253..f220a3f404 100644
--- a/usr/src/man/man9f/Makefile
+++ b/usr/src/man/man9f/Makefile
@@ -15,6 +15,7 @@
 # Copyright 2019 Joyent, Inc.
 # Copyright 2020-2021 Tintri by DDN, Inc. All rights reserved.
 # Copyright 2016 Hans Rosenfeld <rosenfeld@grumpf.hope-2000.org>
+# Copyright 2022 RackTop Systems, Inc.
 #
 
 include		$(SRC)/Makefile.master
@@ -1161,6 +1162,7 @@ MANLINKS=	AVL_NEXT.9f					\
 		scsi_hba_iportmap_iport_remove.9f		\
 		scsi_hba_pkt_free.9f				\
 		scsi_hba_tgtmap_destroy.9f			\
+		scsi_hba_tgtmap_scan_luns.9f			\
 		scsi_hba_tgtmap_set_begin.9f			\
 		scsi_hba_tgtmap_set_add.9f			\
 		scsi_hba_tgtmap_set_end.9f			\
@@ -2026,6 +2028,7 @@ 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_destroy.9f		:= LINKSRC = scsi_hba_tgtmap_create.9f
+scsi_hba_tgtmap_scan_luns.9f		:= LINKSRC = scsi_hba_tgtmap_create.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
diff --git a/usr/src/man/man9f/scsi_hba_tgtmap_create.9f b/usr/src/man/man9f/scsi_hba_tgtmap_create.9f
index a8a16afab0..77596030dc 100644
--- a/usr/src/man/man9f/scsi_hba_tgtmap_create.9f
+++ b/usr/src/man/man9f/scsi_hba_tgtmap_create.9f
@@ -11,6 +11,7 @@
 .\"
 .\" Copyright 2019, Joyent, Inc.
 .\" Copyright 2022 Oxide Computer Company
+.\" Copyright 2022 RackTop Systems, Inc.
 .\"
 .Dd January 29, 2022
 .Dt SCSI_HBA_TGTMAP_CREATE 9F
@@ -18,6 +19,7 @@
 .Sh NAME
 .Nm scsi_hba_tgtmap_create ,
 .Nm scsi_hba_tgtmap_destroy ,
+.Nm scsi_hba_tgtmap_scan_luns ,
 .Nm scsi_hba_tgtmap_set_begin ,
 .Nm scsi_hba_tgtmap_set_add ,
 .Nm scsi_hba_tgtmap_set_end ,
@@ -57,6 +59,11 @@
 .Fa "void *tgt_priv"
 .Fa "scsi_tgtmap_deact_rsn_t deact"
 .Fc
+.Ft void
+.Fo scsi_hba_tgtmap_scan_luns
+.Fa "scsi_hba_tgtmap_t *tgtmap"
+.Fa "char *tgt_addr"
+.Fc
 .Ft int
 .Fo scsi_hba_tgtmap_set_begin
 .Fa "scsi_hba_tgtmap_t *tgtmap"
@@ -425,6 +432,20 @@ and
 arguments match those that were used when calling the
 .Fn scsi_hba_tgtmap_tgt_add
 function.
+.Ss Scanning for Logical Units
+SCSI targets may contain logical units
+.Pq LUNS
+that are created or destroyed by the target dynamically.
+In order to facilitate discovery of logical units, the HBA may call
+.Fn scsi_hba_tgtmap_scan_luns
+using the address of a target that has been registered using the given
+.Fa tgt_addr .
+.Pp
+This will cause the framework to issue a
+.Sy REPORT_LUNS
+command, to enumerate any present logical units.
+Logical units that are no longer present will be pruned from the system,
+and any new ones will be created.
 .Sh CONTEXT
 The
 .Fn scsi_hba_tgtmap_create
@@ -450,6 +471,7 @@ functions for a target map will be called into the driver from
 context.
 .Pp
 The
+.Fn scsi_hba_tgtmap_scan_luns ,
 .Fn scsi_hba_tgtmap_set_begin ,
 .Fn scsi_hba_tgtmap_set_add ,
 .Fn scsi_hba_tgtmap_set_end ,
@@ -462,13 +484,12 @@ functions may be called from
 or
 .Sy kernel
 context.
-It is recommended that device drivers do not call these functions from
+Device drivers should not call these functions from
 .Sy interrupt
-context and instead should schedule deferred work with a task queue
+context and should instead 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.
+if a need to call these arises while handling an interrupt.
 .Sh RETURN VALUES
 Upon successful completion, the
 .Fn scsi_hba_tgtmap_create ,