include/grlib/ambapp.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  * @ingroup amba
0006  */
0007
0008 /*
0009  *  COPYRIGHT (c) 2009.
0010  *  Aeroflex Gaisler.
0011  *
0012  * Redistribution and use in source and binary forms, with or without
0013  * modification, are permitted provided that the following conditions
0014  * are met:
0015  * 1. Redistributions of source code must retain the above copyright
0016  *    notice, this list of conditions and the following disclaimer.
0017  * 2. Redistributions in binary form must reproduce the above copyright
0018  *    notice, this list of conditions and the following disclaimer in the
0019  *    documentation and/or other materials provided with the distribution.
0020  *
0021  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0022  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0023  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0024  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0025  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0026  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0027  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0028  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0029  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0030  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0031  * POSSIBILITY OF SUCH DAMAGE.
0032  */
0033
0034 #ifndef __AMBAPP_H__
0035 #define __AMBAPP_H__
0036
0037 #include <stddef.h>
0038
0039 /* Include VENDOR and DEVICE definitions */
0040 #include "ambapp_ids.h"
0041
0042 #ifdef __cplusplus
0043 extern "C" {
0044 #endif
0045
0046 /**
0047  * @defgroup amba AMBA
0048  *
0049  * @ingroup RTEMSBSPsSharedGRLIB
0050  *
0051  * @brief AMBA Plug & Play routines
0052  *
0053  * @{
0054  */
0055
0056 /* Max supported AHB buses */
0057 #define AHB_BUS_MAX 6
0058
0059 #define AMBAPP_FLAG_FFACT_DIR   0x100   /* Frequency factor direction, 0=down, 1=up */
0060 #define AMBAPP_FLAG_FFACT   0x0f0   /* Frequency factor against top bus */
0061 #define AMBAPP_FLAG_MBUS    0x00c
0062 #define AMBAPP_FLAG_SBUS    0x003
0063
0064 /* Get APB or AHB information from a AMBA device */
0065 #define DEV_TO_APB(adev) ((struct ambapp_apb_info *)((adev)->devinfo))
0066 #define DEV_TO_AHB(adev) ((struct ambapp_ahb_info *)((adev)->devinfo))
0067 #define DEV_TO_COMMON(adev) (((adev)->devinfo))
0068
0069 struct ambapp_common_info {
0070     unsigned char irq;
0071     unsigned char ver;
0072     unsigned char ahbidx;   /* AHB Bus Index */
0073 };
0074
0075 struct ambapp_apb_info {
0076     struct ambapp_common_info common;
0077
0078     /* APB SPECIFIC */
0079     unsigned int start;
0080     unsigned int mask;
0081 };
0082
0083 struct ambapp_ahb_info {
0084     struct ambapp_common_info common;
0085
0086     /* AHB SPECIFIC */
0087     unsigned int start[4];
0088     unsigned int mask[4];
0089     char type[4];       /* type[N] Determine type of start[N]-mask[N],
0090                  * 2=AHB Memory Space, 3=AHB I/O Space */
0091     unsigned int custom[3];
0092 };
0093
0094 struct ambapp_dev {
0095     struct ambapp_dev *next;    /* Next */
0096     struct ambapp_dev *prev;    /* Previous Device. If (this ==
0097                      * rev->child) prev is bus bridge */
0098     struct ambapp_dev *children;    /* Points to first device on sub-bus */
0099     void *owner;            /* Owner of this AMBA device */
0100     unsigned char dev_type;     /* AHB MST, AHB SLV or APB SLV*/
0101     unsigned char vendor;       /* Vendor ID */
0102     unsigned short device;      /* Device ID */
0103
0104     /* Device info (APB/AHB dep. on type) */
0105     struct ambapp_common_info devinfo[0];
0106 };
0107
0108 /* Describes a complete AMBA Core. Each device may consist of 3 interfaces */
0109 struct ambapp_core {
0110     char            irq;        /* irq=-1 indicate no IRQ */
0111     unsigned char       vendor;
0112     unsigned short      device;
0113     int         index;      /* Core index */
0114     struct ambapp_ahb_info  *ahb_mst;
0115     struct ambapp_ahb_info  *ahb_slv;
0116     struct ambapp_apb_info  *apb_slv;
0117 };
0118
0119 struct ambapp_ahb_bus {
0120     unsigned int ioarea;    /* AHB Bus IOAREA */
0121     unsigned int freq_hz;   /* Frequency of AHB Bus */
0122     struct ambapp_dev *bridge;/* Bridge Device on Parent AHB Bus */
0123     struct ambapp_dev *dev; /* First Device on AHB Bus */
0124 };
0125
0126 struct ambapp_mmap {
0127     unsigned int        size;
0128     unsigned int        local_adr;
0129     unsigned int        remote_adr;
0130 };
0131
0132 /* Complete AMBA PnP information */
0133 struct ambapp_bus {
0134     struct ambapp_dev   *root;          /* AHB/APB Device Tree*/
0135     struct ambapp_mmap  *mmaps;         /* Memory MAP Array */
0136     struct ambapp_ahb_bus   ahbs[AHB_BUS_MAX];  /* AHB Buses */
0137 };
0138
0139 /*
0140  * Return values
0141  *  0 - continue
0142  *  1 - stop scanning
0143  */
0144 typedef int (*ambapp_func_t)(struct ambapp_dev *dev, int index, void *arg);
0145
0146 #define DEV_IS_FREE(dev) (dev->owner == NULL)
0147 #define DEV_IS_ALLOCATED(dev) (dev->owner != NULL)
0148
0149 /* Options to ambapp_for_each */
0150 #define OPTIONS_AHB_MSTS    0x00000001
0151 #define OPTIONS_AHB_SLVS    0x00000002
0152 #define OPTIONS_APB_SLVS    0x00000004
0153 #define OPTIONS_ALL_DEVS    (OPTIONS_AHB_MSTS|OPTIONS_AHB_SLVS|OPTIONS_APB_SLVS)
0154
0155 #define OPTIONS_FREE        0x00000010
0156 #define OPTIONS_ALLOCATED   0x00000020
0157 #define OPTIONS_ALL     (OPTIONS_FREE|OPTIONS_ALLOCATED)
0158
0159 /* Depth first search, Defualt is breath first search. */
0160 #define OPTIONS_DEPTH_FIRST 0x00000100
0161
0162 #define DEV_AHB_NONE 0
0163 #define DEV_AHB_MST  1
0164 #define DEV_AHB_SLV  2
0165 #define DEV_APB_SLV 3
0166
0167 /* Structures used to access Plug&Play information directly */
0168 struct ambapp_pnp_ahb {
0169     const unsigned int  id;     /* VENDOR, DEVICE, VER, IRQ, */
0170     const unsigned int  custom[3];
0171     const unsigned int  mbar[4];    /* MASK, ADDRESS, TYPE, CACHABLE/PREFETCHABLE */
0172 };
0173
0174 struct ambapp_pnp_apb {
0175     const unsigned int  id;     /* VENDOR, DEVICE, VER, IRQ, */
0176     const unsigned int  iobar;      /* MASK, ADDRESS, TYPE, CACHABLE/PREFETCHABLE */
0177 };
0178
0179 #define ambapp_pnp_vendor(id) (((id) >> 24) & 0xff)
0180 #define ambapp_pnp_device(id) (((id) >> 12) & 0xfff)
0181 #define ambapp_pnp_ver(id) (((id)>>5) & 0x1f)
0182 #define ambapp_pnp_irq(id) ((id) & 0x1f)
0183
0184 #define ambapp_pnp_start(mbar)  (((mbar) & 0xfff00000) & (((mbar) & 0xfff0) << 16))
0185 #define ambapp_pnp_mbar_mask(mbar) (((mbar)>>4) & 0xfff)
0186 #define ambapp_pnp_mbar_type(mbar) ((mbar) & 0xf)
0187
0188 #define ambapp_pnp_apb_start(iobar, base) ((base) | ((((iobar) & 0xfff00000)>>12) & (((iobar) & 0xfff0)<<4)) )
0189 #define ambapp_pnp_apb_mask(iobar) ((~(ambapp_pnp_mbar_mask(iobar)<<8) & 0x000fffff) + 1)
0190
0191 #define AMBA_TYPE_AHBIO_ADDR(addr,base_ioarea) ((unsigned int)(base_ioarea) | ((addr) >> 12))
0192
0193 #define AMBA_TYPE_APBIO 0x1
0194 #define AMBA_TYPE_MEM   0x2
0195 #define AMBA_TYPE_AHBIO 0x3
0196
0197 /* Copy Data from AMBA PnP I/O Area */
0198 typedef void *(*ambapp_memcpy_t)(
0199     void *dest,     /* Destination RAM copy */
0200     const void *src,    /* Source AMBA PnP Address to copy from */
0201     int n,          /* Number of bytes to be copied */
0202     struct ambapp_bus *abus /* Optional AMBA Bus pointer */
0203     );
0204
0205 struct ambapp_context {
0206   ambapp_memcpy_t copy_from_device;
0207   void *(*alloc)(size_t);
0208 };
0209
0210 /**
0211  * @brief Gets the fully scanned AMBA Plug & Play Processor Local Bus (PLB).
0212  */
0213 extern struct ambapp_bus *ambapp_plb(void);
0214
0215 /* Scan a AMBA Plug & Play bus and create all device structures describing the
0216  * the devices. The devices will form a tree, where every node describes one
0217  * interface. The resulting tree is placed in the location pointed to by root.
0218  *
0219  * Since it the tree is located in RAM it is easier to work with AMBA buses
0220  * that is located over PCI and SpaceWire etc.
0221  *
0222  * \param abus     Resulting device node tree root is stored here.
0223  * \param ioarea   The IO-AREA where Plug & Play information can be found.
0224  * \param ctx      The scan context.  May be NULL.
0225  * \param mmaps    Is used to perform address translation if needed.
0226  *
0227  */
0228 extern int ambapp_scan(
0229     struct ambapp_bus *abus,
0230     unsigned int ioarea,
0231     const struct ambapp_context *ctx,
0232     struct ambapp_mmap *mmaps
0233     );
0234
0235 /* Initialize the frequency [Hz] of all AHB Buses from knowing the frequency
0236  * of one particular APB/AHB Device.
0237  */
0238 extern void ambapp_freq_init(
0239     struct ambapp_bus *abus,
0240     struct ambapp_dev *dev,
0241     unsigned int freq);
0242
0243 /* Returns the frequency [Hz] of a AHB/APB device */
0244 extern unsigned int ambapp_freq_get(
0245     struct ambapp_bus *abus,
0246     struct ambapp_dev *dev);
0247
0248 /* Iterates through all AMBA devices previously found, it calls func
0249  * once for every device that match the search arguments.
0250  *
0251  * SEARCH OPTIONS
0252  * All search options must be fulfilled, type of devices searched (options)
0253  * and AMBA Plug&Play ID [VENDOR,DEVICE], before func() is called. The options
0254  * can be use to search only for AMBA APB or AHB Slaves or AHB Masters for
0255  * example. Note that when VENDOR=-1 or DEVICE=-1 it will match any vendor or
0256  * device ID, this means setting both VENDOR and DEVICE to -1 will result in
0257  * calling all devices matches the options argument.
0258  *
0259  * \param abus     AMBAPP Bus to search
0260  * \param options  Search options, see OPTIONS_* above
0261  * \param vendor   AMBAPP VENDOR ID to search for
0262  * \param device   AMBAPP DEVICE ID to search for
0263  * \param func     Function called for every device matching search options
0264  * \param arg      Optional argument passed on to func
0265  *
0266  * func return value affects the search, returning a non-zero value will
0267  * stop the search and ambapp_for_each will return immediately returning the
0268  * same non-zero value.
0269  *
0270  * Return Values
0271  *  0 - all devices was scanned
0272  *  non-zero - stopped by user function returning the non-zero value
0273  */
0274 extern int ambapp_for_each(
0275     struct ambapp_bus *abus,
0276     unsigned int options,
0277     int vendor,
0278     int device,
0279     ambapp_func_t func,
0280     void *arg);
0281
0282 /* Helper function for ambapp_for_each(), find a device by index. If pcount
0283  * is NULL the first device is returned, else pcount is interpreted as index
0284  * by decrementing the value until zero is reaced: *count=0 first device,
0285  * *count=1 second device etc.
0286  *
0287  * The matching device is returned, which will stop the ambapp_for_each search.
0288  * If zero is returned from ambapp_for_each no device matching the index was
0289  * found
0290  */
0291 extern int ambapp_find_by_idx(struct ambapp_dev *dev, int index, void *pcount);
0292
0293 /* Get number of devices matching the options/vendor/device arguments, the
0294  * arguments are passed onto ambapp_for_each().
0295  */
0296 extern int ambapp_dev_count(struct ambapp_bus *abus, unsigned int options,
0297                 int vendor, int device);
0298
0299 /* Print short information about devices on the AMBA bus onto the console */
0300 extern void ambapp_print(struct ambapp_bus *abus, int show_depth);
0301
0302 /* Mark a device taken (allocate), Owner field is set with owner Data. Returns
0303  * -1 if device has already been allocated.
0304  */
0305 extern int ambapp_alloc_dev(struct ambapp_dev *dev, void *owner);
0306
0307 /* Owner field is cleared, which indicates that device is not allocated */
0308 extern void ambapp_free_dev(struct ambapp_dev *dev);
0309
0310 /* Find AHB/APB Bridge or AHB/AHB Bridge Parent */
0311 extern struct ambapp_dev *ambapp_find_parent(struct ambapp_dev *dev);
0312
0313 /* Returns bus depth (number of sub AHB buses) of device from root bus */
0314 extern int ambapp_depth(struct ambapp_dev *dev);
0315
0316 /* Get Device Name from AMBA PnP name database */
0317 extern char *ambapp_device_id2str(int vendor, int id);
0318
0319 /* Get Vendor Name from AMBA PnP name database */
0320 extern char *ambapp_vendor_id2str(int vendor);
0321
0322 /* Set together VENDOR_DEVICE Name from AMBA PnP name database. Return length
0323  * of C-string stored in buf not including string termination '\0'.
0324  */
0325 extern int ambapp_vendev_id2str(int vendor, int id, char *buf);
0326
0327 /* Help functions for backwards compability */
0328
0329 extern int ambapp_find_apbslv(
0330     struct ambapp_bus *abus,
0331     int vendor,
0332     int device,
0333     struct ambapp_apb_info *dev);
0334
0335 extern int ambapp_find_apbslv_next(
0336     struct ambapp_bus *abus,
0337     int vendor,
0338     int device,
0339     struct ambapp_apb_info *dev,
0340     int index);
0341
0342 extern int ambapp_find_apbslvs_next(
0343     struct ambapp_bus *abus,
0344     int vendor,
0345     int device,
0346     struct ambapp_apb_info *dev,
0347     int index,
0348     int maxno);
0349
0350 extern int ambapp_find_apbslvs(
0351     struct ambapp_bus *abus,
0352     int vendor,
0353     int device,
0354     struct ambapp_apb_info *dev,
0355     int maxno);
0356
0357 extern int ambapp_find_ahbslv(
0358     struct ambapp_bus *abus,
0359     int vendor,
0360     int device,
0361     struct ambapp_ahb_info *dev);
0362
0363 extern int ambapp_find_ahbslv_next(
0364     struct ambapp_bus *abus,
0365     int vendor,
0366     int device,
0367     struct ambapp_ahb_info *dev,
0368     int index);
0369
0370 extern int ambapp_find_ahbslvs_next(
0371     struct ambapp_bus *abus,
0372     int vendor,
0373     int device,
0374     struct ambapp_ahb_info *dev,
0375     int index,
0376     int maxno);
0377
0378 extern int ambapp_find_ahbslvs(
0379     struct ambapp_bus *abus,
0380     int vendor,
0381     int device,
0382     struct ambapp_ahb_info *dev,
0383     int maxno);
0384
0385
0386 extern int ambapp_get_number_ahbslv_devices(
0387     struct ambapp_bus *abus,
0388     int vendor,
0389     int device);
0390
0391 extern int ambapp_get_number_apbslv_devices(
0392     struct ambapp_bus *abus,
0393     int vendor,
0394     int device);
0395
0396 #ifdef __cplusplus
0397 }
0398 #endif
0399
0400 /** @} */
0401
0402 #endif