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 (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved.
24  * Copyright (c) 2017, Joyent, Inc.
25  */
26 
27 #ifndef	_LIBSCSI_H
28 #define	_LIBSCSI_H
29 
30 #ifdef	__cplusplus
31 extern "C" {
32 #endif
33 
34 #include <sys/types.h>
35 #include <sys/sysmacros.h>
36 #include <sys/scsi/impl/spc3_types.h>
37 #include <stdarg.h>
38 
39 #define	LIBSCSI_VERSION		1
40 #define	LIBSCSI_STATUS_INVALID	((sam4_status_t)-1)
41 #define	LIBSCSI_DEFAULT_ENGINE_PATH	"/usr/lib/scsi/plugins/scsi/engines"
42 #define	LIBSCSI_DEFAULT_ENGINE	"uscsi"
43 
44 /*
45  * Flags for action creation.  Selected to avoid overlap with the uscsi
46  * flags with similar or identical meaning.
47  */
48 #define	LIBSCSI_AF_READ		0x80000000
49 #define	LIBSCSI_AF_WRITE	0x40000000
50 #define	LIBSCSI_AF_SILENT	0x20000000
51 #define	LIBSCSI_AF_DIAGNOSE	0x10000000
52 #define	LIBSCSI_AF_ISOLATE	0x08000000
53 #define	LIBSCSI_AF_RQSENSE	0x04000000
54 
55 typedef enum libscsi_errno {
56 	ESCSI_NONE,		/* no error */
57 	ESCSI_NOMEM,		/* no memory */
58 	ESCSI_ZERO_LENGTH,	/* zero-length allocation requested */
59 	ESCSI_VERSION,		/* library version mismatch */
60 	ESCSI_BADTARGET,	/* invalid target specification */
61 	ESCSI_BADCMD,		/* invalid SCSI command */
62 	ESCSI_BADENGINE,	/* engine library corrupt */
63 	ESCSI_NOENGINE,		/* engine library not found */
64 	ESCSI_ENGINE_INIT,	/* engine initialization failed */
65 	ESCSI_ENGINE_VER,	/* engine version mismatch */
66 	ESCSI_ENGINE_BADPATH,	/* engine path contains no usable components */
67 	ESCSI_BADFLAGS,		/* incorrect action flags */
68 	ESCSI_BOGUSFLAGS,	/* unknown flag value */
69 	ESCSI_BADLENGTH,	/* buffer length overflow */
70 	ESCSI_NEEDBUF,		/* missing required buffer */
71 	ESCSI_IO,		/* I/O operation failed */
72 	ESCSI_SYS,		/* system call failed */
73 	ESCSI_PERM,		/* insufficient permissions */
74 	ESCSI_RANGE,		/* parameter outside valid range */
75 	ESCSI_NOTSUP,		/* operation not supported */
76 	ESCSI_UNKNOWN,		/* error of unknown type */
77 	ESCSI_INQUIRY_FAILED,	/* initial inquiry command failed */
78 	ESCSI_MAX		/* maximum libscsi errno value */
79 } libscsi_errno_t;
80 
81 struct libscsi_hdl;
82 typedef struct libscsi_hdl libscsi_hdl_t;
83 
84 struct libscsi_target;
85 typedef struct libscsi_target libscsi_target_t;
86 
87 typedef struct libscsi_status {
88 	uint64_t lss_status;		/* SCSI status of this command */
89 	size_t lss_sense_len;		/* Length in bytes of sense data */
90 	uint8_t *lss_sense_data;	/* Pointer to sense data */
91 } libscsi_status_t;
92 
93 struct libscsi_action;
94 typedef struct libscsi_action libscsi_action_t;
95 
96 typedef struct libscsi_engine_ops {
97 	void *(*lseo_open)(libscsi_hdl_t *, const void *);
98 	void (*lseo_close)(libscsi_hdl_t *, void *);
99 	int (*lseo_exec)(libscsi_hdl_t *, void *, libscsi_action_t *);
100 	void (*lseo_target_name)(libscsi_hdl_t *, void *, char *, size_t);
101 	int (*lseo_max_transfer)(libscsi_hdl_t *, void *, size_t *);
102 } libscsi_engine_ops_t;
103 
104 typedef struct libscsi_engine {
105 	const char *lse_name;
106 	uint_t lse_libversion;
107 	const libscsi_engine_ops_t *lse_ops;
108 } libscsi_engine_t;
109 
110 extern libscsi_hdl_t *libscsi_init(uint_t, libscsi_errno_t *);
111 extern void libscsi_fini(libscsi_hdl_t *);
112 
113 extern libscsi_target_t *libscsi_open(libscsi_hdl_t *, const char *,
114     const void *);
115 extern void libscsi_close(libscsi_hdl_t *, libscsi_target_t *);
116 extern libscsi_hdl_t *libscsi_get_handle(libscsi_target_t *);
117 
118 extern const char *libscsi_vendor(libscsi_target_t *);
119 extern const char *libscsi_product(libscsi_target_t *);
120 extern const char *libscsi_revision(libscsi_target_t *);
121 extern int libscsi_max_transfer(libscsi_target_t *, size_t *);
122 
123 extern libscsi_errno_t libscsi_errno(libscsi_hdl_t *);
124 extern const char *libscsi_errmsg(libscsi_hdl_t *);
125 extern const char *libscsi_strerror(libscsi_errno_t);
126 extern const char *libscsi_errname(libscsi_errno_t);
127 extern libscsi_errno_t libscsi_errcode(const char *);
128 
129 extern libscsi_action_t *libscsi_action_alloc(libscsi_hdl_t *, spc3_cmd_t,
130     uint_t, void *, size_t);
131 extern libscsi_action_t *libscsi_action_alloc_vendor(libscsi_hdl_t *,
132     spc3_cmd_t, size_t, uint_t, void *, size_t);
133 extern sam4_status_t libscsi_action_get_status(const libscsi_action_t *);
134 extern void libscsi_action_set_timeout(libscsi_action_t *, uint32_t);
135 extern size_t libscsi_action_get_cdblen(const libscsi_action_t *);
136 extern uint32_t libscsi_action_get_timeout(const libscsi_action_t *);
137 extern uint_t libscsi_action_get_flags(const libscsi_action_t *);
138 extern uint8_t *libscsi_action_get_cdb(const libscsi_action_t *);
139 extern int libscsi_action_get_buffer(const libscsi_action_t *,
140     uint8_t **, size_t *, size_t *);
141 extern int libscsi_action_get_sense(const libscsi_action_t *,
142     uint8_t **, size_t *, size_t *);
143 extern int libscsi_action_parse_sense(const libscsi_action_t *, uint64_t *,
144     uint64_t *, uint64_t *, diskaddr_t *);
145 extern void libscsi_action_set_status(libscsi_action_t *, sam4_status_t);
146 extern int libscsi_action_set_datalen(libscsi_action_t *, size_t);
147 extern int libscsi_action_set_senselen(libscsi_action_t *, size_t);
148 extern int libscsi_exec(libscsi_action_t *, libscsi_target_t *);
149 extern void libscsi_action_free(libscsi_action_t *);
150 
151 extern const char *libscsi_sense_key_name(uint64_t);
152 extern const char *libscsi_sense_code_name(uint64_t, uint64_t);
153 
154 /*
155  * Interfaces for engine providers
156  */
157 extern void *libscsi_alloc(libscsi_hdl_t *, size_t);
158 extern void *libscsi_zalloc(libscsi_hdl_t *, size_t);
159 extern char *libscsi_strdup(libscsi_hdl_t *, const char *);
160 extern void libscsi_free(libscsi_hdl_t *, void *);
161 extern libscsi_status_t *libscsi_status_alloc(libscsi_hdl_t *, size_t);
162 extern int libscsi_status_fill(libscsi_hdl_t *, libscsi_status_t *,
163     uint16_t, size_t);
164 extern void libscsi_status_free(libscsi_hdl_t *, libscsi_status_t *);
165 
166 extern int libscsi_set_errno(libscsi_hdl_t *, libscsi_errno_t);
167 extern int libscsi_verror(libscsi_hdl_t *, libscsi_errno_t, const char *,
168     va_list);
169 extern int libscsi_error(libscsi_hdl_t *, libscsi_errno_t, const char *, ...);
170 
171 typedef const libscsi_engine_t *(*libscsi_engine_init_f)(libscsi_hdl_t *);
172 
173 /*
174  * Generic SCSI utility functions.
175  */
176 extern size_t libscsi_cmd_cdblen(libscsi_hdl_t *, uint8_t);
177 
178 #ifdef	__cplusplus
179 }
180 #endif
181 
182 #endif	/* _LIBSCSI_H */
183