[PATCH 09/15] pcmcia: Documentation update
Dominik Brodowski
linux at dominikbrodowski.net
Fri Sep 3 06:57:08 EDT 2010
Fill in missing descriptions and update some others for functions in
pcmcia_resource.c.
Signed-off-by: Dominik Brodowski <linux at dominikbrodowski.net>
---
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
@@ -6,7 +6,7 @@
* are Copyright (C) 1999 David A. Hinds. All Rights Reserved.
*
* Copyright (C) 1999 David A. Hinds
- * Copyright (C) 2004-2005 Dominik Brodowski
+ * Copyright (C) 2004-2010 Dominik Brodowski
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
@@ -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()
+ *
+ */
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
*
* 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 */
+}
/**
@@ -174,7 +180,7 @@ static int pcmcia_access_config(struct pcmcia_device *p_dev,
mutex_unlock(&s->ops_mutex);
return ret;
-} /* pcmcia_access_config */
+}
/**
@@ -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
+ *
+ * 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)
{
@@ -221,7 +234,7 @@ int pcmcia_map_mem_page(struct pcmcia_device *p_dev, struct resource *res,
dev_warn(&s->dev, "failed to set_mem_map\n");
mutex_unlock(&s->ops_mutex);
return ret;
-} /* pcmcia_map_mem_page */
+}
EXPORT_SYMBOL(pcmcia_map_mem_page);
@@ -312,6 +325,16 @@ unlock:
EXPORT_SYMBOL(pcmcia_fixup_vpp);
+/**
+ * pcmcia_release_configuration() - physically disable a PCMCIA device
+ *
+ * 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 };
@@ -324,7 +347,7 @@ int pcmcia_release_configuration(struct pcmcia_device *p_dev)
if (p_dev->_locked) {
p_dev->_locked = 0;
if (--(s->lock_count) == 0) {
- s->socket.flags = SS_OUTPUT_ENA; /* Is this correct? */
+ s->socket.flags = SS_OUTPUT_ENA; /* Is this correct? */
s->socket.Vpp = 0;
s->socket.io_irq = 0;
s->ops->set_socket(s, &s->socket);
@@ -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
*
- * 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
*
- * 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
*
+ * 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
*
- * 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
*
- * 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
*
- * 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
*
* 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
+ *
+ * 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;
--
1.7.0.4
More information about the linux-pcmcia
mailing list