[mirror_ubuntu-bionic-kernel.git] / Documentation / pcmcia / locking.txt

This file explains the locking and exclusion scheme used in the PCCARD
and PCMCIA subsystems.


A) Overview, Locking Hierarchy:
===============================

pcmcia_socket_list_rwsem	- protects only the list of sockets
- skt_mutex			- serializes card insert / ejection
  - ops_mutex			- serializes socket operation


B) Exclusion
============

The following functions and callbacks to struct pcmcia_socket must
be called with "skt_mutex" held:

	socket_detect_change()
	send_event()
	socket_reset()
	socket_shutdown()
	socket_setup()
	socket_remove()
	socket_insert()
	socket_early_resume()
	socket_late_resume()
	socket_resume()
	socket_suspend()

	struct pcmcia_callback	*callback

The following functions and callbacks to struct pcmcia_socket must
be called with "ops_mutex" held:

	socket_reset()
	socket_setup()

	struct pccard_operations	*ops
	struct pccard_resource_ops	*resource_ops;

Note that send_event() and struct pcmcia_callback *callback must not be
called with "ops_mutex" held.


C) Protection
=============

1. Global Data:
---------------
struct list_head	pcmcia_socket_list;

protected by pcmcia_socket_list_rwsem;


2. Per-Socket Data:
-------------------
The resource_ops and their data are protected by ops_mutex.

The "main" struct pcmcia_socket is protected as follows (read-only fields
or single-use fields not mentioned):

- by pcmcia_socket_list_rwsem:
	struct list_head	socket_list;

- by thread_lock:
	unsigned int		thread_events;

- by skt_mutex:
	u_int			suspended_state;
	void			(*tune_bridge);
	struct pcmcia_callback	*callback;
	int			resume_status;

- by ops_mutex:
	socket_state_t		socket;
	u_int			state;
	u_short			lock_count;
	pccard_mem_map		cis_mem;
	void __iomem 		*cis_virt;
	struct { }		irq;
	io_window_t		io[];
	pccard_mem_map		win[];
	struct list_head	cis_cache;
	size_t			fake_cis_len;
	u8			*fake_cis;
	u_int			irq_mask;
	void 			(*zoom_video);
	int 			(*power_hook);
	u8			resource...;
	struct list_head	devices_list;
	u8			device_count;
	struct 			pcmcia_state;


3. Per PCMCIA-device Data:
--------------------------

The "main" struct pcmcia_device is protected as follows (read-only fields
or single-use fields not mentioned):


- by pcmcia_socket->ops_mutex:
	struct list_head	socket_device_list;
	struct config_t		*function_config;
	u16			_irq:1;
	u16			_io:1;
	u16			_win:4;
	u16			_locked:1;
	u16			allow_func_id_match:1;
	u16			suspended:1;
	u16			_removed:1;

- by the PCMCIA driver:
	io_req_t		io;
	irq_req_t		irq;
	config_req_t		conf;
	window_handle_t		win;
Commit	Line	Data
3d068261 DB	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
cfe5d809 DB	39	struct pccard_operations *ops
cfe5d809 DB	40	struct pccard_resource_ops *resource_ops;
3d068261 DB	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	-------------------
cfe5d809	58	The resource_ops and their data are protected by ops_mutex.
3d068261 DB	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;
94a819f8 DB	94
	95
	96	3. Per PCMCIA-device Data:
	97	--------------------------
	98
831527b7	99	The "main" struct pcmcia_device is protected as follows (read-only fields
94a819f8 DB	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;