Add firmware version string and USB API versioning

apollo_fpga/__init__.py

@@ -1,7 +1,7 @@
 #
-# This file is part of LUNA.
+# This file is part of Apollo.
 #
-# Copyright (c) 2020 Great Scott Gadgets <[email protected]>
+# Copyright (c) 2020-2024 Great Scott Gadgets <[email protected]>
 # SPDX-License-Identifier: BSD-3-Clause
 
 import os
@@ -47,6 +47,8 @@ class ApolloDebugger:
         LUNA_USB_IDS += [tuple([int(x, 16) for x in os.getenv("LUNA_USB_IDS").split(":")])]
 
     REQUEST_SET_LED_PATTERN         = 0xa1
+    REQUEST_GET_FIRMWARE_VERSION    = 0xa2
+    REQUEST_GET_USB_API_VERSION     = 0xa3
     REQUEST_RECONFIGURE             = 0xc0
     REQUEST_FORCE_FPGA_OFFLINE      = 0xc1
     REQUEST_ALLOW_FPGA_TAKEOVER_USB = 0xc2
@@ -302,3 +304,20 @@ def close(self):
         """ Closes the USB device so it can be reused, possibly by another ApolloDebugger """
 
         usb.util.dispose_resources(self.device)
+
+
+    def get_firmware_version(self):
+        c_string = self.in_request(self.REQUEST_GET_FIRMWARE_VERSION, length=256)
+        return c_string.decode('utf-8').split('\x00')[0]
+
+
+    def get_usb_api_version(self):
+        raw_api_version = self.in_request(self.REQUEST_GET_USB_API_VERSION, length=2)
+        api_major = int(raw_api_version[0])
+        api_minor = int(raw_api_version[1])
+        return (api_major, api_minor)
+
+
+    def get_usb_api_version_string(self):
+        (api_major, api_minor) = self.get_usb_api_version()
+        return (f"{api_major}.{api_minor}")

apollo_fpga/commands/cli.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 #
-# This file is part of LUNA
+# This file is part of Apollo.
 #
-# Copyright (c) 2020 Great Scott Gadgets <[email protected]>
+# Copyright (c) 2020-2024 Great Scott Gadgets <[email protected]>
 # SPDX-License-Identifier: BSD-3-Clause
 
 from __future__ import print_function
@@ -81,7 +81,9 @@ def print_device_info(device, args):
 
     logging.info(f"Detected a {device.get_compatibility_string()} device!")
     logging.info(f"\tHardware: {device.get_hardware_name()}")
-    logging.info(f"\tSerial number: {device.serial_number}\n")
+    logging.info(f"\tSerial number: {device.serial_number}")
+    logging.info(f"\tFirmware version: {device.get_firmware_version()}")
+    logging.info(f"\tUSB API version: {device.get_usb_api_version_string()}")
 
 
 def print_chain_info(device, args):

firmware/Makefile

@@ -2,6 +2,8 @@
 # Apollo debug controller firmware
 #
 
+VERSION_STRING ?= $(shell git describe --abbrev=7 --dirty --always --tags)
+
 # 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=cynthion)!)
@@ -61,6 +63,7 @@ CFLAGS += \
 	-fstrict-volatile-bitfields \
 	-D_BOARD_REVISION_MAJOR_=$(BOARD_REVISION_MAJOR) \
 	-D_BOARD_REVISION_MINOR_=$(BOARD_REVISION_MINOR) \
+	-D VERSION_STRING=\"$(VERSION_STRING)\" \
 	-g
 
 INC += \

firmware/src/vendor.c

@@ -7,7 +7,7 @@
  *
  * This file is part of LUNA.
  *
- * Copyright (c) 2019-2020 Great Scott Gadgets <[email protected]>
+ * Copyright (c) 2019-2024 Great Scott Gadgets <[email protected]>
  * SPDX-License-Identifier: BSD-3-Clause
  */
 
@@ -22,11 +22,16 @@
 #include "usb_switch.h"
 #include "fpga_adv.h"
 
+#define USB_API_MAJOR 1
+#define USB_API_MINOR 0
+
 
 // Supported vendor requests.
 enum {
-	VENDOR_REQUEST_GET_ID          = 0xa0,
-	VENDOR_REQUEST_SET_LED_PATTERN = 0xa1,
+	VENDOR_REQUEST_GET_ID                  = 0xa0,
+	VENDOR_REQUEST_SET_LED_PATTERN         = 0xa1,
+	VENDOR_REQUEST_GET_FIRMWARE_VERSION    = 0xa2,
+	VENDOR_REQUEST_GET_USB_API_VERSION     = 0xa3,
 
 	//
 	// JTAG requests.
@@ -58,16 +63,15 @@ enum {
 	VENDOR_REQUEST_TAKE_FLASH_LINES        = 0x53,
 	VENDOR_REQUEST_RELEASE_FLASH_LINES     = 0x54,
 
-
 	//
 	// Self-test requests.
 	//
-	VENDOR_REQUEST_GET_RAIL_VOLTAGE      = 0xe0,
+	VENDOR_REQUEST_GET_RAIL_VOLTAGE        = 0xe0,
 
 	//
 	// Microsoft WCID descriptor request
 	//
-	VENDOR_REQUEST_GET_MS_DESCRIPTOR     = 0xee,
+	VENDOR_REQUEST_GET_MS_DESCRIPTOR       = 0xee,
 };
 
 // Microsoft OS 1.0 descriptor
@@ -111,6 +115,26 @@ bool handle_get_id_request(uint8_t rhport, tusb_control_request_t const* request
 }
 
 
+/**
+ * Request firmware version string.
+ */
+bool handle_get_firmware_version_request(uint8_t rhport, tusb_control_request_t const* request)
+{
+	static char version[] = VERSION_STRING;
+	return tud_control_xfer(rhport, request, version, sizeof(version));
+}
+
+
+/**
+ * Request USB API version.
+ */
+bool handle_get_usb_api_version_request(uint8_t rhport, tusb_control_request_t const* request)
+{
+	static char usb_api[2] = {USB_API_MAJOR, USB_API_MINOR};
+	return tud_control_xfer(rhport, request, usb_api, sizeof(usb_api));
+}
+
+
 /**
  * Request that changes the active LED pattern.
  */
@@ -165,6 +189,10 @@ static bool handle_vendor_request_setup(uint8_t rhport, tusb_control_request_t c
 	switch(request->bRequest) {
 		case VENDOR_REQUEST_GET_ID:
 			return handle_get_id_request(rhport, request);
+		case VENDOR_REQUEST_GET_FIRMWARE_VERSION:
+			return handle_get_firmware_version_request(rhport, request);
+		case VENDOR_REQUEST_GET_USB_API_VERSION:
+			return handle_get_usb_api_version_request(rhport, request);
 		case VENDOR_REQUEST_TRIGGER_RECONFIGURATION:
 			return handle_trigger_fpga_reconfiguration(rhport, request);
 		case VENDOR_REQUEST_FORCE_FPGA_OFFLINE: