PCMCIA locking

Lock hierarchy 개요

이 문서는 PCCARD와 PCMCIA subsystem에서 사용하는 locking·exclusion scheme을 설명합니다.

`pcmcia_socket_list_rwsem`은 socket list만 보호합니다. 그 아래 `skt_mutex`는 card insert와 eject를 serialize하고, `ops_mutex`는 socket operation을 serialize합니다.

=======
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

Function·callback 호출 전제

`struct pcmcia_socket`의 다음 함수와 callback은 `skt_mutex`를 잡은 상태에서 호출해야 합니다.

`ops_mutex`를 잡은 상태에서 호출해야 하는 함수는 `socket_reset()`과 `socket_setup()`이며 callback table은 `struct pccard_operations *ops`와 `struct pccard_resource_ops *resource_ops`입니다.

중요한 예외로 `send_event()`와 `struct pcmcia_callback *callback`은 `ops_mutex`를 잡은 상태에서 호출하면 안 됩니다.

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.

Global data 보호

Global `struct list_head pcmcia_socket_list`는 `pcmcia_socket_list_rwsem`으로 보호합니다.

C) Protection
=============

1. Global Data:
---------------
struct list_head        pcmcia_socket_list;

protected by pcmcia_socket_list_rwsem;

Per-socket data 보호

`resource_ops`와 그 data는 `ops_mutex`로 보호합니다. Read-only field와 한 번만 사용하는 field를 제외한 주 `struct pcmcia_socket`의 보호 규칙은 다음과 같습니다.

`pcmcia_socket_list_rwsem`은 socket이 global list에 연결된 상태를, `thread_lock`은 pending thread event를, `skt_mutex`는 suspend·resume와 upper callback 상태를 보호합니다.

`ops_mutex`는 hardware socket state, CIS mapping과 cache, IRQ·I/O·memory window, resource와 연결 device list까지 가장 넓은 per-socket operation state를 보호합니다.

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;

Per-PCMCIA-device data 보호

Read-only·single-use field를 제외한 주 `struct pcmcia_device`의 socket 연결과 configuration 상태는 `pcmcia_socket->ops_mutex`로 보호합니다.

반면 `io_req_t io`, `irq_req_t irq`, `config_req_t conf`, `window_handle_t win`은 PCMCIA driver가 직접 보호합니다.

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;