]>
Commit | Line | Data |
---|---|---|
de258bf5 BH |
1 | /* |
2 | * osd_initiator.h - OSD initiator API definition | |
3 | * | |
4 | * Copyright (C) 2008 Panasas Inc. All rights reserved. | |
5 | * | |
6 | * Authors: | |
7 | * Boaz Harrosh <bharrosh@panasas.com> | |
8 | * Benny Halevy <bhalevy@panasas.com> | |
9 | * | |
10 | * This program is free software; you can redistribute it and/or modify | |
11 | * it under the terms of the GNU General Public License version 2 | |
12 | * | |
13 | */ | |
14 | #ifndef __OSD_INITIATOR_H__ | |
15 | #define __OSD_INITIATOR_H__ | |
16 | ||
17 | #include "osd_protocol.h" | |
18 | #include "osd_types.h" | |
19 | ||
20 | #include <linux/blkdev.h> | |
fc2fac5b | 21 | #include <scsi/scsi_device.h> |
de258bf5 BH |
22 | |
23 | /* Note: "NI" in comments below means "Not Implemented yet" */ | |
24 | ||
c6572c98 BH |
25 | /* Configure of code: |
26 | * #undef if you *don't* want OSD v1 support in runtime. | |
27 | * If #defined the initiator will dynamically configure to encode OSD v1 | |
28 | * CDB's if the target is detected to be OSD v1 only. | |
29 | * OSD v2 only commands, options, and attributes will be ignored if target | |
30 | * is v1 only. | |
31 | * If #defined will result in bigger/slower code (OK Slower maybe not) | |
32 | * Q: Should this be CONFIG_SCSI_OSD_VER1_SUPPORT and set from Kconfig? | |
33 | */ | |
34 | #define OSD_VER1_SUPPORT y | |
35 | ||
36 | enum osd_std_version { | |
37 | OSD_VER_NONE = 0, | |
38 | OSD_VER1 = 1, | |
39 | OSD_VER2 = 2, | |
40 | }; | |
41 | ||
de258bf5 BH |
42 | /* |
43 | * Object-based Storage Device. | |
44 | * This object represents an OSD device. | |
45 | * It is not a full linux device in any way. It is only | |
46 | * a place to hang resources associated with a Linux | |
47 | * request Q and some default properties. | |
48 | */ | |
49 | struct osd_dev { | |
50 | struct scsi_device *scsi_device; | |
51 | unsigned def_timeout; | |
c6572c98 BH |
52 | |
53 | #ifdef OSD_VER1_SUPPORT | |
54 | enum osd_std_version version; | |
55 | #endif | |
de258bf5 BH |
56 | }; |
57 | ||
2cdd6410 BH |
58 | /* Unique Identification of an OSD device */ |
59 | struct osd_dev_info { | |
60 | unsigned systemid_len; | |
61 | u8 systemid[OSD_SYSTEMID_LEN]; | |
62 | unsigned osdname_len; | |
63 | u8 *osdname; | |
64 | }; | |
65 | ||
66 | /* Retrieve/return osd_dev(s) for use by Kernel clients | |
67 | * Use IS_ERR/ERR_PTR on returned "osd_dev *". | |
68 | */ | |
69 | struct osd_dev *osduld_path_lookup(const char *dev_name); | |
70 | struct osd_dev *osduld_info_lookup(const struct osd_dev_info *odi); | |
b799bc7d BH |
71 | void osduld_put_device(struct osd_dev *od); |
72 | ||
2cdd6410 BH |
73 | const struct osd_dev_info *osduld_device_info(struct osd_dev *od); |
74 | bool osduld_device_same(struct osd_dev *od, const struct osd_dev_info *odi); | |
75 | ||
95b05a7d BH |
76 | /* Add/remove test ioctls from external modules */ |
77 | typedef int (do_test_fn)(struct osd_dev *od, unsigned cmd, unsigned long arg); | |
78 | int osduld_register_test(unsigned ioctl, do_test_fn *do_test); | |
79 | void osduld_unregister_test(unsigned ioctl); | |
80 | ||
81 | /* These are called by uld at probe time */ | |
de258bf5 BH |
82 | void osd_dev_init(struct osd_dev *od, struct scsi_device *scsi_device); |
83 | void osd_dev_fini(struct osd_dev *od); | |
84 | ||
2cdd6410 BH |
85 | /** |
86 | * osd_auto_detect_ver - Detect the OSD version, return Unique Identification | |
87 | * | |
88 | * @od: OSD target lun handle | |
89 | * @caps: Capabilities authorizing OSD root read attributes access | |
90 | * @odi: Retrieved information uniquely identifying the osd target lun | |
91 | * Note: odi->osdname must be kfreed by caller. | |
92 | * | |
93 | * Auto detects the OSD version of the OSD target and sets the @od | |
94 | * accordingly. Meanwhile also returns the "system id" and "osd name" root | |
95 | * attributes which uniquely identify the OSD target. This member is usually | |
96 | * called by the ULD. ULD users should call osduld_device_info(). | |
97 | * This rutine allocates osd requests and memory at GFP_KERNEL level and might | |
98 | * sleep. | |
99 | */ | |
100 | int osd_auto_detect_ver(struct osd_dev *od, | |
101 | void *caps, struct osd_dev_info *odi); | |
102 | ||
fc2fac5b BH |
103 | static inline struct request_queue *osd_request_queue(struct osd_dev *od) |
104 | { | |
105 | return od->scsi_device->request_queue; | |
106 | } | |
1b9dce94 | 107 | |
c6572c98 BH |
108 | /* we might want to use function vector in the future */ |
109 | static inline void osd_dev_set_ver(struct osd_dev *od, enum osd_std_version v) | |
110 | { | |
111 | #ifdef OSD_VER1_SUPPORT | |
112 | od->version = v; | |
113 | #endif | |
114 | } | |
115 | ||
d531b379 BH |
116 | static inline bool osd_dev_is_ver1(struct osd_dev *od) |
117 | { | |
118 | #ifdef OSD_VER1_SUPPORT | |
119 | return od->version == OSD_VER1; | |
120 | #else | |
121 | return false; | |
122 | #endif | |
123 | } | |
124 | ||
de258bf5 BH |
125 | struct osd_request; |
126 | typedef void (osd_req_done_fn)(struct osd_request *or, void *private); | |
127 | ||
128 | struct osd_request { | |
129 | struct osd_cdb cdb; | |
130 | struct osd_data_out_integrity_info out_data_integ; | |
131 | struct osd_data_in_integrity_info in_data_integ; | |
132 | ||
133 | struct osd_dev *osd_dev; | |
134 | struct request *request; | |
135 | ||
136 | struct _osd_req_data_segment { | |
137 | void *buff; | |
138 | unsigned alloc_size; /* 0 here means: don't call kfree */ | |
139 | unsigned total_bytes; | |
140 | } set_attr, enc_get_attr, get_attr; | |
141 | ||
142 | struct _osd_io_info { | |
143 | struct bio *bio; | |
144 | u64 total_bytes; | |
145 | struct request *req; | |
146 | struct _osd_req_data_segment *last_seg; | |
147 | u8 *pad_buff; | |
148 | } out, in; | |
149 | ||
150 | gfp_t alloc_flags; | |
151 | unsigned timeout; | |
152 | unsigned retries; | |
153 | u8 sense[OSD_MAX_SENSE_LEN]; | |
154 | enum osd_attributes_mode attributes_mode; | |
155 | ||
156 | osd_req_done_fn *async_done; | |
157 | void *async_private; | |
158 | int async_error; | |
159 | }; | |
160 | ||
c6572c98 BH |
161 | static inline bool osd_req_is_ver1(struct osd_request *or) |
162 | { | |
d531b379 | 163 | return osd_dev_is_ver1(or->osd_dev); |
c6572c98 BH |
164 | } |
165 | ||
de258bf5 BH |
166 | /* |
167 | * How to use the osd library: | |
168 | * | |
169 | * osd_start_request | |
170 | * Allocates a request. | |
171 | * | |
172 | * osd_req_* | |
173 | * Call one of, to encode the desired operation. | |
174 | * | |
175 | * osd_add_{get,set}_attr | |
176 | * Optionally add attributes to the CDB, list or page mode. | |
177 | * | |
178 | * osd_finalize_request | |
179 | * Computes final data out/in offsets and signs the request, | |
180 | * making it ready for execution. | |
181 | * | |
182 | * osd_execute_request | |
183 | * May be called to execute it through the block layer. Other wise submit | |
184 | * the associated block request in some other way. | |
185 | * | |
186 | * After execution: | |
187 | * osd_req_decode_sense | |
188 | * Decodes sense information to verify execution results. | |
189 | * | |
190 | * osd_req_decode_get_attr | |
191 | * Retrieve osd_add_get_attr_list() values if used. | |
192 | * | |
193 | * osd_end_request | |
194 | * Must be called to deallocate the request. | |
195 | */ | |
196 | ||
197 | /** | |
198 | * osd_start_request - Allocate and initialize an osd_request | |
199 | * | |
200 | * @osd_dev: OSD device that holds the scsi-device and default values | |
201 | * that the request is associated with. | |
202 | * @gfp: The allocation flags to use for request allocation, and all | |
203 | * subsequent allocations. This will be stored at | |
204 | * osd_request->alloc_flags, can be changed by user later | |
205 | * | |
206 | * Allocate osd_request and initialize all members to the | |
207 | * default/initial state. | |
208 | */ | |
209 | struct osd_request *osd_start_request(struct osd_dev *od, gfp_t gfp); | |
210 | ||
211 | enum osd_req_options { | |
212 | OSD_REQ_FUA = 0x08, /* Force Unit Access */ | |
213 | OSD_REQ_DPO = 0x10, /* Disable Page Out */ | |
214 | ||
215 | OSD_REQ_BYPASS_TIMESTAMPS = 0x80, | |
216 | }; | |
217 | ||
218 | /** | |
219 | * osd_finalize_request - Sign request and prepare request for execution | |
220 | * | |
221 | * @or: osd_request to prepare | |
222 | * @options: combination of osd_req_options bit flags or 0. | |
223 | * @cap: A Pointer to an OSD_CAP_LEN bytes buffer that is received from | |
224 | * The security manager as capabilities for this cdb. | |
225 | * @cap_key: The cryptographic key used to sign the cdb/data. Can be null | |
226 | * if NOSEC is used. | |
227 | * | |
228 | * The actual request and bios are only allocated here, so are the get_attr | |
229 | * buffers that will receive the returned attributes. Copy's @cap to cdb. | |
230 | * Sign the cdb/data with @cap_key. | |
231 | */ | |
232 | int osd_finalize_request(struct osd_request *or, | |
233 | u8 options, const void *cap, const u8 *cap_key); | |
234 | ||
235 | /** | |
236 | * osd_execute_request - Execute the request synchronously through block-layer | |
237 | * | |
238 | * @or: osd_request to Executed | |
239 | * | |
240 | * Calls blk_execute_rq to q the command and waits for completion. | |
241 | */ | |
242 | int osd_execute_request(struct osd_request *or); | |
243 | ||
244 | /** | |
245 | * osd_execute_request_async - Execute the request without waitting. | |
246 | * | |
247 | * @or: - osd_request to Executed | |
248 | * @done: (Optional) - Called at end of execution | |
249 | * @private: - Will be passed to @done function | |
250 | * | |
251 | * Calls blk_execute_rq_nowait to queue the command. When execution is done | |
252 | * optionally calls @done with @private as parameter. @or->async_error will | |
253 | * have the return code | |
254 | */ | |
255 | int osd_execute_request_async(struct osd_request *or, | |
256 | osd_req_done_fn *done, void *private); | |
257 | ||
98f3aea2 BH |
258 | /** |
259 | * osd_req_decode_sense_full - Decode sense information after execution. | |
260 | * | |
261 | * @or: - osd_request to examine | |
262 | * @osi - Recievs a more detailed error report information (optional). | |
263 | * @silent - Do not print to dmsg (Even if enabled) | |
264 | * @bad_obj_list - Some commands act on multiple objects. Failed objects will | |
265 | * be recieved here (optional) | |
266 | * @max_obj - Size of @bad_obj_list. | |
267 | * @bad_attr_list - List of failing attributes (optional) | |
268 | * @max_attr - Size of @bad_attr_list. | |
269 | * | |
aa9fffbe | 270 | * After execution, osd_request results are analyzed using this function. The |
98f3aea2 BH |
271 | * return code is the final disposition on the error. So it is possible that a |
272 | * CHECK_CONDITION was returned from target but this will return NO_ERROR, for | |
273 | * example on recovered errors. All parameters are optional if caller does | |
274 | * not need any returned information. | |
275 | * Note: This function will also dump the error to dmsg according to settings | |
276 | * of the SCSI_OSD_DPRINT_SENSE Kconfig value. Set @silent if you know the | |
277 | * command would routinely fail, to not spam the dmsg file. | |
278 | */ | |
aa9fffbe BH |
279 | |
280 | /** | |
281 | * osd_err_priority - osd categorized return codes in ascending severity. | |
282 | * | |
283 | * The categories are borrowed from the pnfs_osd_errno enum. | |
284 | * See comments for translated Linux codes returned by osd_req_decode_sense. | |
285 | */ | |
286 | enum osd_err_priority { | |
287 | OSD_ERR_PRI_NO_ERROR = 0, | |
288 | /* Recoverable, caller should clear_highpage() all pages */ | |
289 | OSD_ERR_PRI_CLEAR_PAGES = 1, /* -EFAULT */ | |
290 | OSD_ERR_PRI_RESOURCE = 2, /* -ENOMEM */ | |
291 | OSD_ERR_PRI_BAD_CRED = 3, /* -EINVAL */ | |
292 | OSD_ERR_PRI_NO_ACCESS = 4, /* -EACCES */ | |
293 | OSD_ERR_PRI_UNREACHABLE = 5, /* any other */ | |
294 | OSD_ERR_PRI_NOT_FOUND = 6, /* -ENOENT */ | |
295 | OSD_ERR_PRI_NO_SPACE = 7, /* -ENOSPC */ | |
296 | OSD_ERR_PRI_EIO = 8, /* -EIO */ | |
297 | }; | |
298 | ||
98f3aea2 | 299 | struct osd_sense_info { |
aa9fffbe BH |
300 | u64 out_resid; /* Zero on success otherwise out residual */ |
301 | u64 in_resid; /* Zero on success otherwise in residual */ | |
302 | enum osd_err_priority osd_err_pri; | |
303 | ||
98f3aea2 BH |
304 | int key; /* one of enum scsi_sense_keys */ |
305 | int additional_code ; /* enum osd_additional_sense_codes */ | |
306 | union { /* Sense specific information */ | |
307 | u16 sense_info; | |
308 | u16 cdb_field_offset; /* scsi_invalid_field_in_cdb */ | |
309 | }; | |
310 | union { /* Command specific information */ | |
311 | u64 command_info; | |
312 | }; | |
313 | ||
314 | u32 not_initiated_command_functions; /* osd_command_functions_bits */ | |
315 | u32 completed_command_functions; /* osd_command_functions_bits */ | |
316 | struct osd_obj_id obj; | |
317 | struct osd_attr attr; | |
318 | }; | |
319 | ||
320 | int osd_req_decode_sense_full(struct osd_request *or, | |
321 | struct osd_sense_info *osi, bool silent, | |
322 | struct osd_obj_id *bad_obj_list, int max_obj, | |
323 | struct osd_attr *bad_attr_list, int max_attr); | |
324 | ||
325 | static inline int osd_req_decode_sense(struct osd_request *or, | |
326 | struct osd_sense_info *osi) | |
327 | { | |
328 | return osd_req_decode_sense_full(or, osi, false, NULL, 0, NULL, 0); | |
329 | } | |
330 | ||
de258bf5 BH |
331 | /** |
332 | * osd_end_request - return osd_request to free store | |
333 | * | |
334 | * @or: osd_request to free | |
335 | * | |
336 | * Deallocate all osd_request resources (struct req's, BIOs, buffers, etc.) | |
337 | */ | |
338 | void osd_end_request(struct osd_request *or); | |
339 | ||
340 | /* | |
341 | * CDB Encoding | |
342 | * | |
343 | * Note: call only one of the following methods. | |
344 | */ | |
345 | ||
346 | /* | |
347 | * Device commands | |
348 | */ | |
349 | void osd_req_set_master_seed_xchg(struct osd_request *or, ...);/* NI */ | |
350 | void osd_req_set_master_key(struct osd_request *or, ...);/* NI */ | |
351 | ||
352 | void osd_req_format(struct osd_request *or, u64 tot_capacity); | |
353 | ||
354 | /* list all partitions | |
355 | * @list header must be initialized to zero on first run. | |
356 | * | |
357 | * Call osd_is_obj_list_done() to find if we got the complete list. | |
358 | */ | |
359 | int osd_req_list_dev_partitions(struct osd_request *or, | |
360 | osd_id initial_id, struct osd_obj_id_list *list, unsigned nelem); | |
361 | ||
362 | void osd_req_flush_obsd(struct osd_request *or, | |
363 | enum osd_options_flush_scope_values); | |
364 | ||
365 | void osd_req_perform_scsi_command(struct osd_request *or, | |
366 | const u8 *cdb, ...);/* NI */ | |
367 | void osd_req_task_management(struct osd_request *or, ...);/* NI */ | |
368 | ||
369 | /* | |
370 | * Partition commands | |
371 | */ | |
372 | void osd_req_create_partition(struct osd_request *or, osd_id partition); | |
373 | void osd_req_remove_partition(struct osd_request *or, osd_id partition); | |
374 | ||
375 | void osd_req_set_partition_key(struct osd_request *or, | |
376 | osd_id partition, u8 new_key_id[OSD_CRYPTO_KEYID_SIZE], | |
377 | u8 seed[OSD_CRYPTO_SEED_SIZE]);/* NI */ | |
378 | ||
379 | /* list all collections in the partition | |
380 | * @list header must be init to zero on first run. | |
381 | * | |
382 | * Call osd_is_obj_list_done() to find if we got the complete list. | |
383 | */ | |
384 | int osd_req_list_partition_collections(struct osd_request *or, | |
385 | osd_id partition, osd_id initial_id, struct osd_obj_id_list *list, | |
386 | unsigned nelem); | |
387 | ||
388 | /* list all objects in the partition | |
389 | * @list header must be init to zero on first run. | |
390 | * | |
391 | * Call osd_is_obj_list_done() to find if we got the complete list. | |
392 | */ | |
393 | int osd_req_list_partition_objects(struct osd_request *or, | |
394 | osd_id partition, osd_id initial_id, struct osd_obj_id_list *list, | |
395 | unsigned nelem); | |
396 | ||
397 | void osd_req_flush_partition(struct osd_request *or, | |
398 | osd_id partition, enum osd_options_flush_scope_values); | |
399 | ||
400 | /* | |
401 | * Collection commands | |
402 | */ | |
403 | void osd_req_create_collection(struct osd_request *or, | |
404 | const struct osd_obj_id *);/* NI */ | |
405 | void osd_req_remove_collection(struct osd_request *or, | |
406 | const struct osd_obj_id *);/* NI */ | |
407 | ||
408 | /* list all objects in the collection */ | |
409 | int osd_req_list_collection_objects(struct osd_request *or, | |
410 | const struct osd_obj_id *, osd_id initial_id, | |
411 | struct osd_obj_id_list *list, unsigned nelem); | |
412 | ||
413 | /* V2 only filtered list of objects in the collection */ | |
414 | void osd_req_query(struct osd_request *or, ...);/* NI */ | |
415 | ||
416 | void osd_req_flush_collection(struct osd_request *or, | |
417 | const struct osd_obj_id *, enum osd_options_flush_scope_values); | |
418 | ||
419 | void osd_req_get_member_attrs(struct osd_request *or, ...);/* V2-only NI */ | |
420 | void osd_req_set_member_attrs(struct osd_request *or, ...);/* V2-only NI */ | |
421 | ||
422 | /* | |
423 | * Object commands | |
424 | */ | |
425 | void osd_req_create_object(struct osd_request *or, struct osd_obj_id *); | |
426 | void osd_req_remove_object(struct osd_request *or, struct osd_obj_id *); | |
427 | ||
428 | void osd_req_write(struct osd_request *or, | |
62f469b5 | 429 | const struct osd_obj_id *obj, u64 offset, struct bio *bio, u64 len); |
0e35afbc BH |
430 | int osd_req_write_kern(struct osd_request *or, |
431 | const struct osd_obj_id *obj, u64 offset, void *buff, u64 len); | |
de258bf5 BH |
432 | void osd_req_append(struct osd_request *or, |
433 | const struct osd_obj_id *, struct bio *data_out);/* NI */ | |
434 | void osd_req_create_write(struct osd_request *or, | |
435 | const struct osd_obj_id *, struct bio *data_out, u64 offset);/* NI */ | |
436 | void osd_req_clear(struct osd_request *or, | |
437 | const struct osd_obj_id *, u64 offset, u64 len);/* NI */ | |
438 | void osd_req_punch(struct osd_request *or, | |
439 | const struct osd_obj_id *, u64 offset, u64 len);/* V2-only NI */ | |
440 | ||
441 | void osd_req_flush_object(struct osd_request *or, | |
442 | const struct osd_obj_id *, enum osd_options_flush_scope_values, | |
443 | /*V2*/ u64 offset, /*V2*/ u64 len); | |
444 | ||
445 | void osd_req_read(struct osd_request *or, | |
62f469b5 | 446 | const struct osd_obj_id *obj, u64 offset, struct bio *bio, u64 len); |
0e35afbc BH |
447 | int osd_req_read_kern(struct osd_request *or, |
448 | const struct osd_obj_id *obj, u64 offset, void *buff, u64 len); | |
de258bf5 BH |
449 | |
450 | /* | |
451 | * Root/Partition/Collection/Object Attributes commands | |
452 | */ | |
453 | ||
454 | /* get before set */ | |
455 | void osd_req_get_attributes(struct osd_request *or, const struct osd_obj_id *); | |
456 | ||
457 | /* set before get */ | |
458 | void osd_req_set_attributes(struct osd_request *or, const struct osd_obj_id *); | |
459 | ||
460 | /* | |
461 | * Attributes appended to most commands | |
462 | */ | |
463 | ||
464 | /* Attributes List mode (or V2 CDB) */ | |
465 | /* | |
466 | * TODO: In ver2 if at finalize time only one attr was set and no gets, | |
467 | * then the Attributes CDB mode is used automatically to save IO. | |
468 | */ | |
469 | ||
470 | /* set a list of attributes. */ | |
471 | int osd_req_add_set_attr_list(struct osd_request *or, | |
472 | const struct osd_attr *, unsigned nelem); | |
473 | ||
474 | /* get a list of attributes */ | |
475 | int osd_req_add_get_attr_list(struct osd_request *or, | |
476 | const struct osd_attr *, unsigned nelem); | |
477 | ||
478 | /* | |
479 | * Attributes list decoding | |
480 | * Must be called after osd_request.request was executed | |
481 | * It is called in a loop to decode the returned get_attr | |
482 | * (see osd_add_get_attr) | |
483 | */ | |
484 | int osd_req_decode_get_attr_list(struct osd_request *or, | |
485 | struct osd_attr *, int *nelem, void **iterator); | |
486 | ||
487 | /* Attributes Page mode */ | |
488 | ||
489 | /* | |
490 | * Read an attribute page and optionally set one attribute | |
491 | * | |
492 | * Retrieves the attribute page directly to a user buffer. | |
493 | * @attr_page_data shall stay valid until end of execution. | |
494 | * See osd_attributes.h for common page structures | |
495 | */ | |
496 | int osd_req_add_get_attr_page(struct osd_request *or, | |
497 | u32 page_id, void *attr_page_data, unsigned max_page_len, | |
498 | const struct osd_attr *set_one); | |
499 | ||
500 | #endif /* __OSD_LIB_H__ */ |