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
following criteria:

View File

@ -1,15 +1,21 @@
==============
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(),
@ -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)
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.
@ -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)
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.
@ -72,13 +79,16 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
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
@ -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)
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()

View File

@ -1,16 +1,16 @@
=============
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]" > \
/sys/bus/pcmcia/drivers/{driver}/new_id
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]" > \
/sys/bus/pcmcia/drivers/{driver}/new_id
All fields are passed in as hexadecimal values (no leading 0x).
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
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
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
and PCMCIA subsystems.
@ -5,16 +9,21 @@ 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()
@ -31,7 +40,7 @@ be called with "skt_mutex" held:
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()
@ -39,7 +48,7 @@ be called with "ops_mutex" held:
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.
@ -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
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;
@ -100,7 +113,8 @@ The "main" struct pcmcia_device is protected as follows (read-only fields
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;
@ -111,7 +125,8 @@ or single-use fields not mentioned):
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;

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],
did->prod_id_hash[i], hash);
printk(KERN_DEBUG "pcmcia: see "
"Documentation/pcmcia/devicetable.txt for "
"Documentation/pcmcia/devicetable.rst for "
"details\n");
}
did++;

View File

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

View File

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