SAFE public projects git trees. - safe/jmp/linux-2.6/blob - 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
  41 Note that send_event() and struct pcmcia_callback *callback must not be
  42 called with "ops_mutex" held.
  43
  44
  45 C) Protection
  46 =============
  47
  48 1. Global Data:
  49 ---------------
  50 struct list_head        pcmcia_socket_list;
  51
  52 protected by pcmcia_socket_list_rwsem;
  53
  54
  55 2. Per-Socket Data:
  56 -------------------
  57 The resource_ops are on their own to provide proper locking.
  58
  59 The "main" struct pcmcia_socket is protected as follows (read-only fields
  60 or single-use fields not mentioned):
  61
  62 - by pcmcia_socket_list_rwsem:
  63         struct list_head        socket_list;
  64
  65 - by thread_lock:
  66         unsigned int            thread_events;
  67
  68 - by skt_mutex:
  69         u_int                   suspended_state;
  70         void                    (*tune_bridge);
  71         struct pcmcia_callback  *callback;
  72         int                     resume_status;
  73
  74 - by ops_mutex:
  75         socket_state_t          socket;
  76         u_int                   state;
  77         u_short                 lock_count;
  78         pccard_mem_map          cis_mem;
  79         void __iomem            *cis_virt;
  80         struct { }              irq;
  81         io_window_t             io[];
  82         pccard_mem_map          win[];
  83         struct list_head        cis_cache;
  84         size_t                  fake_cis_len;
  85         u8                      *fake_cis;
  86         u_int                   irq_mask;
  87         void                    (*zoom_video);
  88         int                     (*power_hook);
  89         u8                      resource...;
  90         struct list_head        devices_list;
  91         u8                      device_count;
  92         struct                  pcmcia_state;
  93
  94
  95 3. Per PCMCIA-device Data:
  96 --------------------------
  97
  98 The "main" struct pcmcia_devie is protected as follows (read-only fields
  99 or single-use fields not mentioned):
 100
 101
 102 - by pcmcia_socket->ops_mutex:
 103         struct list_head        socket_device_list;
 104         struct config_t         *function_config;
 105         u16                     _irq:1;
 106         u16                     _io:1;
 107         u16                     _win:4;
 108         u16                     _locked:1;
 109         u16                     allow_func_id_match:1;
 110         u16                     suspended:1;
 111         u16                     _removed:1;
 112
 113 - by the PCMCIA driver:
 114         io_req_t                io;
 115         irq_req_t               irq;
 116         config_req_t            conf;
 117         window_handle_t         win;