[PATCH 09/15] pcmcia: Documentation update
Randy Dunlap
randy.dunlap at oracle.com
Fri Sep 17 17:06:33 EDT 2010
On Fri, 3 Sep 2010 12:57:08 +0200 Dominik Brodowski wrote:
> Fill in missing descriptions and update some others for functions in
> pcmcia_resource.c.
>
> Signed-off-by: Dominik Brodowski <linux at dominikbrodowski.net>
kernel-doc notation (beginning with /**) needs to have function parameters
listed also, please. Otherwise it generates warnings when used in docbook.
OK, I see a few of the functions have that, but they have a '-' following
the parameter name instead of a ':'. Please change them to ':'
(but yes, the function name itself is followed by a '-').
> ---
> drivers/pcmcia/pcmcia_resource.c | 93 +++++++++++++++++++++++++++++---------
> 1 files changed, 71 insertions(+), 22 deletions(-)
>
> diff --git a/drivers/pcmcia/pcmcia_resource.c b/drivers/pcmcia/pcmcia_resource.c
> index f778e6c..511ae78 100644
> --- a/drivers/pcmcia/pcmcia_resource.c
> +++ b/drivers/pcmcia/pcmcia_resource.c
> @@ -55,6 +55,10 @@ struct resource *pcmcia_find_mem_region(u_long base, u_long num, u_long align,
> }
>
>
> +/**
> + * release_io_space() - release IO ports allocated with alloc_io_space()
> + *
> + */
missing function params
> static void release_io_space(struct pcmcia_socket *s, struct resource *res)
> {
> resource_size_t num = resource_size(res);
> @@ -80,9 +84,11 @@ static void release_io_space(struct pcmcia_socket *s, struct resource *res)
> }
> }
> }
> -} /* release_io_space */
> +}
>
> -/** alloc_io_space
> +
> +/**
> + * alloc_io_space() - allocate IO ports for use by a PCMCIA device
ditto
> *
> * Special stuff for managing IO windows, because they are scarce
> */
> @@ -134,7 +140,7 @@ static int alloc_io_space(struct pcmcia_socket *s, struct resource *res,
> }
> dev_dbg(&s->dev, "alloc_io_space request result %d: %pR\n", ret, res);
> return ret;
> -} /* alloc_io_space */
> +}
>
>
> /**
> @@ -203,6 +209,13 @@ int pcmcia_write_config_byte(struct pcmcia_device *p_dev, off_t where, u8 val)
> EXPORT_SYMBOL(pcmcia_write_config_byte);
>
>
> +/**
> + * pcmcia_map_mem_page() - modify IO window to point to a different offset
ditto
> + *
> + * pcmcia_map_mem_page() modifies what can be read and written by accessing
> + * an iomem range previously enabled by pcmcia_request_window(), by setting
> + * the card_offset value to @offset.
> + */
> int pcmcia_map_mem_page(struct pcmcia_device *p_dev, struct resource *res,
> unsigned int offset)
> {
> @@ -312,6 +325,16 @@ unlock:
> EXPORT_SYMBOL(pcmcia_fixup_vpp);
>
>
> +/**
> + * pcmcia_release_configuration() - physically disable a PCMCIA device
ditto
> + *
> + * pcmcia_release_configuration() is the 1:1 counterpart to
> + * pcmcia_enable_device(): If a PCMCIA device is no longer used by any
> + * driver, the Vpp voltage is set to 0, IRQs will no longer be generated,
> + * and I/O ranges will be disabled. As pcmcia_release_io() and
> + * pcmcia_release_window() still need to be called, device drivers are
> + * expected to call pcmcia_disable_device() instead.
> + */
> int pcmcia_release_configuration(struct pcmcia_device *p_dev)
> {
> pccard_io_map io = { 0, 0, 0, 0, 1 };
> @@ -346,16 +369,17 @@ int pcmcia_release_configuration(struct pcmcia_device *p_dev)
> mutex_unlock(&s->ops_mutex);
>
> return 0;
> -} /* pcmcia_release_configuration */
> +}
>
>
> -/** pcmcia_release_io
> +/**
> + * pcmcia_release_io() - release I/O allocated by a PCMCIA device
ditto
> *
> - * Release_io() releases the I/O ranges allocated by a client. This
> - * may be invoked some time after a card ejection has already dumped
> - * the actual socket configuration, so if the client is "stale", we
> - * don't bother checking the port ranges against the current socket
> - * values.
> + * pcmcia_release_io() releases the I/O ranges allocated by a PCMCIA
> + * device. This may be invoked some time after a card ejection has
> + * already dumped the actual socket configuration, so if the client is
> + * "stale", we don't bother checking the port ranges against the
> + * current socket values.
> */
> static int pcmcia_release_io(struct pcmcia_device *p_dev)
> {
> @@ -383,10 +407,11 @@ out:
> return ret;
> } /* pcmcia_release_io */
>
> +
> /**
> * pcmcia_release_window() - release reserved iomem for PCMCIA devices
ditto
> *
> - * pcmcia_release_window() releases struct resource *res which was
> + * pcmcia_release_window() releases &struct resource *res which was
> * previously reserved by calling pcmcia_request_window().
> */
> int pcmcia_release_window(struct pcmcia_device *p_dev, struct resource *res)
> @@ -431,9 +456,16 @@ int pcmcia_release_window(struct pcmcia_device *p_dev, struct resource *res)
> } /* pcmcia_release_window */
> EXPORT_SYMBOL(pcmcia_release_window);
>
> +
> /**
> * pcmcia_enable_device() - set up and activate a PCMCIA device
> + * @p_dev - the associated PCMCIA device
> + * @flags - configuration options for this PCMCIA device
* @p_dev: ...
* @flags: ...
> *
> + * pcmcia_enable_device() physically enables a PCMCIA device. It parses
> + * the flags passed to in @flags and stored in @p_dev->flags and sets up
> + * the Vpp voltage, enables the speaker line, I/O ports and store proper
> + * values to configuration registers.
> */
> int pcmcia_enable_device(struct pcmcia_device *p_dev)
> {
> @@ -565,8 +597,9 @@ EXPORT_SYMBOL(pcmcia_enable_device);
>
> /**
> * pcmcia_request_io() - attempt to reserve port ranges for PCMCIA devices
> + * @p_dev - the associated PCMCIA device
* @p_dev: ...
> *
> - * pcmcia_request_io() attepts to reserve the IO port ranges specified in
> + * pcmcia_request_io() attempts to reserve the IO port ranges specified in
> * &struct pcmcia_device @p_dev->resource[0] and @p_dev->resource[1]. The
> * "start" value is the requested start of the IO port resource; "end"
> * reflects the number of ports requested. The number of IO lines requested
> @@ -624,10 +657,10 @@ EXPORT_SYMBOL(pcmcia_request_io);
> /**
> * pcmcia_request_irq() - attempt to request a IRQ for a PCMCIA device
params?
> *
> - * pcmcia_request_irq() is a wrapper around request_irq which will allow
> + * pcmcia_request_irq() is a wrapper around request_irq() which allows
> * the PCMCIA core to clean up the registration in pcmcia_disable_device().
> * Drivers are free to use request_irq() directly, but then they need to
> - * call free_irq themselfves, too. Also, only IRQF_SHARED capable IRQ
> + * call free_irq() themselfves, too. Also, only %IRQF_SHARED capable IRQ
> * handlers are allowed.
> */
> int __must_check pcmcia_request_irq(struct pcmcia_device *p_dev,
> @@ -651,11 +684,11 @@ EXPORT_SYMBOL(pcmcia_request_irq);
> /**
> * pcmcia_request_exclusive_irq() - attempt to request an exclusive IRQ first
function params
> *
> - * pcmcia_request_exclusive_irq() is a wrapper around request_irq which
> + * pcmcia_request_exclusive_irq() is a wrapper around request_irq() which
> * attempts first to request an exclusive IRQ. If it fails, it also accepts
> * a shared IRQ, but prints out a warning. PCMCIA drivers should allow for
> * IRQ sharing and either use request_irq directly (then they need to call
> - * free_irq themselves, too), or the pcmcia_request_irq() function.
> + * free_irq() themselves, too), or the pcmcia_request_irq() function.
> */
> int __must_check
> __pcmcia_request_exclusive_irq(struct pcmcia_device *p_dev,
> @@ -798,10 +831,13 @@ int pcmcia_setup_irq(struct pcmcia_device *p_dev)
>
> /**
> * pcmcia_request_window() - attempt to reserve iomem for PCMCIA devices
> + * @p_dev - the associated PCMCIA device
> + * @res - &struct resource pointing to p_dev->resource[2..5]
> + * @speed - access speed
change to
* @speed: ...
etc.
> *
> * pcmcia_request_window() attepts to reserve an iomem ranges specified in
> - * struct resource *res pointing to one of the entries in
> - * struct pcmcia_device *p_dev->resource[2..5]. The "start" value is the
> + * &struct resource @res pointing to one of the entries in
> + * &struct pcmcia_device @p_dev->resource[2..5]. The "start" value is the
> * requested start of the IO mem resource; "end" reflects the size
> * requested.
> */
> @@ -893,6 +929,19 @@ int pcmcia_request_window(struct pcmcia_device *p_dev, struct resource *res,
> } /* pcmcia_request_window */
> EXPORT_SYMBOL(pcmcia_request_window);
>
> +
> +/**
> + * pcmcia_disable_device() - disable and clean up a PCMCIA device
> + * @p_dev - the associated PCMCIA device
* @p_dev: ...
> + *
> + * pcmcia_disable_device() is the driver-callable counterpart to
> + * pcmcia_enable_device(): If a PCMCIA device is no longer used,
> + * drivers are expected to clean up and disable the device by calling
> + * this function. Any I/O ranges (iomem and ioports) will be released,
> + * the Vpp voltage will be set to 0, and IRQs will no longer be
> + * generated -- at least if there is no other card function (of
> + * multifunction devices) being used.
> + */
> void pcmcia_disable_device(struct pcmcia_device *p_dev)
> {
> int i;
> --
---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***
More information about the linux-pcmcia
mailing list