pre v1.5 code cleaning and documentation

Author: demik

ChangeLog.md

@@ -3,6 +3,8 @@
 	- https://github.com/espressif/esp-idf/releases/tag/v5.5.2
 	- this fixes a few buffers overflows and other rare stuff in Bluedroid
 - 1.5.x series is compatible with 1.3 to 1.5 PCBs (EDA subfolder)
+- new bespoke ADB RX driver has been developed based on the legacy RMT driver
+	- the functionality is the same as the v1.4 one but it's more SDK future proof
 
 ## v1.4.11
 - update to ESP-IDF v5.4.2

main/adb.c

@@ -27,12 +27,12 @@
 #include <freertos/ringbuf.h>
 #include <freertos/semphr.h>
 #include <freertos/task.h>
-#include "esp_log.h"
-#include "esp_system.h"
-#include "esp_chip_info.h"
-#include "esp_private/periph_ctrl.h"
-#include "soc/periph_defs.h"
-#include "soc/rmt_reg.h"
+#include <esp_log.h>
+#include <esp_system.h>
+#include <esp_chip_info.h>
+#include <esp_private/periph_ctrl.h>
+#include <soc/rmt_reg.h>
+#include <hal/rmt_types.h>
 
 #include "adb.h"
 #include "led.h"
@@ -42,31 +42,36 @@
 /*
  * THEORY OF OPERATION *
  *
- * Quack scheduler is running at 250 Hz which give 4 ms running "slots"
+ * Quack scheduler is running at 250 Hz which give 4 ms time "slots"
  *
  * TRANSMITTING *
  * It's done by toggling the GPIO in an active loop, which is less than ideal because
  * the RTOS may be scheduling stuff.
  *
  * For polling it's ok because the ADB command (TALK) can be send under 4ms so the task
  * shouldn't be rescheduled. For the initial setup it can be a little longer (up to 12 ms)
- * so there is risks of being rescheduled here. On can avoid most of it by putting the
- * transmitting task into high priority and only running others tasks as low priority.
+ * so there is risks of being rescheduled here. One can avoid most of it by putting the
+ * transmitting task into as priority and only running others tasks as low priority.
  *
  * RECEIVING *
  * since we can be scheduled anytime during reception, reception is done using the RMT
  * (Remote Control Transceiver) transceiver of the ESP32.
  *
- * Before ESP-IDF v5.0, it was donne using the RMT driver but this has been deprecated
- * a subset of it for this specific project has been reimplemented within the phy.* files
+ * Before ESP-IDF v5.0, it was donne using the RMT driver but this has been deprecated.
+ * A subset of it for this specific project has been reimplemented within the phy.* files
  * using the RMT HAL.
  *
+ * The driver grab the ADB pulses for about 8ms, then pass then into a ringbuf,
+ * which are then decoded in adb_rx_mouse(). the 8ms is a compromise to be able to poll
+ * at a decent rate because the peripheral can't know when the transmission happens.
+ * this limit us to about 20 bits
+ *
  * Overall, in order to not push our luck this realistically limit the mouse protocol to
  * the simpler ones (classic 100 and 200 cpi)
  */
 
 /* defines */
-#define TAG "ADB"
+#define TAG "ADB_MGR"
 
 /* globals */
 extern TaskHandle_t t_adb2hid;
@@ -77,9 +82,9 @@ extern QueueHandle_t q_qx, q_qy;
 /* static defines */
 static void	adb_handle_button(bool action);
 static void	adb_phy_reset(void);
-static bool	adb_rx_isone(phy_item32_t cell);
-static bool	adb_rx_isstop(phy_item32_t cell);
-static bool	adb_rx_iszero(phy_item32_t cell);
+static bool	adb_rx_isone(rmt_symbol_word_t cell);
+static bool	adb_rx_isstop(rmt_symbol_word_t cell);
+static bool	adb_rx_iszero(rmt_symbol_word_t cell);
 static uint16_t adb_rx_mouse(void);
 static void	adb_rx_setup(void);
 static void	adb_scan_macaj(void);
@@ -163,10 +168,12 @@ void adb_probe(void) {
 
 		adb_tx_cmd(ADB_MOUSE|ADB_TALK|ADB_REG3);
 		register3 = adb_rx_mouse();
-		ESP_LOGD("ADB", "Device $3 register3: %04x", register3);
+		ESP_LOGD(TAG, "$3 register3: %04x", register3);
 
-		if (register3 && (register3 & ADB_H_ALL) == ADB_H_ERR)
+		if (register3 && (register3 & ADB_H_ALL) == ADB_H_ERR) {
 			ESP_LOGE(TAG, "Mouse failed self init test");
+			xTaskNotify(t_red, LED_ONCE, eSetValueWithOverwrite);
+		}
 
 		/*
 		 * try to unglue composite devices (Kensington)
@@ -381,7 +388,7 @@ void	adb_task_host(void *pvParameters) {
 					else
 						state = ADB_S_KEEP;
 				}
-				ESP_LOGD("ADB", "Check mouse presence %04x", data);
+				ESP_LOGD(TAG, "Checking $3: %04x", data);
 			}
 		}
 	}
@@ -417,22 +424,22 @@ void	adb_task_idle(void *pvParameters) {
  * units are in µs
  */
 
-static bool adb_rx_isone(phy_item32_t cell) {
+static bool adb_rx_isone(rmt_symbol_word_t cell) {
 	if (cell.level0 == 0 && (cell.duration0 >= 22 && cell.duration0 <= 44) &&
 		cell.level1 == 1 && (cell.duration1 >= 46 && cell.duration1 <= 86))
 		return true;
 	return false;
 }
 
-static bool adb_rx_isstop(phy_item32_t cell) {
-	/* high part of the well is lengh 0 because of RMT timeout (100µs+) */
+static bool adb_rx_isstop(rmt_symbol_word_t cell) {
+	/* high part of the end cell is lengh 0 because of RMT timeout (100µs+) */
 	if (cell.level0 == 0 && (cell.duration0 >= 46 && cell.duration0 <= 86) &&
 		cell.level1 == 1 && cell.duration1 == 0)
 		return true;
 	return false;
 }
 
-static bool adb_rx_iszero(phy_item32_t cell) {
+static bool adb_rx_iszero(rmt_symbol_word_t cell) {
 	if (cell.level0 == 0 && (cell.duration0 >= 46 && cell.duration0 <= 86) &&
 		cell.level1 == 1 && (cell.duration1 >= 22 && cell.duration1 <= 44))
 		return true;
@@ -443,14 +450,14 @@ static uint16_t	IRAM_ATTR adb_rx_mouse() {
 	uint32_t phy_status;
 	uint16_t data = 0;
 	RingbufHandle_t rb = NULL;
-	phy_item32_t* items = NULL;
+	rmt_symbol_word_t* items = NULL;
 	size_t rx_size = 0;
 	size_t i;
 
 	phy_get_ringbuf_handle(&rb);
 	configASSERT(rb != NULL);
 	phy_rx_start(true);
-	items = (phy_item32_t*)xRingbufferReceive(rb, &rx_size, pdMS_TO_TICKS(8));
+	items = (rmt_symbol_word_t*)xRingbufferReceive(rb, &rx_size, pdMS_TO_TICKS(8));
 
 	phy_get_status(&phy_status);
 	if (((phy_status >> RMT_STATE_CH0_S) & RMT_STATE_CH0_V) == 4)
@@ -461,7 +468,7 @@ static uint16_t	IRAM_ATTR adb_rx_mouse() {
 		return 0;
 
 	/*
-	 * Mouse response size in bits is events / sizeof(phy_item32_t) (4)
+	 * Mouse response size in bits is events / sizeof(rmt_symbol_word_t) (4)
 	 * start bit + 16 data bits + stop bit = 72 bytes in RMT buffer (18 bits received)
 	 *
 	 * Check start / stop bits and size.
@@ -479,18 +486,18 @@ static uint16_t	IRAM_ATTR adb_rx_mouse() {
 			xTaskNotify(t_yellow, LED_ONCE, eSetValueWithOverwrite);
 			break;
 		default:
-			ESP_LOGD(TAG, "wrong size of %i bit(s)", rx_size / sizeof(phy_item32_t));
+			ESP_LOGD(TAG, "wrong size of %i bit(s)", rx_size / sizeof(rmt_symbol_word_t));
 			xTaskNotify(t_red, LED_ONCE, eSetValueWithOverwrite);
 	}
 
 	/* check start and stop bits */
-	if (! adb_rx_isone(*(items+0)) && (! adb_rx_isstop(*(items+(rx_size / sizeof(phy_item32_t) - 1))))) {
+	if (! adb_rx_isone(*(items+0)) && (! adb_rx_isstop(*(items+(rx_size / sizeof(rmt_symbol_word_t) - 1))))) {
 		xTaskNotify(t_red, LED_ONCE, eSetValueWithOverwrite);
 		return 0;
 	}
 
 	/* rebuild our data with RMT buffer */
-	for (i = 1; i < ((rx_size / sizeof(phy_item32_t)) - 1); i++) {
+	for (i = 1; i < ((rx_size / sizeof(rmt_symbol_word_t)) - 1); i++) {
 		data <<= 1;
 
 		/* check that every data is either one or zero */

main/phy.c

@@ -27,6 +27,7 @@
 #include <freertos/ringbuf.h>
 #include <hal/rmt_hal.h>
 #include <hal/rmt_ll.h>
+#include <hal/rmt_types.h>
 #include <soc/io_mux_reg.h>
 #include <soc/rmt_periph.h>
 
@@ -35,7 +36,7 @@
 #include "sdkconfig.h"
 
 /* defines */
-static const char *TAG = "PHY(ADB)";
+static const char *TAG = "ADB_PHY";
 
 /* spinlock for protecting concurrent register-level access only */
 #define PHY_ENTER_CRITICAL()  portENTER_CRITICAL_SAFE(&(rmt_contex.rmt_spinlock))
@@ -47,7 +48,7 @@ typedef struct {
 	_lock_t rmt_driver_isr_lock;
 	/* Mutex lock for protecting concurrent register/unregister of RMT channels (ISR) */
 	portMUX_TYPE rmt_spinlock;
-	phy_isr_handle_t rmt_driver_intr_handle;
+	intr_handle_t rmt_driver_intr_handle;
 	/* Bitmask of installed drivers channels for protecting concurrent register/unregister of RMT channels (ISR) */
 	uint8_t	rmt_driver_channels;
 	bool		rmt_module_enabled;
@@ -63,7 +64,6 @@ static phy_contex_t rmt_contex = {
 
 phy_config_t adb_rmt_rx;
 RingbufHandle_t phy_rx_buf = NULL;
-bool	  phy_driver_installed = false;
 
 /* static defines */
 static void phy_driver_isr(void *arg);
@@ -92,16 +92,17 @@ esp_err_t phy_config(void) {
 
 	phy_module_enable();
 
-	ESP_RETURN_ON_ERROR(phy_set_gpio(adb_rmt_rx.gpio_num, adb_rmt_rx.flags & PHY_CHANNEL_FLAGS_INVERT_SIG), TAG, "set gpio for RMT driver failed");
-	ESP_RETURN_ON_ERROR(phy_internal_config(&RMT, &adb_rmt_rx), TAG, "initialize RMT driver failed");
+	ESP_RETURN_ON_ERROR(phy_set_gpio(adb_rmt_rx.gpio_num, adb_rmt_rx.flags & PHY_CHANNEL_FLAGS_INVERT_SIG), \
+	                    TAG, "set gpio for RMT device failed");
+	ESP_RETURN_ON_ERROR(phy_internal_config(&RMT, &adb_rmt_rx), TAG, "initialize ADB(PHY) driver failed");
 
 	return ESP_OK;
 }
 
 esp_err_t phy_driver_install(size_t rx_buf_size, int intr_alloc_flags) {
 	esp_err_t err = ESP_OK;
 
-	if (phy_driver_installed) {
+	if (phy_rx_buf) {
 		ESP_LOGD(TAG, "RMT driver already installed");
 		return ESP_ERR_INVALID_STATE;
 	}
@@ -133,7 +134,7 @@ esp_err_t phy_driver_install(size_t rx_buf_size, int intr_alloc_flags) {
 
 static void IRAM_ATTR phy_driver_isr(void *arg) {
 	uint32_t status = 0;
-	phy_item32_t *addr = NULL;
+	rmt_symbol_word_t *addr = NULL;
 	rmt_hal_context_t *hal = (rmt_hal_context_t *)arg;
 	BaseType_t HPTaskAwoken = pdFALSE;
 
@@ -161,7 +162,7 @@ static void IRAM_ATTR phy_driver_isr(void *arg) {
 		int item_len = rmt_ll_rx_get_memory_writer_offset(rmt_contex.hal.regs, PHY_CHANNEL_NUM);
 		rmt_ll_rx_set_mem_owner(rmt_contex.hal.regs, PHY_CHANNEL_NUM, RMT_LL_MEM_OWNER_SW);
 		if (phy_rx_buf) {
-			addr = (phy_item32_t *)RMTMEM.chan[PHY_CHANNEL_NUM].data32;
+			addr = (rmt_symbol_word_t *)RMTMEM.chan[PHY_CHANNEL_NUM].data32;
 			BaseType_t res = xRingbufferSendFromISR(phy_rx_buf, (void *)addr, item_len * 4, &HPTaskAwoken);
 			if (res == pdFALSE)
 				ESP_DRAM_LOGE(TAG, "RMT RX buffer is full");
@@ -221,8 +222,9 @@ static esp_err_t phy_internal_config(rmt_dev_t *dev, const phy_config_t *phy_par
 	uint32_t rmt_source_clk_hz;
 	rmt_clock_source_t clk_src = RMT_BASECLK_DEFAULT;
 
-	ESP_RETURN_ON_FALSE(mem_cnt <= SOC_RMT_CHANNELS_PER_GROUP && mem_cnt > 0, ESP_ERR_INVALID_ARG, TAG, PHY_MEM_CNT_ERROR_STR);
-	ESP_RETURN_ON_FALSE(clk_div > 0, ESP_ERR_INVALID_ARG, TAG, PHY_CLK_DIV_ERROR_STR);
+	ESP_RETURN_ON_FALSE(mem_cnt <= SOC_RMT_CHANNELS_PER_GROUP && mem_cnt > 0, \
+	                    ESP_ERR_INVALID_ARG, TAG, "Memory block number error");
+	ESP_RETURN_ON_FALSE(clk_div > 0, ESP_ERR_INVALID_ARG, TAG, "Clock divider error");
 
 	PHY_ENTER_CRITICAL();
 	rmt_ll_enable_mem_access_nonfifo(dev, true);
@@ -253,13 +255,14 @@ static esp_err_t phy_internal_config(rmt_dev_t *dev, const phy_config_t *phy_par
 	return ESP_OK;
 }
 
-esp_err_t phy_isr_deregister(phy_isr_handle_t handle) {
+esp_err_t phy_isr_deregister(intr_handle_t handle) {
     return esp_intr_free(handle);
 }
 
 esp_err_t phy_isr_register(void (*fn)(void *), void *arg, int intr_alloc_flags, intr_handle_t *handle) {
-	ESP_RETURN_ON_FALSE(fn, ESP_ERR_INVALID_ARG, TAG, PHY_ADDR_ERROR_STR);
-	ESP_RETURN_ON_FALSE(rmt_contex.rmt_driver_channels == 0, ESP_FAIL, TAG, "RMT driver installed, can not install ISR handler");
+	ESP_RETURN_ON_FALSE(fn, ESP_ERR_INVALID_ARG, TAG, "ISR address error");
+	ESP_RETURN_ON_FALSE(rmt_contex.rmt_driver_channels == 0, \
+	                    ESP_FAIL, TAG, "RMT driver installed, can not install ISR handler");
 
 	return esp_intr_alloc(rmt_periph_signals.groups[0].irq, intr_alloc_flags, fn, arg, handle);
 }
@@ -277,7 +280,7 @@ void phy_get_status(uint32_t *status) {
 
 /* disable RMT module */
 static void phy_module_disable(void) {
-	/* to suppress build errors about spinlock's __DECLARE_RCC_ATOMIC_ENV */
+
 	int __DECLARE_RCC_ATOMIC_ENV __attribute__ ((unused));
 
 	PHY_ENTER_CRITICAL();
@@ -291,9 +294,7 @@ static void phy_module_disable(void) {
 
 /* enable RMT module */
 static void phy_module_enable(void) {
-	/* to suppress build errors about spinlock's __DECLARE_RCC_ATOMIC_ENV */
-	int __DECLARE_RCC_ATOMIC_ENV __attribute__ ((unused));
-
+	PHY_DECLARE_ATOMIC();
 	PHY_ENTER_CRITICAL();
 	if (rmt_contex.rmt_module_enabled == false) {
 		rmt_ll_enable_bus_clock(0, true);
@@ -327,7 +328,7 @@ esp_err_t phy_rx_stop(void) {
 
 /* set GPIO matrix and GPIO pin for channel 0 */
 esp_err_t phy_set_gpio(gpio_num_t gpio_num, bool invert_signal) {
-	ESP_RETURN_ON_FALSE(GPIO_IS_VALID_GPIO(gpio_num), ESP_ERR_INVALID_ARG, TAG, "PHY(ADB) invalid GPIO");
+	ESP_RETURN_ON_FALSE(GPIO_IS_VALID_GPIO(gpio_num), ESP_ERR_INVALID_ARG, TAG, "invalid GPIO");
 
 	gpio_func_sel(gpio_num, PIN_FUNC_GPIO);
 	gpio_set_direction(gpio_num, GPIO_MODE_INPUT);

main/phy.h

@@ -31,21 +31,18 @@
  */
 
 /* defines */
-#define PHY_CHANNEL_NUM 0
-#define PHY_CHANNEL_FLAGS_INVERT_SIG (1 << 1) /* Invert RMT signal */
-#define PHY_ADDR_ERROR_STR "PHY(ADB) ADDRESS ERR"
-#define PHY_CLK_DIV_ERROR_STR "PHY(ADB) CLK DIV ERR"
-#define PHY_DEFAULT_CLK_DIV 80
-#define PHY_MEM_CNT_ERROR_STR "PHY(ADB) MEM BLOCK NUM ERR"
+#define PHY_CHANNEL_NUM       		0
+#define PHY_CHANNEL_FLAGS_INVERT_SIG	(1 << 1) /* Invert RMT signal */
+#define PHY_DEFAULT_CLK_DIV   		80
 
-/* structures */
-typedef intr_handle_t phy_isr_handle_t;
+/* to suppress build errors about spinlock's __DECLARE_RCC_ATOMIC_ENV */
+#define PHY_DECLARE_ATOMIC() int __DECLARE_RCC_ATOMIC_ENV __attribute__ ((unused));
 
 /* RMT RX specific configure parameters (main structure below) */
 typedef struct {
-	uint16_t idle_threshold;     /* RMT RX idle threshold */
-	uint8_t filter_ticks_thresh; /* RMT filter tick number */
-	bool filter_en;              /* RMT receiver filter enable */
+	uint16_t	idle_threshold;		/* RMT RX idle threshold */
+	uint8_t 	filter_ticks_thresh;	/* RMT filter tick number */
+	bool		filter_en;     		/* RMT receiver filter enable */
 } phy_rx_config_t;
 
 /* structure of RMT configure parameters */
@@ -57,23 +54,10 @@ typedef struct {
 	phy_rx_config_t rx_config;   /* RMT RX parameter */
 } phy_config_t;
 
-/* structure of data coming from the RMT device */
-typedef struct {
-	union {
-		struct {
-			uint32_t duration0 : 15; /* Duration of level0 */
-			uint32_t level0 : 1;     /* Level of the first part */
-			uint32_t duration1 : 15; /* Duration of level1 */
-			uint32_t level1 : 1;     /* Level of the second part */
-		};
-		uint32_t val; /* Equivalent unsigned value for the RMT item */
-	};
-} phy_item32_t;
-
 /* hardware memory layout */
 typedef struct {
 	struct {
-		volatile phy_item32_t data32[SOC_RMT_MEM_WORDS_PER_CHANNEL];
+		volatile rmt_symbol_word_t data32[SOC_RMT_MEM_WORDS_PER_CHANNEL];
 	} chan[SOC_RMT_CHANNELS_PER_GROUP];
 } phy_mem_t;
 
@@ -83,11 +67,10 @@ esp_err_t phy_driver_install(size_t rx_buf_size, int intr_alloc_flags);
 esp_err_t phy_driver_uninstall(void);
 esp_err_t phy_get_ringbuf_handle(RingbufHandle_t *buf_handle);
 void		phy_get_status(uint32_t *status);
-esp_err_t phy_isr_deregister(phy_isr_handle_t handle);
+esp_err_t phy_isr_deregister(intr_handle_t handle);
 esp_err_t phy_isr_register(void (*fn)(void *), void *arg, int intr_alloc_flags, intr_handle_t *handle);
 esp_err_t phy_rx_start(bool rx_idx_rst);
 esp_err_t phy_rx_stop(void);
 esp_err_t phy_set_gpio(gpio_num_t gpio_num, bool invert_signal);
 
-
 #endif