History

blk-mq: fill header with kernel-doc

Insert documentation for structs, enums and functions at header file. Format existing and new comments at struct blk_mq_ops as kernel-doc comments.

André Almeida committed 7 years ago

Commit d3867321 parent 1fead711 file · +185 −40Browse files

Unified · Split

include/linux/blk-mq.h+185−40
@@ -10,74 +10,171 @@ struct blk_mq_tags; · 9 unmodified lines
10struct blk_flush_queue;10struct blk_flush_queue;
11 11
12/**12/**
13 * struct blk_mq_hw_ctx - State for a hardware queue facing the hardware block device13 * struct blk_mq_hw_ctx - State for a hardware queue facing the hardware
14 * block device
14 */15 */
15struct blk_mq_hw_ctx {16struct blk_mq_hw_ctx {
16 struct {17 struct {
18 /** @lock: Protects the dispatch list. */
17 spinlock_t lock;19 spinlock_t lock;
20 /**
21 * @dispatch: Used for requests that are ready to be
22 * dispatched to the hardware but for some reason (e.g. lack of
23 * resources) could not be sent to the hardware. As soon as the
24 * driver can send new requests, requests at this list will
25 * be sent first for a fairer dispatch.
26 */
18 struct list_head dispatch;27 struct list_head dispatch;
19 unsigned long state; /* BLK_MQ_S_* flags */28 /**
29 * @state: BLK_MQ_S_* flags. Defines the state of the hw
30 * queue (active, scheduled to restart, stopped).
31 */
32 unsigned long state;
20 } ____cacheline_aligned_in_smp;33 } ____cacheline_aligned_in_smp;
21 34
35 /**
36 * @run_work: Used for scheduling a hardware queue run at a later time.
37 */
22 struct delayed_work run_work;38 struct delayed_work run_work;
39 /** @cpumask: Map of available CPUs where this hctx can run. */
23 cpumask_var_t cpumask;40 cpumask_var_t cpumask;
41 /**
42 * @next_cpu: Used by blk_mq_hctx_next_cpu() for round-robin CPU
43 * selection from @cpumask.
44 */
24 int next_cpu;45 int next_cpu;
46 /**
47 * @next_cpu_batch: Counter of how many works left in the batch before
48 * changing to the next CPU.
49 */
25 int next_cpu_batch;50 int next_cpu_batch;
26 51
27 unsigned long flags; /* BLK_MQ_F_* flags */52 /** @flags: BLK_MQ_F_* flags. Defines the behaviour of the queue. */
53 unsigned long flags;
28 54
55 /**
56 * @sched_data: Pointer owned by the IO scheduler attached to a request
57 * queue. It's up to the IO scheduler how to use this pointer.
58 */
29 void *sched_data;59 void *sched_data;
60 /**
61 * @queue: Pointer to the request queue that owns this hardware context.
62 */
30 struct request_queue *queue;63 struct request_queue *queue;
64 /** @fq: Queue of requests that need to perform a flush operation. */
31 struct blk_flush_queue *fq;65 struct blk_flush_queue *fq;
32 66
67 /**
68 * @driver_data: Pointer to data owned by the block driver that created
69 * this hctx
70 */
33 void *driver_data;71 void *driver_data;
34 72
73 /**
74 * @ctx_map: Bitmap for each software queue. If bit is on, there is a
75 * pending request in that software queue.
76 */
35 struct sbitmap ctx_map;77 struct sbitmap ctx_map;
36 78
79 /**
80 * @dispatch_from: Software queue to be used when no scheduler was
81 * selected.
82 */
37 struct blk_mq_ctx *dispatch_from;83 struct blk_mq_ctx *dispatch_from;
84 /**
85 * @dispatch_busy: Number used by blk_mq_update_dispatch_busy() to
86 * decide if the hw_queue is busy using Exponential Weighted Moving
87 * Average algorithm.
88 */
38 unsigned int dispatch_busy;89 unsigned int dispatch_busy;
39 90
91 /** @type: HCTX_TYPE_* flags. Type of hardware queue. */
40 unsigned short type;92 unsigned short type;
93 /** @nr_ctx: Number of software queues. */
41 unsigned short nr_ctx;94 unsigned short nr_ctx;
95 /** @ctxs: Array of software queues. */
42 struct blk_mq_ctx **ctxs;96 struct blk_mq_ctx **ctxs;
43 97
98 /** @dispatch_wait_lock: Lock for dispatch_wait queue. */
44 spinlock_t dispatch_wait_lock;99 spinlock_t dispatch_wait_lock;
100 /**
101 * @dispatch_wait: Waitqueue to put requests when there is no tag
102 * available at the moment, to wait for another try in the future.
103 */
45 wait_queue_entry_t dispatch_wait;104 wait_queue_entry_t dispatch_wait;
105
106 /**
107 * @wait_index: Index of next available dispatch_wait queue to insert
108 * requests.
109 */
46 atomic_t wait_index;110 atomic_t wait_index;
47 111
112 /**
113 * @tags: Tags owned by the block driver. A tag at this set is only
114 * assigned when a request is dispatched from a hardware queue.
115 */
48 struct blk_mq_tags *tags;116 struct blk_mq_tags *tags;
117 /**
118 * @sched_tags: Tags owned by I/O scheduler. If there is an I/O
119 * scheduler associated with a request queue, a tag is assigned when
120 * that request is allocated. Else, this member is not used.
121 */
49 struct blk_mq_tags *sched_tags;122 struct blk_mq_tags *sched_tags;
50 123
124 /** @queued: Number of queued requests. */
51 unsigned long queued;125 unsigned long queued;
126 /** @run: Number of dispatched requests. */
52 unsigned long run;127 unsigned long run;
53#define BLK_MQ_MAX_DISPATCH_ORDER 7128#define BLK_MQ_MAX_DISPATCH_ORDER 7
129 /** @dispatched: Number of dispatch requests by queue. */
54 unsigned long dispatched[BLK_MQ_MAX_DISPATCH_ORDER];130 unsigned long dispatched[BLK_MQ_MAX_DISPATCH_ORDER];
55 131
132 /** @numa_node: NUMA node the storage adapter has been connected to. */
56 unsigned int numa_node;133 unsigned int numa_node;
134 /** @queue_num: Index of this hardware queue. */
57 unsigned int queue_num;135 unsigned int queue_num;
58 136
137 /**
138 * @nr_active: Number of active requests. Only used when a tag set is
139 * shared across request queues.
140 */
59 atomic_t nr_active;141 atomic_t nr_active;
60 142
143 /** @cpuhp_dead: List to store request if some CPU die. */
61 struct hlist_node cpuhp_dead;144 struct hlist_node cpuhp_dead;
145 /** @kobj: Kernel object for sysfs. */
62 struct kobject kobj;146 struct kobject kobj;
63 147
148 /** @poll_considered: Count times blk_poll() was called. */
64 unsigned long poll_considered;149 unsigned long poll_considered;
150 /** @poll_invoked: Count how many requests blk_poll() polled. */
65 unsigned long poll_invoked;151 unsigned long poll_invoked;
152 /** @poll_success: Count how many polled requests were completed. */
66 unsigned long poll_success;153 unsigned long poll_success;
67 154
68#ifdef CONFIG_BLK_DEBUG_FS155#ifdef CONFIG_BLK_DEBUG_FS
156 /**
157 * @debugfs_dir: debugfs directory for this hardware queue. Named
158 * as cpu<cpu_number>.
159 */
69 struct dentry *debugfs_dir;160 struct dentry *debugfs_dir;
161 /** @sched_debugfs_dir: debugfs directory for the scheduler. */
70 struct dentry *sched_debugfs_dir;162 struct dentry *sched_debugfs_dir;
71#endif163#endif
72 164
165 /** @hctx_list: List of all hardware queues. */
73 struct list_head hctx_list;166 struct list_head hctx_list;
74 167
75 /* Must be the last member - see also blk_mq_hw_ctx_size(). */168 /**
169 * @srcu: Sleepable RCU. Use as lock when type of the hardware queue is
170 * blocking (BLK_MQ_F_BLOCKING). Must be the last member - see also
171 * blk_mq_hw_ctx_size().
172 */
76 struct srcu_struct srcu[0];173 struct srcu_struct srcu[0];
77};174};
78 175
79/**176/**
80 * struct blk_mq_queue_map - ctx -> hctx mapping177 * struct blk_mq_queue_map - Map software queues to hardware queues
81 * @mq_map: CPU ID to hardware queue index map. This is an array178 * @mq_map: CPU ID to hardware queue index map. This is an array
82 * with nr_cpu_ids elements. Each element has a value in the range179 * with nr_cpu_ids elements. Each element has a value in the range
83 * [@queue_offset, @queue_offset + @nr_queues).180 * [@queue_offset, @queue_offset + @nr_queues).
@@ -92,10 +189,17 @@ struct blk_mq_queue_map { · 8 unmodified lines
92 unsigned int queue_offset;189 unsigned int queue_offset;
93};190};
94 191
192/**
193 * enum hctx_type - Type of hardware queue
194 * @HCTX_TYPE_DEFAULT: All I/O not otherwise accounted for.
195 * @HCTX_TYPE_READ: Just for READ I/O.
196 * @HCTX_TYPE_POLL: Polled I/O of any kind.
197 * @HCTX_MAX_TYPES: Number of types of hctx.
198 */
95enum hctx_type {199enum hctx_type {
96 HCTX_TYPE_DEFAULT, /* all I/O not otherwise accounted for */200 HCTX_TYPE_DEFAULT,
97 HCTX_TYPE_READ, /* just for READ I/O */201 HCTX_TYPE_READ,
98 HCTX_TYPE_POLL, /* polled I/O of any kind */202 HCTX_TYPE_POLL,
99 203
100 HCTX_MAX_TYPES,204 HCTX_MAX_TYPES,
101};205};
@@ -147,6 +251,12 @@ struct blk_mq_tag_set { · 45 unmodified lines
147 struct list_head tag_list;251 struct list_head tag_list;
148};252};
149 253
254/**
255 * struct blk_mq_queue_data - Data about a request inserted in a queue
256 *
257 * @rq: Request pointer.
258 * @last: If it is the last request in the queue.
259 */
150struct blk_mq_queue_data {260struct blk_mq_queue_data {
151 struct request *rq;261 struct request *rq;
152 bool last;262 bool last;
@@ -174,81 +284,101 @@ typedef bool (busy_fn)(struct request_queue *); · 21 unmodified lines
174typedef void (complete_fn)(struct request *);284typedef void (complete_fn)(struct request *);
175typedef void (cleanup_rq_fn)(struct request *);285typedef void (cleanup_rq_fn)(struct request *);
176 286
177 287/**
288 * struct blk_mq_ops - Callback functions that implements block driver
289 * behaviour.
290 */
178struct blk_mq_ops {291struct blk_mq_ops {
179 /*292 /**
180 * Queue request293 * @queue_rq: Queue a new request from block IO.
181 */294 */
182 queue_rq_fn *queue_rq;295 queue_rq_fn *queue_rq;
183 296
184 /*297 /**
185 * If a driver uses bd->last to judge when to submit requests to298 * @commit_rqs: If a driver uses bd->last to judge when to submit
186 * hardware, it must define this function. In case of errors that299 * requests to hardware, it must define this function. In case of errors
187 * make us stop issuing further requests, this hook serves the300 * that make us stop issuing further requests, this hook serves the
188 * purpose of kicking the hardware (which the last request otherwise301 * purpose of kicking the hardware (which the last request otherwise
189 * would have done).302 * would have done).
190 */303 */
191 commit_rqs_fn *commit_rqs;304 commit_rqs_fn *commit_rqs;
192 305
193 /*306 /**
194 * Reserve budget before queue request, once .queue_rq is307 * @get_budget: Reserve budget before queue request, once .queue_rq is
195 * run, it is driver's responsibility to release the308 * run, it is driver's responsibility to release the
196 * reserved budget. Also we have to handle failure case309 * reserved budget. Also we have to handle failure case
197 * of .get_budget for avoiding I/O deadlock.310 * of .get_budget for avoiding I/O deadlock.
198 */311 */
199 get_budget_fn *get_budget;312 get_budget_fn *get_budget;
313 /**
314 * @put_budget: Release the reserved budget.
315 */
200 put_budget_fn *put_budget;316 put_budget_fn *put_budget;
201 317
202 /*318 /**
203 * Called on request timeout319 * @timeout: Called on request timeout.
204 */320 */
205 timeout_fn *timeout;321 timeout_fn *timeout;
206 322
207 /*323 /**
208 * Called to poll for completion of a specific tag.324 * @poll: Called to poll for completion of a specific tag.
209 */325 */
210 poll_fn *poll;326 poll_fn *poll;
211 327
328 /**
329 * @complete: Mark the request as complete.
330 */
212 complete_fn *complete;331 complete_fn *complete;
213 332
214 /*333 /**
215 * Called when the block layer side of a hardware queue has been334 * @init_hctx: Called when the block layer side of a hardware queue has
216 * set up, allowing the driver to allocate/init matching structures.335 * been set up, allowing the driver to allocate/init matching
217 * Ditto for exit/teardown.336 * structures.
218 */337 */
219 init_hctx_fn *init_hctx;338 init_hctx_fn *init_hctx;
339 /**
340 * @exit_hctx: Ditto for exit/teardown.
341 */
220 exit_hctx_fn *exit_hctx;342 exit_hctx_fn *exit_hctx;
221 343
222 /*344 /**
223 * Called for every command allocated by the block layer to allow345 * @init_request: Called for every command allocated by the block layer
224 * the driver to set up driver specific data.346 * to allow the driver to set up driver specific data.
225 *347 *
226 * Tag greater than or equal to queue_depth is for setting up348 * Tag greater than or equal to queue_depth is for setting up
227 * flush request.349 * flush request.
228 *
229 * Ditto for exit/teardown.
230 */350 */
231 init_request_fn *init_request;351 init_request_fn *init_request;
352 /**
353 * @exit_request: Ditto for exit/teardown.
354 */
232 exit_request_fn *exit_request;355 exit_request_fn *exit_request;
233 /* Called from inside blk_get_request() */356
357 /**
358 * @initialize_rq_fn: Called from inside blk_get_request().
359 */
234 void (*initialize_rq_fn)(struct request *rq);360 void (*initialize_rq_fn)(struct request *rq);
235 361
236 /*362 /**
237 * Called before freeing one request which isn't completed yet,363 * @cleanup_rq: Called before freeing one request which isn't completed
238 * and usually for freeing the driver private data364 * yet, and usually for freeing the driver private data.
239 */365 */
240 cleanup_rq_fn *cleanup_rq;366 cleanup_rq_fn *cleanup_rq;
241 367
242 /*368 /**
243 * If set, returns whether or not this queue currently is busy369 * @busy: If set, returns whether or not this queue currently is busy.
244 */370 */
245 busy_fn *busy;371 busy_fn *busy;
246 372
373 /**
374 * @map_queues: This allows drivers specify their own queue mapping by
375 * overriding the setup-time function that builds the mq_map.
376 */
247 map_queues_fn *map_queues;377 map_queues_fn *map_queues;
248 378
249#ifdef CONFIG_BLK_DEBUG_FS379#ifdef CONFIG_BLK_DEBUG_FS
250 /*380 /**
251 * Used by the debugfs implementation to show driver-specific381 * @show_rq: Used by the debugfs implementation to show driver-specific
252 * information about a request.382 * information about a request.
253 */383 */
254 void (*show_rq)(struct seq_file *m, struct request *rq);384 void (*show_rq)(struct seq_file *m, struct request *rq);
@@ -391,14 +521,29 @@ void blk_mq_quiesce_queue_nowait(struct request_queue *q); · 136 unmodified lines
391 521
392unsigned int blk_mq_rq_cpu(struct request *rq);522unsigned int blk_mq_rq_cpu(struct request *rq);
393 523
394/*524/**
525 * blk_mq_rq_from_pdu - cast a PDU to a request
526 * @pdu: the PDU (Protocol Data Unit) to be casted
527 *
528 * Return: request
529 *
395 * Driver command data is immediately after the request. So subtract request530 * Driver command data is immediately after the request. So subtract request
396 * size to get back to the original request, add request size to get the PDU.531 * size to get back to the original request.
397 */532 */
398static inline struct request *blk_mq_rq_from_pdu(void *pdu)533static inline struct request *blk_mq_rq_from_pdu(void *pdu)
399{534{
400 return pdu - sizeof(struct request);535 return pdu - sizeof(struct request);
401}536}
537
538/**
539 * blk_mq_rq_to_pdu - cast a request to a PDU
540 * @rq: the request to be casted
541 *
542 * Return: pointer to the PDU
543 *
544 * Driver command data is immediately after the request. So add request to get
545 * the PDU.
546 */
402static inline void *blk_mq_rq_to_pdu(struct request *rq)547static inline void *blk_mq_rq_to_pdu(struct request *rq)
403{548{
404 return rq + 1;549 return rq + 1;