aboutsummaryrefslogtreecommitdiff
path: root/sys/cam/ctl/ctl_frontend.h
blob: c9ab255cdde490cbcdfb13f5257c493d853919d2 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
/*-
 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
 *
 * Copyright (c) 2003 Silicon Graphics International Corp.
 * Copyright (c) 2014-2017 Alexander Motin <mav@FreeBSD.org>
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions, and the following disclaimer,
 *    without modification.
 * 2. Redistributions in binary form must reproduce at minimum a disclaimer
 *    substantially similar to the "NO WARRANTY" disclaimer below
 *    ("Disclaimer") and any redistribution must be conditioned upon
 *    including a substantially similar Disclaimer requirement for further
 *    binary redistribution.
 *
 * NO WARRANTY
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * $Id: //depot/users/kenm/FreeBSD-test2/sys/cam/ctl/ctl_frontend.h#2 $
 * $FreeBSD$
 */
/*
 * CAM Target Layer front end registration hooks
 *
 * Author: Ken Merry <ken@FreeBSD.org>
 */

#ifndef	_CTL_FRONTEND_H_
#define	_CTL_FRONTEND_H_

#include <cam/ctl/ctl_ioctl.h>
#include <sys/nv.h>

typedef enum {
	CTL_PORT_STATUS_NONE		= 0x00,
	CTL_PORT_STATUS_ONLINE		= 0x01,
	CTL_PORT_STATUS_HA_SHARED	= 0x02
} ctl_port_status;

typedef int (*fe_init_t)(void);
typedef int (*fe_shutdown_t)(void);
typedef void (*port_func_t)(void *onoff_arg);
typedef int (*port_info_func_t)(void *onoff_arg, struct sbuf *sb);
typedef	int (*lun_func_t)(void *arg, int lun_id);
typedef int (*fe_ioctl_t)(struct cdev *dev, u_long cmd, caddr_t addr, int flag,
			  struct thread *td);

