2007-01-29 Till Straumann <strauman@slac.stanford.edu>

	* shared/vme/VMEConfig.h:
	Added more comments about the semantics of the various
	symbols BSPs should define in this file.
	Removed declarations of BSP_VMEInit(), BSP_VMEIrqMgrInstall().

	* shared/vme/vmeconfig.c: declare BSP_VMEInit(),
	BSP_VMEIrqMgrInstall() here.

	* Makefile.am, shared/vme/README,
	* shared/vme/vme_universe_dma.c (added): Added glue code
	implementing the VMEDMA.h API using the vmeUniverse driver.

6 files changed, 260 insertions, 14 deletions

diff --git a/c/src/lib/libbsp/powerpc/ChangeLog b/c/src/lib/libbsp/powerpc/ChangeLog
index 6ff1f42e34..1cd1773992 100644
--- a/c/src/lib/libbsp/powerpc/ChangeLog
+++ b/c/src/lib/libbsp/powerpc/ChangeLog
@@ -1,3 +1,17 @@
+2007-01-29	Till Straumann <strauman@slac.stanford.edu>
+
+	* shared/vme/VMEConfig.h:
+	Added more comments about the semantics of the various
+	symbols BSPs should define in this file.
+	Removed declarations of BSP_VMEInit(), BSP_VMEIrqMgrInstall().
+
+	* shared/vme/vmeconfig.c: declare BSP_VMEInit(),
+	BSP_VMEIrqMgrInstall() here.
+
+	* Makefile.am, shared/vme/README,
+	* shared/vme/vme_universe_dma.c (added): Added glue code
+	implementing the VMEDMA.h API using the vmeUniverse driver.
+
 2007-01-20      Thomas Doerfler <Thomas.Doerfler@embedded-brains.de>
 
 	* gen5200/mscan/mscan.c, gen5200/mscan/mscan.h,
diff --git a/c/src/lib/libbsp/powerpc/Makefile.am b/c/src/lib/libbsp/powerpc/Makefile.am
index f92464053a..0f9698030a 100644
--- a/c/src/lib/libbsp/powerpc/Makefile.am
+++ b/c/src/lib/libbsp/powerpc/Makefile.am
@@ -63,7 +63,7 @@ EXTRA_DIST += shared/vectors/vectors_init.c shared/vectors/vectors.S
 
 ## shared/vme
 EXTRA_DIST += shared/vme/vmeconfig.c shared/vme/VMEConfig.h
-	shared/vme/README shared/vme/vme_universe.c
+	shared/vme/README shared/vme/vme_universe.c shared/vme/vme_universe_dma.c
 
 include $(top_srcdir)/../../../automake/subdirs.am
 include $(top_srcdir)/../../../automake/local.am
diff --git a/c/src/lib/libbsp/powerpc/shared/vme/README b/c/src/lib/libbsp/powerpc/shared/vme/README
index c4737c3fa8..e2e0020026 100644
--- a/c/src/lib/libbsp/powerpc/shared/vme/README
+++ b/c/src/lib/libbsp/powerpc/shared/vme/README
@@ -1,9 +1,10 @@
-VME.h:          VME API; BSP and bridge-chip independent
+libbsp/shared/vmeUniverse/VME.h: VME API; BSP and bridge-chip independent
 VMEConfig.h:    defines BSP specific constants for VME configuration
 vmeconfig.c     configures the VME bridge using the VME.h API calls
                 and BSP specific constants from VMEConfig.h.
                 Independent of the bridge chip, however.
 vme_universe.c: implements VME.h for the vmeUniverse driver.
+vme_universe_dma.c: implements VMEDMA.h for the vmeUniverse driver.
 
-o  other universe BSP     --> use its own vmeConfig.h; may reuse vmeconfig.c, vme_universe.c
+o  other universe BSP     --> use its own VMEConfig.h; may reuse vmeconfig.c, vme_universe.c
 o  other non-universe BSP --> use its own VMEConfig.h and vme_xxx.c; may reuse vmeconfig.c
