Documentation/pcmcia/locking.txt

   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
  39         struct pccard_operations        *ops
  40         struct pccard_resource_ops      *resource_ops;
  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 -------------------
  58 The resource_ops and their data are protected by ops_mutex.
  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;
  94
  95
  96 3. Per PCMCIA-device Data:
  97 --------------------------
  98
  99 The "main" struct pcmcia_devie is protected as follows (read-only fields
 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;