locking.rst

  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;