diff --git a/c/src/lib/libbsp/powerpc/shared/vme/VMEConfig.h b/c/src/lib/libbsp/powerpc/shared/vme/VMEConfig.h
index cce8a99191..5d669bae8a 100644
--- a/c/src/lib/libbsp/powerpc/shared/vme/VMEConfig.h
+++ b/c/src/lib/libbsp/powerpc/shared/vme/VMEConfig.h
@@ -48,6 +48,7 @@
  * 
  * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
  */ 
+
 /*
  * The BSP maps VME address ranges into
  * one BAT.
@@ -60,6 +61,10 @@
  * If this is undefined, no extra BAT will be
  * configured and VME has to share the available
  * PCI address space with PCI devices.
+ *
+ * If you do define BSP_VME_BAT_IDX you must
+ * make sure the corresponding BAT is really
+ * available and unused!
  */
 
 #if defined(mvme2100)
@@ -75,30 +80,107 @@
 #endif
 
 /* start of the A32 window on the VME bus
- * TODO: this should perhaps be a configuration option
+ * TODO: this should perhaps be a run-time configuration option
  */
 #define _VME_A32_WIN0_ON_VME	0x20000000
 
 /* if _VME_DRAM_OFFSET is defined, the BSP
- * will map our RAM onto the VME bus, starting
+ * will map the board RAM onto the VME bus, starting
  * at _VME_DRAM_OFFSET
  */
 #define _VME_DRAM_OFFSET		0xc0000000
 
-/* Tell the interrupt manager that the universe driver
- * already called openpic_eoi() and that this step hence
- * must be omitted.
+/* Define BSP_PCI_VME_DRIVER_DOES_EOI to let the vmeUniverse
+ * driver (Tsi148 driver doesn't implement this) implement
+ * VME IRQ priorities in software.
+ *
+ * Here's how this works:
+ *
+ *    1) VME IRQ happens
+ *    2) universe propagates IRQ to PCI/PPC/main interrupt
+ *       controller ('PIC' - programmable interrupt controller).
+ *    3) PIC driver dispatches universe driver's ISR
+ *    4) universe driver ISR acknowledges IRQ on VME,
+ *       determines VME vector.
+ * ++++++++++++ stuff between ++ signs is related to SW priorities +++++++++
+ *    5) universe driver *masks* all VME IRQ levels <= interrupting
+ *       level.
+ *    6) universe driver calls PIC driver's 'EOI' routine.
+ *       This effectively re-enables PCI and hence higher
+ *       level VME interrupts.
+ *    7) universe driver dispatches user VME ISR.
+ *
+ * ++>> HIGHER PRIORITY VME IRQ COULD HAPPEN HERE and would be handled <<++
+ *
+ *    8) user ISR returns, universe driver re-enables lower
+ *       level VME interrupts, returns.
+ *    9) universe driver ISR returns control to PIC driver
+ *   10) PIC driver *omits* regular EOI sequence since this
+ *       was already done by universe driver (step 6).
+ * ++++++++++++ end of special handling (SW priorities) ++++++++++++++++++++
+ *   11) PIC driver ISR dispatcher returns.
+ *
+ * Note that the BSP *MUST* provide the following hooks
+ * in order for this to work:
+ *   a) bsp.h must define the symbol BSP_PIC_DO_EOI to
+ *      a sequence of instructions that terminates an
+ *      interrupt at the interrupt controller.
+ *   b) The interrupt controller driver must check the
+ *      interrupt source and *must omit* running the EOI
+ *      sequence if the interrupt source is the vmeUniverse
+ *      (because the universe driver already ran BSP_PIC_DO_EOI)
+ *      The interrupt controller must define the variable
+ *
+ *          int _BSP_vme_bridge_irq = -1;
+ *
+ *      which is assigned the universe's interrupt line information
+ *      by vme_universe.c:BSP_VMEIrqMgrInstall(). The interrupt
+ *      controller driver may use this variable to determine
+ *      if an IRQ was caused by the universe.
+ *
+ *   c) define BSP_PCI_VME_DRIVER_DOES_EOI
+ *
+ *  NOTE: If a) and b) are not implemented by the BSP
+ *        BSP_PCI_VME_DRIVER_DOES_EOI must be *undefined*.
  */
