[linux-block.git] / Documentation / pcmcia / locking.rst

=======
Locking
=======

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
3bdab16c MCC	1	=======
	2	Locking
	3	=======
	4
3d068261 DB	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
3bdab16c MCC	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
3d068261 DB	20
	21
	22	B) Exclusion
	23	============
	24
	25	The following functions and callbacks to struct pcmcia_socket must
3bdab16c	26	be called with "skt_mutex" held::
3d068261 DB	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
3bdab16c	43	be called with "ops_mutex" held::
3d068261 DB	44
	45	socket_reset()
	46	socket_setup()
	47
cfe5d809 DB	48	struct pccard_operations *ops
cfe5d809 DB	49	struct pccard_resource_ops *resource_ops;
3d068261	50
3bdab16c	51	Note that send_event() and `struct pcmcia_callback *callback` must not be
3d068261 DB	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	-------------------
cfe5d809	67	The resource_ops and their data are protected by ops_mutex.
3d068261 DB	68
	69	The "main" struct pcmcia_socket is protected as follows (read-only fields
	70	or single-use fields not mentioned):
	71
3bdab16c MCC	72	- by pcmcia_socket_list_rwsem::
3bdab16c MCC	73
3d068261 DB	74	struct list_head socket_list;
3d068261 DB	75
3bdab16c MCC	76	- by thread_lock::
3bdab16c MCC	77
3d068261 DB	78	unsigned int thread_events;
3d068261 DB	79
3bdab16c MCC	80	- by skt_mutex::
3bdab16c MCC	81
3d068261 DB	82	u_int suspended_state;
	83	void (*tune_bridge);
	84	struct pcmcia_callback *callback;
	85	int resume_status;
	86
3bdab16c MCC	87	- by ops_mutex::
3bdab16c MCC	88
3d068261 DB	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;
94a819f8 DB	107
	108
	109	3. Per PCMCIA-device Data:
	110	--------------------------
	111
831527b7	112	The "main" struct pcmcia_device is protected as follows (read-only fields
94a819f8 DB	113	or single-use fields not mentioned):
	114
	115
3bdab16c MCC	116	- by pcmcia_socket->ops_mutex::
3bdab16c MCC	117
94a819f8 DB	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
3bdab16c MCC	128	- by the PCMCIA driver::
3bdab16c MCC	129
94a819f8 DB	130	io_req_t io;
	131	irq_req_t irq;
	132	config_req_t conf;
	133	window_handle_t win;