#define CTL_FRONTEND_DECLARE(name, driver) \
	static int name ## _modevent(module_t mod, int type, void *data) \
	{ \
		switch (type) { \
		case MOD_LOAD: \
			return (ctl_frontend_register( \
				(struct ctl_frontend *)data)); \
			break; \
		case MOD_UNLOAD: \
			return (ctl_frontend_deregister( \
				(struct ctl_frontend *)data)); \
			break; \
		default: \
			return EOPNOTSUPP; \
		} \
		return 0; \
	} \
	static moduledata_t name ## _mod = { \
		#name, \
		name ## _modevent, \
		(void *)&driver \
	}; \
	DECLARE_MODULE(name, name ## _mod, SI_SUB_CONFIGURE, SI_ORDER_FOURTH); \
	MODULE_DEPEND(name, ctl, 1, 1, 1); \
	MODULE_DEPEND(name, cam, 1, 1, 1)

struct ctl_wwpn_iid {
	int in_use;
	time_t last_use;
	uint64_t wwpn;
	char *name;
};

/*
 * The ctl_frontend structure is the registration mechanism between a FETD
 * (Front End Target Driver) and the CTL layer.  Here is a description of
 * the fields:
 *
 * port_type:		  This field tells CTL what kind of front end it is
 *                        dealing with.  This field serves two purposes.
 *                        The first is to let CTL know whether the frontend
 *                        in question is inside the main CTL module (i.e.
 *                        the ioctl front end), and therefore its module
 *                        reference count shouldn't be incremented.  The
 *                        CTL ioctl front end should continue to use the
 *                        CTL_PORT_IOCTL argument as long as it is part of
 *                        the main CTL module.  The second is to let CTL
 *                        know what kind of front end it is dealing with, so
 *                        it can return the proper inquiry data for that
 *                        particular port.
 *
 * num_requested_ctl_io:  This is the number of ctl_io structures that the
 *			  front end needs for its pool.  This should
 * 			  generally be the maximum number of outstanding
 *			  transactions that the FETD can handle.  The CTL
 *			  layer will add a few to this to account for
 *			  ctl_io buffers queued for pending sense data.
 *			  (Pending sense only gets queued if the FETD
 * 			  doesn't support autosense.  e.g. non-packetized
 * 			  parallel SCSI doesn't support autosense.)
 *
 * port_name:		  A string describing the FETD.  e.g. "LSI 1030T U320"
 *			  or whatever you want to use to describe the driver.
 *
 * physical_port:	  This is the physical port number of this
 * 			  particular port within the driver/hardware.  This
 * 			  number is hardware/driver specific.
 * virtual_port:	  This is the virtual port number of this
 * 			  particular port.  This is for things like NP-IV.
 * 
 * port_online():	  This function is called, with onoff_arg as its
 *			  argument, by the CTL layer when it wants the FETD
 *			  to start responding to selections on the specified
 * 			  target ID.
 *
 * port_offline():	  This function is called, with onoff_arg as its
 *			  argument, by the CTL layer when it wants the FETD
 * 			  to stop responding to selection on the specified
 * 			  target ID.
 *
 * onoff_arg:		  This is supplied as an argument to port_online()
 *			  and port_offline().  This is specified by the
 *			  FETD.
 *
 * lun_enable():	  This function is called, with targ_lun_arg, a target
 *			  ID and a LUN ID as its arguments, by CTL when it
 *			  wants the FETD to enable a particular LUN.  If the
 *			  FETD doesn't really know about LUNs, it should
 *			  just ignore this call and return 0.  If the FETD
 *			  cannot enable the requested LUN for some reason, the
 *			  FETD should return non-zero status.
 *
 * lun_disable():	  This function is called, with targ_lun_arg, a target
 *			  ID and LUN ID as its arguments, by CTL when it
 *			  wants the FETD to disable a particular LUN.  If the
 *			  FETD doesn't really know about LUNs, it should just
 *			  ignore this call and return 0.  If the FETD cannot
 *			  disable the requested LUN for some reason, the
 *			  FETD should return non-zero status.
 *
 * targ_lun_arg:	  This is supplied as an argument to the targ/lun
 *			  enable/disable() functions.  This is specified by
 *			  the FETD.
 *
 * fe_datamove():	  This function is called one or more times per I/O
 *			  by the CTL layer to tell the FETD to initiate a
 *			  DMA to or from the data buffer(s) specified by
 * 			  the passed-in ctl_io structure.
 *
 * fe_done():	  	  This function is called by the CTL layer when a
 *			  particular SCSI I/O or task management command has
 * 			  completed.  For SCSI I/O requests (CTL_IO_SCSI),
 *			  sense data is always supplied if the status is
 *			  CTL_SCSI_ERROR and the SCSI status byte is
 *			  SCSI_STATUS_CHECK_COND.  If the FETD doesn't
 *			  support autosense, the sense should be queued
 *			  back to the CTL layer via ctl_queue_sense().
 *
 * fe_dump():		  This function, if it exists, is called by CTL
 *			  to request a dump of any debugging information or
 *			  state to the console.
 *
 * targ_port:		  The CTL layer assigns a "port number" to every
 *			  FETD.  This port number should be passed back in
 *			  in the header of every ctl_io that is queued to
 *			  the CTL layer.  This enables us to determine
 *			  which bus the command came in on.
 *
 * ctl_pool_ref:	  Memory pool reference used by the FETD in calls to
 * 			  ctl_alloc_io().
 *
 * max_initiators:	  Maximum number of initiators that the FETD is
 *			  allowed to have.  Initiators should be numbered
 *			  from 0 to max_initiators - 1.  This value will
 * 			  typically be 16, and thus not a problem for
 * 			  parallel SCSI.  This may present issues for Fibre
 *			  Channel.
 *
 * wwnn			  World Wide Node Name to be used by the FETD.
 *			  Note that this is set *after* registration.  It
 * 			  will be set prior to the online function getting
 * 			  called.
 *
 * wwpn			  World Wide Port Name to be used by the FETD.
 *			  Note that this is set *after* registration.  It
 * 			  will be set prior to the online function getting
 * 			  called.
 *
 * status:		  Used by CTL to keep track of per-FETD state.
 *
 * links:		  Linked list pointers, used by CTL.  The FETD
 *			  shouldn't touch this field.
 */
struct ctl_port {
	struct ctl_softc *ctl_softc;
	struct ctl_frontend *frontend;
	ctl_port_type	port_type;		/* passed to CTL */
	int		num_requested_ctl_io;	/* passed to CTL */
	char		*port_name;		/* passed to CTL */
	int		physical_port;		/* passed to CTL */
	int		virtual_port;		/* passed to CTL */
	port_func_t	port_online;		/* passed to CTL */
	port_func_t	port_offline;		/* passed to CTL */
	port_info_func_t port_info;		/* passed to CTL */
	void		*onoff_arg;		/* passed to CTL */
	lun_func_t	lun_enable;		/* passed to CTL */
	lun_func_t	lun_disable;		/* passed to CTL */
	int		lun_map_size;		/* passed to CTL */
	uint32_t	*lun_map;		/* passed to CTL */
	void		*targ_lun_arg;		/* passed to CTL */
	void		(*fe_datamove)(union ctl_io *io); /* passed to CTL */
	void		(*fe_done)(union ctl_io *io); /* passed to CTL */
	int32_t		targ_port;		/* passed back to FETD */
	void		*ctl_pool_ref;		/* passed back to FETD */
	uint32_t	max_initiators;		/* passed back to FETD */
	struct ctl_wwpn_iid *wwpn_iid;		/* used by CTL */
	uint64_t	wwnn;			/* set by CTL before online */
	uint64_t	wwpn;			/* set by CTL before online */
	ctl_port_status	status;			/* used by CTL */
	nvlist_t	*options;		/* passed to CTL */
	struct ctl_devid *port_devid;		/* passed to CTL */
	struct ctl_devid *target_devid;		/* passed to CTL */
	struct ctl_devid *init_devid;		/* passed to CTL */
	struct ctl_io_stats stats;		/* used by CTL */
	struct mtx	port_lock;		/* used by CTL */
	STAILQ_ENTRY(ctl_port) fe_links;	/* used by CTL */
	STAILQ_ENTRY(ctl_port) links;		/* used by CTL */
};

struct ctl_frontend {
	char		name[CTL_DRIVER_NAME_LEN];	/* passed to CTL */
	fe_init_t	init;			/* passed to CTL */
	fe_ioctl_t	ioctl;			/* passed to CTL */
	void		(*fe_dump)(void);	/* passed to CTL */
	fe_shutdown_t	shutdown;		/* passed to CTL */
	STAILQ_HEAD(, ctl_port) port_list;	/* used by CTL */
	STAILQ_ENTRY(ctl_frontend) links;	/* used by CTL */
};

/*
 * This may block until resources are allocated.  Called at FETD module load
 * time. Returns 0 for success, non-zero for failure.
 */
int ctl_frontend_register(struct ctl_frontend *fe);

/*
 * Called at FETD module unload time.
 * Returns 0 for success, non-zero for failure.
 */
int ctl_frontend_deregister(struct ctl_frontend *fe);

/*
 * Find the frontend by its name. Returns NULL if not found.
 */
struct ctl_frontend * ctl_frontend_find(char *frontend_name);

/*
 * This may block until resources are allocated.  Called at FETD module load
 * time. Returns 0 for success, non-zero for failure.
 */
int ctl_port_register(struct ctl_port *port);

/*
 * Called at FETD module unload time.
 * Returns 0 for success, non-zero for failure.
 */
int ctl_port_deregister(struct ctl_port *port);

/*
 * Called to set the WWNN and WWPN for a particular frontend.
 */
void ctl_port_set_wwns(struct ctl_port *port, int wwnn_valid,
			   uint64_t wwnn, int wwpn_valid, uint64_t wwpn);

/*
 * Called to bring a particular frontend online.
 */
void ctl_port_online(struct ctl_port *fe);

/*
 * Called to take a particular frontend offline.
 */
void ctl_port_offline(struct ctl_port *fe);

/*
 * This routine queues I/O and task management requests from the FETD to the
 * CTL layer.  Returns immediately.  Returns 0 for success, non-zero for
 * failure.
 */
int ctl_queue(union ctl_io *io);

/*
 * This routine starts execution of I/O and task management requests from
 * the FETD to the CTL layer.  May sleep.  Returns 0 for success, non-zero
 * for failure.
 */
int ctl_run(union ctl_io *io);

/*
 * This routine is used if the front end interface doesn't support
 * autosense (e.g. non-packetized parallel SCSI).  This will queue the
 * scsiio structure back to a per-lun pending sense queue.  This MUST be
 * called BEFORE any request sense can get queued to the CTL layer -- I
 * need it in the queue in order to service the request.  The scsiio
 * structure passed in here will be freed by the CTL layer when sense is
 * retrieved by the initiator.  Returns 0 for success, non-zero for failure.
 */
int ctl_queue_sense(union ctl_io *io);

/*
 * This routine adds an initiator to CTL's port database.
 * The iid field should be the same as the iid passed in the nexus of each
 * ctl_io from this initiator.
 * The WWPN should be the FC WWPN, if available.
 */
int ctl_add_initiator(struct ctl_port *port, int iid, uint64_t wwpn, char *name);

/*
 * This routine will remove an initiator from CTL's port database.
 * The iid field should be the same as the iid passed in the nexus of each
 * ctl_io from this initiator.
 */
int ctl_remove_initiator(struct ctl_port *port, int iid);

#endif	/* _CTL_FRONTEND_H_ */