1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright (c) 2017, Joyent, Inc.
13.\"
14.Dd Apr 18, 2017
15.Dt SCSI_HBA_IPORTMAP_CREATE 9F
16.Os
17.Sh NAME
18.Nm scsi_hba_iportmap_create ,
19.Nm scsi_hba_iportmap_destroy ,
20.Nm scsi_hba_iportmap_iport_add ,
21.Nm scsi_hba_iportmap_iport_remove
22.Nd create and manage an iportmap
23.Sh SYNOPSIS
24.In sys/scsi/scsi.h
25.Ft int
26.Fo scsi_hba_iportmap_create
27.Fa "dev_info_t *dip"
28.Fa "int csync_usec"
29.Fa "int settle_usec"
30.Fa "scsi_hba_iportmap_t **iportmapout"
31.Fc
32.Ft void
33.Fo scsi_hba_iportmap_destroy
34.Fa "scsi_hba_iportmap_t *iportmap"
35.Fc
36.Ft int
37.Fo scsi_hba_iportmap_iport_add
38.Fa "scsi_hba_iportmap_t *iportmap"
39.Fa "char *ua"
40.Fa "void *priv"
41.Fc
42.Ft int
43.Fo scsi_hba_iportmap_iport_remove
44.Fa "scsi_hba_iportmap_t *iportmap"
45.Fa "char *ua"
46.Fc
47.Sh INTERFACE LEVEL
48.Sy Evolving -
49This interface is still evolving in illumos.
50API and ABI stability is not guaranteed.
51.Sh PARAMETERS
52.Bl -tag -width Fa
53.It Fa dip
54Pointer to
55.Vt dev_info
56structure.
57.It Fa csync_usec
58A time in microseconds.
59.It Fa settle_usec
60A time in microseconds.
61.It Fa iportmap
62An allocated iportmap.
63.It Fa iportmapout
64Pointer where the iportmap is stored.
65.It Fa ua
66A character string that represents a unit address for an iport.
67.It Fa priv
68Drivers should pass
69.Dv NULL
70for this field.
71.El
72.Sh DESCRIPTION
73The
74.Fn scsi_hba_iportmap_create
75and
76.Fn scsi_hba_iportmap_destroy
77functions are used by HBA drivers to create and destroy an iportmap.
78For more information on an iportmap and its purpose, see
79.Xr iportmap 9 .
80.Pp
81The
82.Fa csync_usec
83and
84.Fa settle_usec
85are both times measured in microseconds that control two different
86properties of the iportmap and how it behaves.
87The value in
88.Fa settle_usec
89indicates the amount of time that the system should wait to quiesce all
90changes and consider the resulting system stable.
91Changes will not be reported until after
92.Fa settle_usec
93have passed.
94.Fa csync_usec
95indicates how much time needs to elapse after creation before an initial
96enumeration has been completed.
97.Pp
98The
99.Vt dev_info
100structure passed into
101.Fa dip
102is usually the HBA driver's
103.Vt dev_info
104structure.
105.Pp
106When the
107.Fn scsi_hba_iportmap_iport
108function returns,
109.Fa iportmapout
110will be populated with a pointer to an iportmap that can be used to add
111and remove iports.
112.Pp
113To destroy the iportmap, drivers should use the
114.Fn scsi_hba_iportmap_destroy
115function.
116As part of destroying the iportmap, all associated iports will
117be detached from the system by having the driver's
118.Xr detach 9E
119entry point called.
120.Pp
121When the driver needs to add an iport to the system, generally in
122response to a hotplug event, then the driver should call the
123.Fn scsi_hba_iportmap_iport_add
124function.
125The value of
126.Fa ua
127should be a character string that uniquely identifies the device.
128If the driver is using a phymap, then this unit address should be the
129same one as the phymap's callback provided.
130Otherwise, the driver sets
131.Fa ua
132to a unique string which is generally the iport's WWN.
133.Pp
134When the corresponding iport needs to be removed, then the driver should
135call the
136.Fn scsi_hba_iportmap_remove
137function.
138The iport to remove is indicated by the
139.Fa ua
140argument, which should match the value passed into the
141.Fn scsi_hba_iportmap_add
142function.
143.Sh CONTEXT
144The
145.Fn scsi_hba_iportmap_create
146function is generally called during a driver's
147.Xr attach 9E
148entry point.
149.Pp
150The
151.Fn scsi_hba_iportmap_destroy
152function is generally called during a driver's
153.Xr detach 9E
154entry point.
155.Pp
156The
157.Fn scsi_hba_iportmap_iport_add
158and
159.Fn scsi_hba_iportmap_iport_remove
160functions should be called from
161.Sy kernel
162context.
163.Sh RETURN VALUES
164Upon successful completion, the
165.Fn scsi_hba_iportmap_create ,
166.Fn scsi_hba_iportmap_iport_add ,
167and
168.Fn scsi_hba_iportmap_iport_remove
169functions return
170.Dv DDI_SUCCESS.
171Otherwise,
172.Dv DDI_FAILURE
173is returned.
174.Sh SEE ALSO
175.Xr iport 9 ,
176.Xr iportmap 9 ,
177.Xr attach 9E ,
178.Xr detach 9E
179