src/cyw43_ctrl: Add roaming and interference-mitigation config via ioctl helpers

Expose the roaming and interference-mitigation ioctls needed to tune
link stability, implemented entirely in terms of cyw43_ioctl() rather
than adding dedicated low-level (cyw43_ll_*) functions for each setting,
per maintainer feedback on PR #146. Only the two generic u32 helpers
cost binary space; the feature-specific wrappers are static inline and
the named-iovar helpers are the only additional functions.

Roaming is enabled by default with no way to configure it. When a STA's
RSSI drops below the (hidden) roam trigger the firmware starts background
roam scans, which causes dropped packets and severe throughput
degradation on a point-to-point link (see #111
and raspberrypi/pico-sdk#2835).

Add public helpers:

  - cyw43_ioctl_set_u32(self, cmd, val, iface)
  - cyw43_ioctl_get_u32(self, cmd, *out_val, iface)
    Wrap cyw43_ioctl() for the common case of a 4-byte ioctl value.
    Argument order matches cyw43_ioctl() (iface last).

Add CYW43_IOCTL_xxx constants, encoded as (WLC_cmd << 1) | is_set to
match the existing CYW43_IOCTL_ defines:

  - GET/SET_ROAM_TRIGGER, GET/SET_ROAM_DELTA, GET/SET_ROAM_SCAN_PERIOD
  - GET/SET_INTERFERENCE_MODE

Add the configuration API:

  - cyw43_wifi_set_roam_params() / cyw43_wifi_get_roam_params()
    static inline, built on the u32 ioctl helpers.
  - cyw43_wifi_set_interference_mode() / cyw43_wifi_get_interference_mode()
    static inline, built on the u32 ioctl helpers, with CYW43_IFMODE_*
    mode constants.
  - cyw43_wifi_set_roam_enabled() / cyw43_wifi_get_roam_enabled()
    toggle/read the "roam_off" iovar via WLC_SET_VAR / WLC_GET_VAR.

The default roaming behaviour is left unchanged.

Author: mitchellcairns

src/cyw43.h

@@ -104,6 +104,20 @@
 #define CYW43_LINK_BADAUTH      (-3)    ///< Authenticatation failure
 //!\}
 
+/*!
+ * \name Interference mitigation mode
+ * \anchor CYW43_IFMODE_
+ * \see cyw43_wifi_set_interference_mode() to set the mitigation mode
+ * \see cyw43_wifi_get_interference_mode() to get the mitigation mode
+ */
+//!\{
+#define CYW43_IFMODE_NONE         (0)     ///< None/Disabled
+#define CYW43_IFMODE_NONWLAN      (1)     ///< Non-WLAN
+#define CYW43_IFMODE_WLANMANUAL   (2)     ///< Adjacent channel interference (ACI) mode
+#define CYW43_IFMODE_AUTO         (3)     ///< Automatic as determined by driver (ACI)
+#define CYW43_IFMODE_AUTONOISE    (4)     ///< Automatic as determined by driver with noise reduction (ACI)
+//!\}
+
 typedef struct _cyw43_t {
     cyw43_ll_t cyw43_ll;
 
@@ -186,6 +200,34 @@ void cyw43_deinit(cyw43_t *self);
  */
 int cyw43_ioctl(cyw43_t *self, uint32_t cmd, size_t len, uint8_t *buf, uint32_t iface);
 
+/*!
+ * \brief Set an ioctl whose value is a single unsigned 32-bit integer
+ *
+ * Convenience wrapper around \ref cyw43_ioctl for the common case of an ioctl
+ * that takes a 4-byte value, e.g. the various \c CYW43_IOCTL_SET_xxx commands.
+ *
+ * \param self  the driver state object. This should always be \c &cyw43_state
+ * \param cmd   the ioctl command to send, e.g. one of the \c CYW43_IOCTL_SET_xxx defines
+ * \param val   the value to set
+ * \param iface the interface to use, either \ref CYW43_ITF_STA or \ref CYW43_ITF_AP
+ * \return 0 on success, negative error code on failure
+ */
+int cyw43_ioctl_set_u32(cyw43_t *self, uint32_t cmd, uint32_t val, uint32_t iface);
+
+/*!
+ * \brief Get an ioctl whose value is a single unsigned 32-bit integer
+ *
+ * Convenience wrapper around \ref cyw43_ioctl for the common case of an ioctl
+ * that returns a 4-byte value, e.g. the various \c CYW43_IOCTL_GET_xxx commands.
+ *
+ * \param self    the driver state object. This should always be \c &cyw43_state
+ * \param cmd     the ioctl command to send, e.g. one of the \c CYW43_IOCTL_GET_xxx defines
+ * \param out_val Output: the value that was read. May be NULL.
+ * \param iface   the interface to use, either \ref CYW43_ITF_STA or \ref CYW43_ITF_AP
+ * \return 0 on success, negative error code on failure
+ */
+int cyw43_ioctl_get_u32(cyw43_t *self, uint32_t cmd, uint32_t *out_val, uint32_t iface);
+
 /*!
  * \brief Send a raw ethernet packet
  *
@@ -200,6 +242,35 @@ int cyw43_ioctl(cyw43_t *self, uint32_t cmd, size_t len, uint8_t *buf, uint32_t
  */
 int cyw43_send_ethernet(cyw43_t *self, int itf, size_t len, const void *buf, bool is_pbuf);
 
+/*!
+ * \brief Set the WiFi interference mitigation mode
+ *
+ * Controls how aggressively the firmware attempts to mitigate interference
+ * on the 2.4GHz band. Higher modes reduce interference at the cost of
+ * RX sensitivity, which can be detrimental to long range operation.
+ *
+ * \note This setting applies globally to the radio and affects both the
+ * STA and AP interfaces in apsta mode.
+ *
+ * \param self  The driver state object, always \c &cyw43_state
+ * \param mode  Interference mitigation mode, one of \ref CYW43_IFMODE_
+ * \return 0 on success, negative error code on failure
+ */
+static inline int cyw43_wifi_set_interference_mode(cyw43_t *self, uint32_t mode) {
+    return cyw43_ioctl_set_u32(self, CYW43_IOCTL_SET_INTERFERENCE_MODE, mode, CYW43_ITF_STA);
+}
+
+/*!
+ * \brief Get the current WiFi interference mitigation mode
+ *
+ * \param self  The driver state object, always \c &cyw43_state
+ * \param mode  Output: current interference mitigation mode, one of \ref CYW43_IFMODE_
+ * \return 0 on success, negative error code on failure
+ */
+static inline int cyw43_wifi_get_interference_mode(cyw43_t *self, uint32_t *mode) {
+    return cyw43_ioctl_get_u32(self, CYW43_IOCTL_GET_INTERFERENCE_MODE, mode, CYW43_ITF_STA);
+}
+
 /*!
  * \brief Set the wifi power management mode
  *
@@ -360,6 +431,109 @@ int cyw43_wifi_join(cyw43_t *self, size_t ssid_len, const uint8_t *ssid, size_t
  */
 int cyw43_wifi_leave(cyw43_t *self, int itf);
 
+/*!
+ * \brief Enable or disable WiFi roaming on the STA interface
+ *
+ * When disabled, the firmware will remain associated to its current AP
+ * regardless of signal strength. When enabled, roaming behaviour is
+ * governed by the parameters set in \c cyw43_wifi_set_roam_params.
+ *
+ * Roaming is enabled by default. 
+ *
+ * \param self     The driver state object, always \c &cyw43_state
+ * \param enabled  true to enable roaming, false to disable
+ * \return 0 on success, negative error code on failure
+ */
+int cyw43_wifi_set_roam_enabled(cyw43_t *self, bool enabled);
+
+/*!
+ * \brief Query whether WiFi roaming is enabled on the STA interface
+ *
+ * Reads back the current state of the \c roam_off iovar.
+ *
+ * \param self     The driver state object, always \c &cyw43_state
+ * \param enabled  Output: true if roaming is enabled, false if disabled
+ * \return 0 on success, negative error code on failure
+ */
+int cyw43_wifi_get_roam_enabled(cyw43_t *self, bool *enabled);
+
+/*!
+ * \brief Configure WiFi roaming parameters for the STA interface
+ *
+ * Controls when the firmware will scan for and switch to a better AP.
+ * Roaming is a STA-mode only feature - these parameters have no effect
+ * when called on the AP interface.
+ *
+ * The firmware begins scanning for alternative APs when the current AP's
+ * RSSI drops below \p trigger_dbm. A candidate AP must have an RSSI at
+ * least \p candidate_delta_db higher than the current AP before the
+ * firmware will roam to it. This prevents thrashing between APs of
+ * similar signal strength.
+ *
+ * \param self          The driver state object, always \c &cyw43_state
+ * \param trigger_dbm   RSSI threshold in dBm below which roam scanning begins.
+ *                      Typical value: -75. Must be negative.
+ * \param candidate_delta_db  Minimum RSSI improvement in dB a candidate AP
+ *                      must offer over the current AP to trigger a roam.
+ *                      Typical value: 10.
+ * \param scan_period_ms How often in milliseconds the firmware scans for better
+ *                      APs while below the trigger threshold.
+ * \return 0 on success, negative error code on failure
+ */
+static inline int cyw43_wifi_set_roam_params(cyw43_t *self, int trigger_dbm, int candidate_delta_db, int scan_period_ms) {
+    int ret = cyw43_ioctl_set_u32(self, CYW43_IOCTL_SET_ROAM_TRIGGER, (uint32_t)trigger_dbm, CYW43_ITF_STA);
+    if (ret) {
+        return ret;
+    }
+    ret = cyw43_ioctl_set_u32(self, CYW43_IOCTL_SET_ROAM_DELTA, (uint32_t)candidate_delta_db, CYW43_ITF_STA);
+    if (ret) {
+        return ret;
+    }
+    return cyw43_ioctl_set_u32(self, CYW43_IOCTL_SET_ROAM_SCAN_PERIOD, (uint32_t)scan_period_ms, CYW43_ITF_STA);
+}
+
+/*!
+ * \brief Retrieve the current WiFi roaming parameters for the STA interface
+ *
+ * Reads back the roaming parameters that are currently set.
+ * Any pointer may be NULL if that parameter is not required.
+ *
+ * \param self                The driver state object, always \c &cyw43_state
+ * \param trigger_dbm         Output: RSSI threshold in dBm below which roam
+ *                            scanning begins. Will be a negative value.
+ * \param candidate_delta_db  Output: Minimum RSSI improvement in dB a candidate
+ *                            AP must offer over the current AP to trigger a roam.
+ * \param scan_period_ms      Output: How often in milliseconds the firmware scans
+ *                            for better APs while below the trigger threshold.
+ * \return 0 on success, negative error code on failure
+ */
+static inline int cyw43_wifi_get_roam_params(cyw43_t *self, int *trigger_dbm, int *candidate_delta_db, int *scan_period_ms) {
+    uint32_t val;
+    int ret;
+    if (trigger_dbm != NULL) {
+        ret = cyw43_ioctl_get_u32(self, CYW43_IOCTL_GET_ROAM_TRIGGER, &val, CYW43_ITF_STA);
+        if (ret) {
+            return ret;
+        }
+        *trigger_dbm = (int)(int32_t)val;
+    }
+    if (candidate_delta_db != NULL) {
+        ret = cyw43_ioctl_get_u32(self, CYW43_IOCTL_GET_ROAM_DELTA, &val, CYW43_ITF_STA);
+        if (ret) {
+            return ret;
+        }
+        *candidate_delta_db = (int)(int32_t)val;
+    }
+    if (scan_period_ms != NULL) {
+        ret = cyw43_ioctl_get_u32(self, CYW43_IOCTL_GET_ROAM_SCAN_PERIOD, &val, CYW43_ITF_STA);
+        if (ret) {
+            return ret;
+        }
+        *scan_period_ms = (int)(int32_t)val;
+    }
+    return 0;
+}
+
 /*!
  * \brief Get the signal strength (RSSI) of the wifi network
  *

src/cyw43_ctrl.c

@@ -455,6 +455,22 @@ int cyw43_ioctl(cyw43_t *self, uint32_t cmd, size_t len, uint8_t *buf, uint32_t
     return ret;
 }
 
+int cyw43_ioctl_set_u32(cyw43_t *self, uint32_t cmd, uint32_t val, uint32_t iface) {
+    // The wire format is little-endian; RP2 hosts are little-endian so the
+    // value can be passed straight through (matching cyw43_wifi_get_rssi()).
+    uint32_t buf = val;
+    return cyw43_ioctl(self, cmd, sizeof(buf), (uint8_t *)&buf, iface);
+}
+
+int cyw43_ioctl_get_u32(cyw43_t *self, uint32_t cmd, uint32_t *out_val, uint32_t iface) {
+    uint32_t buf = 0;
+    int ret = cyw43_ioctl(self, cmd, sizeof(buf), (uint8_t *)&buf, iface);
+    if (ret == 0 && out_val != NULL) {
+        *out_val = buf;
+    }
+    return ret;
+}
+
 int cyw43_send_ethernet(cyw43_t *self, int itf, size_t len, const void *buf, bool is_pbuf) {
     CYW43_THREAD_ENTER;
     int ret = cyw43_ensure_up(self);
@@ -668,6 +684,46 @@ int cyw43_wifi_leave(cyw43_t *self, int itf) {
     return cyw43_ioctl(self, CYW43_IOCTL_SET_DISASSOC, 0, NULL, itf);
 }
 
+int cyw43_wifi_set_roam_enabled(cyw43_t *self, bool enabled) {
+    // "roam_off" is a string-named iovar rather than a numbered ioctl, so it is
+    // sent via the WLC_SET_VAR ioctl with a "<name>\0<le32 value>" payload.
+    static const char var[] = "roam_off";
+    const size_t name_len = sizeof(var); // includes the NUL terminator
+    uint8_t buf[sizeof(var) + 4];
+    memcpy(buf, var, name_len);
+    // roam_off == 1 disables roaming, 0 enables it. Only the low byte is
+    // significant; store little-endian byte-wise to avoid unaligned access.
+    buf[name_len + 0] = enabled ? 0 : 1;
+    buf[name_len + 1] = 0;
+    buf[name_len + 2] = 0;
+    buf[name_len + 3] = 0;
+    return cyw43_ioctl(self, CYW43_IOCTL_SET_VAR, name_len + 4, buf, CYW43_ITF_STA);
+}
+
+int cyw43_wifi_get_roam_enabled(cyw43_t *self, bool *enabled) {
+    if (enabled == NULL) {
+        return -CYW43_EINVAL;
+    }
+    // Read the "roam_off" iovar back via the WLC_GET_VAR ioctl. The variable
+    // name is written into the buffer and the firmware replaces it with the
+    // little-endian u32 value on return (see how CYW43_IOCTL_GET_VAR is used).
+    static const char var[] = "roam_off";
+    const size_t name_len = sizeof(var); // includes the NUL terminator
+    uint8_t buf[sizeof(var) + 4];
+    memcpy(buf, var, name_len);
+    buf[name_len + 0] = 0;
+    buf[name_len + 1] = 0;
+    buf[name_len + 2] = 0;
+    buf[name_len + 3] = 0;
+    int ret = cyw43_ioctl(self, CYW43_IOCTL_GET_VAR, name_len + 4, buf, CYW43_ITF_STA);
+    if (ret == 0) {
+        uint32_t roam_off = (uint32_t)buf[0] | ((uint32_t)buf[1] << 8) |
+            ((uint32_t)buf[2] << 16) | ((uint32_t)buf[3] << 24);
+        // roam_off != 0 means roaming is disabled.
+        *enabled = (roam_off == 0);
+    }
+    return ret;
+}
 
 int cyw43_wifi_get_rssi(cyw43_t *self, int32_t *rssi) {
     if (!rssi || !CYW43_STA_IS_ACTIVE(self)) {

src/cyw43_ll.h

@@ -56,10 +56,18 @@
 #define CYW43_IOCTL_GET_SSID            (0x32)
 #define CYW43_IOCTL_GET_CHANNEL         (0x3a)
 #define CYW43_IOCTL_SET_DISASSOC        (0x69)
+#define CYW43_IOCTL_GET_ROAM_TRIGGER    (0x6c)
+#define CYW43_IOCTL_SET_ROAM_TRIGGER    (0x6f)
+#define CYW43_IOCTL_GET_ROAM_DELTA      (0x70)
+#define CYW43_IOCTL_SET_ROAM_DELTA      (0x73)
+#define CYW43_IOCTL_GET_ROAM_SCAN_PERIOD (0x74)
+#define CYW43_IOCTL_SET_ROAM_SCAN_PERIOD (0x77)
 #define CYW43_IOCTL_GET_ANTDIV          (0x7e)
 #define CYW43_IOCTL_SET_ANTDIV          (0x81)
 #define CYW43_IOCTL_SET_MONITOR         (0xd9)
 #define CYW43_IOCTL_GET_RSSI            (0xfe)
+#define CYW43_IOCTL_GET_INTERFERENCE_MODE (0x1a6)
+#define CYW43_IOCTL_SET_INTERFERENCE_MODE (0x1a9)
 #define CYW43_IOCTL_GET_VAR             (0x20c)
 #define CYW43_IOCTL_SET_VAR             (0x20f)