docs: pcmcia: convert docs to ReST and rename to *.rst

============

Device table

============

Matching of PCMCIA devices to drivers is done using one or more of the

following criteria:

==============

Driver changes

==============

This file details changes in 2.6 which affect PCMCIA card driver authors:

* pcmcia_loop_config() and autoconfiguration (as of 2.6.36)

   If struct pcmcia_device *p_dev->config_flags is set accordingly,

   If `struct pcmcia_device *p_dev->config_flags` is set accordingly,

   pcmcia_loop_config() now sets up certain configuration values

   automatically, though the driver may still override the settings

   in the callback function. The following autoconfiguration options

   are provided at the moment:

	CONF_AUTO_CHECK_VCC : check for matching Vcc

	CONF_AUTO_SET_VPP   : set Vpp

	CONF_AUTO_AUDIO     : auto-enable audio line, if required

	CONF_AUTO_SET_IO    : set ioport resources (->resource[0,1])

	CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2])

	- CONF_AUTO_CHECK_VCC : check for matching Vcc

	- CONF_AUTO_SET_VPP   : set Vpp

	- CONF_AUTO_AUDIO     : auto-enable audio line, if required

	- CONF_AUTO_SET_IO    : set ioport resources (->resource[0,1])

	- CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2])

* pcmcia_request_configuration -> pcmcia_enable_device (as of 2.6.36)

   pcmcia_request_configuration() got renamed to pcmcia_enable_device(),

* pcmcia_request_window changes (as of 2.6.36)

   Instead of win_req_t, drivers are now requested to fill out

   struct pcmcia_device *p_dev->resource[2,3,4,5] for up to four ioport

   `struct pcmcia_device *p_dev->resource[2,3,4,5]` for up to four ioport

   ranges. After a call to pcmcia_request_window(), the regions found there

   are reserved and may be used immediately -- until pcmcia_release_window()

   is called.

* pcmcia_request_io changes (as of 2.6.36)

   Instead of io_req_t, drivers are now requested to fill out

   struct pcmcia_device *p_dev->resource[0,1] for up to two ioport

   `struct pcmcia_device *p_dev->resource[0,1]` for up to two ioport

   ranges. After a call to pcmcia_request_io(), the ports found there

   are reserved, after calling pcmcia_request_configuration(), they may

   be used.

* New IRQ request rules (as of 2.6.35)

   Instead of the old pcmcia_request_irq() interface, drivers may now

   choose between:

   - calling request_irq/free_irq directly. Use the IRQ from *p_dev->irq.

   - calling request_irq/free_irq directly. Use the IRQ from `*p_dev->irq`.

   - use pcmcia_request_irq(p_dev, handler_t); the PCMCIA core will

     clean up automatically on calls to pcmcia_disable_device() or

     device ejection.

   exports for them were removed.

* Unify detach and REMOVAL event code, as well as attach and INSERTION

  code (as of 2.6.16)

  code (as of 2.6.16)::

       void (*remove)          (struct pcmcia_device *dev);

       int (*probe)            (struct pcmcia_device *dev);

* Move suspend, resume and reset out of event handler (as of 2.6.16)

* Move suspend, resume and reset out of event handler (as of 2.6.16)::

       int (*suspend)          (struct pcmcia_device *dev);

       int (*resume)           (struct pcmcia_device *dev);

  should be initialized in struct pcmcia_driver, and handle

  (SUSPEND == RESET_PHYSICAL) and (RESUME == CARD_RESET) events

* core functions no longer available (as of 2.6.11)

   The following functions have been removed from the kernel source

   because they are unused by all in-kernel drivers, and no external

   driver was reported to rely on them:

   driver was reported to rely on them::

	pcmcia_get_first_region()

	pcmcia_get_next_region()

	pcmcia_modify_window()

=============

PCMCIA Driver

-------------

=============

sysfs

-----

New PCMCIA IDs may be added to a device driver pcmcia_device_id table at

runtime as shown below:

runtime as shown below::

  echo "match_flags manf_id card_id func_id function device_no \

  prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \

A common use-case is to add a new device according to the manufacturer ID

and the card ID (form the manf_id and card_id file in the device tree).

For this, just use:

For this, just use::

  echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \

    /sys/bus/pcmcia/drivers/{driver}/new_id

:orphan:

======

pcmcia

======

.. toctree::

    :maxdepth: 1

    driver

    devicetable

    locking

    driver-changes

.. only::  subproject and html

   Indices

   =======

   * :ref:`genindex`

=======

Locking

=======

This file explains the locking and exclusion scheme used in the PCCARD

and PCMCIA subsystems.

A) Overview, Locking Hierarchy:

===============================

pcmcia_socket_list_rwsem	- protects only the list of sockets

- skt_mutex			- serializes card insert / ejection

  - ops_mutex			- serializes socket operation

pcmcia_socket_list_rwsem

	- protects only the list of sockets

- skt_mutex

	- serializes card insert / ejection

  - ops_mutex

	- serializes socket operation

B) Exclusion

============

The following functions and callbacks to struct pcmcia_socket must

be called with "skt_mutex" held:

be called with "skt_mutex" held::

	socket_detect_change()

	send_event()

	struct pcmcia_callback	*callback

The following functions and callbacks to struct pcmcia_socket must

be called with "ops_mutex" held:

be called with "ops_mutex" held::

	socket_reset()

	socket_setup()

	struct pccard_operations	*ops

	struct pccard_resource_ops	*resource_ops;

Note that send_event() and struct pcmcia_callback *callback must not be

Note that send_event() and `struct pcmcia_callback *callback` must not be

called with "ops_mutex" held.

The "main" struct pcmcia_socket is protected as follows (read-only fields

or single-use fields not mentioned):

- by pcmcia_socket_list_rwsem:

- by pcmcia_socket_list_rwsem::

	struct list_head	socket_list;

- by thread_lock:

- by thread_lock::

	unsigned int		thread_events;

- by skt_mutex:

- by skt_mutex::

	u_int			suspended_state;

	void			(*tune_bridge);

	struct pcmcia_callback	*callback;

	int			resume_status;

- by ops_mutex:

- by ops_mutex::

	socket_state_t		socket;

	u_int			state;

	u_short			lock_count;

or single-use fields not mentioned):

- by pcmcia_socket->ops_mutex:

- by pcmcia_socket->ops_mutex::

	struct list_head	socket_device_list;

	struct config_t		*function_config;

	u16			_irq:1;

	u16			suspended:1;

	u16			_removed:1;

- by the PCMCIA driver:

- by the PCMCIA driver::

	io_req_t		io;

	irq_req_t		irq;

	config_req_t		conf;