-
 #define BSP_PCI_VME_DRIVER_DOES_EOI
-/* don't reference vmeUniverse0PciIrqLine directly here - leave it up to
- * bspstart() to set BSP_vme_bridge_irq. That way, we can generate variants
- * of the BSP with / without the universe driver...
+
+#ifdef BSP_PCI_VME_DRIVER_DOES_EOI
+/* don't reference vmeUniverse0PciIrqLine directly from the irq
+ * controller driver - leave it up to BSP_VMEIrqMgrInstall() to
+ * set _BSP_vme_bridge_irq. That way, we can avoid linking
+ * the universe driver if VME is unused...
  */
 extern int _BSP_vme_bridge_irq;
+#endif
 
-extern int BSP_VMEInit();
-extern int BSP_VMEIrqMgrInstall();
+/* If your BSP requires a non-standard way to configure
+ * the VME interrupt manager then define the symbol
+ *
+ * BSP_VME_UNIVERSE_INSTALL_IRQ_MGR
+ *
+ * to a proper instruction sequence that installs the
+ * universe interrupt manager. This requires knowledge
+ * of the wiring between the universe and the PIC (main
+ * interrupt controller), i.e., which IRQ 'pins' of the
+ * universe are wired to which 'lines'/inputs at the PIC.
+ * (consult vmeUniverse.h for more information).
+ *
+ * When installing the universe IRQ manager it is also
+ * possible to specify whether it should try to share
+ * PIC interrupts with other sources. This might not
+ * be supported by all BSPs (but the unverse driver
+ * recognizes that).
+ *
+ * If BSP_VME_UNIVERSE_INSTALL_IRQ_MGR is undefined then
+ * the default algorithm is used (vme_universe.c):
+ *
+ * This default setup uses only a single wire. It reads
+ * the PIC 'line' from PCI configuration space and assumes
+ * this to be wired to the first (LIRQ0) IRQ input at the
+ * universe. The default setup tries to use interrupt
+ * sharing.
+ */
 
 #include <bsp/motorola.h>
 #include <bsp/pci.h>
