xref: /illumos-gate/usr/src/uts/common/sys/blkdev.h (revision 744642a2)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright 2012 DEY Storage Systems, Inc.  All rights reserved.
23  * Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
24  * Copyright 2020 Joyent, Inc.
25  * Copyright 2022 Tintri by DDN, Inc. All rights reserved.
26  */
27 
28 #ifndef	_SYS_BLKDEV_H
29 #define	_SYS_BLKDEV_H
30 
31 #include <sys/types.h>
32 #include <sys/ksynch.h>
33 #include <sys/ddi.h>
34 #include <sys/sunddi.h>
35 
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
39 
40 /*
41  * This describes a fairly simple block device.  The idea here is that
42  * these things want to take advantage of the common labelling support,
43  * but do not need all the capabilities of SCSA.  So we make quite a few
44  * simplifications:
45  *
46  * 1) Device block size is a power of 2 greater or equal to 512 bytes.
47  *    An optional physical block size can be reported if the underlying
48  *    device uses larger block sizes internally, so that writes can be
49  *    aligned properly.
50  *
51  * 2) Non-rotating media.  We assume a simple linear layout.
52  *
53  * 3) Fixed queue depth, for each device.  The adapter driver reports
54  *    the queue depth at registration.  We don't have any form of
55  *    dynamic flow control.
56  *
57  * 4) Negligible power management support.  The framework does not support
58  *    fine grained power management.  If the adapter driver wants to use
59  *    such, it will need to manage power on its own.
60  *
61  * 5) Suspend/resume support managed by the adapter driver.  We don't
62  *    support suspend/resume directly.  The adapter device driver will
63  *    need to manage this on its own behalf.
64  *
65  * 6) No request priorities.  Transfers are assumed to execute in
66  *    roughly FIFO order.  The adapter driver may reorder them, but the
67  *    submitter has no control over that.
68  *
69  * 7) No request cancellation.  Once submitted, the job completes or
70  *    fails.  It cannot be canceled.
71  *
72  * 8) Limited support for removable media.  There is no support for
73  *    locking bay doors or mechanised media bays.  This could be
74  *    added, but at present the only such interesting devices are
75  *    covered by the SCSI disk driver.
76  */
77 
78 typedef struct bd_handle *bd_handle_t;
79 typedef struct bd_xfer bd_xfer_t;
80 typedef struct bd_drive bd_drive_t;
81 typedef struct bd_media bd_media_t;
82 typedef struct bd_free_info bd_free_info_t;
83 typedef struct bd_ops bd_ops_t;
84 
85 struct dkioc_free_list_s;
86 
87 struct bd_xfer {
88 	/*
89 	 * NB: If using DMA the br_ndmac will be non-zero.  Otherwise
90 	 * the br_kaddr will be non-NULL.
91 	 */
92 	diskaddr_t		x_blkno;
93 	size_t			x_nblks;
94 	ddi_dma_handle_t	x_dmah;
95 	ddi_dma_cookie_t	x_dmac;
96 	unsigned		x_ndmac;
97 	caddr_t			x_kaddr;
98 	unsigned		x_flags;
99 	unsigned		x_qnum;
100 	const struct dkioc_free_list_s *x_dfl;
101 };
102 
103 #define	BD_XFER_POLL		(1U << 0)	/* no interrupts (dump) */
104 
105 struct bd_drive {
106 	uint32_t		d_qsize;
107 	uint32_t		d_maxxfer;
108 	boolean_t		d_removable;
109 	boolean_t		d_hotpluggable;
110 	int			d_target;
111 	int			d_lun;
112 	size_t			d_vendor_len;
113 	char			*d_vendor;
114 	size_t			d_product_len;
115 	char			*d_product;
116 	size_t			d_model_len;
117 	char			*d_model;
118 	size_t			d_serial_len;
119 	char			*d_serial;
120 	size_t			d_revision_len;
121 	char			*d_revision;
122 
123 	uint8_t			d_eui64[8];
124 	uint8_t			d_guid[16];
125 
126 	uint32_t		d_qcount;
127 
128 	/*
129 	 * Required starting alignment for free_space requests (in logical
130 	 * blocks). Must be >= 1.
131 	 */
132 	uint64_t		d_free_align;
133 
134 	/*
135 	 * Maximum number of segments supported in a free space request.
136 	 * 0 implies no limit.
137 	 */
138 	uint64_t		d_max_free_seg;
139 
140 	/*
141 	 * Maximum number of logical blocks allowed in a free space request.
142 	 * 0 implies no limit.
143 	 */
144 	uint64_t		d_max_free_blks;
145 
146 	/*
147 	 * Maximum number of logical blocks to free in a single segment.
148 	 * 0 implies no limit. If no limit, d_max_free_blks must also be 0.
149 	 * If > 0, d_max_free_seg_blks must be <= d_max_free_blks (basically
150 	 * you can't set a bigger value of d_max_free_seg_blks than
151 	 * d_max_free_blks).
152 	 */
153 	uint64_t		d_max_free_seg_blks;
154 };
155 
156 struct bd_media {
157 	/*
158 	 * NB: The block size must be a power of two not less than
159 	 * DEV_BSIZE (512).  Other values of the block size will
160 	 * simply not function and the media will be rejected.
161 	 *
162 	 * The block size must also divide evenly into the device's
163 	 * d_maxxfer field.  If the maxxfer is a power of two larger
164 	 * than the block size, then this will automatically be
165 	 * satisfied.
166 	 *
167 	 * The physical block size (m_pblksize) must be 0 or a power
168 	 * of two not less than the block size.
169 	 */
170 	uint64_t		m_nblks;
171 	uint32_t		m_blksize;
172 	boolean_t		m_readonly;
173 	boolean_t		m_solidstate;
174 	uint32_t		m_pblksize;
175 };
176 
177 #define	BD_INFO_FLAG_REMOVABLE		(1U << 0)
178 #define	BD_INFO_FLAG_HOTPLUGGABLE	(1U << 1)
179 #define	BD_INFO_FLAG_READ_ONLY		(1U << 2)
180 
181 /*
182  * When adding a new version of the bd_ops_t struct, be sure to update
183  * BD_OPS_CURRENT_VERSION
184  */
185 typedef enum {
186 	BD_OPS_VERSION_0 = 0,
187 	BD_OPS_VERSION_1 = 1,
188 	BD_OPS_VERSION_2 = 2,
189 } bd_version_t;
190 #define	BD_OPS_CURRENT_VERSION BD_OPS_VERSION_2
191 
192 struct bd_ops {
193 	bd_version_t	o_version;
194 	void		(*o_drive_info)(void *, bd_drive_t *);
195 	int		(*o_media_info)(void *, bd_media_t *);
196 	int		(*o_devid_init)(void *, dev_info_t *, ddi_devid_t *);
197 	int		(*o_sync_cache)(void *, bd_xfer_t *);
198 	int		(*o_read)(void *, bd_xfer_t *);
199 	int		(*o_write)(void *, bd_xfer_t *);
200 	int		(*o_free_space)(void *, bd_xfer_t *);
201 };
202 
203 struct bd_errstats {
204 	/* these are managed by blkdev itself */
205 	kstat_named_t	bd_softerrs;
206 	kstat_named_t	bd_harderrs;
207 	kstat_named_t	bd_transerrs;
208 	kstat_named_t	bd_model;
209 	kstat_named_t	bd_vid;
210 	kstat_named_t	bd_pid;
211 	kstat_named_t	bd_revision;
212 	kstat_named_t	bd_serial;
213 	kstat_named_t	bd_capacity;
214 
215 	/* the following are updated on behalf of the HW driver */
216 	kstat_named_t	bd_rq_media_err;
217 	kstat_named_t	bd_rq_ntrdy_err;
218 	kstat_named_t	bd_rq_nodev_err;
219 	kstat_named_t	bd_rq_recov_err;
220 	kstat_named_t	bd_rq_illrq_err;
221 	kstat_named_t	bd_rq_pfa_err;
222 };
223 
224 #define	BD_ERR_MEDIA	0
225 #define	BD_ERR_NTRDY	1
226 #define	BD_ERR_NODEV	2
227 #define	BD_ERR_RECOV	3
228 #define	BD_ERR_ILLRQ	4
229 #define	BD_ERR_PFA	5
230 
231 /*
232  * Note, one handler *per* address.  Drivers with multiple targets at
233  * different addresses must use separate handles.
234  */
235 bd_handle_t	bd_alloc_handle(void *, bd_ops_t *, ddi_dma_attr_t *, int);
236 void		bd_free_handle(bd_handle_t);
237 int		bd_attach_handle(dev_info_t *, bd_handle_t);
238 int		bd_detach_handle(bd_handle_t);
239 void		bd_state_change(bd_handle_t);
240 const char	*bd_address(bd_handle_t);
241 void		bd_xfer_done(bd_xfer_t *, int);
242 void		bd_error(bd_xfer_t *, int);
243 void		bd_mod_init(struct dev_ops *);
244 void		bd_mod_fini(struct dev_ops *);
245 
246 #ifdef __cplusplus
247 }
248 #endif
249 
250 #endif	/* _SYS_BLKDEV_H */
251