RTEMS
ambapp.h
Go to the documentation of this file.
1 
6 /*
7  * COPYRIGHT (c) 2009.
8  * Aeroflex Gaisler.
9  *
10  * The license and distribution terms for this file may be
11  * found in the file LICENSE in this distribution or at
12  * http://www.rtems.org/license/LICENSE.
13  */
14 
15 #ifndef __AMBAPP_H__
16 #define __AMBAPP_H__
17 
28 /* Include VENDOR and DEVICE definitions */
29 #include "ambapp_ids.h"
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /* Max supported AHB buses */
36 #define AHB_BUS_MAX 6
37 
38 #define AMBAPP_FLAG_FFACT_DIR 0x100 /* Frequency factor direction, 0=down, 1=up */
39 #define AMBAPP_FLAG_FFACT 0x0f0 /* Frequency factor against top bus */
40 #define AMBAPP_FLAG_MBUS 0x00c
41 #define AMBAPP_FLAG_SBUS 0x003
42 
43 /* Get APB or AHB information from a AMBA device */
44 #define DEV_TO_APB(adev) ((struct ambapp_apb_info *)((adev)->devinfo))
45 #define DEV_TO_AHB(adev) ((struct ambapp_ahb_info *)((adev)->devinfo))
46 #define DEV_TO_COMMON(adev) (((adev)->devinfo))
47 
49  unsigned char irq;
50  unsigned char ver;
51  unsigned char ahbidx; /* AHB Bus Index */
52 };
53 
55  struct ambapp_common_info common;
56 
57  /* APB SPECIFIC */
58  unsigned int start;
59  unsigned int mask;
60 };
61 
63  struct ambapp_common_info common;
64 
65  /* AHB SPECIFIC */
66  unsigned int start[4];
67  unsigned int mask[4];
68  char type[4]; /* type[N] Determine type of start[N]-mask[N],
69  * 2=AHB Memory Space, 3=AHB I/O Space */
70  unsigned int custom[3];
71 };
72 
73 struct ambapp_dev {
74  struct ambapp_dev *next; /* Next */
75  struct ambapp_dev *prev; /* Previous Device. If (this ==
76  * rev->child) prev is bus bridge */
77  struct ambapp_dev *children; /* Points to first device on sub-bus */
78  void *owner; /* Owner of this AMBA device */
79  unsigned char dev_type; /* AHB MST, AHB SLV or APB SLV*/
80  unsigned char vendor; /* Vendor ID */
81  unsigned short device; /* Device ID */
82 
83  /* Device info (APB/AHB dep. on type) */
84  struct ambapp_common_info devinfo[0];
85 };
86 
87 /* Describes a complete AMBA Core. Each device may consist of 3 interfaces */
88 struct ambapp_core {
89  char irq; /* irq=-1 indicate no IRQ */
90  unsigned char vendor;
91  unsigned short device;
92  int index; /* Core index */
93  struct ambapp_ahb_info *ahb_mst;
94  struct ambapp_ahb_info *ahb_slv;
95  struct ambapp_apb_info *apb_slv;
96 };
97 
99  unsigned int ioarea; /* AHB Bus IOAREA */
100  unsigned int freq_hz; /* Frequency of AHB Bus */
101  struct ambapp_dev *bridge;/* Bridge Device on Parent AHB Bus */
102  struct ambapp_dev *dev; /* First Device on AHB Bus */
103 };
104 
105 struct ambapp_mmap {
106  unsigned int size;
107  unsigned int local_adr;
108  unsigned int remote_adr;
109 };
110 
111 /* Complete AMBA PnP information */
112 struct ambapp_bus {
113  struct ambapp_dev *root; /* AHB/APB Device Tree*/
114  struct ambapp_mmap *mmaps; /* Memory MAP Array */
115  struct ambapp_ahb_bus ahbs[AHB_BUS_MAX]; /* AHB Buses */
116 };
117 
118 /*
119  * Return values
120  * 0 - continue
121  * 1 - stop scanning
122  */
123 typedef int (*ambapp_func_t)(struct ambapp_dev *dev, int index, void *arg);
124 
125 #define DEV_IS_FREE(dev) (dev->owner == NULL)
126 #define DEV_IS_ALLOCATED(dev) (dev->owner != NULL)
127 
128 /* Options to ambapp_for_each */
129 #define OPTIONS_AHB_MSTS 0x00000001
130 #define OPTIONS_AHB_SLVS 0x00000002
131 #define OPTIONS_APB_SLVS 0x00000004
132 #define OPTIONS_ALL_DEVS (OPTIONS_AHB_MSTS|OPTIONS_AHB_SLVS|OPTIONS_APB_SLVS)
133 
134 #define OPTIONS_FREE 0x00000010
135 #define OPTIONS_ALLOCATED 0x00000020
136 #define OPTIONS_ALL (OPTIONS_FREE|OPTIONS_ALLOCATED)
137 
138 /* Depth first search, Defualt is breath first search. */
139 #define OPTIONS_DEPTH_FIRST 0x00000100
140 
141 #define DEV_AHB_NONE 0
142 #define DEV_AHB_MST 1
143 #define DEV_AHB_SLV 2
144 #define DEV_APB_SLV 3
145 
146 /* Structures used to access Plug&Play information directly */
148  const unsigned int id; /* VENDOR, DEVICE, VER, IRQ, */
149  const unsigned int custom[3];
150  const unsigned int mbar[4]; /* MASK, ADDRESS, TYPE, CACHABLE/PREFETCHABLE */
151 };
152 
154  const unsigned int id; /* VENDOR, DEVICE, VER, IRQ, */
155  const unsigned int iobar; /* MASK, ADDRESS, TYPE, CACHABLE/PREFETCHABLE */
156 };
157 
158 #define ambapp_pnp_vendor(id) (((id) >> 24) & 0xff)
159 #define ambapp_pnp_device(id) (((id) >> 12) & 0xfff)
160 #define ambapp_pnp_ver(id) (((id)>>5) & 0x1f)
161 #define ambapp_pnp_irq(id) ((id) & 0x1f)
162 
163 #define ambapp_pnp_start(mbar) (((mbar) & 0xfff00000) & (((mbar) & 0xfff0) << 16))
164 #define ambapp_pnp_mbar_mask(mbar) (((mbar)>>4) & 0xfff)
165 #define ambapp_pnp_mbar_type(mbar) ((mbar) & 0xf)
166 
167 #define ambapp_pnp_apb_start(iobar, base) ((base) | ((((iobar) & 0xfff00000)>>12) & (((iobar) & 0xfff0)<<4)) )
168 #define ambapp_pnp_apb_mask(iobar) ((~(ambapp_pnp_mbar_mask(iobar)<<8) & 0x000fffff) + 1)
169 
170 #define AMBA_TYPE_AHBIO_ADDR(addr,base_ioarea) ((unsigned int)(base_ioarea) | ((addr) >> 12))
171 
172 #define AMBA_TYPE_APBIO 0x1
173 #define AMBA_TYPE_MEM 0x2
174 #define AMBA_TYPE_AHBIO 0x3
175 
176 /* Copy Data from AMBA PnP I/O Area */
177 typedef void *(*ambapp_memcpy_t)(
178  void *dest, /* Destination RAM copy */
179  const void *src, /* Source AMBA PnP Address to copy from */
180  int n, /* Number of bytes to be copied */
181  struct ambapp_bus *abus /* Optional AMBA Bus pointer */
182  );
183 
184 /* Scan a AMBA Plug & Play bus and create all device structures describing the
185  * the devices. The devices will form a tree, where every node describes one
186  * interface. The resulting tree is placed in the location pointed to by root.
187  *
188  * Since it the tree is located in RAM it is easier to work with AMBA buses
189  * that is located over PCI and SpaceWire etc.
190  *
191  * \param ioarea The IO-AREA where Plug & Play information can be found.
192  * \param parent Used internally when recursing down a bridge. Set to NULL.
193  * \param mmaps Is used to perform address translation if needed.
194  * \param root Resulting device node tree root is stored here.
195  *
196  */
197 extern int ambapp_scan(
198  struct ambapp_bus *abus,
199  unsigned int ioarea,
200  ambapp_memcpy_t memfunc,
201  struct ambapp_mmap *mmaps
202  );
203 
204 /* Initialize the frequency [Hz] of all AHB Buses from knowing the frequency
205  * of one particular APB/AHB Device.
206  */
207 extern void ambapp_freq_init(
208  struct ambapp_bus *abus,
209  struct ambapp_dev *dev,
210  unsigned int freq);
211 
212 /* Returns the frequency [Hz] of a AHB/APB device */
213 extern unsigned int ambapp_freq_get(
214  struct ambapp_bus *abus,
215  struct ambapp_dev *dev);
216 
217 /* Iterates through all AMBA devices previously found, it calls func
218  * once for every device that match the search arguments.
219  *
220  * SEARCH OPTIONS
221  * All search options must be fulfilled, type of devices searched (options)
222  * and AMBA Plug&Play ID [VENDOR,DEVICE], before func() is called. The options
223  * can be use to search only for AMBA APB or AHB Slaves or AHB Masters for
224  * example. Note that when VENDOR=-1 or DEVICE=-1 it will match any vendor or
225  * device ID, this means setting both VENDOR and DEVICE to -1 will result in
226  * calling all devices matches the options argument.
227  *
228  * \param abus AMBAPP Bus to search
229  * \param options Search options, see OPTIONS_* above
230  * \param vendor AMBAPP VENDOR ID to search for
231  * \param device AMBAPP DEVICE ID to search for
232  * \param func Function called for every device matching search options
233  * \param arg Optional argument passed on to func
234  *
235  * func return value affects the search, returning a non-zero value will
236  * stop the search and ambapp_for_each will return immediately returning the
237  * same non-zero value.
238  *
239  * Return Values
240  * 0 - all devices was scanned
241  * non-zero - stopped by user function returning the non-zero value
242  */
243 extern int ambapp_for_each(
244  struct ambapp_bus *abus,
245  unsigned int options,
246  int vendor,
247  int device,
248  ambapp_func_t func,
249  void *arg);
250 
251 /* Helper function for ambapp_for_each(), find a device by index. If pcount
252  * is NULL the first device is returned, else pcount is interpreted as index
253  * by decrementing the value until zero is reaced: *count=0 first device,
254  * *count=1 second device etc.
255  *
256  * The matching device is returned, which will stop the ambapp_for_each search.
257  * If zero is returned from ambapp_for_each no device matching the index was
258  * found
259  */
260 extern int ambapp_find_by_idx(struct ambapp_dev *dev, int index, void *pcount);
261 
262 /* Get number of devices matching the options/vendor/device arguments, the
263  * arguments are passed onto ambapp_for_each().
264  */
265 extern int ambapp_dev_count(struct ambapp_bus *abus, unsigned int options,
266  int vendor, int device);
267 
268 /* Print short information about devices on the AMBA bus onto the console */
269 extern void ambapp_print(struct ambapp_bus *abus, int show_depth);
270 
271 /* Mark a device taken (allocate), Owner field is set with owner Data. Returns
272  * -1 if device has already been allocated.
273  */
274 extern int ambapp_alloc_dev(struct ambapp_dev *dev, void *owner);
275 
276 /* Owner field is cleared, which indicates that device is not allocated */
277 extern void ambapp_free_dev(struct ambapp_dev *dev);
278 
279 /* Find AHB/APB Bridge or AHB/AHB Bridge Parent */
280 extern struct ambapp_dev *ambapp_find_parent(struct ambapp_dev *dev);
281 
282 /* Returns bus depth (number of sub AHB buses) of device from root bus */
283 extern int ambapp_depth(struct ambapp_dev *dev);
284 
285 /* Get Device Name from AMBA PnP name database */
286 extern char *ambapp_device_id2str(int vendor, int id);
287 
288 /* Get Vendor Name from AMBA PnP name database */
289 extern char *ambapp_vendor_id2str(int vendor);
290 
291 /* Set together VENDOR_DEVICE Name from AMBA PnP name database. Return length
292  * of C-string stored in buf not including string termination '\0'.
293  */
294 extern int ambapp_vendev_id2str(int vendor, int id, char *buf);
295 
296 /* Help functions for backwards compability */
297 
298 extern int ambapp_find_apbslv(
299  struct ambapp_bus *abus,
300  int vendor,
301  int device,
302  struct ambapp_apb_info *dev);
303 
304 extern int ambapp_find_apbslv_next(
305  struct ambapp_bus *abus,
306  int vendor,
307  int device,
308  struct ambapp_apb_info *dev,
309  int index);
310 
311 extern int ambapp_find_apbslvs_next(
312  struct ambapp_bus *abus,
313  int vendor,
314  int device,
315  struct ambapp_apb_info *dev,
316  int index,
317  int maxno);
318 
319 extern int ambapp_find_apbslvs(
320  struct ambapp_bus *abus,
321  int vendor,
322  int device,
323  struct ambapp_apb_info *dev,
324  int maxno);
325 
326 extern int ambapp_find_ahbslv(
327  struct ambapp_bus *abus,
328  int vendor,
329  int device,
330  struct ambapp_ahb_info *dev);
331 
332 extern int ambapp_find_ahbslv_next(
333  struct ambapp_bus *abus,
334  int vendor,
335  int device,
336  struct ambapp_ahb_info *dev,
337  int index);
338 
339 extern int ambapp_find_ahbslvs_next(
340  struct ambapp_bus *abus,
341  int vendor,
342  int device,
343  struct ambapp_ahb_info *dev,
344  int index,
345  int maxno);
346 
347 extern int ambapp_find_ahbslvs(
348  struct ambapp_bus *abus,
349  int vendor,
350  int device,
351  struct ambapp_ahb_info *dev,
352  int maxno);
353 
354 
355 extern int ambapp_get_number_ahbslv_devices(
356  struct ambapp_bus *abus,
357  int vendor,
358  int device);
359 
360 extern int ambapp_get_number_apbslv_devices(
361  struct ambapp_bus *abus,
362  int vendor,
363  int device);
364 
365 #ifdef __cplusplus
366 }
367 #endif
368 
371 #endif
AMBA Plug & Play Bus Vendor and Device IDs.