VME Device Drivers

VME device driver 등록과 matching

다른 Linux kernel subsystem과 마찬가지로 VME device driver는 보통 device init routine에서 `vme_register_driver()`를 호출해 VME subsystem에 등록합니다.

Registration function에는 `struct vme_driver` pointer와 해당 driver가 지원할 수 있는 최대 device 수를 전달해야 합니다. 최소한 `.name`, `.match`, `.probe` member를 올바르게 설정해야 하며 `.name`은 device driver 이름 문자열을 가리킵니다.

`.match` function은 driver에 등록할 VME device를 제어합니다. Probe해야 할 device에는 1, 그렇지 않으면 0을 반환합니다. `vme_user.c` 예제는 `vdev->id.num`이 `USER_BUS_MAX` 이상인 device를 거부하여 probe 수를 하나로 제한합니다.

`.probe` member는 probe routine을 가리키며 argument로 `struct vme_dev` pointer를 받습니다. `num` field는 이 특정 driver 안에서 순차적으로 부여되는 device ID이고 bridge 또는 bus number는 `dev->bridge->num`으로 접근합니다.

Driver exit routine에서는 일반적으로 `vme_unregister_driver()`를 호출해 VME core 등록을 해제해야 합니다.

VME Device Drivers
==================

Driver registration
-------------------

As with other subsystems within the Linux kernel, VME device drivers register
with the VME subsystem, typically called from the devices init routine.  This is
achieved via a call to :c:func:`vme_register_driver`.

A pointer to a structure of type :c:type:`struct vme_driver <vme_driver>` must
be provided to the registration function. Along with the maximum number of
devices your driver is able to support.

At the minimum, the '.name', '.match' and '.probe' elements of
:c:type:`struct vme_driver <vme_driver>` should be correctly set. The '.name'
element is a pointer to a string holding the device driver's name.

The '.match' function allows control over which VME devices should be registered
with the driver. The match function should return 1 if a device should be
probed and 0 otherwise. This example match function (from vme_user.c) limits
the number of devices probed to one:

.. code-block:: c

        #define USER_BUS_MAX        1
        ...
        static int vme_user_match(struct vme_dev *vdev)
        {
                if (vdev->id.num >= USER_BUS_MAX)
                        return 0;
                return 1;
        }

The '.probe' element should contain a pointer to the probe routine. The
probe routine is passed a :c:type:`struct vme_dev <vme_dev>` pointer as an
argument.

Here, the 'num' field refers to the sequential device ID for this specific
driver. The bridge number (or bus number) can be accessed using
dev->bridge->num.

A function is also provided to unregister the driver from the VME core called
:c:func:`vme_unregister_driver` and should usually be called from the device
driver's exit routine.

VME resource 요청과 해제

Driver가 VME core에 등록되면 registration 때 지정한 횟수만큼 match routine이 호출됩니다. Match 성공은 non-zero, 실패는 zero로 나타내며, 성공한 각 device에 해당 driver의 probe routine이 호출됩니다.

Probe는 device structure pointer를 받습니다. 이 pointer는 이후 VME resource를 요청할 때 필요하므로 driver가 저장해야 합니다.

Driver는 `vme_master_request()`, `vme_slave_request()`, `vme_dma_request()`로 하나 이상의 master window, slave window, DMA channel ownership을 요청할 수 있습니다. 특정 window나 channel을 직접 요구하면 다른 driver와 충돌할 수 있으므로, API는 필요한 attribute를 만족하는 resource를 core가 배정하게 합니다.

Slave window attribute는 접근할 VME address space를 나타내는 `aspace`와 필요한 VME bus cycle type을 나타내는 `cycle`로 나뉩니다. Master window는 필요한 data-transfer width를 뜻하는 `width` attribute를 추가로 사용합니다.

Attribute는 bitmask이므로 하나의 window 요청에 여러 조합을 지정할 수 있습니다. Core는 조건을 만족하는 window를 찾아 할당하고, 이후 resource 식별에 사용할 `vme_resource` pointer를 반환합니다. 조건에 맞는 미할당 window가 없으면 `NULL`을 반환합니다.

DMA controller 요청에는 가능한 transfer direction을 route attribute로 전달합니다. 일반적으로 VME-to-MEM과 MEM-to-VME이며, hardware에 따라 VME-to-VME, MEM-to-MEM, test-pattern generation도 지원합니다.

Resource가 더 이상 필요하지 않으면 allocation 때 받은 pointer를 `vme_master_free()`, `vme_slave_free()`, `vme_dma_free()`에 전달해 해제합니다.

