Warning, /bsps/powerpc/shared/vme/README.md is written in an unsupported language. File is not indexed.
0001 vme
0002 ===
0003
0004 libbsp/shared/vmeUniverse/VME.h: VME API; BSP and bridge-chip independent
0005 VMEConfig.h: defines BSP specific constants for VME configuration
0006 vmeconfig.c configures the VME bridge using the VME.h API calls
0007 and BSP specific constants from VMEConfig.h.
0008 Independent of the bridge chip, however.
0009 vme_universe.c: implements VME.h for the vmeUniverse driver.
0010 vme_universe_dma.c: implements VMEDMA.h for the vmeUniverse driver.
0011
0012 o other universe BSP --> use its own VMEConfig.h; may reuse vmeconfig.c, vme_universe.c
0013 o other non-universe BSP --> use its own VMEConfig.h and vme_xxx.c; may reuse vmeconfig.c
0014
0015
0016 Porting
0017 =======
0018 NOTE: (T.S, 2007/1) The information in this file is outdated
0019 (but some portions may still be useful). Some more information
0020 about how to use the Universe and Tsi148 drivers in new BSPs
0021 can be found in
0022
0023 README.universe,
0024 libbsp/powerpc/shared/vme/VMEConfig.h,
0025
0026 source files in this directory and libbsp/powerpc/shared/vme
0027
0028 The vmeUniverse driver needs some support from the BSP for
0029
0030 a) PCI configuration space access
0031 b) PCI interrupt acknowledgement
0032 c) PCI interrupt handler installation
0033
0034 The driver was developed using the powerpc/shared/ BSP
0035 (it also supports vxWorks) and by default uses that BSP's
0036 a) PCI access API
0037 b,c) irq handling API (AKA 'new' style BSP_install_rtems_irq_handler()
0038 API).
0039
0040 Some hooks exist in the driver to ease porting to other BSPs.
0041 The following information has been assembled when answering a
0042 question regarding a ppcn_60x BSP port:
0043
0044 I looked through the ppcn_60x BSP. Here's what I found:
0045
0046 - this BSP does NOT adhere to neither the 'old' nor the 'new' API
0047 but provides its own (startup/setvec.c: set_vector()).
0048 - the BSP has a 'driver' for vmeUniverse although mine is far more
0049 complete (including support for VME interrupts, DMA etc.).
0050 - Porting my driver to your BSP should not be too hard:
0051
0052 1) vmeUniverse needs PCI configuration space support from the
0053 BSP:
0054 a) a routine 'pciFindDevice' (need to be macro-aliased
0055 to the proper routine/wrapper of your BSP) who scans
0056 PCI config space for the universe bridge.
0057 You could add 'libbsp/powerpc/shared/pci/pcifinddevice.c'
0058 to your BSP substituting the pci_read_config_xxx calls
0059 by the ones present on your BSP (see step 2))
0060 b) routines to read PCI config registers (byte and longword)
0061 [on your BSP these are PCIConfigRead32/PCIConfigRead8;
0062 hence you could replace the macros on top with
0063 #define pciConfigInLong PCIConfigRead32
0064 2) vmeUniverse needs to know how to acknowledge a PCI interrupt
0065 In your case, nothing needs to be done
0066 #define BSP_PIC_DO_EOI do {} while (0)
0067 3) Install the VME ISR dispatcher: replace the 'new' style
0068 interrupt installer (BSP_install_rtems_irq_handler()) by
0069 a proper call to 'set_vector()'
0070 4) I might have missed something...
0071
0072 I attach the latest version of the vmeUniverse driver in case you want
0073 to try to do the port (should be easy).
0074
0075 For the sake of ease of maintenance, I just added a few hooks making it
0076 possible to override some things without having to modify the driver code.
0077
0078 1,2) PCI config space access macros may be overriden via CFLAGS
0079 when compiling vmeUniverse.c, hence:
0080 CFLAGS += -DBSP_PIC_DO_EOI=do{}while(0)
0081 CFLAGS += -DBSP_PCI_CONFIG_IN_LONG=PCIConfigRead32
0082 CFLAGS += -DBSP_PCI_CONFIG_IN_BYTE=PCIConfigRead8
0083 (you still need to supply pci_find_device)
0084 3) create your own version of vmeUniverseInstallIrqMgr():
0085 copy to a separate file and replace
0086 BSP_rtems_install_irq_handler() by a proper call to set_vector.
0087
0088 4) Send me email :-)
0089
0090 USAGE NOTE: To fully initialize the driver, the following steps can/must
0091 be performed:
0092
0093 vmeUniverseInit(); /* MANDATORY: Driver Initialization */
0094 vmeUniverseReset(); /* OPTIONAL: Reset most registers to a known state;
0095 * if this step is omitted, firmware setup is
0096 * preserved
0097 */
0098 vmeUniverseMasterPortCfg(...); /* OPTIONAL: setup the master windows
0099 * (current setup preserved if omitted)
0100 */
0101 vmeUniverseSlavePortCfg(...); /* OPTIONAL: setup the slave windows
0102 * (current setup preserved if omitted)
0103 */
0104 vmeUniverseInstallIrqMgr(); /* NEEDED FOR VME INTERRUPT SUPPRORT
0105 * initialize the interrupt manager.
0106 * NOTE: you need to call your own
0107 * version of this routine here
0108 */
0109
0110 For an example of init/setup, consult libbsp/powerpc/shared/vme/vmeconfig.c
0111
0112
0113 Universe
0114 ========
0115 The tundra drivers are in a separate subdir
0116 because they are maintained at SSRL outside of the
0117 rtems CVS tree. The directory is called 'vmeUniverse'
0118 for historic reasons. 'tundra' would be better
0119 since we now support the tundra tsi148 as well...
0120
0121 Till Straumann <strauman@slac.stanford.edu> 1/2002, 2005, 2007
0122
0123 A BSP that wants to use these drivers
0124 must implement the following headers / functionality:
0125 - <bsp/pci.h> offering an API like 'libbsp/powerpc/shared/pci'
0126 - <bsp/irq.h> offering the 'new style' RTEMS irq API
0127 (like 'libbsp/powerpc/shared/irq').
0128 - <libcpu/io.h> for the I/O operations (out_le32,in_le32, ..., out_be32,...)
0129 - <libcpu/byteorder.h> for byte-swapping (st_le32, ld_le32, ..., st_be32,...)
0130 - glue code that implements the 'VME.h' and 'VMEDMA.h' APIs
0131 using the vmeUniverse and/or vmeTsi148 driver code.
0132 The 'glue' code initializes appropriate VME/PCI windows when booting
0133 and installs the VME interrupt manager.
0134
0135 The 'glue' may also use the 'bspVmeDmaList' code to implement generic
0136 parts of linked-list DMA.
0137
0138 Boards with a 'universe' chip may use a pretty generic version of
0139 the glue code that is defined in libbsp/powerpc/shared/vmeconfig.c,
0140 libbsp/powerpc/shared/vme_universe.c, and
0141 libbsp/powerpc/shared/vme_universe_dma.c. The board-specific parameters
0142 are defined in a single BSP-specific file 'VMEConfig.h'. That's where
0143 the actual addresses of VME/PCI windows are configured and where
0144 interrupt wires can be assigned etc.
0145
0146 Read libbsp/powerpc/shared/VMEConfig.h for more information and use
0147 it as a template. Note that BSP implementors should try *not* to
0148 clone 'vmeconfig.c' but use the constants in VMEConfig.h
0149
0150 - The BSP should export 'VME.h' and 'VMEDMA.h' to applications
0151 and encourage them to only use the API defined there in order
0152 to make application code driver-independent. This will ensure
0153 seamless portability of applications between the universe and Tsi148
0154 drivers.
0155
0156
0157 TESTING: A valuable tool for testing are the (substitute XXX for
0158 'Universe' or 'Tsi148') routines:
0159 vmeXXXMapCRG()
0160 maps the controller registers to VME space so you
0161 can test if you successfully can read/write from VME.
0162 You can read or DMA the PCI configuration registers
0163 and compare to what you expect (beware of endianness).
0164
0165 vmeXXXIntLoopbackTest()
0166 this installs an ISR and then asserts an IRQ on the VME
0167 backplane so you can verify that your interrupt routing
0168 and handling really works.
0169
0170 NOTES: The universe may always issue MBLTs if a data width of 64-bit
0171 is enabled (default for non-BLT addressing modes -- the
0172 VME_AM_STD_xx_BLT / VME_AM_EXT_xx_BLT enforce 32-bit transfers).
0173
0174 Therefore, if you want to setup a outbound window that always
0175 uses single cycles then you must explicitely request a data
0176 width < 64, e.g.,
0177 ```c
0178 vmeUniverseMasterPortCfg(port, VME_AM_EXT_SUP_DATA | VME_MODE_DBW32, vme_addr, pci_addr, size);
0179 ```
