diff options
author | Mauro Carvalho Chehab <mchehab+samsung@kernel.org> | 2019-06-12 13:52:53 -0400 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2019-06-14 16:23:35 -0400 |
commit | 3bdab16c55f57a24245c97d707241dd9b48d1a91 (patch) | |
tree | cca861d5430a6c3092bc1a2f1869d9ed13e454e7 | |
parent | 593733ab80ac2c607acc1fc3fbaba5031d38253a (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.rst | 20 | ||||
-rw-r--r-- | Documentation/pcmcia/locking.rst (renamed from Documentation/pcmcia/locking.txt) | 39 | ||||
-rw-r--r-- | drivers/pcmcia/ds.c | 2 | ||||
-rw-r--r-- | include/pcmcia/ds.h | 2 | ||||
-rw-r--r-- | include/pcmcia/ss.h | 2 |
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 | ============ | ||
2 | Device table | ||
3 | ============ | ||
4 | |||
1 | Matching of PCMCIA devices to drivers is done using one or more of the | 5 | Matching of PCMCIA devices to drivers is done using one or more of the |
2 | following criteria: | 6 | following 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 | ============== | ||
2 | Driver changes | ||
3 | ============== | ||
4 | |||
1 | This file details changes in 2.6 which affect PCMCIA card driver authors: | 5 | This 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 | ============= | ||
1 | PCMCIA Driver | 2 | PCMCIA Driver |
2 | ------------- | 3 | ============= |
3 | |||
4 | 4 | ||
5 | sysfs | 5 | sysfs |
6 | ----- | 6 | ----- |
7 | 7 | ||
8 | New PCMCIA IDs may be added to a device driver pcmcia_device_id table at | 8 | New PCMCIA IDs may be added to a device driver pcmcia_device_id table at |
9 | runtime as shown below: | 9 | runtime as shown below:: |
10 | 10 | ||
11 | echo "match_flags manf_id card_id func_id function device_no \ | 11 | echo "match_flags manf_id card_id func_id function device_no \ |
12 | prod_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 | ||
15 | All fields are passed in as hexadecimal values (no leading 0x). | 15 | All fields are passed in as hexadecimal values (no leading 0x). |
16 | The meaning is described in the PCMCIA specification, the match_flags is | 16 | 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. | |||
22 | 22 | ||
23 | A common use-case is to add a new device according to the manufacturer ID | 23 | A common use-case is to add a new device according to the manufacturer ID |
24 | and the card ID (form the manf_id and card_id file in the device tree). | 24 | and the card ID (form the manf_id and card_id file in the device tree). |
25 | For this, just use: | 25 | For this, just use:: |
26 | 26 | ||
27 | echo "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 | ||
30 | after loading the driver. | 30 | after 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 | ====== | ||
4 | pcmcia | ||
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 | ======= | ||
2 | Locking | ||
3 | ======= | ||
4 | |||
1 | This file explains the locking and exclusion scheme used in the PCCARD | 5 | This file explains the locking and exclusion scheme used in the PCCARD |
2 | and PCMCIA subsystems. | 6 | and PCMCIA subsystems. |
3 | 7 | ||
@@ -5,16 +9,21 @@ and PCMCIA subsystems. | |||
5 | A) Overview, Locking Hierarchy: | 9 | A) Overview, Locking Hierarchy: |
6 | =============================== | 10 | =============================== |
7 | 11 | ||
8 | pcmcia_socket_list_rwsem - protects only the list of sockets | 12 | pcmcia_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 | ||
13 | B) Exclusion | 22 | B) Exclusion |
14 | ============ | 23 | ============ |
15 | 24 | ||
16 | The following functions and callbacks to struct pcmcia_socket must | 25 | The following functions and callbacks to struct pcmcia_socket must |
17 | be called with "skt_mutex" held: | 26 | be 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 | ||
33 | The following functions and callbacks to struct pcmcia_socket must | 42 | The following functions and callbacks to struct pcmcia_socket must |
34 | be called with "ops_mutex" held: | 43 | be 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 | ||
42 | Note that send_event() and struct pcmcia_callback *callback must not be | 51 | Note that send_event() and `struct pcmcia_callback *callback` must not be |
43 | called with "ops_mutex" held. | 52 | called with "ops_mutex" held. |
44 | 53 | ||
45 | 54 | ||
@@ -60,19 +69,23 @@ The resource_ops and their data are protected by ops_mutex. | |||
60 | The "main" struct pcmcia_socket is protected as follows (read-only fields | 69 | The "main" struct pcmcia_socket is protected as follows (read-only fields |
61 | or single-use fields not mentioned): | 70 | or 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 | |||
100 | or single-use fields not mentioned): | 113 | or 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; | |||
39 | struct net_device; | 39 | struct 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 | */ |
44 | struct pcmcia_dynids { | 44 | struct 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 | ||