Re: [PATCH 1/1] blk-mq: fill header with kernel-doc

[Jens Axboe]

On 9/30/19 1:48 PM, Andrà Almeida wrote:
> diff --git a/include/linux/blk-mq.h b/include/linux/blk-mq.h
> index 0bf056de5cc3..d0aab34972b7 100644
> --- a/include/linux/blk-mq.h
> +++ b/include/linux/blk-mq.h
> @@ -11,12 +11,85 @@ struct blk_flush_queue;
>   
>   /**
>    * struct blk_mq_hw_ctx - State for a hardware queue facing the hardware block device
> + *
> + * @lock:	Lock for accessing dispatch queue
> + * @dispatch:	Queue of dispatched requests, waiting for workers to send them
> + *		to the hardware.
> + * @state:	BLK_MQ_S_* flags. Define the state of the hw queue (active,
> + *		scheduled to restart, stopped).
> + *
> + * @run_work:		Worker for dispatch scheduled requests to hardware.
> + *			BLK_MQ_CPU_WORK_BATCH workers will be assigned to a CPU,
> + *			then the following ones will be assigned to
> + *			the next_cpu.
> + * @cpumask:		Map of available CPUs.
> + * @next_cpu:		Index of CPU/workqueue to be used in the next batch
> + *			of workers.
> + * @next_cpu_batch:	Counter of how many works letf in the batch before
> + *			changing to the next CPU. A batch has the size of
> + *			BLK_MQ_CPU_WORK_BATCH.
> + *
> + * @flags:	BLK_MQ_F_* flags. Define the behaviour of the queue.
> + *
> + * @sched_data: Data to support schedulers.
> + * @queue:	Queue of request to be dispatched.
> + * @fq:		Queue of requests to be flushed from memory to storage.
> + *
> + * @driver_data: Device driver specific queue.
> + *
> + * @ctx_map:	Bitmap for each software queue. If bit is on, there is a
> + *		pending request.
> + *
> + * @dispatch_from: Queue to be used when there is no scheduler was selected.
> + * @dispatch_busy: Number used by blk_mq_update_dispatch_busy() to decide
> + *		   if the hw_queue is busy using Exponential Weighted Moving
> + *		   Average algorithm.
> + *
> + * @type:	HCTX_TYPE_* flags. Type of hardware queue.
> + * @nr_ctx:	Number of software queues.
> + * @ctxs:	Array of software queues.
> + *
> + * @dispatch_wait_lock: Lock for dispatch_wait queue.
> + * @dispatch_wait:	Waitqueue for dispatched requests. Request here will
> + *			be processed when
> + *			percpu_ref_is_zero(&q->q_usage_counter) evaluates true
> + *			for q as a request_queue.
> + * @wait_index:		Index of next wait queue to be used.
> + *
> + * @tags:	Request tags.
> + * @sched_tags:	Request tags for schedulers.
> + *
> + * @queued:	Number of queued requests.
> + * @run:	Number of dispatched requests.
> + * @dispatched:	Number of dispatch requests by queue.
> + *
> + * @numa_node:	NUMA node index of this hardware queue.
> + * @queue_num:	Index of this hardware queue.
> + *
> + * @nr_active:	Number of active tags.
> + *
> + * @cpuhp_dead:	List to store request if some CPU die.
> + * @kobj:	Kernel object for sysfs.
> + *
> + * @poll_considered:	Count times blk_poll() was called.
> + * @poll_invoked:	Count how many requests blk_poll() polled.
> + * @poll_success:	Count how many polled requests were completed.
> + *
> + * @debugfs_dir:	debugfs directory for this hardware queue. Named
> + *			as cpu<cpu_number>.
> + * @sched_debugfs_dir:	debugfs directory for the scheduler.
> + *
> + * @hctx_list:		List of all hardware queues.
> + *
> + * @srcu:	Sleepable RCU. Use as lock when type of the hardware queue is
> + *		blocking (BLK_MQ_F_BLOCKING). Must be the last member - see
> + *		also blk_mq_hw_ctx_size().
>    */
>   struct blk_mq_hw_ctx {
>   	struct {
>   		spinlock_t		lock;
>   		struct list_head	dispatch;
> -		unsigned long		state;		/* BLK_MQ_S_* flags */
> +		unsigned long		state;
>   	} ____cacheline_aligned_in_smp;
>   
>   	struct delayed_work	run_work;
> @@ -24,7 +97,7 @@ struct blk_mq_hw_ctx {
>   	int			next_cpu;
>   	int			next_cpu_batch;
>   
> -	unsigned long		flags;		/* BLK_MQ_F_* flags */
> +	unsigned long		flags;
>   
>   	void			*sched_data;
>   	struct request_queue	*queue;
> @@ -72,41 +145,73 @@ struct blk_mq_hw_ctx {
>   
>   	struct list_head	hctx_list;
>   
> -	/* Must be the last member - see also blk_mq_hw_ctx_size(). */
>   	struct srcu_struct	srcu[0];
>   };

I like improving how much is documented, but I absolutely don't like how
everything is pulled into one section above the struct instead of being
documented inline instead.

I realize this probably makes it easier to make nice external
documentation, but imho that's absolutely secondary to having the
documentation being right there where you read the code.

> @@ -142,81 +253,100 @@ typedef bool (busy_fn)(struct request_queue *);
>   typedef void (complete_fn)(struct request *);
>   typedef void (cleanup_rq_fn)(struct request *);
>   
> -
> +/**
> + * struct blk_mq_ops - list of callback functions for blk-mq drivers
> + */
>   struct blk_mq_ops {
> -	/*
> -	 * Queue request
> +	/**
> +	 * @queue_rq: Queue a new request from block IO.
>   	 */
>   	queue_rq_fn		*queue_rq;
>   
> -	/*
> -	 * If a driver uses bd->last to judge when to submit requests to
> -	 * hardware, it must define this function. In case of errors that
> -	 * make us stop issuing further requests, this hook serves the
> +	/**
> +	 * @commit_rqs: If a driver uses bd->last to judge when to submit
> +	 * requests to hardware, it must define this function. In case of errors
> +	 * that make us stop issuing further requests, this hook serves the
>   	 * purpose of kicking the hardware (which the last request otherwise
>   	 * would have done).
>   	 */
>   	commit_rqs_fn		*commit_rqs;

Stuff like this is MUCH better. Why isn't all of it done like this?

-- 
Jens Axboe