pcmcia: Documentation update (9485ee14) · Commits · EulixOS / Software / Kernel

drivers/pcmcia/pcmcia_resource.c

+89 −22

Original line number	Diff line number	Diff line
		@@ -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 @@ int pcmcia_fixup_vpp(struct pcmcia_device *p_dev, unsigned char new_vpp)
		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 };
		@@ -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 @@ static int pcmcia_release_io(struct pcmcia_device *p_dev)
		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;