diff --git a/c/src/lib/libbsp/powerpc/shared/vme/vme_universe_dma.c b/c/src/lib/libbsp/powerpc/shared/vme/vme_universe_dma.c
new file mode 100644
index 0000000000..68a0dc887c
--- /dev/null
+++ b/c/src/lib/libbsp/powerpc/shared/vme/vme_universe_dma.c
@@ -0,0 +1,146 @@
+/* $Id$ */
+
+/* Implementation of the VMEDMA.h API for the BSP using the vmeUniverse driver */
+
+/* 
+ * Authorship
+ * ----------
+ * This software was created by
+ *     Till Straumann <strauman@slac.stanford.edu>, 2006, 2007
+ * 	   Stanford Linear Accelerator Center, Stanford University.
+ * 
+ * Acknowledgement of sponsorship
+ * ------------------------------
+ * This software was produced by
+ *     the Stanford Linear Accelerator Center, Stanford University,
+ * 	   under Contract DE-AC03-76SFO0515 with the Department of Energy.
+ * 
+ * Government disclaimer of liability
+ * ----------------------------------
+ * Neither the United States nor the United States Department of Energy,
+ * nor any of their employees, makes any warranty, express or implied, or
+ * assumes any legal liability or responsibility for the accuracy,
+ * completeness, or usefulness of any data, apparatus, product, or process
+ * disclosed, or represents that its use would not infringe privately owned
+ * rights.
+ * 
+ * Stanford disclaimer of liability
+ * --------------------------------
+ * Stanford University makes no representations or warranties, express or
+ * implied, nor assumes any liability for the use of this software.
+ * 
+ * Stanford disclaimer of copyright
+ * --------------------------------
+ * Stanford University, owner of the copyright, hereby disclaims its
+ * copyright and all other rights in this software.  Hence, anyone may
+ * freely use it for any purpose without restriction.  
+ * 
+ * Maintenance of notices
+ * ----------------------
+ * In the interest of clarity regarding the origin and status of this
+ * SLAC software, this and all the preceding Stanford University notices
+ * are to remain affixed to any copy or derivative of this software made
+ * or distributed by the recipient and are to be affixed to any copy of
+ * software made or distributed by the recipient that contains a copy or
+ * derivative of this software.
+ * 
+ * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
+ */ 
+
+#include <stdint.h>
+#include <rtems.h>
+#include <bsp.h>
+#include <bsp/VME.h>
+#include <bsp/VMEDMA.h>
+#include <bsp/vmeUniverse.h>
+#include <bsp/vmeUniverseDMA.h>
+#include <bsp/bspVmeDmaList.h>
+
+int
+BSP_VMEDmaSetup(int channel, uint32_t bus_mode, uint32_t xfer_mode, void *custom_setup)
+{
+	return vmeUniverseDmaSetup(channel, bus_mode, xfer_mode, custom_setup);
+}
+
+int
+BSP_VMEDmaStart(int channel, uint32_t pci_addr, uint32_t vme_addr, uint32_t n_bytes)
+{
+	return vmeUniverseDmaStart(channel, pci_addr, vme_addr, n_bytes);
+}
+
+uint32_t
+BSP_VMEDmaStatus(int channel)
+{
+	return vmeUniverseDmaStatus(channel);
+}
+
+BSP_VMEDmaListDescriptor
+BSP_VMEDmaListDescriptorSetup(
+		BSP_VMEDmaListDescriptor d,
+		uint32_t                 attr_mask,
+		uint32_t				 xfer_mode,
+		uint32_t                 pci_addr,
+		uint32_t                 vme_addr,
+		uint32_t                 n_bytes)
+{
+VMEDmaListClass	pc;
+	if ( !d ) {
+		pc = &vmeUniverseDmaListClass;
+
+		return BSP_VMEDmaListDescriptorNewTool(
+					pc,
+					attr_mask,
+					xfer_mode,
+					pci_addr,
+					vme_addr,
+					n_bytes);
+					
+	}
+	return BSP_VMEDmaListDescriptorSetupTool(d, attr_mask, xfer_mode, pci_addr, vme_addr, n_bytes);
+}
+
+int
+BSP_VMEDmaListStart(int channel, BSP_VMEDmaListDescriptor list)
+{
+	return BSP_VMEDmaListDescriptorStartTool(0, channel, list);
+}
+
+/* NOT thread safe! */
+int
+BSP_VMEDmaInstallISR(int channel, BSP_VMEDmaIRQCallback cb, void *usr_arg)
+{
+int vec;
+BSP_VME_ISR_t curr;
+void          *carg;
+
+	if ( channel != 0 )
+		return -1;
+
+	vec = UNIV_DMA_INT_VEC;
+
+	curr = BSP_getVME_isr(vec, &carg);
+
+	if ( cb && curr ) {
+		/* IRQ currently in use */
+		return -1;
+	}
+
+	if ( !cb && !curr ) {
+		/* Allow uninstall if no handler is currently installed;
+		 * just make sure IRQ is disabled
+		 */
+		BSP_disableVME_int_lvl(vec);
+		return 0;
+	}
+		
+	if ( cb ) {
+		if ( BSP_installVME_isr(vec, (BSP_VME_ISR_t)cb, usr_arg) )
+			return -4;
+		BSP_enableVME_int_lvl(vec);
+	} else {
+		BSP_disableVME_int_lvl(vec);
+		if ( BSP_removeVME_isr(vec, curr, carg) )
+			return -4;
+	}
+	return 0;
+}
diff --git a/c/src/lib/libbsp/powerpc/shared/vme/vmeconfig.c b/c/src/lib/libbsp/powerpc/shared/vme/vmeconfig.c
index 9a1eda4844..4c6da0471c 100644
--- a/c/src/lib/libbsp/powerpc/shared/vme/vmeconfig.c
+++ b/c/src/lib/libbsp/powerpc/shared/vme/vmeconfig.c
@@ -55,6 +55,9 @@
 #include <libcpu/bat.h>
 #include <rtems/bspIo.h>
 
+extern int BSP_VMEInit();
+extern int BSP_VMEIrqMgrInstall();
+
 /* Use a weak alias for the VME configuration.
  * This permits individual applications to override
  * this routine.