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

Convert the pcmcia docs to ReST format. Most of the changes here
are trivial.

The conversion is actually:
  - add blank lines and identation in order to identify paragraphs;
  - fix tables markups;
  - add some lists markups;
  - mark literal blocks;
  - adjust title markups.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Dominik Brodowski <linux@dominikbrodowski.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab 2019-06-12 14:52:53 -03:00 committed by Jonathan Corbet
parent 593733ab80
commit 3bdab16c55
8 changed files with 86 additions and 36 deletions

View File

@ -1,3 +1,7 @@
============
Device table
============
Matching of PCMCIA devices to drivers is done using one or more of the Matching of PCMCIA devices to drivers is done using one or more of the
following criteria: following criteria:

View File

@ -1,15 +1,21 @@
==============
Driver changes
==============
This file details changes in 2.6 which affect PCMCIA card driver authors: This file details changes in 2.6 which affect PCMCIA card driver authors:
* pcmcia_loop_config() and autoconfiguration (as of 2.6.36) * 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 pcmcia_loop_config() now sets up certain configuration values
automatically, though the driver may still override the settings automatically, though the driver may still override the settings
in the callback function. The following autoconfiguration options in the callback function. The following autoconfiguration options
are provided at the moment: are provided at the moment:
CONF_AUTO_CHECK_VCC : check for matching Vcc
CONF_AUTO_SET_VPP : set Vpp - CONF_AUTO_CHECK_VCC : check for matching Vcc
CONF_AUTO_AUDIO : auto-enable audio line, if required - CONF_AUTO_SET_VPP : set Vpp
CONF_AUTO_SET_IO : set ioport resources (->resource[0,1]) - CONF_AUTO_AUDIO : auto-enable audio line, if required
CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2]) - 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 -> pcmcia_enable_device (as of 2.6.36)
pcmcia_request_configuration() got renamed to pcmcia_enable_device(), pcmcia_request_configuration() got renamed to pcmcia_enable_device(),
@ -19,14 +25,14 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* pcmcia_request_window changes (as of 2.6.36) * pcmcia_request_window changes (as of 2.6.36)
Instead of win_req_t, drivers are now requested to fill out 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 ranges. After a call to pcmcia_request_window(), the regions found there
are reserved and may be used immediately -- until pcmcia_release_window() are reserved and may be used immediately -- until pcmcia_release_window()
is called. is called.
* pcmcia_request_io changes (as of 2.6.36) * pcmcia_request_io changes (as of 2.6.36)
Instead of io_req_t, drivers are now requested to fill out 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 ranges. After a call to pcmcia_request_io(), the ports found there
are reserved, after calling pcmcia_request_configuration(), they may are reserved, after calling pcmcia_request_configuration(), they may
be used. be used.
@ -42,7 +48,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* New IRQ request rules (as of 2.6.35) * New IRQ request rules (as of 2.6.35)
Instead of the old pcmcia_request_irq() interface, drivers may now Instead of the old pcmcia_request_irq() interface, drivers may now
choose between: 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 - use pcmcia_request_irq(p_dev, handler_t); the PCMCIA core will
clean up automatically on calls to pcmcia_disable_device() or clean up automatically on calls to pcmcia_disable_device() or
device ejection. device ejection.
@ -72,13 +79,16 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
exports for them were removed. exports for them were removed.
* Unify detach and REMOVAL event code, as well as attach and INSERTION * 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); void (*remove) (struct pcmcia_device *dev);
int (*probe) (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 (*suspend) (struct pcmcia_device *dev);
int (*resume) (struct pcmcia_device *dev); int (*resume) (struct pcmcia_device *dev);
should be initialized in struct pcmcia_driver, and handle should be initialized in struct pcmcia_driver, and handle
(SUSPEND == RESET_PHYSICAL) and (RESUME == CARD_RESET) events (SUSPEND == RESET_PHYSICAL) and (RESUME == CARD_RESET) events
@ -117,7 +127,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* core functions no longer available (as of 2.6.11) * core functions no longer available (as of 2.6.11)
The following functions have been removed from the kernel source The following functions have been removed from the kernel source
because they are unused by all in-kernel drivers, and no external 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_first_region()
pcmcia_get_next_region() pcmcia_get_next_region()
pcmcia_modify_window() pcmcia_modify_window()

View File

@ -1,16 +1,16 @@
=============
PCMCIA Driver PCMCIA Driver
------------- =============
sysfs sysfs
----- -----
New PCMCIA IDs may be added to a device driver pcmcia_device_id table at 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 \ 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]" > \ prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \
/sys/bus/pcmcia/drivers/{driver}/new_id /sys/bus/pcmcia/drivers/{driver}/new_id
All fields are passed in as hexadecimal values (no leading 0x). All fields are passed in as hexadecimal values (no leading 0x).
The meaning is described in the PCMCIA specification, the match_flags is The meaning is described in the PCMCIA specification, the match_flags is
@ -22,9 +22,9 @@ PCMCIA device listed in its (newly updated) pcmcia_device_id list.
A common use-case is to add a new device according to the manufacturer ID 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). 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" > \ echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \
/sys/bus/pcmcia/drivers/{driver}/new_id /sys/bus/pcmcia/drivers/{driver}/new_id
after loading the driver. after loading the driver.

