1=======
2Locking
3=======
4
5This file explains the locking and exclusion scheme used in the PCCARD
6and PCMCIA subsystems.
7
8
9A) Overview, Locking Hierarchy:
10===============================
11
12pcmcia_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
22B) Exclusion
23============
24
25The following functions and callbacks to struct pcmcia_socket must
26be 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
42The following functions and callbacks to struct pcmcia_socket must
43be 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
51Note that send_event() and `struct pcmcia_callback *callback` must not be
52called with "ops_mutex" held.
53
54
55C) Protection
56=============
57
581. Global Data:
59---------------
60struct list_head	pcmcia_socket_list;
61
62protected by pcmcia_socket_list_rwsem;
63
64
652. Per-Socket Data:
66-------------------
67The resource_ops and their data are protected by ops_mutex.
68
69The "main" struct pcmcia_socket is protected as follows (read-only fields
70or 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
1093. Per PCMCIA-device Data:
110--------------------------
111
112The "main" struct pcmcia_device is protected as follows (read-only fields
113or 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;
134