175a163c4SMartyn WelchVME Device Drivers 275a163c4SMartyn Welch================== 375a163c4SMartyn Welch 475a163c4SMartyn WelchDriver registration 575a163c4SMartyn Welch------------------- 675a163c4SMartyn Welch 775a163c4SMartyn WelchAs with other subsystems within the Linux kernel, VME device drivers register 875a163c4SMartyn Welchwith the VME subsystem, typically called from the devices init routine. This is 948a5e6bdSMartyn Welchachieved via a call to :c:func:`vme_register_driver`. 1075a163c4SMartyn Welch 1148a5e6bdSMartyn WelchA pointer to a structure of type :c:type:`struct vme_driver <vme_driver>` must 1248a5e6bdSMartyn Welchbe provided to the registration function. Along with the maximum number of 1348a5e6bdSMartyn Welchdevices your driver is able to support. 1475a163c4SMartyn Welch 1548a5e6bdSMartyn WelchAt the minimum, the '.name', '.match' and '.probe' elements of 1648a5e6bdSMartyn Welch:c:type:`struct vme_driver <vme_driver>` should be correctly set. The '.name' 1748a5e6bdSMartyn Welchelement is a pointer to a string holding the device driver's name. 1875a163c4SMartyn Welch 1975a163c4SMartyn WelchThe '.match' function allows control over which VME devices should be registered 2075a163c4SMartyn Welchwith the driver. The match function should return 1 if a device should be 2175a163c4SMartyn Welchprobed and 0 otherwise. This example match function (from vme_user.c) limits 2275a163c4SMartyn Welchthe number of devices probed to one: 2375a163c4SMartyn Welch 2475a163c4SMartyn Welch.. code-block:: c 2575a163c4SMartyn Welch 2675a163c4SMartyn Welch #define USER_BUS_MAX 1 2775a163c4SMartyn Welch ... 2875a163c4SMartyn Welch static int vme_user_match(struct vme_dev *vdev) 2975a163c4SMartyn Welch { 3075a163c4SMartyn Welch if (vdev->id.num >= USER_BUS_MAX) 3175a163c4SMartyn Welch return 0; 3275a163c4SMartyn Welch return 1; 3375a163c4SMartyn Welch } 3475a163c4SMartyn Welch 3575a163c4SMartyn WelchThe '.probe' element should contain a pointer to the probe routine. The 3648a5e6bdSMartyn Welchprobe routine is passed a :c:type:`struct vme_dev <vme_dev>` pointer as an 3748a5e6bdSMartyn Welchargument. 3875a163c4SMartyn Welch 3975a163c4SMartyn WelchHere, the 'num' field refers to the sequential device ID for this specific 4075a163c4SMartyn Welchdriver. The bridge number (or bus number) can be accessed using 4175a163c4SMartyn Welchdev->bridge->num. 4275a163c4SMartyn Welch 4348a5e6bdSMartyn WelchA function is also provided to unregister the driver from the VME core called 4448a5e6bdSMartyn Welch:c:func:`vme_unregister_driver` and should usually be called from the device 4548a5e6bdSMartyn Welchdriver's exit routine. 4675a163c4SMartyn Welch 4775a163c4SMartyn Welch 4875a163c4SMartyn WelchResource management 4975a163c4SMartyn Welch------------------- 5075a163c4SMartyn Welch 5175a163c4SMartyn WelchOnce a driver has registered with the VME core the provided match routine will 5275a163c4SMartyn Welchbe called the number of times specified during the registration. If a match 5375a163c4SMartyn Welchsucceeds, a non-zero value should be returned. A zero return value indicates 5475a163c4SMartyn Welchfailure. For all successful matches, the probe routine of the corresponding 5575a163c4SMartyn Welchdriver is called. The probe routine is passed a pointer to the devices 5675a163c4SMartyn Welchdevice structure. This pointer should be saved, it will be required for 5775a163c4SMartyn Welchrequesting VME resources. 5875a163c4SMartyn Welch 5948a5e6bdSMartyn WelchThe driver can request ownership of one or more master windows 6048a5e6bdSMartyn Welch(:c:func:`vme_master_request`), slave windows (:c:func:`vme_slave_request`) 6148a5e6bdSMartyn Welchand/or dma channels (:c:func:`vme_dma_request`). Rather than allowing the device 6248a5e6bdSMartyn Welchdriver to request a specific window or DMA channel (which may be used by a 6348a5e6bdSMartyn Welchdifferent driver) the API allows a resource to be assigned based on the required 6448a5e6bdSMartyn Welchattributes of the driver in question. For slave windows these attributes are 6548a5e6bdSMartyn Welchsplit into the VME address spaces that need to be accessed in 'aspace' and VME 6648a5e6bdSMartyn Welchbus cycle types required in 'cycle'. Master windows add a further set of 6748a5e6bdSMartyn Welchattributes in 'width' specifying the required data transfer widths. These 6848a5e6bdSMartyn Welchattributes are defined as bitmasks and as such any combination of the 6948a5e6bdSMartyn Welchattributes can be requested for a single window, the core will assign a window 7048a5e6bdSMartyn Welchthat meets the requirements, returning a pointer of type vme_resource that 7148a5e6bdSMartyn Welchshould be used to identify the allocated resource when it is used. For DMA 7248a5e6bdSMartyn Welchcontrollers, the request function requires the potential direction of any 7348a5e6bdSMartyn Welchtransfers to be provided in the route attributes. This is typically VME-to-MEM 7448a5e6bdSMartyn Welchand/or MEM-to-VME, though some hardware can support VME-to-VME and MEM-to-MEM 7548a5e6bdSMartyn Welchtransfers as well as test pattern generation. If an unallocated window fitting 7648a5e6bdSMartyn Welchthe requirements can not be found a NULL pointer will be returned. 7775a163c4SMartyn Welch 7875a163c4SMartyn WelchFunctions are also provided to free window allocations once they are no longer 7948a5e6bdSMartyn Welchrequired. These functions (:c:func:`vme_master_free`, :c:func:`vme_slave_free` 8048a5e6bdSMartyn Welchand :c:func:`vme_dma_free`) should be passed the pointer to the resource 8148a5e6bdSMartyn Welchprovided during resource allocation. 8275a163c4SMartyn Welch 8375a163c4SMartyn Welch 8475a163c4SMartyn WelchMaster windows 8575a163c4SMartyn Welch-------------- 8675a163c4SMartyn Welch 8775a163c4SMartyn WelchMaster windows provide access from the local processor[s] out onto the VME bus. 8875a163c4SMartyn WelchThe number of windows available and the available access modes is dependent on 8975a163c4SMartyn Welchthe underlying chipset. A window must be configured before it can be used. 9075a163c4SMartyn Welch 9175a163c4SMartyn Welch 9275a163c4SMartyn WelchMaster window configuration 9375a163c4SMartyn Welch~~~~~~~~~~~~~~~~~~~~~~~~~~~ 9475a163c4SMartyn Welch 9548a5e6bdSMartyn WelchOnce a master window has been assigned :c:func:`vme_master_set` can be used to 9648a5e6bdSMartyn Welchconfigure it and :c:func:`vme_master_get` to retrieve the current settings. The 9748a5e6bdSMartyn Welchaddress spaces, transfer widths and cycle types are the same as described 9875a163c4SMartyn Welchunder resource management, however some of the options are mutually exclusive. 9975a163c4SMartyn WelchFor example, only one address space may be specified. 10075a163c4SMartyn Welch 10175a163c4SMartyn Welch 10275a163c4SMartyn WelchMaster window access 10375a163c4SMartyn Welch~~~~~~~~~~~~~~~~~~~~ 10475a163c4SMartyn Welch 10548a5e6bdSMartyn WelchThe function :c:func:`vme_master_read` can be used to read from and 10648a5e6bdSMartyn Welch:c:func:`vme_master_write` used to write to configured master windows. 10775a163c4SMartyn Welch 10848a5e6bdSMartyn WelchIn addition to simple reads and writes, :c:func:`vme_master_rmw` is provided to 10948a5e6bdSMartyn Welchdo a read-modify-write transaction. Parts of a VME window can also be mapped 11048a5e6bdSMartyn Welchinto user space memory using :c:func:`vme_master_mmap`. 11175a163c4SMartyn Welch 11275a163c4SMartyn Welch 11375a163c4SMartyn WelchSlave windows 11475a163c4SMartyn Welch------------- 11575a163c4SMartyn Welch 11675a163c4SMartyn WelchSlave windows provide devices on the VME bus access into mapped portions of the 11775a163c4SMartyn Welchlocal memory. The number of windows available and the access modes that can be 11875a163c4SMartyn Welchused is dependent on the underlying chipset. A window must be configured before 11975a163c4SMartyn Welchit can be used. 12075a163c4SMartyn Welch 12175a163c4SMartyn Welch 12275a163c4SMartyn WelchSlave window configuration 12375a163c4SMartyn Welch~~~~~~~~~~~~~~~~~~~~~~~~~~ 12475a163c4SMartyn Welch 12548a5e6bdSMartyn WelchOnce a slave window has been assigned :c:func:`vme_slave_set` can be used to 12648a5e6bdSMartyn Welchconfigure it and :c:func:`vme_slave_get` to retrieve the current settings. 12775a163c4SMartyn Welch 12875a163c4SMartyn WelchThe address spaces, transfer widths and cycle types are the same as described 12975a163c4SMartyn Welchunder resource management, however some of the options are mutually exclusive. 13075a163c4SMartyn WelchFor example, only one address space may be specified. 13175a163c4SMartyn Welch 13275a163c4SMartyn Welch 13375a163c4SMartyn WelchSlave window buffer allocation 13475a163c4SMartyn Welch~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 13575a163c4SMartyn Welch 13648a5e6bdSMartyn WelchFunctions are provided to allow the user to allocate 13748a5e6bdSMartyn Welch(:c:func:`vme_alloc_consistent`) and free (:c:func:`vme_free_consistent`) 13848a5e6bdSMartyn Welchcontiguous buffers which will be accessible by the VME bridge. These functions 13948a5e6bdSMartyn Welchdo not have to be used, other methods can be used to allocate a buffer, though 14048a5e6bdSMartyn Welchcare must be taken to ensure that they are contiguous and accessible by the VME 14148a5e6bdSMartyn Welchbridge. 14275a163c4SMartyn Welch 14375a163c4SMartyn Welch 14475a163c4SMartyn WelchSlave window access 14575a163c4SMartyn Welch~~~~~~~~~~~~~~~~~~~ 14675a163c4SMartyn Welch 14775a163c4SMartyn WelchSlave windows map local memory onto the VME bus, the standard methods for 14875a163c4SMartyn Welchaccessing memory should be used. 14975a163c4SMartyn Welch 15075a163c4SMartyn Welch 15175a163c4SMartyn WelchDMA channels 15275a163c4SMartyn Welch------------ 15375a163c4SMartyn Welch 15475a163c4SMartyn WelchThe VME DMA transfer provides the ability to run link-list DMA transfers. The 15575a163c4SMartyn WelchAPI introduces the concept of DMA lists. Each DMA list is a link-list which can 15675a163c4SMartyn Welchbe passed to a DMA controller. Multiple lists can be created, extended, 15775a163c4SMartyn Welchexecuted, reused and destroyed. 15875a163c4SMartyn Welch 15975a163c4SMartyn Welch 16075a163c4SMartyn WelchList Management 16175a163c4SMartyn Welch~~~~~~~~~~~~~~~ 16275a163c4SMartyn Welch 16348a5e6bdSMartyn WelchThe function :c:func:`vme_new_dma_list` is provided to create and 16448a5e6bdSMartyn Welch:c:func:`vme_dma_list_free` to destroy DMA lists. Execution of a list will not 16548a5e6bdSMartyn Welchautomatically destroy the list, thus enabling a list to be reused for repetitive 16648a5e6bdSMartyn Welchtasks. 16775a163c4SMartyn Welch 16875a163c4SMartyn Welch 16975a163c4SMartyn WelchList Population 17075a163c4SMartyn Welch~~~~~~~~~~~~~~~ 17175a163c4SMartyn Welch 17248a5e6bdSMartyn WelchAn item can be added to a list using :c:func:`vme_dma_list_add` (the source and 17375a163c4SMartyn Welchdestination attributes need to be created before calling this function, this is 17448a5e6bdSMartyn Welchcovered under "Transfer Attributes"). 17575a163c4SMartyn Welch 17675a163c4SMartyn Welch.. note:: 17775a163c4SMartyn Welch 17875a163c4SMartyn Welch The detailed attributes of the transfers source and destination 17975a163c4SMartyn Welch are not checked until an entry is added to a DMA list, the request 18075a163c4SMartyn Welch for a DMA channel purely checks the directions in which the 18175a163c4SMartyn Welch controller is expected to transfer data. As a result it is 18275a163c4SMartyn Welch possible for this call to return an error, for example if the 18375a163c4SMartyn Welch source or destination is in an unsupported VME address space. 18475a163c4SMartyn Welch 18575a163c4SMartyn WelchTransfer Attributes 18675a163c4SMartyn Welch~~~~~~~~~~~~~~~~~~~ 18775a163c4SMartyn Welch 18875a163c4SMartyn WelchThe attributes for the source and destination are handled separately from adding 18975a163c4SMartyn Welchan item to a list. This is due to the diverse attributes required for each type 19075a163c4SMartyn Welchof source and destination. There are functions to create attributes for PCI, VME 19175a163c4SMartyn Welchand pattern sources and destinations (where appropriate): 19275a163c4SMartyn Welch 19348a5e6bdSMartyn Welch - PCI source or destination: :c:func:`vme_dma_pci_attribute` 19448a5e6bdSMartyn Welch - VME source or destination: :c:func:`vme_dma_vme_attribute` 19548a5e6bdSMartyn Welch - Pattern source: :c:func:`vme_dma_pattern_attribute` 19675a163c4SMartyn Welch 19748a5e6bdSMartyn WelchThe function :c:func:`vme_dma_free_attribute` should be used to free an 19848a5e6bdSMartyn Welchattribute. 19975a163c4SMartyn Welch 20075a163c4SMartyn Welch 20175a163c4SMartyn WelchList Execution 20275a163c4SMartyn Welch~~~~~~~~~~~~~~ 20375a163c4SMartyn Welch 20448a5e6bdSMartyn WelchThe function :c:func:`vme_dma_list_exec` queues a list for execution and will 20548a5e6bdSMartyn Welchreturn once the list has been executed. 20675a163c4SMartyn Welch 20775a163c4SMartyn Welch 20875a163c4SMartyn WelchInterrupts 20975a163c4SMartyn Welch---------- 21075a163c4SMartyn Welch 21175a163c4SMartyn WelchThe VME API provides functions to attach and detach callbacks to specific VME 21275a163c4SMartyn Welchlevel and status ID combinations and for the generation of VME interrupts with 21375a163c4SMartyn Welchspecific VME level and status IDs. 21475a163c4SMartyn Welch 21575a163c4SMartyn Welch 21675a163c4SMartyn WelchAttaching Interrupt Handlers 21775a163c4SMartyn Welch~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 21875a163c4SMartyn Welch 21948a5e6bdSMartyn WelchThe function :c:func:`vme_irq_request` can be used to attach and 22048a5e6bdSMartyn Welch:c:func:`vme_irq_free` to free a specific VME level and status ID combination. 22148a5e6bdSMartyn WelchAny given combination can only be assigned a single callback function. A void 22248a5e6bdSMartyn Welchpointer parameter is provided, the value of which is passed to the callback 22348a5e6bdSMartyn Welchfunction, the use of this pointer is user undefined. The callback parameters are 22448a5e6bdSMartyn Welchas follows. Care must be taken in writing a callback function, callback 22548a5e6bdSMartyn Welchfunctions run in interrupt context: 22675a163c4SMartyn Welch 22775a163c4SMartyn Welch.. code-block:: c 22875a163c4SMartyn Welch 22975a163c4SMartyn Welch void callback(int level, int statid, void *priv); 23075a163c4SMartyn Welch 23175a163c4SMartyn Welch 23275a163c4SMartyn WelchInterrupt Generation 23375a163c4SMartyn Welch~~~~~~~~~~~~~~~~~~~~ 23475a163c4SMartyn Welch 23548a5e6bdSMartyn WelchThe function :c:func:`vme_irq_generate` can be used to generate a VME interrupt 23648a5e6bdSMartyn Welchat a given VME level and VME status ID. 23775a163c4SMartyn Welch 23875a163c4SMartyn Welch 23975a163c4SMartyn WelchLocation monitors 24075a163c4SMartyn Welch----------------- 24175a163c4SMartyn Welch 24275a163c4SMartyn WelchThe VME API provides the following functionality to configure the location 24375a163c4SMartyn Welchmonitor. 24475a163c4SMartyn Welch 24575a163c4SMartyn Welch 24675a163c4SMartyn WelchLocation Monitor Management 24775a163c4SMartyn Welch~~~~~~~~~~~~~~~~~~~~~~~~~~~ 24875a163c4SMartyn Welch 24948a5e6bdSMartyn WelchThe function :c:func:`vme_lm_request` is provided to request the use of a block 25048a5e6bdSMartyn Welchof location monitors and :c:func:`vme_lm_free` to free them after they are no 25148a5e6bdSMartyn Welchlonger required. Each block may provide a number of location monitors, 25248a5e6bdSMartyn Welchmonitoring adjacent locations. The function :c:func:`vme_lm_count` can be used 25348a5e6bdSMartyn Welchto determine how many locations are provided. 25475a163c4SMartyn Welch 25575a163c4SMartyn Welch 25675a163c4SMartyn WelchLocation Monitor Configuration 25775a163c4SMartyn Welch~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 25875a163c4SMartyn Welch 25948a5e6bdSMartyn WelchOnce a bank of location monitors has been allocated, the function 26048a5e6bdSMartyn Welch:c:func:`vme_lm_set` is provided to configure the location and mode of the 26148a5e6bdSMartyn Welchlocation monitor. The function :c:func:`vme_lm_get` can be used to retrieve 26248a5e6bdSMartyn Welchexisting settings. 26375a163c4SMartyn Welch 26475a163c4SMartyn Welch 26575a163c4SMartyn WelchLocation Monitor Use 26675a163c4SMartyn Welch~~~~~~~~~~~~~~~~~~~~ 26775a163c4SMartyn Welch 26848a5e6bdSMartyn WelchThe function :c:func:`vme_lm_attach` enables a callback to be attached and 26948a5e6bdSMartyn Welch:c:func:`vme_lm_detach` allows on to be detached from each location monitor 27048a5e6bdSMartyn Welchlocation. Each location monitor can monitor a number of adjacent locations. The 27148a5e6bdSMartyn Welchcallback function is declared as follows. 27275a163c4SMartyn Welch 27375a163c4SMartyn Welch.. code-block:: c 27475a163c4SMartyn Welch 27575a163c4SMartyn Welch void callback(void *data); 27675a163c4SMartyn Welch 27775a163c4SMartyn Welch 27875a163c4SMartyn WelchSlot Detection 27975a163c4SMartyn Welch-------------- 28075a163c4SMartyn Welch 28148a5e6bdSMartyn WelchThe function :c:func:`vme_slot_num` returns the slot ID of the provided bridge. 28275a163c4SMartyn Welch 28375a163c4SMartyn Welch 28475a163c4SMartyn WelchBus Detection 28575a163c4SMartyn Welch------------- 28675a163c4SMartyn Welch 28748a5e6bdSMartyn WelchThe function :c:func:`vme_bus_num` returns the bus ID of the provided bridge. 28875a163c4SMartyn Welch 28975a163c4SMartyn Welch 29048a5e6bdSMartyn WelchVME API 29148a5e6bdSMartyn Welch------- 29275a163c4SMartyn Welch 293*35ba63b8SArnd Bergmann.. kernel-doc:: drivers/staging/vme_user/vme.h 29448a5e6bdSMartyn Welch :internal: 29548a5e6bdSMartyn Welch 296*35ba63b8SArnd Bergmann.. kernel-doc:: drivers/staging/vme_user/vme.c 29748a5e6bdSMartyn Welch :export: 298