About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / vme_api.txt


Based on kernel version 4.9. Page generated on 2016-12-21 14:37 EST.

1				VME Device Driver API
2				=====================
3	
4	Driver registration
5	===================
6	
7	As with other subsystems within the Linux kernel, VME device drivers register
8	with the VME subsystem, typically called from the devices init routine.  This is
9	achieved via a call to the following function:
10	
11		int vme_register_driver (struct vme_driver *driver, unsigned int ndevs);
12	
13	If driver registration is successful this function returns zero, if an error
14	occurred a negative error code will be returned.
15	
16	A pointer to a structure of type 'vme_driver' must be provided to the
17	registration function. Along with ndevs, which is the number of devices your
18	driver is able to support. The structure is as follows:
19	
20		struct vme_driver {
21			struct list_head node;
22			const char *name;
23			int (*match)(struct vme_dev *);
24			int (*probe)(struct vme_dev *);
25			int (*remove)(struct vme_dev *);
26			void (*shutdown)(void);
27			struct device_driver driver;
28			struct list_head devices;
29			unsigned int ndev;
30		};
31	
32	At the minimum, the '.name', '.match' and '.probe' elements of this structure
33	should be correctly set. The '.name' element is a pointer to a string holding
34	the device driver's name.
35	
36	The '.match' function allows control over which VME devices should be registered
37	with the driver. The match function should return 1 if a device should be
38	probed and 0 otherwise. This example match function (from vme_user.c) limits
39	the number of devices probed to one:
40	
41		#define USER_BUS_MAX	1
42		...
43		static int vme_user_match(struct vme_dev *vdev)
44		{
45			if (vdev->id.num >= USER_BUS_MAX)
46				return 0;
47			return 1;
48		}
49	
50	The '.probe' element should contain a pointer to the probe routine. The
51	probe routine is passed a 'struct vme_dev' pointer as an argument. The
52	'struct vme_dev' structure looks like the following:
53	
54		struct vme_dev {
55			int num;
56			struct vme_bridge *bridge;
57			struct device dev;
58			struct list_head drv_list;
59			struct list_head bridge_list;
60		};
61	
62	Here, the 'num' field refers to the sequential device ID for this specific
63	driver. The bridge number (or bus number) can be accessed using
64	dev->bridge->num.
65	
66	A function is also provided to unregister the driver from the VME core and is
67	usually called from the device driver's exit routine:
68	
69		void vme_unregister_driver (struct vme_driver *driver);
70	
71	
72	Resource management
73	===================
74	
75	Once a driver has registered with the VME core the provided match routine will
76	be called the number of times specified during the registration. If a match
77	succeeds, a non-zero value should be returned. A zero return value indicates
78	failure. For all successful matches, the probe routine of the corresponding
79	driver is called. The probe routine is passed a pointer to the devices
80	device structure. This pointer should be saved, it will be required for
81	requesting VME resources.
82	
83	The driver can request ownership of one or more master windows, slave windows
84	and/or dma channels. Rather than allowing the device driver to request a
85	specific window or DMA channel (which may be used by a different driver) this
86	driver allows a resource to be assigned based on the required attributes of the
87	driver in question:
88	
89		struct vme_resource * vme_master_request(struct vme_dev *dev,
90			u32 aspace, u32 cycle, u32 width);
91	
92		struct vme_resource * vme_slave_request(struct vme_dev *dev, u32 aspace,
93			u32 cycle);
94	
95		struct vme_resource *vme_dma_request(struct vme_dev *dev, u32 route);
96	
97	For slave windows these attributes are split into the VME address spaces that
98	need to be accessed in 'aspace' and VME bus cycle types required in 'cycle'.
99	Master windows add a further set of attributes in 'width' specifying the
100	required data transfer widths. These attributes are defined as bitmasks and as
101	such any combination of the attributes can be requested for a single window,
102	the core will assign a window that meets the requirements, returning a pointer
103	of type vme_resource that should be used to identify the allocated resource
104	when it is used. For DMA controllers, the request function requires the
105	potential direction of any transfers to be provided in the route attributes.
106	This is typically VME-to-MEM and/or MEM-to-VME, though some hardware can
107	support VME-to-VME and MEM-to-MEM transfers as well as test pattern generation.
108	If an unallocated window fitting the requirements can not be found a NULL
109	pointer will be returned.
110	
111	Functions are also provided to free window allocations once they are no longer
112	required. These functions should be passed the pointer to the resource provided
113	during resource allocation:
114	
115		void vme_master_free(struct vme_resource *res);
116	
117		void vme_slave_free(struct vme_resource *res);
118	
119		void vme_dma_free(struct vme_resource *res);
120	
121	
122	Master windows
123	==============
124	
125	Master windows provide access from the local processor[s] out onto the VME bus.
126	The number of windows available and the available access modes is dependent on
127	the underlying chipset. A window must be configured before it can be used.
128	
129	
130	Master window configuration
131	---------------------------
132	
133	Once a master window has been assigned the following functions can be used to
134	configure it and retrieve the current settings:
135	
136		int vme_master_set (struct vme_resource *res, int enabled,
137			unsigned long long base, unsigned long long size, u32 aspace,
138			u32 cycle, u32 width);
139	
140		int vme_master_get (struct vme_resource *res, int *enabled,
141			unsigned long long *base, unsigned long long *size, u32 *aspace,
142			u32 *cycle, u32 *width);
143	
144	The address spaces, transfer widths and cycle types are the same as described
145	under resource management, however some of the options are mutually exclusive.
146	For example, only one address space may be specified.
147	
148	These functions return 0 on success or an error code should the call fail.
149	
150	
151	Master window access
152	--------------------
153	
154	The following functions can be used to read from and write to configured master
155	windows. These functions return the number of bytes copied:
156	
157		ssize_t vme_master_read(struct vme_resource *res, void *buf,
158			size_t count, loff_t offset);
159	
160		ssize_t vme_master_write(struct vme_resource *res, void *buf,
161			size_t count, loff_t offset);
162	
163	In addition to simple reads and writes, a function is provided to do a
164	read-modify-write transaction. This function returns the original value of the
165	VME bus location :
166	
167		unsigned int vme_master_rmw (struct vme_resource *res,
168			unsigned int mask, unsigned int compare, unsigned int swap,
169			loff_t offset);
170	
171	This functions by reading the offset, applying the mask. If the bits selected in
172	the mask match with the values of the corresponding bits in the compare field,
173	the value of swap is written the specified offset.
174	
175	Parts of a VME window can be mapped into user space memory using the following
176	function:
177	
178		int vme_master_mmap(struct vme_resource *resource,
179			struct vm_area_struct *vma)
180	
181	
182	Slave windows
183	=============
184	
185	Slave windows provide devices on the VME bus access into mapped portions of the
186	local memory. The number of windows available and the access modes that can be
187	used is dependent on the underlying chipset. A window must be configured before
188	it can be used.
189	
190	
191	Slave window configuration
192	--------------------------
193	
194	Once a slave window has been assigned the following functions can be used to
195	configure it and retrieve the current settings:
196	
197		int vme_slave_set (struct vme_resource *res, int enabled,
198			unsigned long long base, unsigned long long size,
199			dma_addr_t mem, u32 aspace, u32 cycle);
200	
201		int vme_slave_get (struct vme_resource *res, int *enabled,
202			unsigned long long *base, unsigned long long *size,
203			dma_addr_t *mem, u32 *aspace, u32 *cycle);
204	
205	The address spaces, transfer widths and cycle types are the same as described
206	under resource management, however some of the options are mutually exclusive.
207	For example, only one address space may be specified.
208	
209	These functions return 0 on success or an error code should the call fail.
210	
211	
212	Slave window buffer allocation
213	------------------------------
214	
215	Functions are provided to allow the user to allocate and free a contiguous
216	buffers which will be accessible by the VME bridge. These functions do not have
217	to be used, other methods can be used to allocate a buffer, though care must be
218	taken to ensure that they are contiguous and accessible by the VME bridge:
219	
220		void * vme_alloc_consistent(struct vme_resource *res, size_t size,
221			dma_addr_t *mem);
222	
223		void vme_free_consistent(struct vme_resource *res, size_t size,
224			void *virt,	dma_addr_t mem);
225	
226	
227	Slave window access
228	-------------------
229	
230	Slave windows map local memory onto the VME bus, the standard methods for
231	accessing memory should be used.
232	
233	
234	DMA channels
235	============
236	
237	The VME DMA transfer provides the ability to run link-list DMA transfers. The
238	API introduces the concept of DMA lists. Each DMA list is a link-list which can
239	be passed to a DMA controller. Multiple lists can be created, extended,
240	executed, reused and destroyed.
241	
242	
243	List Management
244	---------------
245	
246	The following functions are provided to create and destroy DMA lists. Execution
247	of a list will not automatically destroy the list, thus enabling a list to be
248	reused for repetitive tasks:
249	
250		struct vme_dma_list *vme_new_dma_list(struct vme_resource *res);
251	
252		int vme_dma_list_free(struct vme_dma_list *list);
253	
254	
255	List Population
256	---------------
257	
258	An item can be added to a list using the following function ( the source and
259	destination attributes need to be created before calling this function, this is
260	covered under "Transfer Attributes"):
261	
262		int vme_dma_list_add(struct vme_dma_list *list,
263			struct vme_dma_attr *src, struct vme_dma_attr *dest,
264			size_t count);
265	
266	NOTE:	The detailed attributes of the transfers source and destination
267		are not checked until an entry is added to a DMA list, the request
268		for a DMA channel purely checks the directions in which the
269		controller is expected to transfer data. As a result it is
270		possible for this call to return an error, for example if the
271		source or destination is in an unsupported VME address space.
272	
273	Transfer Attributes
274	-------------------
275	
276	The attributes for the source and destination are handled separately from adding
277	an item to a list. This is due to the diverse attributes required for each type
278	of source and destination. There are functions to create attributes for PCI, VME
279	and pattern sources and destinations (where appropriate):
280	
281	Pattern source:
282	
283		struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type);
284	
285	PCI source or destination:
286	
287		struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem);
288	
289	VME source or destination:
290	
291		struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base,
292			u32 aspace, u32 cycle, u32 width);
293	
294	The following function should be used to free an attribute:
295	
296		void vme_dma_free_attribute(struct vme_dma_attr *attr);
297	
298	
299	List Execution
300	--------------
301	
302	The following function queues a list for execution. The function will return
303	once the list has been executed:
304	
305		int vme_dma_list_exec(struct vme_dma_list *list);
306	
307	
308	Interrupts
309	==========
310	
311	The VME API provides functions to attach and detach callbacks to specific VME
312	level and status ID combinations and for the generation of VME interrupts with
313	specific VME level and status IDs.
314	
315	
316	Attaching Interrupt Handlers
317	----------------------------
318	
319	The following functions can be used to attach and free a specific VME level and
320	status ID combination. Any given combination can only be assigned a single
321	callback function. A void pointer parameter is provided, the value of which is
322	passed to the callback function, the use of this pointer is user undefined:
323	
324		int vme_irq_request(struct vme_dev *dev, int level, int statid,
325			void (*callback)(int, int, void *), void *priv);
326	
327		void vme_irq_free(struct vme_dev *dev, int level, int statid);
328	
329	The callback parameters are as follows. Care must be taken in writing a callback
330	function, callback functions run in interrupt context:
331	
332		void callback(int level, int statid, void *priv);
333	
334	
335	Interrupt Generation
336	--------------------
337	
338	The following function can be used to generate a VME interrupt at a given VME
339	level and VME status ID:
340	
341		int vme_irq_generate(struct vme_dev *dev, int level, int statid);
342	
343	
344	Location monitors
345	=================
346	
347	The VME API provides the following functionality to configure the location
348	monitor.
349	
350	
351	Location Monitor Management
352	---------------------------
353	
354	The following functions are provided to request the use of a block of location
355	monitors and to free them after they are no longer required:
356	
357		struct vme_resource * vme_lm_request(struct vme_dev *dev);
358	
359		void vme_lm_free(struct vme_resource * res);
360	
361	Each block may provide a number of location monitors, monitoring adjacent
362	locations. The following function can be used to determine how many locations
363	are provided:
364	
365		int vme_lm_count(struct vme_resource * res);
366	
367	
368	Location Monitor Configuration
369	------------------------------
370	
371	Once a bank of location monitors has been allocated, the following functions
372	are provided to configure the location and mode of the location monitor:
373	
374		int vme_lm_set(struct vme_resource *res, unsigned long long base,
375			u32 aspace, u32 cycle);
376	
377		int vme_lm_get(struct vme_resource *res, unsigned long long *base,
378			u32 *aspace, u32 *cycle);
379	
380	
381	Location Monitor Use
382	--------------------
383	
384	The following functions allow a callback to be attached and detached from each
385	location monitor location. Each location monitor can monitor a number of
386	adjacent locations:
387	
388		int vme_lm_attach(struct vme_resource *res, int num,
389			void (*callback)(void *));
390	
391		int vme_lm_detach(struct vme_resource *res, int num);
392	
393	The callback function is declared as follows.
394	
395		void callback(void *data);
396	
397	
398	Slot Detection
399	==============
400	
401	This function returns the slot ID of the provided bridge.
402	
403		int vme_slot_num(struct vme_dev *dev);
404	
405	
406	Bus Detection
407	=============
408	
409	This function returns the bus ID of the provided bridge.
410	
411		int vme_bus_num(struct vme_dev *dev);
412	
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog