| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-Id: <E1cRjRu-0008WL-5c@debutante>
Date: Thu, 12 Jan 2017 17:46:06 +0000
From: Mark Brown <broonie@...nel.org>
To: Charles Keepax <ckeepax@...nsource.wolfsonmicro.com>
Cc: Mark Brown <broonie@...nel.org>, broonie@...nel.org,
linux-kernel@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Applied "regmap: Fixup the kernel-doc comments on functions/structures" to the regmap tree
The patch
regmap: Fixup the kernel-doc comments on functions/structures
has been applied to the regmap tree at
git://git.kernel.org/pub/scm/linux/kernel/git/broonie/regmap.git
All being well this means that it will be integrated into the linux-next
tree (usually sometime in the next 24 hours) and sent to Linus during
the next merge window (or sooner if it is a bug fix), however if
problems are discovered then the patch may be dropped or reverted.
You may get further e-mails resulting from automated or manual testing
and review of the tree, please engage with people reporting problems and
send followup patches addressing any issues that are reported if needed.
If any updates are required or you are submitting further changes they
should be sent as incremental updates against current git, existing
patches will not be replaced.
Please add any relevant lists and maintainers to the CCs when replying
to this mail.
Thanks,
Mark
>From 2cf8e2dfdf88363476f23bc600745250b94dbbed Mon Sep 17 00:00:00 2001
From: Charles Keepax <ckeepax@...nsource.wolfsonmicro.com>
Date: Thu, 12 Jan 2017 11:17:39 +0000
Subject: [PATCH] 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@...nsource.wolfsonmicro.com>
Signed-off-by: Mark Brown <broonie@...nel.org>
---
drivers/base/regmap/regcache.c | 20 +++----
drivers/base/regmap/regmap-irq.c | 62 ++++++++++---------
drivers/base/regmap/regmap.c | 125 +++++++++++++++++++++------------------
include/linux/regmap.h | 115 ++++++++++++++++++++---------------
4 files changed, 179 insertions(+), 143 deletions(-)
diff --git a/drivers/base/regmap/regcache.c b/drivers/base/regmap/regcache.c
index 4e582561e1e7..b0a0dcf32fb7 100644
--- a/drivers/base/regmap/regcache.c
+++ b/drivers/base/regmap/regcache.c
@@ -224,7 +224,7 @@ void regcache_exit(struct regmap *map)
}
/**
- * regcache_read: Fetch the value of a given register from the cache.
+ * regcache_read - Fetch the value of a given register from the cache.
*
* @map: map to configure.
* @reg: The register index.
@@ -255,7 +255,7 @@ int regcache_read(struct regmap *map,
}
/**
- * regcache_write: Set the value of a given register in the cache.
+ * regcache_write - Set the value of a given register in the cache.
*
* @map: map to configure.
* @reg: The register index.
@@ -328,7 +328,7 @@ static int regcache_default_sync(struct regmap *map, unsigned int min,
}
/**
- * regcache_sync: Sync the register cache with the hardware.
+ * regcache_sync - Sync the register cache with the hardware.
*
* @map: map to configure.
*
@@ -396,7 +396,7 @@ int regcache_sync(struct regmap *map)
EXPORT_SYMBOL_GPL(regcache_sync);
/**
- * regcache_sync_region: Sync part of the register cache with the hardware.
+ * regcache_sync_region - Sync part of the register cache with the hardware.
*
* @map: map to sync.
* @min: first register to sync
@@ -452,7 +452,7 @@ int regcache_sync_region(struct regmap *map, unsigned int min,
EXPORT_SYMBOL_GPL(regcache_sync_region);
/**
- * regcache_drop_region: Discard part of the register cache
+ * regcache_drop_region - Discard part of the register cache
*
* @map: map to operate on
* @min: first register to discard
@@ -483,10 +483,10 @@ int regcache_drop_region(struct regmap *map, unsigned int min,
EXPORT_SYMBOL_GPL(regcache_drop_region);
/**
- * regcache_cache_only: Put a register map into cache only mode
+ * regcache_cache_only - Put a register map into cache only mode
*
* @map: map to configure
- * @cache_only: flag if changes should be written to the hardware
+ * @enable: flag if changes should be written to the hardware
*
* When a register map is marked as cache only writes to the register
* map API will only update the register cache, they will not cause
@@ -505,7 +505,7 @@ void regcache_cache_only(struct regmap *map, bool enable)
EXPORT_SYMBOL_GPL(regcache_cache_only);
/**
- * regcache_mark_dirty: Indicate that HW registers were reset to default values
+ * regcache_mark_dirty - Indicate that HW registers were reset to default values
*
* @map: map to mark
*
@@ -527,10 +527,10 @@ void regcache_mark_dirty(struct regmap *map)
EXPORT_SYMBOL_GPL(regcache_mark_dirty);
/**
- * regcache_cache_bypass: Put a register map into cache bypass mode
+ * regcache_cache_bypass - Put a register map into cache bypass mode
*
* @map: map to configure
- * @cache_bypass: flag if changes should not be written to the cache
+ * @enable: flag if changes should not be written to the cache
*
* When a register map is marked with the cache bypass option, writes
* to the register map API will only update the hardware and not the
diff --git a/drivers/base/regmap/regmap-irq.c b/drivers/base/regmap/regmap-irq.c
index ec262476d043..cd54189f2b1d 100644
--- a/drivers/base/regmap/regmap-irq.c
+++ b/drivers/base/regmap/regmap-irq.c
@@ -398,13 +398,14 @@ static const struct irq_domain_ops regmap_domain_ops = {
};
/**
- * regmap_add_irq_chip(): Use standard regmap IRQ controller handling
+ * regmap_add_irq_chip() - Use standard regmap IRQ controller handling
*
- * map: The regmap for the device.
- * irq: The IRQ the device uses to signal interrupts
- * irq_flags: The IRQF_ flags to use for the primary interrupt.
- * chip: Configuration for the interrupt controller.
- * data: Runtime data structure for the controller, allocated on success
+ * @map: The regmap for the device.
+ * @irq: The IRQ the device uses to signal interrupts.
+ * @irq_flags: The IRQF_ flags to use for the primary interrupt.
+ * @irq_base: Allocate at specific IRQ number if irq_base > 0.
+ * @chip: Configuration for the interrupt controller.
+ * @data: Runtime data structure for the controller, allocated on success.
*
* Returns 0 on success or an errno on failure.
*
@@ -659,12 +660,12 @@ int regmap_add_irq_chip(struct regmap *map, int irq, int irq_flags,
EXPORT_SYMBOL_GPL(regmap_add_irq_chip);
/**
- * regmap_del_irq_chip(): Stop interrupt handling for a regmap IRQ chip
+ * regmap_del_irq_chip() - Stop interrupt handling for a regmap IRQ chip
*
* @irq: Primary IRQ for the device
- * @d: regmap_irq_chip_data allocated by regmap_add_irq_chip()
+ * @d: ®map_irq_chip_data allocated by regmap_add_irq_chip()
*
- * This function also dispose all mapped irq on chip.
+ * This function also disposes of all mapped IRQs on the chip.
*/
void regmap_del_irq_chip(int irq, struct regmap_irq_chip_data *d)
{
@@ -723,18 +724,19 @@ static int devm_regmap_irq_chip_match(struct device *dev, void *res, void *data)
}
/**
- * devm_regmap_add_irq_chip(): Resource manager regmap_add_irq_chip()
+ * devm_regmap_add_irq_chip() - Resource manager regmap_add_irq_chip()
*
- * @dev: The device pointer on which irq_chip belongs to.
- * @map: The regmap for the device.
- * @irq: The IRQ the device uses to signal interrupts
+ * @dev: The device pointer on which irq_chip belongs to.
+ * @map: The regmap for the device.
+ * @irq: The IRQ the device uses to signal interrupts
* @irq_flags: The IRQF_ flags to use for the primary interrupt.
- * @chip: Configuration for the interrupt controller.
- * @data: Runtime data structure for the controller, allocated on success
+ * @irq_base: Allocate at specific IRQ number if irq_base > 0.
+ * @chip: Configuration for the interrupt controller.
+ * @data: Runtime data structure for the controller, allocated on success
*
* Returns 0 on success or an errno on failure.
*
- * The regmap_irq_chip data automatically be released when the device is
+ * The ®map_irq_chip_data will be automatically released when the device is
* unbound.
*/
int devm_regmap_add_irq_chip(struct device *dev, struct regmap *map, int irq,
@@ -765,11 +767,13 @@ int devm_regmap_add_irq_chip(struct device *dev, struct regmap *map, int irq,
EXPORT_SYMBOL_GPL(devm_regmap_add_irq_chip);
/**
- * devm_regmap_del_irq_chip(): Resource managed regmap_del_irq_chip()
+ * devm_regmap_del_irq_chip() - Resource managed regmap_del_irq_chip()
*
* @dev: Device for which which resource was allocated.
- * @irq: Primary IRQ for the device
- * @d: regmap_irq_chip_data allocated by regmap_add_irq_chip()
+ * @irq: Primary IRQ for the device.
+ * @data: ®map_irq_chip_data allocated by regmap_add_irq_chip().
+ *
+ * A resource managed version of regmap_del_irq_chip().
*/
void devm_regmap_del_irq_chip(struct device *dev, int irq,
struct regmap_irq_chip_data *data)
@@ -786,11 +790,11 @@ void devm_regmap_del_irq_chip(struct device *dev, int irq,
EXPORT_SYMBOL_GPL(devm_regmap_del_irq_chip);
/**
- * regmap_irq_chip_get_base(): Retrieve interrupt base for a regmap IRQ chip
+ * regmap_irq_chip_get_base() - Retrieve interrupt base for a regmap IRQ chip
*
- * Useful for drivers to request their own IRQs.
+ * @data: regmap irq controller to operate on.
*
- * @data: regmap_irq controller to operate on.
+ * Useful for drivers to request their own IRQs.
*/
int regmap_irq_chip_get_base(struct regmap_irq_chip_data *data)
{
@@ -800,12 +804,12 @@ int regmap_irq_chip_get_base(struct regmap_irq_chip_data *data)
EXPORT_SYMBOL_GPL(regmap_irq_chip_get_base);
/**
- * regmap_irq_get_virq(): Map an interrupt on a chip to a virtual IRQ
+ * regmap_irq_get_virq() - Map an interrupt on a chip to a virtual IRQ
*
- * Useful for drivers to request their own IRQs.
+ * @data: regmap irq controller to operate on.
+ * @irq: index of the interrupt requested in the chip IRQs.
*
- * @data: regmap_irq controller to operate on.
- * @irq: index of the interrupt requested in the chip IRQs
+ * Useful for drivers to request their own IRQs.
*/
int regmap_irq_get_virq(struct regmap_irq_chip_data *data, int irq)
{
@@ -818,14 +822,14 @@ int regmap_irq_get_virq(struct regmap_irq_chip_data *data, int irq)
EXPORT_SYMBOL_GPL(regmap_irq_get_virq);
/**
- * regmap_irq_get_domain(): Retrieve the irq_domain for the chip
+ * regmap_irq_get_domain() - Retrieve the irq_domain for the chip
+ *
+ * @data: regmap_irq controller to operate on.
*
* Useful for drivers to request their own IRQs and for integration
* with subsystems. For ease of integration NULL is accepted as a
* domain, allowing devices to just call this even if no domain is
* allocated.
- *
- * @data: regmap_irq controller to operate on.
*/
struct irq_domain *regmap_irq_get_domain(struct regmap_irq_chip_data *data)
{
diff --git a/drivers/base/regmap/regmap.c b/drivers/base/regmap/regmap.c
index ae63bb0875ea..0e770ba8d361 100644
--- a/drivers/base/regmap/regmap.c
+++ b/drivers/base/regmap/regmap.c
@@ -1091,8 +1091,7 @@ static void regmap_field_init(struct regmap_field *rm_field,
}
/**
- * devm_regmap_field_alloc(): Allocate and initialise a register field
- * in a register map.
+ * devm_regmap_field_alloc() - Allocate and initialise a register field.
*
* @dev: Device that will be interacted with
* @regmap: regmap bank in which this register field is located.
@@ -1118,13 +1117,15 @@ struct regmap_field *devm_regmap_field_alloc(struct device *dev,
EXPORT_SYMBOL_GPL(devm_regmap_field_alloc);
/**
- * devm_regmap_field_free(): Free register field allocated using
- * devm_regmap_field_alloc. Usally drivers need not call this function,
- * as the memory allocated via devm will be freed as per device-driver
- * life-cyle.
+ * devm_regmap_field_free() - Free a register field allocated using
+ * devm_regmap_field_alloc.
*
* @dev: Device that will be interacted with
* @field: regmap field which should be freed.
+ *
+ * Free register field allocated using devm_regmap_field_alloc(). Usually
+ * drivers need not call this function, as the memory allocated via devm
+ * will be freed as per device-driver life-cyle.
*/
void devm_regmap_field_free(struct device *dev,
struct regmap_field *field)
@@ -1134,8 +1135,7 @@ void devm_regmap_field_free(struct device *dev,
EXPORT_SYMBOL_GPL(devm_regmap_field_free);
/**
- * regmap_field_alloc(): Allocate and initialise a register field
- * in a register map.
+ * regmap_field_alloc() - Allocate and initialise a register field.
*
* @regmap: regmap bank in which this register field is located.
* @reg_field: Register field with in the bank.
@@ -1159,7 +1159,8 @@ struct regmap_field *regmap_field_alloc(struct regmap *regmap,
EXPORT_SYMBOL_GPL(regmap_field_alloc);
/**
- * regmap_field_free(): Free register field allocated using regmap_field_alloc
+ * regmap_field_free() - Free register field allocated using
+ * regmap_field_alloc.
*
* @field: regmap field which should be freed.
*/
@@ -1170,7 +1171,7 @@ void regmap_field_free(struct regmap_field *field)
EXPORT_SYMBOL_GPL(regmap_field_free);
/**
- * regmap_reinit_cache(): Reinitialise the current register cache
+ * regmap_reinit_cache() - Reinitialise the current register cache
*
* @map: Register map to operate on.
* @config: New configuration. Only the cache data will be used.
@@ -1205,7 +1206,9 @@ int regmap_reinit_cache(struct regmap *map, const struct regmap_config *config)
EXPORT_SYMBOL_GPL(regmap_reinit_cache);
/**
- * regmap_exit(): Free a previously allocated register map
+ * regmap_exit() - Free a previously allocated register map
+ *
+ * @map: Register map to operate on.
*/
void regmap_exit(struct regmap *map)
{
@@ -1245,7 +1248,7 @@ static int dev_get_regmap_match(struct device *dev, void *res, void *data)
}
/**
- * dev_get_regmap(): Obtain the regmap (if any) for a device
+ * dev_get_regmap() - Obtain the regmap (if any) for a device
*
* @dev: Device to retrieve the map for
* @name: Optional name for the register map, usually NULL.
@@ -1268,7 +1271,7 @@ struct regmap *dev_get_regmap(struct device *dev, const char *name)
EXPORT_SYMBOL_GPL(dev_get_regmap);
/**
- * regmap_get_device(): Obtain the device from a regmap
+ * regmap_get_device() - Obtain the device from a regmap
*
* @map: Register map to operate on.
*
@@ -1654,7 +1657,7 @@ int _regmap_write(struct regmap *map, unsigned int reg,
}
/**
- * regmap_write(): Write a value to a single register
+ * regmap_write() - Write a value to a single register
*
* @map: Register map to write to
* @reg: Register to write to
@@ -1681,7 +1684,7 @@ int regmap_write(struct regmap *map, unsigned int reg, unsigned int val)
EXPORT_SYMBOL_GPL(regmap_write);
/**
- * regmap_write_async(): Write a value to a single register asynchronously
+ * regmap_write_async() - Write a value to a single register asynchronously
*
* @map: Register map to write to
* @reg: Register to write to
@@ -1712,7 +1715,7 @@ int regmap_write_async(struct regmap *map, unsigned int reg, unsigned int val)
EXPORT_SYMBOL_GPL(regmap_write_async);
/**
- * regmap_raw_write(): Write raw values to one or more registers
+ * regmap_raw_write() - Write raw values to one or more registers
*
* @map: Register map to write to
* @reg: Initial register to write to
@@ -1750,9 +1753,8 @@ int regmap_raw_write(struct regmap *map, unsigned int reg,
EXPORT_SYMBOL_GPL(regmap_raw_write);
/**
- * regmap_field_update_bits_base():
- * Perform a read/modify/write cycle on the register field
- * with change, async, force option
+ * regmap_field_update_bits_base() - Perform a read/modify/write cycle a
+ * register field.
*
* @field: Register field to write to
* @mask: Bitmask to change
@@ -1761,6 +1763,9 @@ EXPORT_SYMBOL_GPL(regmap_raw_write);
* @async: Boolean indicating asynchronously
* @force: Boolean indicating use force update
*
+ * Perform a read/modify/write cycle on the register field with change,
+ * async, force option.
+ *
* A value of zero will be returned on success, a negative errno will
* be returned in error cases.
*/
@@ -1777,9 +1782,8 @@ int regmap_field_update_bits_base(struct regmap_field *field,
EXPORT_SYMBOL_GPL(regmap_field_update_bits_base);
/**
- * regmap_fields_update_bits_base():
- * Perform a read/modify/write cycle on the register field
- * with change, async, force option
+ * regmap_fields_update_bits_base() - Perform a read/modify/write cycle a
+ * register field with port ID
*
* @field: Register field to write to
* @id: port ID
@@ -1808,8 +1812,8 @@ int regmap_fields_update_bits_base(struct regmap_field *field, unsigned int id,
}
EXPORT_SYMBOL_GPL(regmap_fields_update_bits_base);
-/*
- * regmap_bulk_write(): Write multiple registers to the device
+/**
+ * regmap_bulk_write() - Write multiple registers to the device
*
* @map: Register map to write to
* @reg: First register to be write from
@@ -2174,18 +2178,18 @@ static int _regmap_multi_reg_write(struct regmap *map,
return _regmap_raw_multi_reg_write(map, regs, num_regs);
}
-/*
- * regmap_multi_reg_write(): Write multiple registers to the device
- *
- * where the set of register,value pairs are supplied in any order,
- * possibly not all in a single range.
+/**
+ * regmap_multi_reg_write() - Write multiple registers to the device
*
* @map: Register map to write to
* @regs: Array of structures containing register,value to be written
* @num_regs: Number of registers to write
*
+ * Write multiple registers to the device where the set of register, value
+ * pairs are supplied in any order, possibly not all in a single range.
+ *
* The 'normal' block write mode will send ultimately send data on the
- * target bus as R,V1,V2,V3,..,Vn where successively higer registers are
+ * target bus as R,V1,V2,V3,..,Vn where successively higher registers are
* addressed. However, this alternative block multi write mode will send
* the data as R1,V1,R2,V2,..,Rn,Vn on the target bus. The target device
* must of course support the mode.
@@ -2208,16 +2212,17 @@ int regmap_multi_reg_write(struct regmap *map, const struct reg_sequence *regs,
}
EXPORT_SYMBOL_GPL(regmap_multi_reg_write);
-/*
- * regmap_multi_reg_write_bypassed(): Write multiple registers to the
- * device but not the cache
- *
- * where the set of register are supplied in any order
+/**
+ * regmap_multi_reg_write_bypassed() - Write multiple registers to the
+ * device but not the cache
*
* @map: Register map to write to
* @regs: Array of structures containing register,value to be written
* @num_regs: Number of registers to write
*
+ * Write multiple registers to the device but not the cache where the set
+ * of register are supplied in any order.
+ *
* This function is intended to be used for writing a large block of data
* atomically to the device in single transfer for those I2C client devices
* that implement this alternative block write mode.
@@ -2248,8 +2253,8 @@ int regmap_multi_reg_write_bypassed(struct regmap *map,
EXPORT_SYMBOL_GPL(regmap_multi_reg_write_bypassed);
/**
- * regmap_raw_write_async(): Write raw values to one or more registers
- * asynchronously
+ * regmap_raw_write_async() - Write raw values to one or more registers
+ * asynchronously
*
* @map: Register map to write to
* @reg: Initial register to write to
@@ -2385,7 +2390,7 @@ static int _regmap_read(struct regmap *map, unsigned int reg,
}
/**
- * regmap_read(): Read a value from a single register
+ * regmap_read() - Read a value from a single register
*
* @map: Register map to read from
* @reg: Register to be read from
@@ -2412,7 +2417,7 @@ int regmap_read(struct regmap *map, unsigned int reg, unsigned int *val)
EXPORT_SYMBOL_GPL(regmap_read);
/**
- * regmap_raw_read(): Read raw data from the device
+ * regmap_raw_read() - Read raw data from the device
*
* @map: Register map to read from
* @reg: First register to be read from
@@ -2477,7 +2482,7 @@ int regmap_raw_read(struct regmap *map, unsigned int reg, void *val,
EXPORT_SYMBOL_GPL(regmap_raw_read);
/**
- * regmap_field_read(): Read a value to a single register field
+ * regmap_field_read() - Read a value to a single register field
*
* @field: Register field to read from
* @val: Pointer to store read value
@@ -2502,7 +2507,7 @@ int regmap_field_read(struct regmap_field *field, unsigned int *val)
EXPORT_SYMBOL_GPL(regmap_field_read);
/**
- * regmap_fields_read(): Read a value to a single register field with port ID
+ * regmap_fields_read() - Read a value to a single register field with port ID
*
* @field: Register field to read from
* @id: port ID
@@ -2535,7 +2540,7 @@ int regmap_fields_read(struct regmap_field *field, unsigned int id,
EXPORT_SYMBOL_GPL(regmap_fields_read);
/**
- * regmap_bulk_read(): Read multiple registers from the device
+ * regmap_bulk_read() - Read multiple registers from the device
*
* @map: Register map to read from
* @reg: First register to be read from
@@ -2692,9 +2697,7 @@ static int _regmap_update_bits(struct regmap *map, unsigned int reg,
}
/**
- * regmap_update_bits_base:
- * Perform a read/modify/write cycle on the
- * register map with change, async, force option
+ * regmap_update_bits_base() - Perform a read/modify/write cycle on a register
*
* @map: Register map to update
* @reg: Register to update
@@ -2704,10 +2707,14 @@ static int _regmap_update_bits(struct regmap *map, unsigned int reg,
* @async: Boolean indicating asynchronously
* @force: Boolean indicating use force update
*
- * if async was true,
- * With most buses the read must be done synchronously so this is most
- * useful for devices with a cache which do not need to interact with
- * the hardware to determine the current register value.
+ * Perform a read/modify/write cycle on a register map with change, async, force
+ * options.
+ *
+ * If async is true:
+ *
+ * With most buses the read must be done synchronously so this is most useful
+ * for devices with a cache which do not need to interact with the hardware to
+ * determine the current register value.
*
* Returns zero for success, a negative number on error.
*/
@@ -2765,7 +2772,7 @@ static int regmap_async_is_done(struct regmap *map)
}
/**
- * regmap_async_complete: Ensure all asynchronous I/O has completed.
+ * regmap_async_complete - Ensure all asynchronous I/O has completed.
*
* @map: Map to operate on.
*
@@ -2797,8 +2804,8 @@ int regmap_async_complete(struct regmap *map)
EXPORT_SYMBOL_GPL(regmap_async_complete);
/**
- * regmap_register_patch: Register and apply register updates to be applied
- * on device initialistion
+ * regmap_register_patch - Register and apply register updates to be applied
+ * on device initialistion
*
* @map: Register map to apply updates to.
* @regs: Values to update.
@@ -2855,8 +2862,10 @@ int regmap_register_patch(struct regmap *map, const struct reg_sequence *regs,
}
EXPORT_SYMBOL_GPL(regmap_register_patch);
-/*
- * regmap_get_val_bytes(): Report the size of a register value
+/**
+ * regmap_get_val_bytes() - Report the size of a register value
+ *
+ * @map: Register map to operate on.
*
* Report the size of a register value, mainly intended to for use by
* generic infrastructure built on top of regmap.
@@ -2871,7 +2880,9 @@ int regmap_get_val_bytes(struct regmap *map)
EXPORT_SYMBOL_GPL(regmap_get_val_bytes);
/**
- * regmap_get_max_register(): Report the max register value
+ * regmap_get_max_register() - Report the max register value
+ *
+ * @map: Register map to operate on.
*
* Report the max register value, mainly intended to for use by
* generic infrastructure built on top of regmap.
@@ -2883,7 +2894,9 @@ int regmap_get_max_register(struct regmap *map)
EXPORT_SYMBOL_GPL(regmap_get_max_register);
/**
- * regmap_get_reg_stride(): Report the register address stride
+ * regmap_get_reg_stride() - Report the register address stride
+ *
+ * @map: Register map to operate on.
*
* Report the register address stride, mainly intended to for use by
* generic infrastructure built on top of regmap.
diff --git a/include/linux/regmap.h b/include/linux/regmap.h
index 9adc7b21903d..38a85d50fefd 100644
--- a/include/linux/regmap.h
+++ b/include/linux/regmap.h
@@ -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;
--
2.11.0
Powered by blists - more mailing lists