diff options
| -rw-r--r-- | drivers/pcmcia/pcmcia_resource.c | 111 |
1 files changed, 89 insertions, 22 deletions
diff --git a/drivers/pcmcia/pcmcia_resource.c b/drivers/pcmcia/pcmcia_resource.c index 28de5e6e164c..3194d515c023 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,12 @@ 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() + * @s: pcmcia socket + * @res: resource to release + * + */ static void release_io_space(struct pcmcia_socket *s, struct resource *res) { resource_size_t num = resource_size(res); @@ -80,9 +86,14 @@ 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 + * @s: pcmcia socket + * @res: resource to allocate (begin: begin, end: size) + * @lines: number of IO lines decoded by the PCMCIA card * * Special stuff for managing IO windows, because they are scarce */ @@ -134,7 +145,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 +185,7 @@ static int pcmcia_access_config(struct pcmcia_device *p_dev, mutex_unlock(&s->ops_mutex); return ret; -} /* pcmcia_access_config */ +} /** @@ -203,6 +214,16 @@ 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 iomem window to point to a different offset + * @p_dev: pcmcia device + * @res: iomem resource already enabled by pcmcia_request_window() + * @offset: card_offset to map + * + * 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,12 +242,13 @@ int pcmcia_map_mem_page(struct pcmcia_device *p_dev, struct resource *res, dev_warn(&p_dev->dev, "failed to set_mem_map\n"); mutex_unlock(&s->ops_mutex); return ret; -} /* pcmcia_map_mem_page */ +} EXPORT_SYMBOL(pcmcia_map_mem_page); /** * pcmcia_fixup_iowidth() - reduce io width to 8bit + * @p_dev: pcmcia device * * pcmcia_fixup_iowidth() allows a PCMCIA device driver to reduce the * IO width to 8bit after having called pcmcia_enable_device() @@ -275,6 +297,8 @@ EXPORT_SYMBOL(pcmcia_fixup_iowidth); /** * pcmcia_fixup_vpp() - set Vpp to a new voltage level + * @p_dev: pcmcia device + * @new_vpp: new Vpp voltage * * pcmcia_fixup_vpp() allows a PCMCIA device driver to set Vpp to * a new voltage level between calls to pcmcia_enable_device() @@ -312,6 +336,17 @@ unlock: EXPORT_SYMBOL(pcmcia_fixup_vpp); +/** + * pcmcia_release_configuration() - physically disable a PCMCIA device + * @p_dev: 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 +359,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 +381,18 @@ 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 + * @p_dev: 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 +420,13 @@ out: return ret; } /* pcmcia_release_io */ + /** * pcmcia_release_window() - release reserved iomem for PCMCIA devices + * @p_dev: pcmcia device + * @res: iomem resource to release * - * 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 +471,15 @@ 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 * + * 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 +611,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 @@ -630,11 +677,13 @@ EXPORT_SYMBOL(pcmcia_request_io); /** * pcmcia_request_irq() - attempt to request a IRQ for a PCMCIA device + * @p_dev: the associated PCMCIA device + * @handler: IRQ handler to register * - * 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, @@ -657,12 +706,14 @@ EXPORT_SYMBOL(pcmcia_request_irq); /** * pcmcia_request_exclusive_irq() - attempt to request an exclusive IRQ first + * @p_dev: the associated PCMCIA device + * @handler: IRQ handler to register * - * 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, @@ -805,10 +856,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. */ @@ -900,6 +954,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; |