About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / vme_api.txt




Custom Search

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.