0001 =======
0002 Locking
0003 =======
0004
0005 This file explains the locking and exclusion scheme used in the PCCARD
0006 and PCMCIA subsystems.
0007
0008
0009 A) Overview, Locking Hierarchy:
0010 ===============================
0011
0012 pcmcia_socket_list_rwsem
0013 - protects only the list of sockets
0014
0015 - skt_mutex
0016 - serializes card insert / ejection
0017
0018 - ops_mutex
0019 - serializes socket operation
0020
0021
0022 B) Exclusion
0023 ============
0024
0025 The following functions and callbacks to struct pcmcia_socket must
0026 be called with "skt_mutex" held::
0027
0028 socket_detect_change()
0029 send_event()
0030 socket_reset()
0031 socket_shutdown()
0032 socket_setup()
0033 socket_remove()
0034 socket_insert()
0035 socket_early_resume()
0036 socket_late_resume()
0037 socket_resume()
0038 socket_suspend()
0039
0040 struct pcmcia_callback *callback
0041
0042 The following functions and callbacks to struct pcmcia_socket must
0043 be called with "ops_mutex" held::
0044
0045 socket_reset()
0046 socket_setup()
0047
0048 struct pccard_operations *ops
0049 struct pccard_resource_ops *resource_ops;
0050
0051 Note that send_event() and `struct pcmcia_callback *callback` must not be
0052 called with "ops_mutex" held.
0053
0054
0055 C) Protection
0056 =============
0057
0058 1. Global Data:
0059 ---------------
0060 struct list_head pcmcia_socket_list;
0061
0062 protected by pcmcia_socket_list_rwsem;
0063
0064
0065 2. Per-Socket Data:
0066 -------------------
0067 The resource_ops and their data are protected by ops_mutex.
0068
0069 The "main" struct pcmcia_socket is protected as follows (read-only fields
0070 or single-use fields not mentioned):
0071
0072 - by pcmcia_socket_list_rwsem::
0073
0074 struct list_head socket_list;
0075
0076 - by thread_lock::
0077
0078 unsigned int thread_events;
0079
0080 - by skt_mutex::
0081
0082 u_int suspended_state;
0083 void (*tune_bridge);
0084 struct pcmcia_callback *callback;
0085 int resume_status;
0086
0087 - by ops_mutex::
0088
0089 socket_state_t socket;
0090 u_int state;
0091 u_short lock_count;
0092 pccard_mem_map cis_mem;
0093 void __iomem *cis_virt;
0094 struct { } irq;
0095 io_window_t io[];
0096 pccard_mem_map win[];
0097 struct list_head cis_cache;
0098 size_t fake_cis_len;
0099 u8 *fake_cis;
0100 u_int irq_mask;
0101 void (*zoom_video);
0102 int (*power_hook);
0103 u8 resource...;
0104 struct list_head devices_list;
0105 u8 device_count;
0106 struct pcmcia_state;
0107
0108
0109 3. Per PCMCIA-device Data:
0110 --------------------------
0111
0112 The "main" struct pcmcia_device is protected as follows (read-only fields
0113 or single-use fields not mentioned):
0114
0115
0116 - by pcmcia_socket->ops_mutex::
0117
0118 struct list_head socket_device_list;
0119 struct config_t *function_config;
0120 u16 _irq:1;
0121 u16 _io:1;
0122 u16 _win:4;
0123 u16 _locked:1;
0124 u16 allow_func_id_match:1;
0125 u16 suspended:1;
0126 u16 _removed:1;
0127
0128 - by the PCMCIA driver::
0129
0130 io_req_t io;
0131 irq_req_t irq;
0132 config_req_t conf;
0133 window_handle_t win;
