Documentation/pcmcia/locking.rst

   1 =======
   2 Locking
   3 =======
   4
   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
  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
  20
  21
  22 B) Exclusion
  23 ============
  24
  25 The following functions and callbacks to struct pcmcia_socket must
  26 be 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
  42 The following functions and callbacks to struct pcmcia_socket must
  43 be 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
  51 Note that send_event() and `struct pcmcia_callback *callback` must not be
  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 -------------------
  67 The resource_ops and their data are protected by ops_mutex.
  68
  69 The "main" struct pcmcia_socket is protected as follows (read-only fields
  70 or 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
 109 3. Per PCMCIA-device Data:
 110 --------------------------
 111
 112 The "main" struct pcmcia_device is protected as follows (read-only fields
 113 or 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;