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