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
1010 struct blk_flush_queue;
1111
1212 /**
13− * struct blk_mq_hw_ctx - State for a hardware queue facing the hardware block device
13+ * struct blk_mq_hw_ctx - State for a hardware queue facing the hardware
14+ * block device
1415 */
1516 struct blk_mq_hw_ctx {
1617 struct {
18+ /** @lock: Protects the dispatch list. */
1719 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+ */
1827 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;
2033 } ____cacheline_aligned_in_smp;
2134
35+ /**
36+ * @run_work: Used for scheduling a hardware queue run at a later time.
37+ */
2238 struct delayed_work run_work;
39+ /** @cpumask: Map of available CPUs where this hctx can run. */
2340 cpumask_var_t cpumask;
41+ /**
42+ * @next_cpu: Used by blk_mq_hctx_next_cpu() for round-robin CPU
43+ * selection from @cpumask.
44+ */
2445 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+ */
2550 int next_cpu_batch;
2651
27− unsigned long flags; /* BLK_MQ_F_* flags */
52+ /** @flags: BLK_MQ_F_* flags. Defines the behaviour of the queue. */
53+ unsigned long flags;
2854
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+ */
2959 void *sched_data;
60+ /**
61+ * @queue: Pointer to the request queue that owns this hardware context.
62+ */
3063 struct request_queue *queue;
64+ /** @fq: Queue of requests that need to perform a flush operation. */
3165 struct blk_flush_queue *fq;
3266
67+ /**
68+ * @driver_data: Pointer to data owned by the block driver that created
69+ * this hctx
70+ */
3371 void *driver_data;
3472
73+ /**
74+ * @ctx_map: Bitmap for each software queue. If bit is on, there is a
75+ * pending request in that software queue.
76+ */
3577 struct sbitmap ctx_map;
3678
79+ /**
80+ * @dispatch_from: Software queue to be used when no scheduler was
81+ * selected.
82+ */
3783 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+ */
3889 unsigned int dispatch_busy;
3990
91+ /** @type: HCTX_TYPE_* flags. Type of hardware queue. */
4092 unsigned short type;
93+ /** @nr_ctx: Number of software queues. */
4194 unsigned short nr_ctx;
95+ /** @ctxs: Array of software queues. */
4296 struct blk_mq_ctx **ctxs;
4397
98+ /** @dispatch_wait_lock: Lock for dispatch_wait queue. */
4499 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+ */
45104 wait_queue_entry_t dispatch_wait;
105+
106+ /**
107+ * @wait_index: Index of next available dispatch_wait queue to insert
108+ * requests.
109+ */
46110 atomic_t wait_index;
47111
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+ */
48116 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+ */
49122 struct blk_mq_tags *sched_tags;
50123
124+ /** @queued: Number of queued requests. */
51125 unsigned long queued;
126+ /** @run: Number of dispatched requests. */
52127 unsigned long run;
53128 #define BLK_MQ_MAX_DISPATCH_ORDER 7
129+ /** @dispatched: Number of dispatch requests by queue. */
54130 unsigned long dispatched[BLK_MQ_MAX_DISPATCH_ORDER];
55131
132+ /** @numa_node: NUMA node the storage adapter has been connected to. */
56133 unsigned int numa_node;
134+ /** @queue_num: Index of this hardware queue. */
57135 unsigned int queue_num;
58136
137+ /**
138+ * @nr_active: Number of active requests. Only used when a tag set is
139+ * shared across request queues.
140+ */
59141 atomic_t nr_active;
60142
143+ /** @cpuhp_dead: List to store request if some CPU die. */
61144 struct hlist_node cpuhp_dead;
145+ /** @kobj: Kernel object for sysfs. */
62146 struct kobject kobj;
63147
148+ /** @poll_considered: Count times blk_poll() was called. */
64149 unsigned long poll_considered;
150+ /** @poll_invoked: Count how many requests blk_poll() polled. */
65151 unsigned long poll_invoked;
152+ /** @poll_success: Count how many polled requests were completed. */
66153 unsigned long poll_success;
67154
68155 #ifdef CONFIG_BLK_DEBUG_FS
156+ /**
157+ * @debugfs_dir: debugfs directory for this hardware queue. Named
158+ * as cpu<cpu_number>.
159+ */
69160 struct dentry *debugfs_dir;
161+ /** @sched_debugfs_dir: debugfs directory for the scheduler. */
70162 struct dentry *sched_debugfs_dir;
71163 #endif
72164
165+ /** @hctx_list: List of all hardware queues. */
73166 struct list_head hctx_list;
74167
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+ */
76173 struct srcu_struct srcu[0];
77174 };
78175
79176 /**
80− * struct blk_mq_queue_map - ctx -> hctx mapping
177+ * struct blk_mq_queue_map - Map software queues to hardware queues
81178 * @mq_map: CPU ID to hardware queue index map. This is an array
82179 * with nr_cpu_ids elements. Each element has a value in the range
83180 * [@queue_offset, @queue_offset + @nr_queues).
@@ -92,10 +189,17 @@ struct blk_mq_queue_map { · 8 unmodified lines
92189 unsigned int queue_offset;
93190 };
94191
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+ */
95199 enum hctx_type {
96− HCTX_TYPE_DEFAULT, /* all I/O not otherwise accounted for */
97− HCTX_TYPE_READ, /* just for READ I/O */
98− HCTX_TYPE_POLL, /* polled I/O of any kind */
200+ HCTX_TYPE_DEFAULT,
201+ HCTX_TYPE_READ,
202+ HCTX_TYPE_POLL,
99203
100204 HCTX_MAX_TYPES,
101205 };
@@ -147,6 +251,12 @@ struct blk_mq_tag_set { · 45 unmodified lines
147251 struct list_head tag_list;
148252 };
149253
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+ */
150260 struct blk_mq_queue_data {
151261 struct request *rq;
152262 bool last;
@@ -174,81 +284,101 @@ typedef bool (busy_fn)(struct request_queue *); · 21 unmodified lines
174284 typedef void (complete_fn)(struct request *);
175285 typedef void (cleanup_rq_fn)(struct request *);
176286
177−
287+/**
288+ * struct blk_mq_ops - Callback functions that implements block driver
289+ * behaviour.
290+ */
178291 struct blk_mq_ops {
179− /*
180− * Queue request
292+ /**
293+ * @queue_rq: Queue a new request from block IO.
181294 */
182295 queue_rq_fn *queue_rq;
183296
184− /*
185− * If a driver uses bd->last to judge when to submit requests to
186− * hardware, it must define this function. In case of errors that
187− * make us stop issuing further requests, this hook serves the
297+ /**
298+ * @commit_rqs: If a driver uses bd->last to judge when to submit
299+ * requests to hardware, it must define this function. In case of errors
300+ * that make us stop issuing further requests, this hook serves the
188301 * purpose of kicking the hardware (which the last request otherwise
189302 * would have done).
190303 */
191304 commit_rqs_fn *commit_rqs;
192305
193− /*
194− * Reserve budget before queue request, once .queue_rq is
306+ /**
307+ * @get_budget: Reserve budget before queue request, once .queue_rq is
195308 * run, it is driver's responsibility to release the
196309 * reserved budget. Also we have to handle failure case
197310 * of .get_budget for avoiding I/O deadlock.
198311 */
199312 get_budget_fn *get_budget;
313+ /**
314+ * @put_budget: Release the reserved budget.
315+ */
200316 put_budget_fn *put_budget;
201317
202− /*
203− * Called on request timeout
318+ /**
319+ * @timeout: Called on request timeout.
204320 */
205321 timeout_fn *timeout;
206322
207− /*
208− * Called to poll for completion of a specific tag.
323+ /**
324+ * @poll: Called to poll for completion of a specific tag.
209325 */
210326 poll_fn *poll;
211327
328+ /**
329+ * @complete: Mark the request as complete.
330+ */
212331 complete_fn *complete;
213332
214− /*
215− * Called when the block layer side of a hardware queue has been
216− * set up, allowing the driver to allocate/init matching structures.
217− * Ditto for exit/teardown.
333+ /**
334+ * @init_hctx: Called when the block layer side of a hardware queue has
335+ * been set up, allowing the driver to allocate/init matching
336+ * structures.
218337 */
219338 init_hctx_fn *init_hctx;
339+ /**
340+ * @exit_hctx: Ditto for exit/teardown.
341+ */
220342 exit_hctx_fn *exit_hctx;
221343
222− /*
223− * Called for every command allocated by the block layer to allow
224− * the driver to set up driver specific data.
344+ /**
345+ * @init_request: Called for every command allocated by the block layer
346+ * to allow the driver to set up driver specific data.
225347 *
226348 * Tag greater than or equal to queue_depth is for setting up
227349 * flush request.
228− *
229− * Ditto for exit/teardown.
230350 */
231351 init_request_fn *init_request;
352+ /**
353+ * @exit_request: Ditto for exit/teardown.
354+ */
232355 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+ */
234360 void (*initialize_rq_fn)(struct request *rq);
235361
236− /*
237− * Called before freeing one request which isn't completed yet,
238− * and usually for freeing the driver private data
362+ /**
363+ * @cleanup_rq: Called before freeing one request which isn't completed
364+ * yet, and usually for freeing the driver private data.
239365 */
240366 cleanup_rq_fn *cleanup_rq;
241367
242− /*
243− * If set, returns whether or not this queue currently is busy
368+ /**
369+ * @busy: If set, returns whether or not this queue currently is busy.
244370 */
245371 busy_fn *busy;
246372
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+ */
247377 map_queues_fn *map_queues;
248378
249379 #ifdef CONFIG_BLK_DEBUG_FS
250− /*
251− * Used by the debugfs implementation to show driver-specific
380+ /**
381+ * @show_rq: Used by the debugfs implementation to show driver-specific
252382 * information about a request.
253383 */
254384 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
391521
392522 unsigned int blk_mq_rq_cpu(struct request *rq);
393523
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+ *
395530 * 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.
397532 */
398533 static inline struct request *blk_mq_rq_from_pdu(void *pdu)
399534 {
400535 return pdu - sizeof(struct request);
401536 }
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+ */
402547 static inline void *blk_mq_rq_to_pdu(struct request *rq)
403548 {
404549 return rq + 1;