GNU Linux-libre 6.6.34-gnu
[releases.git] / Documentation / pcmcia / locking.rst
1 =======
2 Locking
3 =======
4
5 This file explains the locking and exclusion scheme used in the PCCARD
6 and PCMCIA subsystems.
7
8
9 A) Overview, Locking Hierarchy:
10 ===============================
11
12 pcmcia_socket_list_rwsem
13         - protects only the list of sockets
14
15 - skt_mutex
16         - serializes card insert / ejection
17
18   - ops_mutex
19         - serializes socket operation
20
21
22 B) Exclusion
23 ============
24
25 The following functions and callbacks to struct pcmcia_socket must
26 be called with "skt_mutex" held::
27
28         socket_detect_change()
29         send_event()
30         socket_reset()
31         socket_shutdown()
32         socket_setup()
33         socket_remove()
34         socket_insert()
35         socket_early_resume()
36         socket_late_resume()
37         socket_resume()
38         socket_suspend()
39
40         struct pcmcia_callback  *callback
41
42 The following functions and callbacks to struct pcmcia_socket must
43 be called with "ops_mutex" held::
44
45         socket_reset()
46         socket_setup()
47
48         struct pccard_operations        *ops
49         struct pccard_resource_ops      *resource_ops;
50
51 Note that send_event() and `struct pcmcia_callback *callback` must not be
52 called with "ops_mutex" held.
53
54
55 C) Protection
56 =============
57
58 1. Global Data:
59 ---------------
60 struct list_head        pcmcia_socket_list;
61
62 protected by pcmcia_socket_list_rwsem;
63
64
65 2. Per-Socket Data:
66 -------------------
67 The resource_ops and their data are protected by ops_mutex.
68
69 The "main" struct pcmcia_socket is protected as follows (read-only fields
70 or single-use fields not mentioned):
71
72 - by pcmcia_socket_list_rwsem::
73
74         struct list_head        socket_list;
75
76 - by thread_lock::
77
78         unsigned int            thread_events;
79
80 - by skt_mutex::
81
82         u_int                   suspended_state;
83         void                    (*tune_bridge);
84         struct pcmcia_callback  *callback;
85         int                     resume_status;
86
87 - by ops_mutex::
88
89         socket_state_t          socket;
90         u_int                   state;
91         u_short                 lock_count;
92         pccard_mem_map          cis_mem;
93         void __iomem            *cis_virt;
94         struct { }              irq;
95         io_window_t             io[];
96         pccard_mem_map          win[];
97         struct list_head        cis_cache;
98         size_t                  fake_cis_len;
99         u8                      *fake_cis;
100         u_int                   irq_mask;
101         void                    (*zoom_video);
102         int                     (*power_hook);
103         u8                      resource...;
104         struct list_head        devices_list;
105         u8                      device_count;
106         struct                  pcmcia_state;
107
108
109 3. Per PCMCIA-device Data:
110 --------------------------
111
112 The "main" struct pcmcia_device is protected as follows (read-only fields
113 or single-use fields not mentioned):
114
115
116 - by pcmcia_socket->ops_mutex::
117
118         struct list_head        socket_device_list;
119         struct config_t         *function_config;
120         u16                     _irq:1;
121         u16                     _io:1;
122         u16                     _win:4;
123         u16                     _locked:1;
124         u16                     allow_func_id_match:1;
125         u16                     suspended:1;
126         u16                     _removed:1;
127
128 - by the PCMCIA driver::
129
130         io_req_t                io;
131         irq_req_t               irq;
132         config_req_t            conf;
133         window_handle_t         win;