Resource management
-------------------

Once a driver has registered with the VME core the provided match routine will
be called the number of times specified during the registration. If a match
succeeds, a non-zero value should be returned. A zero return value indicates
failure. For all successful matches, the probe routine of the corresponding
driver is called. The probe routine is passed a pointer to the devices
device structure. This pointer should be saved, it will be required for
requesting VME resources.

The driver can request ownership of one or more master windows
(:c:func:`vme_master_request`), slave windows (:c:func:`vme_slave_request`)
and/or dma channels (:c:func:`vme_dma_request`). Rather than allowing the device
driver to request a specific window or DMA channel (which may be used by a
different driver) the API allows a resource to be assigned based on the required
attributes of the driver in question. For slave windows these attributes are
split into the VME address spaces that need to be accessed in 'aspace' and VME
bus cycle types required in 'cycle'. Master windows add a further set of
attributes in 'width' specifying the required data transfer widths. These
attributes are defined as bitmasks and as such any combination of the
attributes can be requested for a single window, the core will assign a window
that meets the requirements, returning a pointer of type vme_resource that
should be used to identify the allocated resource when it is used. For DMA
controllers, the request function requires the potential direction of any
transfers to be provided in the route attributes. This is typically VME-to-MEM
and/or MEM-to-VME, though some hardware can support VME-to-VME and MEM-to-MEM
transfers as well as test pattern generation. If an unallocated window fitting
the requirements can not be found a NULL pointer will be returned.

Functions are also provided to free window allocations once they are no longer
required. These functions (:c:func:`vme_master_free`, :c:func:`vme_slave_free`
and :c:func:`vme_dma_free`) should be passed the pointer to the resource
provided during resource allocation.

Master window 구성과 접근

Master window는 local processor가 VME bus 쪽으로 접근할 수 있게 합니다. 사용할 수 있는 window 수와 access mode는 underlying chipset에 따라 달라지며 사용 전에 반드시 구성해야 합니다.

할당된 master window는 `vme_master_set()`으로 구성하고 `vme_master_get()`으로 현재 setting을 조회합니다. Address space, transfer width, cycle type은 resource-management 절의 attribute와 같지만 일부 option은 서로 배타적입니다. 예를 들어 address space는 하나만 지정할 수 있습니다.

구성된 master window는 `vme_master_read()`로 읽고 `vme_master_write()`로 씁니다. `vme_master_rmw()`는 read-modify-write transaction을 제공하며 `vme_master_mmap()`은 VME window 일부를 userspace memory에 mapping합니다.

Master windows
--------------

Master windows provide access from the local processor[s] out onto the VME bus.
The number of windows available and the available access modes is dependent on
the underlying chipset. A window must be configured before it can be used.


Master window configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once a master window has been assigned :c:func:`vme_master_set` can be used to
configure it and :c:func:`vme_master_get` to retrieve the current settings. The
address spaces, transfer widths and cycle types are the same as described
under resource management, however some of the options are mutually exclusive.
For example, only one address space may be specified.


Master window access
~~~~~~~~~~~~~~~~~~~~

The function :c:func:`vme_master_read` can be used to read from and
:c:func:`vme_master_write` used to write to configured master windows.

In addition to simple reads and writes, :c:func:`vme_master_rmw` is provided to
do a read-modify-write transaction. Parts of a VME window can also be mapped
into user space memory using :c:func:`vme_master_mmap`.

Slave window와 contiguous buffer

Slave window는 VME bus의 device가 mapping된 local memory 영역에 접근하게 합니다. Window 수와 access mode는 underlying chipset에 따라 다르며 사용 전에 구성해야 합니다.

할당된 slave window는 `vme_slave_set()`으로 구성하고 `vme_slave_get()`으로 현재 setting을 조회합니다. Address space, transfer width, cycle type 규칙은 resource-management 절과 같고, address space 하나만 선택할 수 있는 것처럼 일부 option은 서로 배타적입니다.

`vme_alloc_consistent()`와 `vme_free_consistent()`는 VME bridge가 접근 가능한 contiguous buffer를 할당하고 해제합니다. 반드시 이 함수만 써야 하는 것은 아니지만 다른 allocation method를 사용하면 buffer가 contiguous하고 VME bridge에서 접근 가능한지 보장해야 합니다.

Slave window는 local memory를 VME bus에 mapping하므로 실제 memory 접근에는 standard memory-access method를 사용합니다.

Slave windows
-------------

Slave windows provide devices on the VME bus access into mapped portions of the
local memory. The number of windows available and the access modes that can be
used is dependent on the underlying chipset. A window must be configured before
it can be used.


Slave window configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~

Once a slave window has been assigned :c:func:`vme_slave_set` can be used to
configure it and :c:func:`vme_slave_get` to retrieve the current settings.

The address spaces, transfer widths and cycle types are the same as described
under resource management, however some of the options are mutually exclusive.
For example, only one address space may be specified.


Slave window buffer allocation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Functions are provided to allow the user to allocate
(:c:func:`vme_alloc_consistent`) and free (:c:func:`vme_free_consistent`)
contiguous buffers which will be accessible by the VME bridge. These functions
do not have to be used, other methods can be used to allocate a buffer, though
care must be taken to ensure that they are contiguous and accessible by the VME
bridge.


Slave window access
~~~~~~~~~~~~~~~~~~~

Slave windows map local memory onto the VME bus, the standard methods for
accessing memory should be used.

DMA channel과 linked-list 관리

VME DMA transfer는 linked-list DMA operation을 실행할 수 있습니다. API의 DMA list는 DMA controller에 넘기는 linked list이며 여러 list를 만들고 확장하고 실행하고 재사용하고 제거할 수 있습니다.

`vme_new_dma_list()`로 list를 만들고 `vme_dma_list_free()`로 제거합니다. List를 실행해도 자동으로 파괴되지 않으므로 반복 작업에 같은 list를 재사용할 수 있습니다.

DMA channels
------------

The VME DMA transfer provides the ability to run link-list DMA transfers. The
API introduces the concept of DMA lists. Each DMA list is a link-list which can
be passed to a DMA controller. Multiple lists can be created, extended,
executed, reused and destroyed.


List Management
~~~~~~~~~~~~~~~

The function :c:func:`vme_new_dma_list` is provided to create and
:c:func:`vme_dma_list_free` to destroy DMA lists. Execution of a list will not
automatically destroy the list, thus enabling a list to be reused for repetitive
tasks.

DMA item attribute와 실행

`vme_dma_list_add()`로 DMA list에 item을 추가합니다. 호출 전에 source와 destination attribute를 만들어야 하며 구체적인 생성 함수는 transfer endpoint 종류에 따라 다릅니다.

DMA channel 요청 단계에서는 controller가 지원해야 할 transfer direction만 검사합니다. Source와 destination의 세부 attribute는 item을 DMA list에 추가할 때 비로소 검증하므로, unsupported VME address space 같은 이유로 `vme_dma_list_add()`가 error를 반환할 수 있습니다.

Source와 destination attribute를 list item 추가와 분리한 이유는 endpoint 종류마다 필요한 속성이 다양하기 때문입니다. PCI source 또는 destination은 `vme_dma_pci_attribute()`, VME source 또는 destination은 `vme_dma_vme_attribute()`, pattern source는 `vme_dma_pattern_attribute()`로 만듭니다.

생성한 attribute는 `vme_dma_free_attribute()`로 해제합니다. 완성된 list는 `vme_dma_list_exec()`로 execution queue에 넣으며 함수는 list 실행이 끝난 뒤 반환합니다.

List Population
~~~~~~~~~~~~~~~

An item can be added to a list using :c:func:`vme_dma_list_add` (the source and
destination attributes need to be created before calling this function, this is
covered under "Transfer Attributes").

.. note::

        The detailed attributes of the transfers source and destination
        are not checked until an entry is added to a DMA list, the request
        for a DMA channel purely checks the directions in which the
        controller is expected to transfer data. As a result it is
        possible for this call to return an error, for example if the
        source or destination is in an unsupported VME address space.

Transfer Attributes
~~~~~~~~~~~~~~~~~~~

The attributes for the source and destination are handled separately from adding
an item to a list. This is due to the diverse attributes required for each type
of source and destination. There are functions to create attributes for PCI, VME
and pattern sources and destinations (where appropriate):

 - PCI source or destination: :c:func:`vme_dma_pci_attribute`
 - VME source or destination: :c:func:`vme_dma_vme_attribute`
 - Pattern source: :c:func:`vme_dma_pattern_attribute`

The function :c:func:`vme_dma_free_attribute` should be used to free an
attribute.


List Execution
~~~~~~~~~~~~~~

The function :c:func:`vme_dma_list_exec` queues a list for execution and will
return once the list has been executed.

VME interrupt handler와 생성

VME API는 특정 VME level과 status ID 조합에 callback을 attach/detach하고, 지정 level과 status ID로 VME interrupt를 생성하는 기능을 제공합니다.

`vme_irq_request()`로 특정 조합에 handler를 연결하고 `vme_irq_free()`로 해제합니다. 하나의 level/status-ID 조합에는 callback 하나만 할당할 수 있습니다.

Request에 전달한 `void *` 값은 callback의 `priv` argument로 그대로 전달되며 사용 의미는 driver가 정의합니다. Callback prototype은 `void callback(int level, int statid, void *priv);`이고 interrupt context에서 실행되므로 sleeping operation 등 context 제약을 지켜야 합니다.

`vme_irq_generate()`는 지정한 VME level과 status ID로 interrupt를 발생시킵니다.

Interrupts
----------

The VME API provides functions to attach and detach callbacks to specific VME
level and status ID combinations and for the generation of VME interrupts with
specific VME level and status IDs.


Attaching Interrupt Handlers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The function :c:func:`vme_irq_request` can be used to attach and
:c:func:`vme_irq_free` to free a specific VME level and status ID combination.
Any given combination can only be assigned a single callback function. A void
pointer parameter is provided, the value of which is passed to the callback
function, the use of this pointer is user undefined. The callback parameters are
as follows. Care must be taken in writing a callback function, callback
functions run in interrupt context:

.. code-block:: c

        void callback(int level, int statid, void *priv);


Interrupt Generation
~~~~~~~~~~~~~~~~~~~~

The function :c:func:`vme_irq_generate` can be used to generate a VME interrupt
at a given VME level and VME status ID.

Location monitor 관리와 callback

VME API는 location monitor를 구성하고 사용할 수 있는 기능을 제공합니다.

`vme_lm_request()`로 location-monitor block을 요청하고 더 이상 필요하지 않으면 `vme_lm_free()`로 해제합니다. 각 block은 서로 인접한 location을 감시하는 여러 monitor를 제공할 수 있으며 `vme_lm_count()`로 제공 개수를 확인합니다.

Monitor bank를 할당한 뒤 `vme_lm_set()`으로 감시 location과 mode를 구성하고 `vme_lm_get()`으로 기존 setting을 조회합니다.

각 location monitor에는 `vme_lm_attach()`로 callback을 연결하고 `vme_lm_detach()`로 해제합니다. Monitor 하나가 여러 adjacent location을 감시할 수 있으며 callback prototype은 `void callback(void *data);`입니다.

Location monitors
-----------------

The VME API provides the following functionality to configure the location
monitor.


Location Monitor Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The function :c:func:`vme_lm_request` is provided to request the use of a block
of location monitors and :c:func:`vme_lm_free` to free them after they are no
longer required. Each block may provide a number of location monitors,
monitoring adjacent locations. The function :c:func:`vme_lm_count` can be used
to determine how many locations are provided.


Location Monitor Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once a bank of location monitors has been allocated, the function
:c:func:`vme_lm_set` is provided to configure the location and mode of the
location monitor. The function :c:func:`vme_lm_get` can be used to retrieve
existing settings.


Location Monitor Use
~~~~~~~~~~~~~~~~~~~~

The function :c:func:`vme_lm_attach` enables a callback to be attached and
:c:func:`vme_lm_detach` allows on to be detached from each location monitor
location. Each location monitor can monitor a number of adjacent locations. The
callback function is declared as follows.

.. code-block:: c

        void callback(void *data);

Bridge의 slot과 bus ID 조회

`vme_slot_num()`은 제공된 VME bridge의 slot ID를 반환합니다. `vme_bus_num()`은 같은 bridge의 bus ID를 반환합니다.

Slot Detection
--------------

The function :c:func:`vme_slot_num` returns the slot ID of the provided bridge.


Bus Detection
-------------

The function :c:func:`vme_bus_num` returns the bus ID of the provided bridge.

VME kernel-doc API 원본

VME API의 internal declaration 문서는 `drivers/staging/vme_user/vme.h`에서, export된 함수 구현 문서는 `drivers/staging/vme_user/vme.c`에서 kernel-doc으로 생성됩니다. 실제 callback signature와 function contract를 확인할 때 이 source path가 기준입니다.

VME API
-------

.. kernel-doc:: drivers/staging/vme_user/vme.h
   :internal:

.. kernel-doc:: drivers/staging/vme_user/vme.c
   :export: