Commit 9872e23d authored by Andy Shevchenko's avatar Andy Shevchenko Committed by Vinod Koul
Browse files

dmaengine: Fix doc strings to satisfy validation script 



The validation kernel doc script complains about undescribed
function parameters

.../dmaengine.c:155: warning: Function parameter or member 'dev' not descr ibed in 'dev_to_dma_chan'
.../dmaengine.c:251: warning: cannot understand function prototype: 'dma_cap_mask_t dma_cap_mask_all; '
.../dmaengine.c:257: warning: cannot understand function prototype: 'struct dma_chan_tbl_ent '
.../dmaengine.c:264: warning: cannot understand function prototype: 'struct dma_chan_tbl_ent __percpu *channel_table[DMA_TX_TYPE_END]; '
.../dmaengine.c:304: warning: Function parameter or member 'chan' not described in 'dma_chan_is_local'
.../dmaengine.c:304: warning: Function parameter or member 'cpu' not described in 'dma_chan_is_local'
.../dmaengine.c:414: warning: Function parameter or member 'chan' not described in 'balance_ref_count'
.../dmaengine.c:447: warning: Function parameter or member 'chan' not described in 'dma_chan_get'
.../dmaengine.c:494: warning: Function parameter or member 'chan' not described in 'dma_chan_put'

Add descriptions to the function parameters and in some cases update
existing text as well.

Signed-off-by: default avatarAndy Shevchenko <andriy.shevchenko@linux.intel.com>
Link: https://lore.kernel.org/r/20200429122151.50989-2-andriy.shevchenko@linux.intel.com


Signed-off-by: default avatarVinod Koul <vkoul@kernel.org>
parent 833d88f3

drivers/dma/dmaengine.c

+50 −46
Original line number Diff line number Diff line
@@ -147,9 +147,9 @@ static inline void dmaengine_debug_unregister(struct dma_device *dma_dev) { } 


/**

 * dev_to_dma_chan - convert a device pointer to its sysfs container object

 * @dev - device node

 * @dev:	device node

 *

 * Must be called under dma_list_mutex

 * Must be called under dma_list_mutex.

 */

static struct dma_chan *dev_to_dma_chan(struct device *dev)

{
@@ -249,22 +249,18 @@ static struct class dma_devclass = { 


/* --- client and device registration --- */



/**

 * dma_cap_mask_all - enable iteration over all operation types

 */

/* enable iteration over all operation types */

static dma_cap_mask_t dma_cap_mask_all;



/**

 * dma_chan_tbl_ent - tracks channel allocations per core/operation

 * @chan - associated channel for this entry

 * struct dma_chan_tbl_ent - tracks channel allocations per core/operation

 * @chan:	associated channel for this entry

 */

struct dma_chan_tbl_ent {

	struct dma_chan *chan;

};



/**

 * channel_table - percpu lookup table for memory-to-memory offload providers

 */

/* percpu lookup table for memory-to-memory offload providers */

static struct dma_chan_tbl_ent __percpu *channel_table[DMA_TX_TYPE_END];



static int __init dma_channel_table_init(void)
@@ -301,8 +297,11 @@ static int __init dma_channel_table_init(void) 
arch_initcall(dma_channel_table_init);



/**

 * dma_chan_is_local - returns true if the channel is in the same numa-node as

 *	the cpu

 * dma_chan_is_local - checks if the channel is in the same NUMA-node as the CPU

 * @chan:	DMA channel to test

 * @cpu:	CPU index which the channel should be close to

 *

 * Returns true if the channel is in the same NUMA-node as the CPU.

 */

static bool dma_chan_is_local(struct dma_chan *chan, int cpu)

{
@@ -312,14 +311,14 @@ static bool dma_chan_is_local(struct dma_chan *chan, int cpu) 
}



/**

 * min_chan - returns the channel with min count and in the same numa-node as

 *	the cpu

 * min_chan - finds the channel with min count and in the same NUMA-node as the CPU

 * @cap:	capability to match

 * @cpu: cpu index which the channel should be close to

 * @cpu:	CPU index which the channel should be close to

 *

 * If some channels are close to the given cpu, the one with the lowest

 * reference count is returned. Otherwise, cpu is ignored and only the

 * If some channels are close to the given CPU, the one with the lowest

 * reference count is returned. Otherwise, CPU is ignored and only the

 * reference count is taken into account.

 *

 * Must be called under dma_list_mutex.

 */

static struct dma_chan *min_chan(enum dma_transaction_type cap, int cpu)
@@ -357,10 +356,11 @@ static struct dma_chan *min_chan(enum dma_transaction_type cap, int cpu) 
/**

 * dma_channel_rebalance - redistribute the available channels

 *

 * Optimize for cpu isolation (each cpu gets a dedicated channel for an

 * Optimize for CPU isolation (each CPU gets a dedicated channel for an

 * operation type) in the SMP case, and operation isolation (avoid

 * multi-tasking channels) in the non-SMP case.  Must be called under

 * dma_list_mutex.

 * multi-tasking channels) in the non-SMP case.

 *

 * Must be called under dma_list_mutex.

 */

static void dma_channel_rebalance(void)

{
@@ -410,9 +410,9 @@ static struct module *dma_chan_to_owner(struct dma_chan *chan) 


/**

 * balance_ref_count - catch up the channel reference count

 * @chan - channel to balance ->client_count versus dmaengine_ref_count

 * @chan:	channel to balance ->client_count versus dmaengine_ref_count

 *

 * balance_ref_count must be called under dma_list_mutex

 * Must be called under dma_list_mutex.

 */

static void balance_ref_count(struct dma_chan *chan)

{
@@ -442,10 +442,10 @@ static void dma_device_put(struct dma_device *device) 
}



/**

 * dma_chan_get - try to grab a dma channel's parent driver module

 * @chan - channel to grab

 * dma_chan_get - try to grab a DMA channel's parent driver module

 * @chan:	channel to grab

 *

 * Must be called under dma_list_mutex

 * Must be called under dma_list_mutex.

 */

static int dma_chan_get(struct dma_chan *chan)

{
@@ -489,10 +489,10 @@ static int dma_chan_get(struct dma_chan *chan) 
}



/**

 * dma_chan_put - drop a reference to a dma channel's parent driver module

 * @chan - channel to release

 * dma_chan_put - drop a reference to a DMA channel's parent driver module

 * @chan:	channel to release

 *

 * Must be called under dma_list_mutex

 * Must be called under dma_list_mutex.

 */

static void dma_chan_put(struct dma_chan *chan)

{
@@ -739,7 +739,7 @@ EXPORT_SYMBOL_GPL(dma_get_any_slave_channel); 
 * __dma_request_channel - try to allocate an exclusive channel

 * @mask:	capabilities that the channel must satisfy

 * @fn:		optional callback to disposition available channels

 * @fn_param: opaque parameter to pass to dma_filter_fn

 * @fn_param:	opaque parameter to pass to dma_filter_fn()

 * @np:		device node to look for DMA channels

 *

 * Returns pointer to appropriate DMA channel on success or NULL.
@@ -974,7 +974,7 @@ void dmaengine_get(void) 
EXPORT_SYMBOL(dmaengine_get);



/**

 * dmaengine_put - let dma drivers be removed when ref_count == 0

 * dmaengine_put - let DMA drivers be removed when ref_count == 0

 */

void dmaengine_put(void)

{
@@ -1146,7 +1146,7 @@ EXPORT_SYMBOL_GPL(dma_async_device_channel_unregister); 


/**

 * dma_async_device_register - registers DMA devices found

 * @device: &dma_device

 * @device:	pointer to &struct dma_device

 *

 * After calling this routine the structure should not be freed except in the

 * device_release() callback which will be called after
@@ -1315,7 +1315,7 @@ EXPORT_SYMBOL(dma_async_device_register); 


/**

 * dma_async_device_unregister - unregister a DMA device

 * @device: &dma_device

 * @device:	pointer to &struct dma_device

 *

 * This routine is called by dma driver exit routines, dmaengine holds module

 * references to prevent it being called while channels are in use.
@@ -1351,7 +1351,7 @@ static void dmam_device_release(struct device *dev, void *res) 


/**

 * dmaenginem_async_device_register - registers DMA devices found

 * @device: &dma_device

 * @device:	pointer to &struct dma_device

 *

 * The operation is managed and will be undone on driver detach.

 */
@@ -1588,7 +1588,8 @@ int dmaengine_desc_set_metadata_len(struct dma_async_tx_descriptor *desc, 
}

EXPORT_SYMBOL_GPL(dmaengine_desc_set_metadata_len);



/* dma_wait_for_async_tx - spin wait for a transaction to complete

/**

 * dma_wait_for_async_tx - spin wait for a transaction to complete

 * @tx:		in-flight transaction to wait on

 */

enum dma_status
@@ -1612,9 +1613,12 @@ dma_wait_for_async_tx(struct dma_async_tx_descriptor *tx) 
}

EXPORT_SYMBOL_GPL(dma_wait_for_async_tx);



/* dma_run_dependencies - helper routine for dma drivers to process

 *	(start) dependent operations on their target channel

/**

 * dma_run_dependencies - process dependent operations on the target channel

 * @tx:		transaction with dependencies

 *

 * Helper routine for DMA drivers to process (start) dependent operations

 * on their target channel.

 */

void dma_run_dependencies(struct dma_async_tx_descriptor *tx)

{