From 75a163c4a3ee8235072f0e1bd4875dd2443cdb8e Mon Sep 17 00:00:00 2001 From: Martyn Welch Date: Fri, 21 Oct 2016 22:15:27 +0100 Subject: [PATCH] vme: Convert documentation to reStructuredText, move under driver APIs Perform a relatively simple conversion of vme_api.txt to reStructuredText and move under driver-api, which seems the most logical place for this documentation. Signed-off-by: Martyn Welch Signed-off-by: Jonathan Corbet --- Documentation/driver-api/index.rst | 1 + .../{vme_api.txt => driver-api/vme.rst} | 115 ++++++++++++++---- MAINTAINERS | 2 +- 3 files changed, 90 insertions(+), 28 deletions(-) rename Documentation/{vme_api.txt => driver-api/vme.rst} (92%) diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 8e259c5d0322..b567907db350 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -24,3 +24,4 @@ available subsections can be seen below. i2c hsi miscellaneous + vme diff --git a/Documentation/vme_api.txt b/Documentation/driver-api/vme.rst similarity index 92% rename from Documentation/vme_api.txt rename to Documentation/driver-api/vme.rst index 90006550f485..89776fb3c8bd 100644 --- a/Documentation/vme_api.txt +++ b/Documentation/driver-api/vme.rst @@ -1,13 +1,15 @@ - 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 @@ -17,6 +19,8 @@ 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; @@ -38,6 +42,8 @@ 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) @@ -51,6 +57,8 @@ 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; @@ -66,11 +74,13 @@ 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); 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 @@ -86,6 +96,8 @@ 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); @@ -112,6 +124,8 @@ 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); @@ -120,7 +134,7 @@ during resource allocation: 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 @@ -128,11 +142,13 @@ the underlying chipset. A window must be configured before it can be used. 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); @@ -149,11 +165,13 @@ 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); @@ -164,6 +182,8 @@ 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); @@ -175,12 +195,14 @@ 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: +.. 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 @@ -189,11 +211,13 @@ it can be used. 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); @@ -210,13 +234,15 @@ 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); @@ -225,14 +251,14 @@ 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 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 @@ -241,29 +267,35 @@ executed, reused and destroyed. 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 @@ -271,7 +303,7 @@ NOTE: The detailed attributes of the transfers source and destination 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 @@ -280,33 +312,43 @@ 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: +.. 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 @@ -314,13 +356,15 @@ specific VME level and status IDs. 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); @@ -329,31 +373,37 @@ 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 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); @@ -362,15 +412,19 @@ 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); 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); @@ -379,12 +433,14 @@ are provided to configure the location and mode of the location monitor: 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 *)); @@ -392,22 +448,27 @@ adjacent locations: 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. +.. code-block:: c + int vme_bus_num(struct vme_dev *dev); - diff --git a/MAINTAINERS b/MAINTAINERS index 1cd38a7e0064..de0451df542f 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -12877,7 +12877,7 @@ M: Greg Kroah-Hartman 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*