vme: Convert documentation to reStructuredText, move under driver APIs

   i2c

   hsi

   miscellaneous

   vme

			VME Device Driver API

			=====================

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

.. code-block:: c

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

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

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;

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)

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;

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);

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

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);

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);

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

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);

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);

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);

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

function:

.. code-block:: c

	int vme_master_mmap(struct vme_resource *resource,

		struct vm_area_struct *vma)

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

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);

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);

Slave window access

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

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

Slave windows map local memory onto the VME bus, the standard methods for

accessing memory should be used.

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

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);

List Population

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

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

An item can be added to a list using the following function ( 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);

NOTE:	The detailed attributes of the transfers source and destination

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

	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

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:

.. 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);

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);

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

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);

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 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);

Location monitors

=================

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

The VME API provides the following functionality to configure the location

monitor.

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);

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);

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);

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 *));

The callback function is declared as follows.

.. code-block:: c

	void callback(void *data);

Slot Detection

==============

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

This function returns the slot ID of the provided bridge.

.. code-block:: c

	int vme_slot_num(struct vme_dev *dev);

Bus Detection

=============

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

This function returns the bus ID of the provided bridge.

	int vme_bus_num(struct vme_dev *dev);

.. code-block:: c

	int vme_bus_num(struct vme_dev *dev);

L:	devel@driverdev.osuosl.org

S:	Maintained

T:	git git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core.git

F:	Documentation/vme_api.txt

F:	Documentation/driver-api/vme.rst

F:	drivers/staging/vme/

F:	drivers/vme/

F:	include/linux/vme*