View File

@ -0,0 +1,20 @@
:orphan:
======
pcmcia
======
.. toctree::
:maxdepth: 1
driver
devicetable
locking
driver-changes
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -1,3 +1,7 @@
=======
Locking
=======
This file explains the locking and exclusion scheme used in the PCCARD This file explains the locking and exclusion scheme used in the PCCARD
and PCMCIA subsystems. and PCMCIA subsystems.
@ -5,16 +9,21 @@ and PCMCIA subsystems.
A) Overview, Locking Hierarchy: A) Overview, Locking Hierarchy:
=============================== ===============================
pcmcia_socket_list_rwsem - protects only the list of sockets pcmcia_socket_list_rwsem
- skt_mutex - serializes card insert / ejection - protects only the list of sockets
- ops_mutex - serializes socket operation
- skt_mutex
- serializes card insert / ejection
- ops_mutex
- serializes socket operation
B) Exclusion B) Exclusion
============ ============
The following functions and callbacks to struct pcmcia_socket must 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() socket_detect_change()
send_event() send_event()
@ -31,7 +40,7 @@ be called with "skt_mutex" held:
struct pcmcia_callback *callback struct pcmcia_callback *callback
The following functions and callbacks to struct pcmcia_socket must 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_reset()
socket_setup() socket_setup()
@ -39,7 +48,7 @@ be called with "ops_mutex" held:
struct pccard_operations *ops struct pccard_operations *ops
struct pccard_resource_ops *resource_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. called with "ops_mutex" held.
@ -60,19 +69,23 @@ The resource_ops and their data are protected by ops_mutex.
The "main" struct pcmcia_socket is protected as follows (read-only fields The "main" struct pcmcia_socket is protected as follows (read-only fields
or single-use fields not mentioned): or single-use fields not mentioned):
- by pcmcia_socket_list_rwsem: - by pcmcia_socket_list_rwsem::
struct list_head socket_list; struct list_head socket_list;
- by thread_lock: - by thread_lock::
unsigned int thread_events; unsigned int thread_events;
- by skt_mutex: - by skt_mutex::
u_int suspended_state; u_int suspended_state;
void (*tune_bridge); void (*tune_bridge);
struct pcmcia_callback *callback; struct pcmcia_callback *callback;
int resume_status; int resume_status;
- by ops_mutex: - by ops_mutex::
socket_state_t socket; socket_state_t socket;
u_int state; u_int state;
u_short lock_count; u_short lock_count;
@ -100,7 +113,8 @@ The "main" struct pcmcia_device is protected as follows (read-only fields
or single-use fields not mentioned): or single-use fields not mentioned):
- by pcmcia_socket->ops_mutex: - by pcmcia_socket->ops_mutex::
struct list_head socket_device_list; struct list_head socket_device_list;
struct config_t *function_config; struct config_t *function_config;
u16 _irq:1; u16 _irq:1;
@ -111,7 +125,8 @@ or single-use fields not mentioned):
u16 suspended:1; u16 suspended:1;
u16 _removed:1; u16 _removed:1;
- by the PCMCIA driver: - by the PCMCIA driver::
io_req_t io; io_req_t io;
irq_req_t irq; irq_req_t irq;
config_req_t conf; config_req_t conf;

View File

@ -67,7 +67,7 @@ static void pcmcia_check_driver(struct pcmcia_driver *p_drv)
"be 0x%x\n", p_drv->name, did->prod_id[i], "be 0x%x\n", p_drv->name, did->prod_id[i],
did->prod_id_hash[i], hash); did->prod_id_hash[i], hash);
printk(KERN_DEBUG "pcmcia: see " printk(KERN_DEBUG "pcmcia: see "
"Documentation/pcmcia/devicetable.txt for " "Documentation/pcmcia/devicetable.rst for "
"details\n"); "details\n");
} }
did++; did++;

View File

@ -39,7 +39,7 @@ struct config_t;
struct net_device; struct net_device;
/* dynamic device IDs for PCMCIA device drivers. See /* dynamic device IDs for PCMCIA device drivers. See
* Documentation/pcmcia/driver.txt for details. * Documentation/pcmcia/driver.rst for details.
*/ */
struct pcmcia_dynids { struct pcmcia_dynids {
struct mutex lock; struct mutex lock;

View File

@ -190,7 +190,7 @@ struct pcmcia_socket {
unsigned int sysfs_events; unsigned int sysfs_events;
/* For the non-trivial interaction between these locks, /* For the non-trivial interaction between these locks,
* see Documentation/pcmcia/locking.txt */ * see Documentation/pcmcia/locking.rst */
struct mutex skt_mutex; struct mutex skt_mutex;
struct mutex ops_mutex; struct mutex ops_mutex;