lkml.org 
[lkml]   [2017]   [Jan]   [12]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH] regmap: Fixup the kernel-doc comments on functions/structures
    Date
    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>
    ---

    Apologies for the giant patch, let me know if you want it split
    up into a patch per file or something like that, but I figured
    since it doesn't touch any actual code and is mostly fairly
    mechanical one patch seemed simplest.

    Thanks,
    Charles

    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 4e58256..b0a0dcf 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 ec26247..cd54189 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: &regmap_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 &regmap_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: &regmap_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 900a319f..b9a779a 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 f667313..e886492 100644
    --- a/include/linux/regmap.h
    +++ b/include/linux/regmap.h
    @@ -40,12 +40,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;
    @@ -53,12 +54,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;
    @@ -98,6 +101,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
    @@ -146,8 +150,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
    @@ -159,16 +163,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;
    @@ -181,7 +187,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.
    @@ -314,22 +320,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;
    @@ -372,7 +380,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
    @@ -385,6 +394,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.
    @@ -514,7 +527,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
    @@ -532,7 +545,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
    @@ -545,9 +558,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
    @@ -558,8 +571,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
    @@ -570,8 +584,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
    @@ -582,7 +597,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
    @@ -597,7 +612,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
    @@ -610,7 +625,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
    @@ -624,7 +639,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
    @@ -641,7 +656,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
    @@ -655,9 +670,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
    @@ -669,8 +684,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
    @@ -682,8 +698,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
    @@ -695,7 +712,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
    @@ -711,7 +728,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
    @@ -725,7 +742,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
    @@ -800,7 +817,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.
    @@ -841,7 +858,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.
    @@ -861,9 +878,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.
    *
    @@ -897,6 +912,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.1.4
    \
     
     \ /
      Last update: 2017-01-12 12:17    [W:0.080 / U:1.880 seconds]
    ©2003-2017 Jasper Spaans. hosted at Digital OceanAdvertise on this site