docs: Update VME documentation to include kerneldoc comments

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 the following function:

achieved via a call to :c:func:`vme_register_driver`.

.. code-block:: c

	int vme_register_driver (struct vme_driver *driver, unsigned int ndevs);

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.

If driver registration is successful this function returns zero, if an error

occurred a negative error code will be returned.

A pointer to a structure of type 'vme_driver' must be provided to the

registration function. Along with ndevs, which is the number of devices your

driver is able to support. The structure is as follows:

.. code-block:: c

	struct vme_driver {

		struct list_head node;

		const char *name;

		int (*match)(struct vme_dev *);

		int (*probe)(struct vme_dev *);

		int (*remove)(struct vme_dev *);

		void (*shutdown)(void);

		struct device_driver driver;

		struct list_head devices;

		unsigned int ndev;

	};

At the minimum, the '.name', '.match' and '.probe' elements of this structure

should be correctly set. The '.name' element is a pointer to a string holding

the device driver's name.

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

	}

The '.probe' element should contain a pointer to the probe routine. The

probe routine is passed a 'struct vme_dev' pointer as an argument. The

'struct vme_dev' structure looks like the following:

.. code-block:: c

	struct vme_dev {

		int num;

		struct vme_bridge *bridge;

		struct device dev;

		struct list_head drv_list;

		struct list_head bridge_list;

	};

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 and is

usually called from the device driver's exit routine:

.. code-block:: c

	void vme_unregister_driver (struct vme_driver *driver);

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.

Resource management

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, slave windows

and/or dma channels. Rather than allowing the device driver to request a

specific window or DMA channel (which may be used by a different driver) this

driver allows a resource to be assigned based on the required attributes of the

driver in question:

.. code-block:: c

	struct vme_resource * vme_master_request(struct vme_dev *dev,

		u32 aspace, u32 cycle, u32 width);

	struct vme_resource * vme_slave_request(struct vme_dev *dev, u32 aspace,

		u32 cycle);

	struct vme_resource *vme_dma_request(struct vme_dev *dev, u32 route);

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.

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 should be passed the pointer to the resource provided

during resource allocation:

.. code-block:: c

	void vme_master_free(struct vme_resource *res);

	void vme_slave_free(struct vme_resource *res);

	void vme_dma_free(struct vme_resource *res);

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 windows

Master window configuration

~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once a master window has been assigned the following functions can be used to

configure it and retrieve the current settings:

.. code-block:: c

	int vme_master_set (struct vme_resource *res, int enabled,

		unsigned long long base, unsigned long long size, u32 aspace,

		u32 cycle, u32 width);

	int vme_master_get (struct vme_resource *res, int *enabled,

		unsigned long long *base, unsigned long long *size, u32 *aspace,

		u32 *cycle, u32 *width);

The address spaces, transfer widths and cycle types are the same as described

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.

These functions return 0 on success or an error code should the call fail.

Master window access

~~~~~~~~~~~~~~~~~~~~

The following functions can be used to read from and write to configured master

windows. These functions return the number of bytes copied:

.. code-block:: c

	ssize_t vme_master_read(struct vme_resource *res, void *buf,

		size_t count, loff_t offset);

	ssize_t vme_master_write(struct vme_resource *res, void *buf,

		size_t count, loff_t offset);

In addition to simple reads and writes, a function is provided to do a

read-modify-write transaction. This function returns the original value of the

VME bus location :

.. code-block:: c

	unsigned int vme_master_rmw (struct vme_resource *res,

		unsigned int mask, unsigned int compare, unsigned int swap,

		loff_t offset);

This functions by reading the offset, applying the mask. If the bits selected in

the mask match with the values of the corresponding bits in the compare field,

the value of swap is written the specified offset.

Parts of a VME window can be mapped into user space memory using the following

function:

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.

.. code-block:: c

	int vme_master_mmap(struct vme_resource *resource,

		struct vm_area_struct *vma)

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 windows

Slave window configuration

~~~~~~~~~~~~~~~~~~~~~~~~~~

Once a slave window has been assigned the following functions can be used to

configure it and retrieve the current settings:

.. code-block:: c

	int vme_slave_set (struct vme_resource *res, int enabled,

		unsigned long long base, unsigned long long size,

		dma_addr_t mem, u32 aspace, u32 cycle);

	int vme_slave_get (struct vme_resource *res, int *enabled,

		unsigned long long *base, unsigned long long *size,

		dma_addr_t *mem, u32 *aspace, u32 *cycle);

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.

These functions return 0 on success or an error code should the call fail.

Slave window buffer allocation

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Functions are provided to allow the user to allocate and free a 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:

.. code-block:: c

	void * vme_alloc_consistent(struct vme_resource *res, size_t size,

		dma_addr_t *mem);

	void vme_free_consistent(struct vme_resource *res, size_t size,

		void *virt,	dma_addr_t mem);

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

List Management

~~~~~~~~~~~~~~~

The following functions are provided to create and destroy DMA lists. Execution

of a list will not automatically destroy the list, thus enabling a list to be

reused for repetitive tasks:

.. code-block:: c

	struct vme_dma_list *vme_new_dma_list(struct vme_resource *res);

	int vme_dma_list_free(struct vme_dma_list *list);

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.

List Population

~~~~~~~~~~~~~~~

An item can be added to a list using the following function ( the source and

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"):

.. code-block:: c

	int vme_dma_list_add(struct vme_dma_list *list,

		struct vme_dma_attr *src, struct vme_dma_attr *dest,

		size_t count);

covered under "Transfer Attributes").

.. note::

of source and destination. There are functions to create attributes for PCI, VME

and pattern sources and destinations (where appropriate):

Pattern source:

.. code-block:: c

	struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type);

PCI source or destination:

.. code-block:: c

	struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem);

VME source or destination:

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

.. code-block:: c

	struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base,

		u32 aspace, u32 cycle, u32 width);

The following function should be used to free an attribute:

.. code-block:: c

	void vme_dma_free_attribute(struct vme_dma_attr *attr);

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

attribute.

List Execution

~~~~~~~~~~~~~~

The following function queues a list for execution. The function will return

once the list has been executed:

.. code-block:: c

	int vme_dma_list_exec(struct vme_dma_list *list);

The function :c:func:`vme_dma_list_exec` queues a list for execution and will

return once the list has been executed.

Interrupts

Attaching Interrupt Handlers

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following functions can be used to attach and 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:

.. code-block:: c

	int vme_irq_request(struct vme_dev *dev, int level, int statid,

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

	void vme_irq_free(struct vme_dev *dev, int level, int statid);

The callback parameters are as follows. Care must be taken in writing a callback

function, callback functions run in interrupt context:

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

Interrupt Generation

~~~~~~~~~~~~~~~~~~~~

The following function can be used to generate a VME interrupt at a given VME

level and VME status ID:

.. code-block:: c

	int vme_irq_generate(struct vme_dev *dev, int level, int statid);

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 monitors

Location Monitor Management

~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following functions are provided to request the use of a block of location

monitors and to free them after they are no longer required:

.. code-block:: c

	struct vme_resource * vme_lm_request(struct vme_dev *dev);

	void vme_lm_free(struct vme_resource * res);

Each block may provide a number of location monitors, monitoring adjacent

locations. The following function can be used to determine how many locations

are provided:

.. code-block:: c

	int vme_lm_count(struct vme_resource * res);

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 following functions

are provided to configure the location and mode of the location monitor:

.. code-block:: c

	int vme_lm_set(struct vme_resource *res, unsigned long long base,

		u32 aspace, u32 cycle);

	int vme_lm_get(struct vme_resource *res, unsigned long long *base,

		u32 *aspace, u32 *cycle);

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 following functions allow a callback to be attached and detached from each

location monitor location. Each location monitor can monitor a number of

adjacent locations:

.. code-block:: c

	int vme_lm_attach(struct vme_resource *res, int num,

		void (*callback)(void *));

	int vme_lm_detach(struct vme_resource *res, int num);

The callback function is declared as follows.

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

Slot Detection

--------------

This function returns the slot ID of the provided bridge.

.. code-block:: c

	int vme_slot_num(struct vme_dev *dev);

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

Bus Detection

-------------

This function returns the bus ID of the provided bridge.

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

.. code-block:: c

	int vme_bus_num(struct vme_dev *dev);

VME API

-------

.. kernel-doc:: include/linux/vme.h

   :internal:

.. kernel-doc:: drivers/vme/vme.c

   :export: