summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+samsung@kernel.org>2019-06-12 13:52:53 -0400
committerJonathan Corbet <corbet@lwn.net>2019-06-14 16:23:35 -0400
commit3bdab16c55f57a24245c97d707241dd9b48d1a91 (patch)
treecca861d5430a6c3092bc1a2f1869d9ed13e454e7
parent593733ab80ac2c607acc1fc3fbaba5031d38253a (diff)
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>
-rw-r--r--Documentation/pcmcia/devicetable.rst (renamed from Documentation/pcmcia/devicetable.txt)4
-rw-r--r--Documentation/pcmcia/driver-changes.rst (renamed from Documentation/pcmcia/driver-changes.txt)35
-rw-r--r--Documentation/pcmcia/driver.rst (renamed from Documentation/pcmcia/driver.txt)18
-rw-r--r--Documentation/pcmcia/index.rst20
-rw-r--r--Documentation/pcmcia/locking.rst (renamed from Documentation/pcmcia/locking.txt)39
-rw-r--r--drivers/pcmcia/ds.c2
-rw-r--r--include/pcmcia/ds.h2
-rw-r--r--include/pcmcia/ss.h2
8 files changed, 86 insertions, 36 deletions
diff --git a/Documentation/pcmcia/devicetable.txt b/Documentation/pcmcia/devicetable.rst
index 5f3e00ab54c4..fd1d60d12ca1 100644
--- a/Documentation/pcmcia/devicetable.txt
+++ b/Documentation/pcmcia/devicetable.rst
@@ -1,3 +1,7 @@
1============
2Device table
3============
4
1Matching of PCMCIA devices to drivers is done using one or more of the 5Matching of PCMCIA devices to drivers is done using one or more of the
2following criteria: 6following criteria:
3 7
diff --git a/Documentation/pcmcia/driver-changes.txt b/Documentation/pcmcia/driver-changes.rst
index 78355c4c268a..33fe9ebec049 100644
--- a/Documentation/pcmcia/driver-changes.txt
+++ b/Documentation/pcmcia/driver-changes.rst
@@ -1,15 +1,21 @@
1==============
2Driver changes
3==============
4
1This file details changes in 2.6 which affect PCMCIA card driver authors: 5This file details changes in 2.6 which affect PCMCIA card driver authors:
6
2* pcmcia_loop_config() and autoconfiguration (as of 2.6.36) 7* pcmcia_loop_config() and autoconfiguration (as of 2.6.36)
3 If struct pcmcia_device *p_dev->config_flags is set accordingly, 8 If `struct pcmcia_device *p_dev->config_flags` is set accordingly,
4 pcmcia_loop_config() now sets up certain configuration values 9 pcmcia_loop_config() now sets up certain configuration values
5 automatically, though the driver may still override the settings 10 automatically, though the driver may still override the settings
6 in the callback function. The following autoconfiguration options 11 in the callback function. The following autoconfiguration options
7 are provided at the moment: 12 are provided at the moment:
8 CONF_AUTO_CHECK_VCC : check for matching Vcc 13
9 CONF_AUTO_SET_VPP : set Vpp 14 - CONF_AUTO_CHECK_VCC : check for matching Vcc
10 CONF_AUTO_AUDIO : auto-enable audio line, if required 15 - CONF_AUTO_SET_VPP : set Vpp
11 CONF_AUTO_SET_IO : set ioport resources (->resource[0,1]) 16 - CONF_AUTO_AUDIO : auto-enable audio line, if required
12 CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2]) 17 - CONF_AUTO_SET_IO : set ioport resources (->resource[0,1])
18 - CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2])
13 19
14* pcmcia_request_configuration -> pcmcia_enable_device (as of 2.6.36) 20* pcmcia_request_configuration -> pcmcia_enable_device (as of 2.6.36)
15 pcmcia_request_configuration() got renamed to pcmcia_enable_device(), 21 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:
19 25
20* pcmcia_request_window changes (as of 2.6.36) 26* pcmcia_request_window changes (as of 2.6.36)
21 Instead of win_req_t, drivers are now requested to fill out 27 Instead of win_req_t, drivers are now requested to fill out
22 struct pcmcia_device *p_dev->resource[2,3,4,5] for up to four ioport 28 `struct pcmcia_device *p_dev->resource[2,3,4,5]` for up to four ioport
23 ranges. After a call to pcmcia_request_window(), the regions found there 29 ranges. After a call to pcmcia_request_window(), the regions found there
24 are reserved and may be used immediately -- until pcmcia_release_window() 30 are reserved and may be used immediately -- until pcmcia_release_window()
25 is called. 31 is called.
26 32
27* pcmcia_request_io changes (as of 2.6.36) 33* pcmcia_request_io changes (as of 2.6.36)
28 Instead of io_req_t, drivers are now requested to fill out 34 Instead of io_req_t, drivers are now requested to fill out
29 struct pcmcia_device *p_dev->resource[0,1] for up to two ioport 35 `struct pcmcia_device *p_dev->resource[0,1]` for up to two ioport
30 ranges. After a call to pcmcia_request_io(), the ports found there 36 ranges. After a call to pcmcia_request_io(), the ports found there
31 are reserved, after calling pcmcia_request_configuration(), they may 37 are reserved, after calling pcmcia_request_configuration(), they may
32 be used. 38 be used.
@@ -42,7 +48,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
42* New IRQ request rules (as of 2.6.35) 48* New IRQ request rules (as of 2.6.35)
43 Instead of the old pcmcia_request_irq() interface, drivers may now 49 Instead of the old pcmcia_request_irq() interface, drivers may now
44 choose between: 50 choose between:
45 - calling request_irq/free_irq directly. Use the IRQ from *p_dev->irq. 51
52 - calling request_irq/free_irq directly. Use the IRQ from `*p_dev->irq`.
46 - use pcmcia_request_irq(p_dev, handler_t); the PCMCIA core will 53 - use pcmcia_request_irq(p_dev, handler_t); the PCMCIA core will
47 clean up automatically on calls to pcmcia_disable_device() or 54 clean up automatically on calls to pcmcia_disable_device() or
48 device ejection. 55 device ejection.
@@ -72,13 +79,16 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
72 exports for them were removed. 79 exports for them were removed.
73 80
74* Unify detach and REMOVAL event code, as well as attach and INSERTION 81* Unify detach and REMOVAL event code, as well as attach and INSERTION
75 code (as of 2.6.16) 82 code (as of 2.6.16)::
83
76 void (*remove) (struct pcmcia_device *dev); 84 void (*remove) (struct pcmcia_device *dev);
77 int (*probe) (struct pcmcia_device *dev); 85 int (*probe) (struct pcmcia_device *dev);
78 86
79* Move suspend, resume and reset out of event handler (as of 2.6.16) 87* Move suspend, resume and reset out of event handler (as of 2.6.16)::
88
80 int (*suspend) (struct pcmcia_device *dev); 89 int (*suspend) (struct pcmcia_device *dev);
81 int (*resume) (struct pcmcia_device *dev); 90 int (*resume) (struct pcmcia_device *dev);
91
82 should be initialized in struct pcmcia_driver, and handle 92 should be initialized in struct pcmcia_driver, and handle
83 (SUSPEND == RESET_PHYSICAL) and (RESUME == CARD_RESET) events 93 (SUSPEND == RESET_PHYSICAL) and (RESUME == CARD_RESET) events
84 94
@@ -117,7 +127,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
117* core functions no longer available (as of 2.6.11) 127* core functions no longer available (as of 2.6.11)
118 The following functions have been removed from the kernel source 128 The following functions have been removed from the kernel source
119 because they are unused by all in-kernel drivers, and no external 129 because they are unused by all in-kernel drivers, and no external
120 driver was reported to rely on them: 130 driver was reported to rely on them::
131
121 pcmcia_get_first_region() 132 pcmcia_get_first_region()
122 pcmcia_get_next_region() 133 pcmcia_get_next_region()
123 pcmcia_modify_window() 134 pcmcia_modify_window()
diff --git a/Documentation/pcmcia/driver.txt b/Documentation/pcmcia/driver.rst
index 0ac167920778..5c4fe84d51c1 100644
--- a/Documentation/pcmcia/driver.txt
+++ b/Documentation/pcmcia/driver.rst
@@ -1,16 +1,16 @@
1=============
1PCMCIA Driver 2PCMCIA Driver
2------------- 3=============
3
4 4
5sysfs 5sysfs
6----- 6-----
7 7
8New PCMCIA IDs may be added to a device driver pcmcia_device_id table at 8New PCMCIA IDs may be added to a device driver pcmcia_device_id table at
9runtime as shown below: 9runtime as shown below::
10 10
11echo "match_flags manf_id card_id func_id function device_no \ 11 echo "match_flags manf_id card_id func_id function device_no \
12prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \ 12 prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \
13/sys/bus/pcmcia/drivers/{driver}/new_id 13 /sys/bus/pcmcia/drivers/{driver}/new_id
14 14
15All fields are passed in as hexadecimal values (no leading 0x). 15All fields are passed in as hexadecimal values (no leading 0x).
16The meaning is described in the PCMCIA specification, the match_flags is 16The 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.
22 22
23A common use-case is to add a new device according to the manufacturer ID 23A common use-case is to add a new device according to the manufacturer ID
24and the card ID (form the manf_id and card_id file in the device tree). 24and the card ID (form the manf_id and card_id file in the device tree).
25For this, just use: 25For this, just use::
26 26
27echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \ 27 echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \
28 /sys/bus/pcmcia/drivers/{driver}/new_id 28 /sys/bus/pcmcia/drivers/{driver}/new_id
29 29
30after loading the driver. 30after loading the driver.
diff --git a/Documentation/pcmcia/index.rst b/Documentation/pcmcia/index.rst
new file mode 100644
index 000000000000..779c8527109e
--- /dev/null
+++ b/Documentation/pcmcia/index.rst
@@ -0,0 +1,20 @@
1:orphan:
2
3======
4pcmcia
5======
6
7.. toctree::
8 :maxdepth: 1
9
10 driver
11 devicetable
12 locking
13 driver-changes
14
15.. only:: subproject and html
16
17 Indices
18 =======
19
20 * :ref:`genindex`
diff --git a/Documentation/pcmcia/locking.txt b/Documentation/pcmcia/locking.rst
index b2c9b478906b..e35257139c89 100644
--- a/Documentation/pcmcia/locking.txt
+++ b/Documentation/pcmcia/locking.rst
@@ -1,3 +1,7 @@
1=======
2Locking
3=======
4
1This file explains the locking and exclusion scheme used in the PCCARD 5This file explains the locking and exclusion scheme used in the PCCARD
2and PCMCIA subsystems. 6and PCMCIA subsystems.
3 7
@@ -5,16 +9,21 @@ and PCMCIA subsystems.
5A) Overview, Locking Hierarchy: 9A) Overview, Locking Hierarchy:
6=============================== 10===============================
7 11
8pcmcia_socket_list_rwsem - protects only the list of sockets 12pcmcia_socket_list_rwsem
9- skt_mutex - serializes card insert / ejection 13 - protects only the list of sockets
10 - ops_mutex - serializes socket operation 14
15- skt_mutex
16 - serializes card insert / ejection
17
18 - ops_mutex
19 - serializes socket operation
11 20
12 21
13B) Exclusion 22B) Exclusion
14============ 23============
15 24
16The following functions and callbacks to struct pcmcia_socket must 25The following functions and callbacks to struct pcmcia_socket must
17be called with "skt_mutex" held: 26be called with "skt_mutex" held::
18 27
19 socket_detect_change() 28 socket_detect_change()
20 send_event() 29 send_event()
@@ -31,7 +40,7 @@ be called with "skt_mutex" held:
31 struct pcmcia_callback *callback 40 struct pcmcia_callback *callback
32 41
33The following functions and callbacks to struct pcmcia_socket must 42The following functions and callbacks to struct pcmcia_socket must
34be called with "ops_mutex" held: 43be called with "ops_mutex" held::
35 44
36 socket_reset() 45 socket_reset()
37 socket_setup() 46 socket_setup()
@@ -39,7 +48,7 @@ be called with "ops_mutex" held:
39 struct pccard_operations *ops 48 struct pccard_operations *ops
40 struct pccard_resource_ops *resource_ops; 49 struct pccard_resource_ops *resource_ops;
41 50
42Note that send_event() and struct pcmcia_callback *callback must not be 51Note that send_event() and `struct pcmcia_callback *callback` must not be
43called with "ops_mutex" held. 52called with "ops_mutex" held.
44 53
45 54
@@ -60,19 +69,23 @@ The resource_ops and their data are protected by ops_mutex.
60The "main" struct pcmcia_socket is protected as follows (read-only fields 69The "main" struct pcmcia_socket is protected as follows (read-only fields
61or single-use fields not mentioned): 70or single-use fields not mentioned):
62 71
63- by pcmcia_socket_list_rwsem: 72- by pcmcia_socket_list_rwsem::
73
64 struct list_head socket_list; 74 struct list_head socket_list;
65 75
66- by thread_lock: 76- by thread_lock::
77
67 unsigned int thread_events; 78 unsigned int thread_events;
68 79
69- by skt_mutex: 80- by skt_mutex::
81
70 u_int suspended_state; 82 u_int suspended_state;
71 void (*tune_bridge); 83 void (*tune_bridge);
72 struct pcmcia_callback *callback; 84 struct pcmcia_callback *callback;
73 int resume_status; 85 int resume_status;
74 86
75- by ops_mutex: 87- by ops_mutex::
88
76 socket_state_t socket; 89 socket_state_t socket;
77 u_int state; 90 u_int state;
78 u_short lock_count; 91 u_short lock_count;
@@ -100,7 +113,8 @@ The "main" struct pcmcia_device is protected as follows (read-only fields
100or single-use fields not mentioned): 113or single-use fields not mentioned):
101 114
102 115
103- by pcmcia_socket->ops_mutex: 116- by pcmcia_socket->ops_mutex::
117
104 struct list_head socket_device_list; 118 struct list_head socket_device_list;
105 struct config_t *function_config; 119 struct config_t *function_config;
106 u16 _irq:1; 120 u16 _irq:1;
@@ -111,7 +125,8 @@ or single-use fields not mentioned):
111 u16 suspended:1; 125 u16 suspended:1;
112 u16 _removed:1; 126 u16 _removed:1;
113 127
114- by the PCMCIA driver: 128- by the PCMCIA driver::
129
115 io_req_t io; 130 io_req_t io;
116 irq_req_t irq; 131 irq_req_t irq;
117 config_req_t conf; 132 config_req_t conf;
diff --git a/drivers/pcmcia/ds.c b/drivers/pcmcia/ds.c
index a9258f641cee..5230e284bb20 100644
--- a/drivers/pcmcia/ds.c
+++ b/drivers/pcmcia/ds.c
@@ -67,7 +67,7 @@ static void pcmcia_check_driver(struct pcmcia_driver *p_drv)
67 "be 0x%x\n", p_drv->name, did->prod_id[i], 67 "be 0x%x\n", p_drv->name, did->prod_id[i],
68 did->prod_id_hash[i], hash); 68 did->prod_id_hash[i], hash);
69 printk(KERN_DEBUG "pcmcia: see " 69 printk(KERN_DEBUG "pcmcia: see "
70 "Documentation/pcmcia/devicetable.txt for " 70 "Documentation/pcmcia/devicetable.rst for "
71 "details\n"); 71 "details\n");
72 } 72 }
73 did++; 73 did++;
diff --git a/include/pcmcia/ds.h b/include/pcmcia/ds.h
index 3037157855f0..4e58c20dabcb 100644
--- a/include/pcmcia/ds.h
+++ b/include/pcmcia/ds.h
@@ -39,7 +39,7 @@ struct config_t;
39struct net_device; 39struct net_device;
40 40
41/* dynamic device IDs for PCMCIA device drivers. See 41/* dynamic device IDs for PCMCIA device drivers. See
42 * Documentation/pcmcia/driver.txt for details. 42 * Documentation/pcmcia/driver.rst for details.
43*/ 43*/
44struct pcmcia_dynids { 44struct pcmcia_dynids {
45 struct mutex lock; 45 struct mutex lock;
diff --git a/include/pcmcia/ss.h b/include/pcmcia/ss.h
index 731cde010f42..89629ee57840 100644
--- a/include/pcmcia/ss.h
+++ b/include/pcmcia/ss.h
@@ -190,7 +190,7 @@ struct pcmcia_socket {
190 unsigned int sysfs_events; 190 unsigned int sysfs_events;
191 191
192 /* For the non-trivial interaction between these locks, 192 /* For the non-trivial interaction between these locks,
193 * see Documentation/pcmcia/locking.txt */ 193 * see Documentation/pcmcia/locking.rst */
194 struct mutex skt_mutex; 194 struct mutex skt_mutex;
195 struct mutex ops_mutex; 195 struct mutex ops_mutex;
196 196