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> | |
21 | ||
22 | /* Note: "NI" in comments below means "Not Implemented yet" */ | |
23 | ||
24 | /* | |
25 | * Object-based Storage Device. | |
26 | * This object represents an OSD device. | |
27 | * It is not a full linux device in any way. It is only | |
28 | * a place to hang resources associated with a Linux | |
29 | * request Q and some default properties. | |
30 | */ | |
31 | struct osd_dev { | |
32 | struct scsi_device *scsi_device; | |
33 | unsigned def_timeout; | |
34 | }; | |
35 | ||
b799bc7d BH |
36 | /* Retrieve/return osd_dev(s) for use by Kernel clients */ |
37 | struct osd_dev *osduld_path_lookup(const char *dev_name); /*Use IS_ERR/ERR_PTR*/ | |
38 | void osduld_put_device(struct osd_dev *od); | |
39 | ||
95b05a7d BH |
40 | /* Add/remove test ioctls from external modules */ |
41 | typedef int (do_test_fn)(struct osd_dev *od, unsigned cmd, unsigned long arg); | |
42 | int osduld_register_test(unsigned ioctl, do_test_fn *do_test); | |
43 | void osduld_unregister_test(unsigned ioctl); | |
44 | ||
45 | /* These are called by uld at probe time */ | |
de258bf5 BH |
46 | void osd_dev_init(struct osd_dev *od, struct scsi_device *scsi_device); |
47 | void osd_dev_fini(struct osd_dev *od); | |
48 | ||
49 | struct osd_request; | |
50 | typedef void (osd_req_done_fn)(struct osd_request *or, void *private); | |
51 | ||
52 | struct osd_request { | |
53 | struct osd_cdb cdb; | |
54 | struct osd_data_out_integrity_info out_data_integ; | |
55 | struct osd_data_in_integrity_info in_data_integ; | |
56 | ||
57 | struct osd_dev *osd_dev; | |
58 | struct request *request; | |
59 | ||
60 | struct _osd_req_data_segment { | |
61 | void *buff; | |
62 | unsigned alloc_size; /* 0 here means: don't call kfree */ | |
63 | unsigned total_bytes; | |
64 | } set_attr, enc_get_attr, get_attr; | |
65 | ||
66 | struct _osd_io_info { | |
67 | struct bio *bio; | |
68 | u64 total_bytes; | |
69 | struct request *req; | |
70 | struct _osd_req_data_segment *last_seg; | |
71 | u8 *pad_buff; | |
72 | } out, in; | |
73 | ||
74 | gfp_t alloc_flags; | |
75 | unsigned timeout; | |
76 | unsigned retries; | |
77 | u8 sense[OSD_MAX_SENSE_LEN]; | |
78 | enum osd_attributes_mode attributes_mode; | |
79 | ||
80 | osd_req_done_fn *async_done; | |
81 | void *async_private; | |
82 | int async_error; | |
83 | }; | |
84 | ||
85 | /* | |
86 | * How to use the osd library: | |
87 | * | |
88 | * osd_start_request | |
89 | * Allocates a request. | |
90 | * | |
91 | * osd_req_* | |
92 | * Call one of, to encode the desired operation. | |
93 | * | |
94 | * osd_add_{get,set}_attr | |
95 | * Optionally add attributes to the CDB, list or page mode. | |
96 | * | |
97 | * osd_finalize_request | |
98 | * Computes final data out/in offsets and signs the request, | |
99 | * making it ready for execution. | |
100 | * | |
101 | * osd_execute_request | |
102 | * May be called to execute it through the block layer. Other wise submit | |
103 | * the associated block request in some other way. | |
104 | * | |
105 | * After execution: | |
106 | * osd_req_decode_sense | |
107 | * Decodes sense information to verify execution results. | |
108 | * | |
109 | * osd_req_decode_get_attr | |
110 | * Retrieve osd_add_get_attr_list() values if used. | |
111 | * | |
112 | * osd_end_request | |
113 | * Must be called to deallocate the request. | |
114 | */ | |
115 | ||
116 | /** | |
117 | * osd_start_request - Allocate and initialize an osd_request | |
118 | * | |
119 | * @osd_dev: OSD device that holds the scsi-device and default values | |
120 | * that the request is associated with. | |
121 | * @gfp: The allocation flags to use for request allocation, and all | |
122 | * subsequent allocations. This will be stored at | |
123 | * osd_request->alloc_flags, can be changed by user later | |
124 | * | |
125 | * Allocate osd_request and initialize all members to the | |
126 | * default/initial state. | |
127 | */ | |
128 | struct osd_request *osd_start_request(struct osd_dev *od, gfp_t gfp); | |
129 | ||
130 | enum osd_req_options { | |
131 | OSD_REQ_FUA = 0x08, /* Force Unit Access */ | |
132 | OSD_REQ_DPO = 0x10, /* Disable Page Out */ | |
133 | ||
134 | OSD_REQ_BYPASS_TIMESTAMPS = 0x80, | |
135 | }; | |
136 | ||
137 | /** | |
138 | * osd_finalize_request - Sign request and prepare request for execution | |
139 | * | |
140 | * @or: osd_request to prepare | |
141 | * @options: combination of osd_req_options bit flags or 0. | |
142 | * @cap: A Pointer to an OSD_CAP_LEN bytes buffer that is received from | |
143 | * The security manager as capabilities for this cdb. | |
144 | * @cap_key: The cryptographic key used to sign the cdb/data. Can be null | |
145 | * if NOSEC is used. | |
146 | * | |
147 | * The actual request and bios are only allocated here, so are the get_attr | |
148 | * buffers that will receive the returned attributes. Copy's @cap to cdb. | |
149 | * Sign the cdb/data with @cap_key. | |
150 | */ | |
151 | int osd_finalize_request(struct osd_request *or, | |
152 | u8 options, const void *cap, const u8 *cap_key); | |
153 | ||
154 | /** | |
155 | * osd_execute_request - Execute the request synchronously through block-layer | |
156 | * | |
157 | * @or: osd_request to Executed | |
158 | * | |
159 | * Calls blk_execute_rq to q the command and waits for completion. | |
160 | */ | |
161 | int osd_execute_request(struct osd_request *or); | |
162 | ||
163 | /** | |
164 | * osd_execute_request_async - Execute the request without waitting. | |
165 | * | |
166 | * @or: - osd_request to Executed | |
167 | * @done: (Optional) - Called at end of execution | |
168 | * @private: - Will be passed to @done function | |
169 | * | |
170 | * Calls blk_execute_rq_nowait to queue the command. When execution is done | |
171 | * optionally calls @done with @private as parameter. @or->async_error will | |
172 | * have the return code | |
173 | */ | |
174 | int osd_execute_request_async(struct osd_request *or, | |
175 | osd_req_done_fn *done, void *private); | |
176 | ||
177 | /** | |
178 | * osd_end_request - return osd_request to free store | |
179 | * | |
180 | * @or: osd_request to free | |
181 | * | |
182 | * Deallocate all osd_request resources (struct req's, BIOs, buffers, etc.) | |
183 | */ | |
184 | void osd_end_request(struct osd_request *or); | |
185 | ||
186 | /* | |
187 | * CDB Encoding | |
188 | * | |
189 | * Note: call only one of the following methods. | |
190 | */ | |
191 | ||
192 | /* | |
193 | * Device commands | |
194 | */ | |
195 | void osd_req_set_master_seed_xchg(struct osd_request *or, ...);/* NI */ | |
196 | void osd_req_set_master_key(struct osd_request *or, ...);/* NI */ | |
197 | ||
198 | void osd_req_format(struct osd_request *or, u64 tot_capacity); | |
199 | ||
200 | /* list all partitions | |
201 | * @list header must be initialized to zero on first run. | |
202 | * | |
203 | * Call osd_is_obj_list_done() to find if we got the complete list. | |
204 | */ | |
205 | int osd_req_list_dev_partitions(struct osd_request *or, | |
206 | osd_id initial_id, struct osd_obj_id_list *list, unsigned nelem); | |
207 | ||
208 | void osd_req_flush_obsd(struct osd_request *or, | |
209 | enum osd_options_flush_scope_values); | |
210 | ||
211 | void osd_req_perform_scsi_command(struct osd_request *or, | |
212 | const u8 *cdb, ...);/* NI */ | |
213 | void osd_req_task_management(struct osd_request *or, ...);/* NI */ | |
214 | ||
215 | /* | |
216 | * Partition commands | |
217 | */ | |
218 | void osd_req_create_partition(struct osd_request *or, osd_id partition); | |
219 | void osd_req_remove_partition(struct osd_request *or, osd_id partition); | |
220 | ||
221 | void osd_req_set_partition_key(struct osd_request *or, | |
222 | osd_id partition, u8 new_key_id[OSD_CRYPTO_KEYID_SIZE], | |
223 | u8 seed[OSD_CRYPTO_SEED_SIZE]);/* NI */ | |
224 | ||
225 | /* list all collections in the partition | |
226 | * @list header must be init to zero on first run. | |
227 | * | |
228 | * Call osd_is_obj_list_done() to find if we got the complete list. | |
229 | */ | |
230 | int osd_req_list_partition_collections(struct osd_request *or, | |
231 | osd_id partition, osd_id initial_id, struct osd_obj_id_list *list, | |
232 | unsigned nelem); | |
233 | ||
234 | /* list all objects in the partition | |
235 | * @list header must be init to zero on first run. | |
236 | * | |
237 | * Call osd_is_obj_list_done() to find if we got the complete list. | |
238 | */ | |
239 | int osd_req_list_partition_objects(struct osd_request *or, | |
240 | osd_id partition, osd_id initial_id, struct osd_obj_id_list *list, | |
241 | unsigned nelem); | |
242 | ||
243 | void osd_req_flush_partition(struct osd_request *or, | |
244 | osd_id partition, enum osd_options_flush_scope_values); | |
245 | ||
246 | /* | |
247 | * Collection commands | |
248 | */ | |
249 | void osd_req_create_collection(struct osd_request *or, | |
250 | const struct osd_obj_id *);/* NI */ | |
251 | void osd_req_remove_collection(struct osd_request *or, | |
252 | const struct osd_obj_id *);/* NI */ | |
253 | ||
254 | /* list all objects in the collection */ | |
255 | int osd_req_list_collection_objects(struct osd_request *or, | |
256 | const struct osd_obj_id *, osd_id initial_id, | |
257 | struct osd_obj_id_list *list, unsigned nelem); | |
258 | ||
259 | /* V2 only filtered list of objects in the collection */ | |
260 | void osd_req_query(struct osd_request *or, ...);/* NI */ | |
261 | ||
262 | void osd_req_flush_collection(struct osd_request *or, | |
263 | const struct osd_obj_id *, enum osd_options_flush_scope_values); | |
264 | ||
265 | void osd_req_get_member_attrs(struct osd_request *or, ...);/* V2-only NI */ | |
266 | void osd_req_set_member_attrs(struct osd_request *or, ...);/* V2-only NI */ | |
267 | ||
268 | /* | |
269 | * Object commands | |
270 | */ | |
271 | void osd_req_create_object(struct osd_request *or, struct osd_obj_id *); | |
272 | void osd_req_remove_object(struct osd_request *or, struct osd_obj_id *); | |
273 | ||
274 | void osd_req_write(struct osd_request *or, | |
275 | const struct osd_obj_id *, struct bio *data_out, u64 offset); | |
276 | void osd_req_append(struct osd_request *or, | |
277 | const struct osd_obj_id *, struct bio *data_out);/* NI */ | |
278 | void osd_req_create_write(struct osd_request *or, | |
279 | const struct osd_obj_id *, struct bio *data_out, u64 offset);/* NI */ | |
280 | void osd_req_clear(struct osd_request *or, | |
281 | const struct osd_obj_id *, u64 offset, u64 len);/* NI */ | |
282 | void osd_req_punch(struct osd_request *or, | |
283 | const struct osd_obj_id *, u64 offset, u64 len);/* V2-only NI */ | |
284 | ||
285 | void osd_req_flush_object(struct osd_request *or, | |
286 | const struct osd_obj_id *, enum osd_options_flush_scope_values, | |
287 | /*V2*/ u64 offset, /*V2*/ u64 len); | |
288 | ||
289 | void osd_req_read(struct osd_request *or, | |
290 | const struct osd_obj_id *, struct bio *data_in, u64 offset); | |
291 | ||
292 | /* | |
293 | * Root/Partition/Collection/Object Attributes commands | |
294 | */ | |
295 | ||
296 | /* get before set */ | |
297 | void osd_req_get_attributes(struct osd_request *or, const struct osd_obj_id *); | |
298 | ||
299 | /* set before get */ | |
300 | void osd_req_set_attributes(struct osd_request *or, const struct osd_obj_id *); | |
301 | ||
302 | /* | |
303 | * Attributes appended to most commands | |
304 | */ | |
305 | ||
306 | /* Attributes List mode (or V2 CDB) */ | |
307 | /* | |
308 | * TODO: In ver2 if at finalize time only one attr was set and no gets, | |
309 | * then the Attributes CDB mode is used automatically to save IO. | |
310 | */ | |
311 | ||
312 | /* set a list of attributes. */ | |
313 | int osd_req_add_set_attr_list(struct osd_request *or, | |
314 | const struct osd_attr *, unsigned nelem); | |
315 | ||
316 | /* get a list of attributes */ | |
317 | int osd_req_add_get_attr_list(struct osd_request *or, | |
318 | const struct osd_attr *, unsigned nelem); | |
319 | ||
320 | /* | |
321 | * Attributes list decoding | |
322 | * Must be called after osd_request.request was executed | |
323 | * It is called in a loop to decode the returned get_attr | |
324 | * (see osd_add_get_attr) | |
325 | */ | |
326 | int osd_req_decode_get_attr_list(struct osd_request *or, | |
327 | struct osd_attr *, int *nelem, void **iterator); | |
328 | ||
329 | /* Attributes Page mode */ | |
330 | ||
331 | /* | |
332 | * Read an attribute page and optionally set one attribute | |
333 | * | |
334 | * Retrieves the attribute page directly to a user buffer. | |
335 | * @attr_page_data shall stay valid until end of execution. | |
336 | * See osd_attributes.h for common page structures | |
337 | */ | |
338 | int osd_req_add_get_attr_page(struct osd_request *or, | |
339 | u32 page_id, void *attr_page_data, unsigned max_page_len, | |
340 | const struct osd_attr *set_one); | |
341 | ||
342 | #endif /* __OSD_LIB_H__ */ |