mirror of
https://github.com/Fishwaldo/linux-bl808.git
synced 2025-06-17 20:25:19 +00:00
regmap: Fixup the kernel-doc comments on functions/structures
Most of the kernel-doc comments in regmap don't actually generate correctly. This patch fixes up a few common issues, corrects some typos and adds some missing argument descriptions. The most common issues being using a : after the function name which causes the short description to not render correctly and not separating the long and short descriptions of the function. There are quite a few instances of arguments not being described or given the wrong name as well. This patch doesn't fixup functions/structures that are currently missing descriptions. Signed-off-by: Charles Keepax <ckeepax@opensource.wolfsonmicro.com> Signed-off-by: Mark Brown <broonie@kernel.org>
This commit is contained in:
Charles Keepax
Mark Brown
parent
daaadbf074
commit
2cf8e2dfdf
4 changed files with 179 additions and 143 deletions
|
|
@ -39,12 +39,13 @@ enum regcache_type {
|
|||
};
|
||||
|
||||
/**
|
||||
* Default value for a register. We use an array of structs rather
|
||||
* than a simple array as many modern devices have very sparse
|
||||
* register maps.
|
||||
* struct reg_default - Default value for a register.
|
||||
*
|
||||
* @reg: Register address.
|
||||
* @def: Register default value.
|
||||
*
|
||||
* We use an array of structs rather than a simple array as many modern devices
|
||||
* have very sparse register maps.
|
||||
*/
|
||||
struct reg_default {
|
||||
unsigned int reg;
|
||||
|
|
@ -52,12 +53,14 @@ struct reg_default {
|
|||
};
|
||||
|
||||
/**
|
||||
* Register/value pairs for sequences of writes with an optional delay in
|
||||
* microseconds to be applied after each write.
|
||||
* struct reg_sequence - An individual write from a sequence of writes.
|
||||
*
|
||||
* @reg: Register address.
|
||||
* @def: Register value.
|
||||
* @delay_us: Delay to be applied after the register write in microseconds
|
||||
*
|
||||
* Register/value pairs for sequences of writes with an optional delay in
|
||||
* microseconds to be applied after each write.
|
||||
*/
|
||||
struct reg_sequence {
|
||||
unsigned int reg;
|
||||
|
|
@ -97,6 +100,7 @@ struct reg_sequence {
|
|||
|
||||
/**
|
||||
* regmap_read_poll_timeout - Poll until a condition is met or a timeout occurs
|
||||
*
|
||||
* @map: Regmap to read from
|
||||
* @addr: Address to poll
|
||||
* @val: Unsigned integer variable to read the value into
|
||||
|
|
@ -145,8 +149,8 @@ enum regmap_endian {
|
|||
};
|
||||
|
||||
/**
|
||||
* A register range, used for access related checks
|
||||
* (readable/writeable/volatile/precious checks)
|
||||
* struct regmap_range - A register range, used for access related checks
|
||||
* (readable/writeable/volatile/precious checks)
|
||||
*
|
||||
* @range_min: address of first register
|
||||
* @range_max: address of last register
|
||||
|
|
@ -158,16 +162,18 @@ struct regmap_range {
|
|||
|
||||
#define regmap_reg_range(low, high) { .range_min = low, .range_max = high, }
|
||||
|
||||
/*
|
||||
* A table of ranges including some yes ranges and some no ranges.
|
||||
* If a register belongs to a no_range, the corresponding check function
|
||||
* will return false. If a register belongs to a yes range, the corresponding
|
||||
* check function will return true. "no_ranges" are searched first.
|
||||
/**
|
||||
* struct regmap_access_table - A table of register ranges for access checks
|
||||
*
|
||||
* @yes_ranges : pointer to an array of regmap ranges used as "yes ranges"
|
||||
* @n_yes_ranges: size of the above array
|
||||
* @no_ranges: pointer to an array of regmap ranges used as "no ranges"
|
||||
* @n_no_ranges: size of the above array
|
||||
*
|
||||
* A table of ranges including some yes ranges and some no ranges.
|
||||
* If a register belongs to a no_range, the corresponding check function
|
||||
* will return false. If a register belongs to a yes range, the corresponding
|
||||
* check function will return true. "no_ranges" are searched first.
|
||||
*/
|
||||
struct regmap_access_table {
|
||||
const struct regmap_range *yes_ranges;
|
||||
|
|
@ -180,7 +186,7 @@ typedef void (*regmap_lock)(void *);
|
|||
typedef void (*regmap_unlock)(void *);
|
||||
|
||||
/**
|
||||
* Configuration for the register map of a device.
|
||||
* struct regmap_config - Configuration for the register map of a device.
|
||||
*
|
||||
* @name: Optional name of the regmap. Useful when a device has multiple
|
||||
* register regions.
|
||||
|
|
@ -313,22 +319,24 @@ struct regmap_config {
|
|||
};
|
||||
|
||||
/**
|
||||
* Configuration for indirectly accessed or paged registers.
|
||||
* Registers, mapped to this virtual range, are accessed in two steps:
|
||||
* 1. page selector register update;
|
||||
* 2. access through data window registers.
|
||||
* struct regmap_range_cfg - Configuration for indirectly accessed or paged
|
||||
* registers.
|
||||
*
|
||||
* @name: Descriptive name for diagnostics
|
||||
*
|
||||
* @range_min: Address of the lowest register address in virtual range.
|
||||
* @range_max: Address of the highest register in virtual range.
|
||||
*
|
||||
* @page_sel_reg: Register with selector field.
|
||||
* @page_sel_mask: Bit shift for selector value.
|
||||
* @page_sel_shift: Bit mask for selector value.
|
||||
* @selector_reg: Register with selector field.
|
||||
* @selector_mask: Bit shift for selector value.
|
||||
* @selector_shift: Bit mask for selector value.
|
||||
*
|
||||
* @window_start: Address of first (lowest) register in data window.
|
||||
* @window_len: Number of registers in data window.
|
||||
*
|
||||
* Registers, mapped to this virtual range, are accessed in two steps:
|
||||
* 1. page selector register update;
|
||||
* 2. access through data window registers.
|
||||
*/
|
||||
struct regmap_range_cfg {
|
||||
const char *name;
|
||||
|
|
@ -371,7 +379,8 @@ typedef struct regmap_async *(*regmap_hw_async_alloc)(void);
|
|||
typedef void (*regmap_hw_free_context)(void *context);
|
||||
|
||||
/**
|
||||
* Description of a hardware bus for the register map infrastructure.
|
||||
* struct regmap_bus - Description of a hardware bus for the register map
|
||||
* infrastructure.
|
||||
*
|
||||
* @fast_io: Register IO is fast. Use a spinlock instead of a mutex
|
||||
* to perform locking. This field is ignored if custom lock/unlock
|
||||
|
|
@ -384,6 +393,10 @@ typedef void (*regmap_hw_free_context)(void *context);
|
|||
* must serialise with respect to non-async I/O.
|
||||
* @reg_write: Write a single register value to the given register address. This
|
||||
* write operation has to complete when returning from the function.
|
||||
* @reg_update_bits: Update bits operation to be used against volatile
|
||||
* registers, intended for devices supporting some mechanism
|
||||
* for setting clearing bits without having to
|
||||
* read/modify/write.
|
||||
* @read: Read operation. Data is returned in the buffer used to transmit
|
||||
* data.
|
||||
* @reg_read: Read a single register value from a given register address.
|
||||
|
|
@ -513,7 +526,7 @@ struct regmap *__devm_regmap_init_ac97(struct snd_ac97 *ac97,
|
|||
#endif
|
||||
|
||||
/**
|
||||
* regmap_init(): Initialise register map
|
||||
* regmap_init() - Initialise register map
|
||||
*
|
||||
* @dev: Device that will be interacted with
|
||||
* @bus: Bus-specific callbacks to use with device
|
||||
|
|
@ -531,7 +544,7 @@ int regmap_attach_dev(struct device *dev, struct regmap *map,
|
|||
const struct regmap_config *config);
|
||||
|
||||
/**
|
||||
* regmap_init_i2c(): Initialise register map
|
||||
* regmap_init_i2c() - Initialise register map
|
||||
*
|
||||
* @i2c: Device that will be interacted with
|
||||
* @config: Configuration for register map
|
||||
|
|
@ -544,9 +557,9 @@ int regmap_attach_dev(struct device *dev, struct regmap *map,
|
|||
i2c, config)
|
||||
|
||||
/**
|
||||
* regmap_init_spi(): Initialise register map
|
||||
* regmap_init_spi() - Initialise register map
|
||||
*
|
||||
* @spi: Device that will be interacted with
|
||||
* @dev: Device that will be interacted with
|
||||
* @config: Configuration for register map
|
||||
*
|
||||
* The return value will be an ERR_PTR() on error or a valid pointer to
|
||||
|
|
@ -557,8 +570,9 @@ int regmap_attach_dev(struct device *dev, struct regmap *map,
|
|||
dev, config)
|
||||
|
||||
/**
|
||||
* regmap_init_spmi_base(): Create regmap for the Base register space
|
||||
* @sdev: SPMI device that will be interacted with
|
||||
* regmap_init_spmi_base() - Create regmap for the Base register space
|
||||
*
|
||||
* @dev: SPMI device that will be interacted with
|
||||
* @config: Configuration for register map
|
||||
*
|
||||
* The return value will be an ERR_PTR() on error or a valid pointer to
|
||||
|
|
@ -569,8 +583,9 @@ int regmap_attach_dev(struct device *dev, struct regmap *map,
|
|||
dev, config)
|
||||
|
||||
/**
|
||||
* regmap_init_spmi_ext(): Create regmap for Ext register space
|
||||
* @sdev: Device that will be interacted with
|
||||
* regmap_init_spmi_ext() - Create regmap for Ext register space
|
||||
*
|
||||
* @dev: Device that will be interacted with
|
||||
* @config: Configuration for register map
|
||||
*
|
||||
* The return value will be an ERR_PTR() on error or a valid pointer to
|
||||
|
|
@ -581,7 +596,7 @@ int regmap_attach_dev(struct device *dev, struct regmap *map,
|
|||
dev, config)
|
||||
|
||||
/**
|
||||
* regmap_init_mmio_clk(): Initialise register map with register clock
|
||||
* regmap_init_mmio_clk() - Initialise register map with register clock
|
||||
*
|
||||
* @dev: Device that will be interacted with
|
||||
* @clk_id: register clock consumer ID
|
||||
|
|
@ -596,7 +611,7 @@ int regmap_attach_dev(struct device *dev, struct regmap *map,
|
|||
dev, clk_id, regs, config)
|
||||
|
||||
/**
|
||||
* regmap_init_mmio(): Initialise register map
|
||||
* regmap_init_mmio() - Initialise register map
|
||||
*
|
||||
* @dev: Device that will be interacted with
|
||||
* @regs: Pointer to memory-mapped IO region
|
||||
|
|
@ -609,7 +624,7 @@ int regmap_attach_dev(struct device *dev, struct regmap *map,
|
|||
regmap_init_mmio_clk(dev, NULL, regs, config)
|
||||
|
||||
/**
|
||||
* regmap_init_ac97(): Initialise AC'97 register map
|
||||
* regmap_init_ac97() - Initialise AC'97 register map
|
||||
*
|
||||
* @ac97: Device that will be interacted with
|
||||
* @config: Configuration for register map
|
||||
|
|
@ -623,7 +638,7 @@ int regmap_attach_dev(struct device *dev, struct regmap *map,
|
|||
bool regmap_ac97_default_volatile(struct device *dev, unsigned int reg);
|
||||
|
||||
/**
|
||||
* devm_regmap_init(): Initialise managed register map
|
||||
* devm_regmap_init() - Initialise managed register map
|
||||
*
|
||||
* @dev: Device that will be interacted with
|
||||
* @bus: Bus-specific callbacks to use with device
|
||||
|
|
@ -640,7 +655,7 @@ bool regmap_ac97_default_volatile(struct device *dev, unsigned int reg);
|
|||
dev, bus, bus_context, config)
|
||||
|
||||
/**
|
||||
* devm_regmap_init_i2c(): Initialise managed register map
|
||||
* devm_regmap_init_i2c() - Initialise managed register map
|
||||
*
|
||||
* @i2c: Device that will be interacted with
|
||||
* @config: Configuration for register map
|
||||
|
|
@ -654,9 +669,9 @@ bool regmap_ac97_default_volatile(struct device *dev, unsigned int reg);
|
|||
i2c, config)
|
||||
|
||||
/**
|
||||
* devm_regmap_init_spi(): Initialise register map
|
||||
* devm_regmap_init_spi() - Initialise register map
|
||||
*
|
||||
* @spi: Device that will be interacted with
|
||||
* @dev: Device that will be interacted with
|
||||
* @config: Configuration for register map
|
||||
*
|
||||
* The return value will be an ERR_PTR() on error or a valid pointer
|
||||
|
|
@ -668,8 +683,9 @@ bool regmap_ac97_default_volatile(struct device *dev, unsigned int reg);
|
|||
dev, config)
|
||||
|
||||
/**
|
||||
* devm_regmap_init_spmi_base(): Create managed regmap for Base register space
|
||||
* @sdev: SPMI device that will be interacted with
|
||||
* devm_regmap_init_spmi_base() - Create managed regmap for Base register space
|
||||
*
|
||||
* @dev: SPMI device that will be interacted with
|
||||
* @config: Configuration for register map
|
||||
*
|
||||
* The return value will be an ERR_PTR() on error or a valid pointer
|
||||
|
|
@ -681,8 +697,9 @@ bool regmap_ac97_default_volatile(struct device *dev, unsigned int reg);
|
|||
dev, config)
|
||||
|
||||
/**
|
||||
* devm_regmap_init_spmi_ext(): Create managed regmap for Ext register space
|
||||
* @sdev: SPMI device that will be interacted with
|
||||
* devm_regmap_init_spmi_ext() - Create managed regmap for Ext register space
|
||||
*
|
||||
* @dev: SPMI device that will be interacted with
|
||||
* @config: Configuration for register map
|
||||
*
|
||||
* The return value will be an ERR_PTR() on error or a valid pointer
|
||||
|
|
@ -694,7 +711,7 @@ bool regmap_ac97_default_volatile(struct device *dev, unsigned int reg);
|
|||
dev, config)
|
||||
|
||||
/**
|
||||
* devm_regmap_init_mmio_clk(): Initialise managed register map with clock
|
||||
* devm_regmap_init_mmio_clk() - Initialise managed register map with clock
|
||||
*
|
||||
* @dev: Device that will be interacted with
|
||||
* @clk_id: register clock consumer ID
|
||||
|
|
@ -710,7 +727,7 @@ bool regmap_ac97_default_volatile(struct device *dev, unsigned int reg);
|
|||
dev, clk_id, regs, config)
|
||||
|
||||
/**
|
||||
* devm_regmap_init_mmio(): Initialise managed register map
|
||||
* devm_regmap_init_mmio() - Initialise managed register map
|
||||
*
|
||||
* @dev: Device that will be interacted with
|
||||
* @regs: Pointer to memory-mapped IO region
|
||||
|
|
@ -724,7 +741,7 @@ bool regmap_ac97_default_volatile(struct device *dev, unsigned int reg);
|
|||
devm_regmap_init_mmio_clk(dev, NULL, regs, config)
|
||||
|
||||
/**
|
||||
* devm_regmap_init_ac97(): Initialise AC'97 register map
|
||||
* devm_regmap_init_ac97() - Initialise AC'97 register map
|
||||
*
|
||||
* @ac97: Device that will be interacted with
|
||||
* @config: Configuration for register map
|
||||
|
|
@ -799,7 +816,7 @@ bool regmap_reg_in_ranges(unsigned int reg,
|
|||
unsigned int nranges);
|
||||
|
||||
/**
|
||||
* Description of an register field
|
||||
* struct reg_field - Description of an register field
|
||||
*
|
||||
* @reg: Offset of the register within the regmap bank
|
||||
* @lsb: lsb of the register field.
|
||||
|
|
@ -840,7 +857,7 @@ int regmap_fields_update_bits_base(struct regmap_field *field, unsigned int id,
|
|||
bool *change, bool async, bool force);
|
||||
|
||||
/**
|
||||
* Description of an IRQ for the generic regmap irq_chip.
|
||||
* struct regmap_irq - Description of an IRQ for the generic regmap irq_chip.
|
||||
*
|
||||
* @reg_offset: Offset of the status/mask register within the bank
|
||||
* @mask: Mask used to flag/control the register.
|
||||
|
|
@ -860,9 +877,7 @@ struct regmap_irq {
|
|||
[_irq] = { .reg_offset = (_off), .mask = (_mask) }
|
||||
|
||||
/**
|
||||
* Description of a generic regmap irq_chip. This is not intended to
|
||||
* handle every possible interrupt controller, but it should handle a
|
||||
* substantial proportion of those that are found in the wild.
|
||||
* struct regmap_irq_chip - Description of a generic regmap irq_chip.
|
||||
*
|
||||
* @name: Descriptive name for IRQ controller.
|
||||
*
|
||||
|
|
@ -896,6 +911,10 @@ struct regmap_irq {
|
|||
* after handling the interrupts in regmap_irq_handler().
|
||||
* @irq_drv_data: Driver specific IRQ data which is passed as parameter when
|
||||
* driver specific pre/post interrupt handler is called.
|
||||
*
|
||||
* This is not intended to handle every possible interrupt controller, but
|
||||
* it should handle a substantial proportion of those that are found in the
|
||||
* wild.
|
||||
*/
|
||||
struct regmap_irq_chip {
|
||||
const char *name;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue