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/*
23 * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
24 * Use is subject to license terms.
25 */
26
27/*
28 * Copyright (c) 2012, Joyent, Inc. All rights reserved.
29 * Copyright 2017 Nexenta Systems, Inc.
30 */
31
32#ifndef _LIBDISKMGT_H
33#define	_LIBDISKMGT_H
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39#include <libnvpair.h>
40#include <sys/swap.h>
41
42
43/*
44 * Disk Management Library
45 *
46 * This library provides a common way to gather information about a system's
47 * disks, controllers, and related components.
48 *
49 *
50 * THREADS
51 * -------
52 *
53 * In general all of the functions are thread safe, however there are some
54 * specific considerations for getting events.  The dm_get_event function may
55 * block the calling thread if no event is currently available.  If another
56 * thread calls dm_get_event while a thread is already blocked in this function,
57 * the second thread will also block.  When an event arrives and multiple
58 * threads are waiting for events, it is undefined which thread will be
59 * unblocked and receive the event.  If a callback is used for handling events,
60 * this is equivalent to the dm_get_event function, so mixing callbacks and
61 * dm_get_event is also nondeterministic.
62 *
63 *
64 * ERRORS
65 * ------
66 *
67 * In general all of the functions take an errno pointer.  This is an integer
68 * that will contain 0 if the function succeeded or contains an errno (see
69 * errno.h) if there was an error.  If the function returns some data, that
70 * return data will generally be null if an error occured (see the API comment
71 * for the specific function for details).  Many of the functions take a
72 * descriptor and provide more information for that descriptor.  These functions
73 * may return an error if the object was removed between the call which obtained
74 * the descriptor and the call to get more information about the object (errno
75 * will be ENODEV).  Only a few of the possible errno values will be returned;
76 * typically:
77 *     EPERM       not super-user
78 *     ENOMEM      not enough memory
79 *     ENODEV      no such device
80 *     EINVAL      invalid argument
81 *     ENOENT      no event queue has been created
82 *
83 * Many of the functions require the application to be running as root in order
84 * to get complete information.  EPERM will be returned if the application is
85 * not running as root.  However, not all of the functions have this requirement
86 * (i.e. event handling).
87 *
88 * It is possible for the system to run out of memory while receiving events.
89 * Since event receipt is asyncronous from the dm_get_event call there may not
90 * be a thread waiting when the event occurs and ENOMEM is detected.  In this
91 * case the event will be lost.  The first call to dm_get_event following this
92 * condition will immediately return ENOMEM, even if events are queued.
93 * Subsequent calls can return events.  The dm_get_event call will clear the
94 * pending ENOMEM condition.  There is no way to know how many events were lost
95 * when this situation occurs.  If a thread is waiting when the event arrives
96 * and the ENOMEM condition occurs, the call will also return with ENOMEM.
97 * There is no way to determine if the system ran out of memory before the
98 * dm_get_event call or while the thread was blocked in the dm_get_event call
99 * since both conditions cause dm_get_event to return ENOMEM.
100 *
101 *
102 * MEMORY MANAGEMENT
103 * -----------------
104 *
105 * Most of the functions that return data are returning memory that has been
106 * allocated and must be freed by the application when no longer needed.  The
107 * application should call the proper free function to free the memory.  Most of
108 * the functions return either a nvlist or an array of descriptors.  The normal
109 * nvlist function (nvlist_free; see libnvpair(3LIB)) can be used to free the
110 * simple nvlists.  Other functions are provided to free the more complex data
111 * structures.
112 *
113 * The following list shows the functions that return allocated memory and the
114 * corresponding function to free the memory:
115 *     dm_get_descriptors            dm_free_descriptors
116 *     dm_get_associated_descriptors dm_free_descriptors
117 *     dm_get_descriptor_by_name     dm_free_descriptor
118 *     dm_get_name                   dm_free_name
119 *     dm_get_attributes             nvlist_free
120 *     dm_get_stats	          nvlist_free
121 *     dm_get_event                  nvlist_free
122 *
123 *
124 * EVENTS
125 * ------
126 *
127 * Event information is returned as a nvlist.  It may be possible to return more
128 * information about events over time, especially information about what has
129 * changed.  However, that may not always be the case, so by using an nvlist we
130 * have a very generic event indication.  At a minimum the event will return the
131 * name of the device, the type of device (see dm_desc_type_t) and the type of
132 * event.  The event type is a string which can currently be; add, remove,
133 * change.
134 *
135 * If a drive goes up or down this could be returned as event type "change".
136 * The application could get the drive information to see that the "status"
137 * attribute has changed value (ideally the event would include an attribute
138 * with the name of the changed attribute as the value).  Although the API can
139 * return events for all drive related changes, events will not necessarily be
140 * delivered for all changes unless the system generates those events.
141 *
142 *
143 * Controller/HBAs
144 * ---------------
145 *
146 * In general the API means "the parent node of the drive in the device tree"
147 * where the word "controller" is used.  This can actually be either the HBA or
148 * the drive controller depending on the type of the drive.
149 *
150 * Drives can be connected to their controller(s) in three different ways:
151 *     single controller
152 *     multiple controllers
153 *     multiple controllers with mpxio
154 * These cases will lead to different information being available for the
155 * configuration.  The two interesting cases are multi-path with and without
156 * mpxio.  With mpxio the drive will have a unique name and a single controller
157 * (scsi_vhci).  The physical controllers, the paths to the drive, can be
158 * obtained by calling dm_get_associated_descriptors with a drive descriptor and
159 * a type of DM_PATH.  This will only return these physical paths when MPXIO, or
160 * possibly some future similar feature, is controlling the drive.
161 *
162 * Without mpxio the drive does not have a unique public name (in all cases the
163 * alias(es) of the drive can be determined by calling
164 * dm_get_associated_descriptors to get the DM_ALIAS descriptors.  There will be
165 * more than one controller returned from dm_get_associated_descriptors when
166 * called with a type of DM_CONTROLLER.  The controllers for each of the aliases
167 * will be returned in the same order as the aliases descriptors.  For example,
168 * a drive with two paths has the aliases c5t3d2 and c7t1d0.  There will be two
169 * controllers returned; the first corresponds to c5 and the second corresponds
170 * to c7.
171 *
172 * In the multi-path, non-mpxio case the drive has more than one alias.
173 * Although most of the drive attributes are represented on the drive (see
174 * dm_get_attributes) there can be some different attributes for the different
175 * aliases for the drive.  Use dm_get_associated_descriptors to get the DM_ALIAS
176 * descriptors which can then be used to obtain these attributes.  Use of this
177 * algorithm is not restricted to the multi-path, non-mpxio case.  For example,
178 * it can be used to get the target/lun for a SCSI drive with a single path.
179 */
180
181/*
182 * Holds all the data regarding the device.
183 * Private to libdiskmgt. Must use dm_xxx functions to set/get data.
184 */
185typedef uint64_t  dm_descriptor_t;
186
187typedef enum {
188	DM_WHO_MKFS = 0,
189	DM_WHO_ZPOOL,
190	DM_WHO_ZPOOL_FORCE,
191	DM_WHO_FORMAT,
192	DM_WHO_SWAP,
193	DM_WHO_DUMP,
194	DM_WHO_ZPOOL_SPARE
195} dm_who_type_t;
196
197/*
198 * The API uses a "descriptor" to identify the managed objects such as drives,
199 * controllers, media, slices, partitions, paths and buses.  The descriptors are
200 * opaque and are only returned or used as parameters to the other functions in
201 * the API.  The descriptor definition is a typedef to dm_descriptor_t.
202 *
203 * Applications call either the dm_get_descriptors or
204 * dm_get_associated_descriptors function to obtain a list of descriptors of a
205 * specific type.  The application specifies the desired type from the following
206 * enumeration:
207 */
208typedef enum {
209    DM_DRIVE = 0,
210    DM_CONTROLLER,
211    DM_MEDIA,
212    DM_SLICE,
213    DM_PARTITION,
214    DM_PATH,
215    DM_ALIAS,
216    DM_BUS
217} dm_desc_type_t;
218
219/*
220 * These descriptors are associated with each other in the following way:
221 *
222 *                      alias                 partition
223 *     _                    \                /   |
224 *    / \                    \              /    |
225 *    \ /                     \            /     |
226 *    bus --- controller --- drive --- media     |
227 *                     |      /            \     |
228 *                     |     /              \    |
229 *                     |    /                \   |
230 *                      path                  slice
231 *
232 * The dm_get_associated_descriptors function can be used get the descriptors
233 * associated with a given descriptor.  The dm_get_associated_types function can
234 * be used to find the types that can be associated with a given type.
235 *
236 * The attributes and values for these objects are described using a list of
237 * name/value pairs (see libnvpair(3LIB) and the specific comments for each
238 * function in the API section of this document).
239 *
240 * Drives and media have a type which are defined as the following enumerations.
241 * There could be additional types added to these enumerations as new drive and
242 * media types are supported by the system.
243 */
244
245typedef enum {
246    DM_DT_UNKNOWN = 0,
247    DM_DT_FIXED,
248    DM_DT_ZIP,
249    DM_DT_JAZ,
250    DM_DT_FLOPPY,
251    DM_DT_MO_ERASABLE,
252    DM_DT_MO_WRITEONCE,
253    DM_DT_AS_MO,
254    DM_DT_CDROM,
255    DM_DT_CDR,
256    DM_DT_CDRW,
257    DM_DT_DVDROM,
258    DM_DT_DVDR,
259    DM_DT_DVDRAM,
260    DM_DT_DVDRW,
261    DM_DT_DDCDROM,
262    DM_DT_DDCDR,
263    DM_DT_DDCDRW
264} dm_drive_type_t;
265
266typedef enum {
267    DM_MT_UNKNOWN = 0,
268    DM_MT_FIXED,
269    DM_MT_FLOPPY,
270    DM_MT_CDROM,
271    DM_MT_ZIP,
272    DM_MT_JAZ,
273    DM_MT_CDR,
274    DM_MT_CDRW,
275    DM_MT_DVDROM,
276    DM_MT_DVDR,
277    DM_MT_DVDRAM,
278    DM_MT_MO_ERASABLE,
279    DM_MT_MO_WRITEONCE,
280    DM_MT_AS_MO
281} dm_media_type_t;
282
283#define	DM_FILTER_END	-1
284
285/*
286 * The dm_get_stats function takes a stat_type argument for the specific sample
287 * to get for the descriptor.  The following enums specify the drive and slice
288 * stat types.
289 */
290/* drive stat name */
291typedef enum {
292    DM_DRV_STAT_PERFORMANCE = 0,
293    DM_DRV_STAT_DIAGNOSTIC,
294    DM_DRV_STAT_TEMPERATURE
295} dm_drive_stat_t;
296
297/* slice stat name */
298typedef enum {
299    DM_SLICE_STAT_USE = 0
300} dm_slice_stat_t;
301
302/* partition type */
303typedef enum {
304	DM_PRIMARY = 0,
305	DM_EXTENDED,
306	DM_LOGICAL
307} dm_partition_type_t;
308
309/* attribute definitions */
310
311/* drive */
312#define	DM_DISK_UP		1
313#define	DM_DISK_DOWN		0
314
315#define	DM_DRVTYPE		"drvtype"
316#define	DM_FAILING		"failing"
317#define	DM_LOADED		"loaded"	/* also in media */
318#define	DM_NDNRERRS		"ndevice_not_ready_errors"
319#define	DM_NBYTESREAD		"nbytes_read"
320#define	DM_NBYTESWRITTEN	"nbytes_written"
321#define	DM_NHARDERRS		"nhard_errors"
322#define	DM_NILLREQERRS		"nillegal_req_errors"
323#define	DM_NMEDIAERRS		"nmedia_errors"
324#define	DM_NNODEVERRS		"nno_dev_errors"
325#define	DM_NREADOPS		"nread_ops"
326#define	DM_NRECOVERRS		"nrecoverable_errors"
327#define	DM_NSOFTERRS		"nsoft_errors"
328#define	DM_NTRANSERRS		"ntransport_errors"
329#define	DM_NWRITEOPS		"nwrite_ops"
330#define	DM_OPATH		"opath"
331#define	DM_PRODUCT_ID		"product_id"
332#define	DM_REMOVABLE		"removable"	/* also in media */
333#define	DM_RPM			"rpm"
334#define	DM_SOLIDSTATE		"solid_state"
335#define	DM_STATUS		"status"
336#define	DM_SYNC_SPEED		"sync_speed"
337#define	DM_TEMPERATURE		"temperature"
338#define	DM_VENDOR_ID		"vendor_id"
339#define	DM_WIDE			"wide"		/* also on controller */
340#define	DM_WWN			"wwn"
341
342/* bus */
343#define	DM_BTYPE		"btype"
344#define	DM_CLOCK		"clock"		/* also on controller */
345#define	DM_PNAME		"pname"
346
347/* controller */
348#define	DM_FAST			"fast"
349#define	DM_FAST20		"fast20"
350#define	DM_FAST40		"fast40"
351#define	DM_FAST80		"fast80"
352#define	DM_MULTIPLEX		"multiplex"
353#define	DM_PATH_STATE		"path_state"
354
355#define	DM_CTYPE_ATA		"ata"
356#define	DM_CTYPE_FIBRE		"fibre"
357#define	DM_CTYPE_NVME		"nvme"
358#define	DM_CTYPE_SATA		"sata"
359#define	DM_CTYPE_SCSI		"scsi"
360#define	DM_CTYPE_USB		"usb"
361#define	DM_CTYPE_XEN		"xen"
362#define	DM_CTYPE_UNKNOWN	"unknown"
363
364/* media */
365#define	DM_BLOCKSIZE		"blocksize"
366#define	DM_FDISK		"fdisk"
367#define	DM_MTYPE		"mtype"
368#define	DM_NACTUALCYLINDERS	"nactual_cylinders"
369#define	DM_NALTCYLINDERS	"nalt_cylinders"
370#define	DM_NCYLINDERS		"ncylinders"
371#define	DM_NHEADS		"nheads"
372#define	DM_NPHYSCYLINDERS	"nphys_cylinders"
373#define	DM_NSECTORS		"nsectors"	/* also in partition */
374#define	DM_SIZE			"size"		/* also in slice */
375#define	DM_NACCESSIBLE		"naccessible"
376#define	DM_LABEL		"label"
377
378/* partition */
379#define	DM_BCYL			"bcyl"
380#define	DM_BHEAD		"bhead"
381#define	DM_BOOTID		"bootid"
382#define	DM_BSECT		"bsect"
383#define	DM_ECYL			"ecyl"
384#define	DM_EHEAD		"ehead"
385#define	DM_ESECT		"esect"
386#define	DM_PTYPE		"ptype" /* this references the partition id */
387#define	DM_PARTITION_TYPE	"part_type" /* primary, extended, logical */
388#define	DM_RELSECT		"relsect"
389
390/* slice */
391#define	DM_DEVICEID		"deviceid"
392#define	DM_DEVT			"devt"
393#define	DM_INDEX		"index"
394#define	DM_EFI_NAME		"name"
395#define	DM_MOUNTPOINT		"mountpoint"
396#define	DM_LOCALNAME		"localname"
397#define	DM_START		"start"
398#define	DM_TAG			"tag"
399#define	DM_FLAG			"flag"
400#define	DM_EFI			"efi"	/* also on media */
401#define	DM_USED_BY		"used_by"
402#define	DM_USED_NAME		"used_name"
403#define	DM_USE_MOUNT		"mount"
404#define	DM_USE_LU		"lu"
405#define	DM_USE_DUMP		"dump"
406#define	DM_USE_VXVM		"vxvm"
407#define	DM_USE_FS		"fs"
408#define	DM_USE_VFSTAB		"vfstab"
409#define	DM_USE_EXPORTED_ZPOOL	"exported_zpool"
410#define	DM_USE_ACTIVE_ZPOOL	"active_zpool"
411#define	DM_USE_SPARE_ZPOOL	"spare_zpool"
412#define	DM_USE_L2CACHE_ZPOOL	"l2cache_zpool"
413
414/* event */
415#define	DM_EV_NAME		"name"
416#define	DM_EV_DTYPE		"edtype"
417#define	DM_EV_TYPE		"evtype"
418#define	DM_EV_TADD		"add"
419#define	DM_EV_TREMOVE		"remove"
420#define	DM_EV_TCHANGE		"change"
421
422/* findisks */
423#define	DM_CTYPE		"ctype"
424#define	DM_LUN			"lun"
425#define	DM_TARGET		"target"
426
427#define	NOINUSE_SET	getenv("NOINUSE_CHECK") != NULL
428
429void			dm_free_descriptors(dm_descriptor_t *desc_list);
430void			dm_free_descriptor(dm_descriptor_t desc);
431void			dm_free_name(char *name);
432void			dm_free_swapentries(swaptbl_t *);
433
434dm_descriptor_t		*dm_get_descriptors(dm_desc_type_t type, int filter[],
435			    int *errp);
436dm_descriptor_t		*dm_get_associated_descriptors(dm_descriptor_t desc,
437			    dm_desc_type_t type, int *errp);
438dm_desc_type_t		*dm_get_associated_types(dm_desc_type_t type);
439dm_descriptor_t		dm_get_descriptor_by_name(dm_desc_type_t desc_type,
440			    char *name, int *errp);
441char			*dm_get_name(dm_descriptor_t desc, int *errp);
442dm_desc_type_t		dm_get_type(dm_descriptor_t desc);
443nvlist_t		*dm_get_attributes(dm_descriptor_t desc, int *errp);
444nvlist_t		*dm_get_stats(dm_descriptor_t desc, int stat_type,
445			    int *errp);
446void			dm_init_event_queue(void(*callback)(nvlist_t *, int),
447			    int *errp);
448nvlist_t		*dm_get_event(int *errp);
449void			dm_get_slices(char *drive, dm_descriptor_t **slices,
450			    int *errp);
451void			dm_get_slice_stats(char *slice, nvlist_t **dev_stats,
452			    int *errp);
453int			dm_get_swapentries(swaptbl_t **, int *);
454void			dm_get_usage_string(char *who, char *data, char **msg);
455int			dm_inuse(char *dev_name, char **msg, dm_who_type_t who,
456			    int *errp);
457int			dm_inuse_swap(const char *dev_name, int *errp);
458int			dm_isoverlapping(char *dev_name, char **msg, int *errp);
459
460#ifdef __cplusplus
461}
462#endif
463
464#endif /* _LIBDISKMGT_H */
465