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 20, 2017
15.Dt SAS_PHYMAP_CREATE 9F
16.Os
17.Sh NAME
18.Nm sas_phymap_create ,
19.Nm sas_phymap_destroy ,
20.Nm sas_phymap_phy_add ,
21.Nm sas_phymap_phy_rem
22.Nd SAS PHY map functions
23.Sh SYNOPSIS
24.In sys/scsi/scsi.h
25.Ft int
26.Fo sas_phymap_create
27.Fa "dev_info_t *dip"
28.Fa "int settle_usec"
29.Fa "sas_phymap_mode_t mode"
30.Fa "void *mode_argument"
31.Fa "void *phymap_priv"
32.Fa "sas_phymap_activate_cb_t activate_cb"
33.Fa "sas_phymap_deactivate_cb_t deactivate_cb"
34.Fa "sas_phymap_t **phymapout"
35.Fc
36.Ft void
37.Fo sas_phymap_destroy
38.Fa "sas_phymap_t *phymap"
39.Fc
40.Ft int
41.Fo sas_phymap_phy_add
42.Fa "sas_phymap_t *phymap"
43.Fa "int phy"
44.Fa "uint64_t local"
45.Fa "uint64_t remote"
46.Fc
47.Ft int
48.Fo sas_phymap_phy_rem
49.Fa "sas_phymap_t *phymap"
50.Fa "int phy"
51.Fc
52.Ft void
53.Fo (*sas_phymap_activate_cb_t)
54.Fa "void *phymap_priv"
55.Fa "char *ua"
56.Fa "void **ua_privp"
57.Fc
58.Ft void
59.Fo (*sas_phymap_deactivate_cb_t)
60.Fa "void *phymap_priv"
61.Fa "char *ua"
62.Fa "void *ua_priv"
63.Fc
64.Sh INTERFACE LEVEL
65.Sy Evolving -
66This interface is still evolving in illumos.
67API and ABI stability is
68not guaranteed.
69.Sh PARAMETERS
70.Bl -tag -width Fa
71.It Fa dip
72Pointer to
73.Vt dev_info
74structure.
75.It Fa settle_usec
76A time in microseconds.
77.It Fa mode
78Mode of operation for the phy map.
79Should be set to
80.Dv PHYMAP_MODE_SIMPLE .
81.It Fa mode_priv
82Drivers should pass
83.Dv NULL .
84.It Fa phymap_priv
85A private argument to be used in callback functions.
86.It Fa activate_cb
87An optional callback that will be called when a new phy is being
88added to the system.
89.It Fa deactivate_cb
90An optional callback that will be called when an existing phys is
91removed from the system.
92.It Fa phymapout
93Pointer where the phy map is stored.
94.It Fa phymap
95Pointer to an allocated phy map.
96.It Fa phy
97A non-negative integer that uniquely identifies a phy on a device.
98.It Fa local
99The World Wide Number (WWN) of the HBA-owned side of the phy.
100.It Fa remote
101The World Wide Number (WWN) of the device that is plugged into the phy.
102.It Fa ua
103A character string that indicates the system generated unit address for
104the logical port.
105.It Fa ua_privp
106A private value that can be stored for the corresponding unit address.
107.It Fa ua_priv
108A private value for the unit address stored into
109.Fa ua_privp .
110.El
111.Sh DESCRIPTION
112The
113.Fn sas_phymap_create
114and
115.Fn sas_phymap_destroy
116functions create and destroy phymaps which are used to manage a set of
117potentially-active SAS phys and the attached devices.
118For more background, see
119.Xr phymap 9 .
120If the driver in question is not a SAS HBA or a similar fabric-like
121device, then do not use this interface.
122.Pp
123The phy map maps one or more phys to a logical port-like construct that
124is represented based on the WWNs in question.
125This logical SAS port has a unit address derived from the two WWNs.
126When the first phy is noted as using these WWNs, then the phymap will
127call any registered callbacks as the port is created.
128If additional phys come online in service of the
129same port, then a new port will not be created.
130.Pp
131To facilitate the mapping between a PHY and the corresponding port unit
132address, the
133.Xr sas_phymap_phy2ua 9F
134and
135.Xr sas_phymap_lookup_ua 9F
136functions are available.
137.Pp
138To create a phy map, the driver uses the
139.Fn sas_phymap_create
140function.
141The resulting phy map will be stored in the
142.Fa phymapout
143argument.
144The value in
145.Fa settle_usec
146indicates the amount of time that the system should wait to quiesce all
147changes and consider the resulting system stable.
148Changes will not be reported until after
149.Fa settle_usec
150have passed.
151.Pp
152If a driver places a function pointer for either the
153.Fa activate_cb
154or
155.Fa deactivate cb
156then those functions will be called when phys are added and removed from
157the phy map.
158.Pp
159The value placed in the
160.Fa phymap_priv
161argument will be passed to both callback functions.
162.Pp
163To destroy a phymap, the driver should call the
164.Fn sas_phymap_destroy
165function.
166A side effect of this is that all existing entries in the phy
167map will be removed and their deactivate callbacks will fire.
168.Ss Callbacks
169The phymap provides a means for receiving callbacks when the addition of
170a phy causes a new logical port to be created or when the phy being
171removed is the last phy that is a member of the port.
172Unlike with the
173.Xr tgtmap 9 ,
174there is no system managed driver that is attached with the phymap.
175For the phymap to be useful to drivers, the callbacks should generally
176be registered.
177.Pp
178It's important to emphasize that the callbacks do not represent phys,
179but instead the logical port that they are bound to.
180This is different
181from the
182.Xr tgtmap 9
183and
184.Xr iportmap 9 .
185Calls to the
186.Fn sas_phymap_phy_add
187and
188.Fn sas_phymap_phy_rem
189functions may not result in anything being created in the system.
190.Pp
191The
192.Fa activate_cb
193callback occurs whenever a new logical port is created because the first
194phy that references that pair of WWNs has been created.
195The
196.Fa phymap_priv
197argument corresponds to the value passed in the
198.Fn sas_phymap_create
199function.
200.Pp
201The
202.Fa ua
203argument is a unit-address string that the system constructs based on
204the WWNs passed in the
205.Fa local
206and
207.Fa remote
208arguments to the
209.Fn sas_phymap_phy_add
210function.
211If this is being used together with an
212.Xr iportmap 9
213then the
214.Fa ua
215should be the name of the added iport.
216.Pp
217The
218.Fa ua_privp
219argument allows for data to be correlated with the unit-address.
220This data is accessible throughout the lifetime of the unit-address
221through the
222.Xr sas_phymap_lookup_uapriv 9F
223function and is also made available during the deactivate callback.
224.Pp
225The
226.Fa deactivate_cb
227callback occurs when the logical port is being removed, because the last
228associated phy has been removed.
229The arguments to this are the same as to the activate callback, with the
230exception that the
231.Fa ua_priv
232argument is the value that was stored in the
233.Fa ua_privp
234argument of the activate callback.
235.Ss Adding and Removing PHYs
236To add a phy to the system, the driver should call the
237.Fn sas_phymap_phy_add
238function.
239The
240.Fa phy
241argument should indicate the phy identifier of the phy that has come up.
242The
243.Fa local
244WWN generally corresponds to the SAS port on the controller, while the
245.Fa remote
246WWN is whatever device is on the other side of the phy.
247The system enforces that a given phy only maps to a single port at any
248time.
249.Pp
250When a phy goes offline, then the driver should call the
251.Fn sas_phymap_phy_rem
252function using the same phy identifier that it used when adding the phy.
253If this is the last phy that was used for this logical port, then the
254corresponding logical port will be removed and the deactivate callback
255function, if registered, will be called.
256.Sh CONTEXT
257The
258.Fn sas_phymap_create
259and
260.Fn sas_phymap_destroy
261functions are generally called during an HBA driver's
262.Xr attach 9E
263and
264.Xr detach 9E
265entry points, though may be called by a driver from
266.Sy user
267or
268.Sy kernel
269context.
270.Pp
271The optional
272.Fn activate_cb
273and
274.Fn deactivate_cb
275functions for a phymap will be called into the driver from
276.Sy kernel
277context.
278.Pp
279The
280.Fn sas_phymap_phy_add
281and
282.Fn sas_phymap_phy_rem
283functions may be called from
284.Sy user
285or
286.Sy kernel
287context.
288.Sh RETURN VALUES
289Upon successful completion, the
290.Fn sas_phymap_create ,
291.Fn sas_phymap_phy_add ,
292and
293.Fn sas_phymap_phy_rem
294functions return
295.Dv DDI_SUCCESS .
296Otherwise,
297.Dv DDI_FAILURE
298is returned to indicate failure.
299.Sh SEE ALSO
300.Xr iportmap 9 ,
301.Xr phymap 9 ,
302.Xr tgtmap 9 ,
303.Xr attach 9E ,
304.Xr detach 9E ,
305.Xr sas_phymap_lookup_ua 9F ,
306.Xr sas_phymap_lookup_uapriv 9F ,
307.Xr sas_phymap_phy2ua 9F
308