Add support for Cynthion r0.6, r0.7, r1.0, r1.1, r1.2

.github/workflows/firmware.yml

@@ -8,8 +8,7 @@ jobs:
       fail-fast: false
       matrix:
         target-board:
-        - 'luna_d11'
-        - 'luna_d21'
+        - 'cynthion'
         - 'samd11_xplained'
         - 'qtpy'
     steps:
@@ -26,4 +25,4 @@ jobs:
     - name: Build Apollo firmware for ${{ matrix.target-board }}
       run: |
         cd firmware
-        APOLLO_BOARD=${{ matrix.target-board }} make all
+        APOLLO_BOARD=${{ matrix.target-board }} make get-deps all

README.md

@@ -1,4 +1,27 @@
-
 # Apollo FPGA Programmer / Debugger
 
-This repository contains the work-in-progress extraction of the Apollo programmer from the LUNA repository.
+Apollo is the on-board debugger and programmer on [Cynthion](https://greatscottgadgets.com/cynthion/). It is used to load gateware over USB onto Cynthion's FPGA. Alternatively it may be used as an on-board or external debugger for certain other FPGA platforms.
+
+Apollo consists of two main parts: firmware for the on-board debug microcontroller and Python-based software for the host computer.
+
+## Building and Installing Firmware
+
+First activate Cynthion's Saturn-V bootloader by holding down the PROGRAM button while connecting power or while pressing and releasing the RESET button. LED C will blink, indicating that Saturn-V is running.
+
+To compile for the latest Cynthion hardware revision, type:
+
+```
+$ cd apollo/firmware
+$ make APOLLO_BOARD=cynthion get-deps dfu
+```
+
+This will download dependencies, compile the firmware, and install it onto Cynthion with Saturn-V.
+
+Alternatively you can use variables to specify the hardware revision:
+
+```
+$ cd apollo/firmware
+$ make APOLLO_BOARD=cynthion BOARD_REVISION_MAJOR=1 BOARD_REVISION_MINOR=3 get-deps dfu
+```
+
+Once installation is complete, LED E should blink, indicating that Apollo is running and idle.

apollo_fpga/__init__.py

@@ -196,13 +196,13 @@ def create_jtag_spi(self, jtag_chain):
         if self.major == self.EXTERNAL_BOARD_MAJOR:
             return None, None
 
-        # Otherwise, if we have a revision greater than r0.2, our SPI should be via JTAG.
-        elif self.minor >= 0.3:
-            return ECP5_JTAGDebugSPIConnection(jtag_chain, self), ECP5_JTAGRegisters(jtag_chain)
+        # Use a real debug SPI on r0.1 and r0.2.
+        elif self.major == 0 and self.minor < 3:
+            return None, None
 
-        # Otherwise, we'll want to use a real debug SPI, rather than a JTAG-SPI.
+        # Otherwise, if we have a revision greater than r0.2, our SPI should be via JTAG.
         else:
-            return None, None
+            return ECP5_JTAGDebugSPIConnection(jtag_chain, self), ECP5_JTAGRegisters(jtag_chain)
 
 
 

firmware/Makefile

@@ -4,25 +4,30 @@
 
 # Ensure that a APOLLO_BOARD is selected.
 ifeq ($(APOLLO_BOARD), )
-	BOARD:=$(error You need to specify an APOLLO_BOARD as a make variable (e.g. APOLLO_BOARD=luna)!)
+	BOARD:=$(error You need to specify an APOLLO_BOARD as a make variable (e.g. APOLLO_BOARD=cynthion)!)
 endif
 
-# If the board is specified as 'luna' without a processor, we'll try to emulate the behavior
-# of LUNA's Apollo as much as we can.
+ifeq ($(APOLLO_BOARD), cynthion)
+	BOARD := cynthion_d11
+endif
+
+# Allow Cynthion's old name "LUNA" for backward compatibility.
 ifeq ($(APOLLO_BOARD), luna)
-	BOARD := luna_d11
+	BOARD := cynthion_d11
+endif
 
-	# These should default to the latest revision; but can be set on the command line.
-	BOARD_REVISION_MAJOR ?= 0
-	BOARD_REVISION_MINOR ?= 4
+ifeq ($(BOARD), cynthion_d11)
+	# These should default to the latest revision but can be set on the command line.
+	BOARD_REVISION_MAJOR ?= 1
+	BOARD_REVISION_MINOR ?= 0
 
-	# On r0.1 or r0.2 boards, we want to target the SAMD21 / luna_d11 configuration.
+	# On r0.1 or r0.2 boards, we target the SAMD21 configuration.
 	ifeq ($(BOARD_REVISION_MAJOR), 0)
 		ifeq ($(BOARD_REVISION_MINOR), 1)
-			BOARD := luna_d21
+			BOARD := cynthion_d21
 		endif
 		ifeq ($(BOARD_REVISION_MINOR), 2)
-			BOARD := luna_d21
+			BOARD := cynthion_d21
 		endif
 	endif
 else
@@ -43,7 +48,6 @@ ifeq ($(CC), intercept-cc)
 endif
 
 # Include the tinyusb basis BSP.
-include $(TINYUSB_PATH)/tools/top.mk
 include $(TINYUSB_PATH)/examples/make.mk
 
 # If we're using intercept-build, override our compiler back to intercept-cc.

firmware/src/boards/luna_d11/apollo_board.h → firmware/src/boards/cynthion_d11/apollo_board.h

@@ -29,7 +29,7 @@ typedef enum {
 
 
 /**
- * GPIO pin numbers.
+ * GPIO pins for FPGA JTAG
  */
 enum {
 	// Each of the JTAG pins.
@@ -41,11 +41,18 @@ enum {
 
 
 /**
- * List of pins used for FPGA interfacing.
+ * Other GPIO pins
  */
 enum {
-	PROGRAM_GPIO  = PIN_PA08,
-	PIN_PHY_RESET = PIN_PA09
+	FPGA_PROGRAM   = PIN_PA08,
+#if ((_BOARD_REVISION_MAJOR_ == 0) && (_BOARD_REVISION_MINOR_ < 6))
+	PROGRAM_BUTTON = PIN_PA16,
+	PHY_RESET      = PIN_PA09,
+#else
+	PROGRAM_BUTTON = PIN_PA02,
+	USB_SWITCH     = PIN_PA06,
+	FPGA_INT       = PIN_PA09,
+#endif
 };
 
 

firmware/src/boards/luna_d11/fpga.c → firmware/src/boards/cynthion_d11/fpga.c

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: BSD-3-Clause
  */
 
-#include <bsp/board.h>
+#include <bsp/board_api.h>
 #include <hal/include/hal_gpio.h>
 
 #include <apollo_board.h>
@@ -18,10 +18,8 @@
 void fpga_io_init(void)
 {
 	// By default, keep PROGRAM_N from being driven.
-	gpio_set_pin_level(PROGRAM_GPIO, true);
-	gpio_set_pin_direction(PROGRAM_GPIO, GPIO_DIRECTION_IN);
-
-	gpio_set_pin_direction(PIN_PHY_RESET, GPIO_DIRECTION_IN);
+	gpio_set_pin_level(FPGA_PROGRAM, true);
+	gpio_set_pin_direction(FPGA_PROGRAM, GPIO_DIRECTION_IN);
 }
 
 
@@ -30,13 +28,13 @@ void fpga_io_init(void)
  */
 void trigger_fpga_reconfiguration(void)
 {
-	gpio_set_pin_direction(PROGRAM_GPIO, GPIO_DIRECTION_OUT);
-	gpio_set_pin_level(PROGRAM_GPIO, false);
+	gpio_set_pin_direction(FPGA_PROGRAM, GPIO_DIRECTION_OUT);
+	gpio_set_pin_level(FPGA_PROGRAM, false);
 
 	board_delay(1);
 
-	gpio_set_pin_level(PROGRAM_GPIO, true);
-	gpio_set_pin_direction(PROGRAM_GPIO, GPIO_DIRECTION_IN);
+	gpio_set_pin_level(FPGA_PROGRAM, true);
+	gpio_set_pin_direction(FPGA_PROGRAM, GPIO_DIRECTION_IN);
 }
 
 
@@ -45,6 +43,6 @@ void trigger_fpga_reconfiguration(void)
  */
 void force_fpga_offline(void)
 {
-	gpio_set_pin_direction(PROGRAM_GPIO, GPIO_DIRECTION_OUT);
-	gpio_set_pin_level(PROGRAM_GPIO, false);
+	gpio_set_pin_direction(FPGA_PROGRAM, GPIO_DIRECTION_OUT);
+	gpio_set_pin_level(FPGA_PROGRAM, false);
 }

firmware/src/boards/luna_d11/led.c → firmware/src/boards/cynthion_d11/led.c

@@ -14,7 +14,7 @@
 
 #include <tusb.h>
 #include <sam.h>
-#include <bsp/board.h>
+#include <bsp/board_api.h>
 #include <hal/include/hal_gpio.h>
 
 

firmware/src/boards/luna_d11/spi.c → firmware/src/boards/cynthion_d11/spi.c

@@ -16,8 +16,6 @@
 #include "spi.h"
 #include "led.h"
 
-#include <bsp/board.h>
-
 
 // Hide the ugly Atmel Sercom object name.
 typedef Sercom sercom_t;

firmware/src/boards/cynthion_d11/usb_switch.c

@@ -0,0 +1,55 @@
+/**
+ * switch control for USB port shared by Apollo and FPGA
+ *
+ * This file is part of Apollo.
+ *
+ * Copyright (c) 2023 Great Scott Gadgets <[email protected]>
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "usb_switch.h"
+#include "apollo_board.h"
+#include "led.h"
+#include <hal/include/hal_gpio.h>
+
+/**
+ * Hand off shared USB port to FPGA.
+ */
+void hand_off_usb(void)
+{
+#if ((_BOARD_REVISION_MAJOR_ == 0) && (_BOARD_REVISION_MINOR_ < 6))
+	led_on(LED_D);
+#else
+	gpio_set_pin_level(USB_SWITCH, false);
+	gpio_set_pin_direction(USB_SWITCH, GPIO_DIRECTION_OUT);
+	led_off(LED_D);
+#endif
+}
+
+/**
+ * Take control of USB port from FPGA.
+ */
+void take_over_usb(void)
+{
+#if (((_BOARD_REVISION_MAJOR_ == 0) && (_BOARD_REVISION_MINOR_ >= 6)) || (_BOARD_REVISION_MAJOR_ == 1))
+	gpio_set_pin_level(USB_SWITCH, true);
+	gpio_set_pin_direction(USB_SWITCH, GPIO_DIRECTION_OUT);
+#endif
+	led_on(LED_D);
+}
+
+/**
+ * Handle switch control user request.
+ */
+void switch_control_task(void)
+{
+#if ((_BOARD_REVISION_MAJOR_ == 0) && (_BOARD_REVISION_MINOR_ < 6))
+	gpio_set_pin_pull_mode(PROGRAM_BUTTON, GPIO_PULL_UP);
+#else
+	gpio_set_pin_pull_mode(PROGRAM_BUTTON, GPIO_PULL_OFF);
+#endif
+	gpio_set_pin_direction(PROGRAM_BUTTON, GPIO_DIRECTION_IN);
+	if (gpio_get_pin_level(PROGRAM_BUTTON) == false) {
+		take_over_usb();
+	}
+}

firmware/src/boards/luna_d21/fpga.c → firmware/src/boards/cynthion_d21/fpga.c

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: BSD-3-Clause
  */
 
-#include <bsp/board.h>
+#include <bsp/board_api.h>
 #include <hal/include/hal_gpio.h>
 
 // List of pins used for FPGA interfacing.

firmware/src/boards/luna_d21/led.c → firmware/src/boards/cynthion_d21/led.c

@@ -14,7 +14,7 @@
 
 #include <tusb.h>
 #include <sam.h>
-#include <bsp/board.h>
+#include <bsp/board_api.h>
 #include <hal/include/hal_gpio.h>
 
 

firmware/src/boards/luna_d21/spi.c → firmware/src/boards/cynthion_d21/spi.c

@@ -16,8 +16,6 @@
 #include "spi.h"
 #include "led.h"
 
-#include <bsp/board.h>
-
 
 // Hide the ugly Atmel Sercom object name.
 typedef Sercom sercom_t;

firmware/src/boards/cynthion_d21/usb_switch.c

@@ -0,0 +1,34 @@
+/**
+ * switch control for USB port shared by Apollo and FPGA
+ *
+ * This file is part of Apollo.
+ *
+ * Copyright (c) 2023 Great Scott Gadgets <[email protected]>
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "led.h"
+#include "usb_switch.h"
+
+/**
+ * Hand off shared USB port to FPGA.
+ */
+void hand_off_usb(void)
+{
+	led_on(LED_D);
+}
+
+/**
+ * Take control of USB port from FPGA.
+ */
+void take_over_usb(void)
+{
+	led_on(LED_D);
+}
+
+/**
+ * Handle switch control user request.
+ */
+void switch_control_task(void)
+{
+}

firmware/src/boards/daisho/fpga.c

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: BSD-3-Clause
  */
 
-#include <bsp/board.h>
+#include <bsp/board_api.h>
 #include <apollo_board.h>
 
 

firmware/src/boards/daisho/led.c

@@ -13,7 +13,7 @@
 #include <string.h>
 
 #include <tusb.h>
-#include <bsp/board.h>
+#include <bsp/board_api.h>
 #include <apollo_board.h>
 
 

firmware/src/boards/daisho/usb_switch.c

@@ -0,0 +1,31 @@
+/**
+ * switch control for USB port shared by Apollo and FPGA
+ *
+ * This file is part of Apollo.
+ *
+ * Copyright (c) 2023 Great Scott Gadgets <[email protected]>
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "usb_switch.h"
+
+/**
+ * Hand off shared USB port to FPGA.
+ */
+void hand_off_usb(void)
+{
+}
+
+/**
+ * Take control of USB port from FPGA.
+ */
+void take_over_usb(void)
+{
+}
+
+/**
+ * Handle switch control user request.
+ */
+void switch_control_task(void)
+{
+}