[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