Enhance rtl8196e_uart_bridge_main to support SW Flow control

[hlyi]

Hi @jnilo1, I am creating a separated request based upon the discussion in #119.

Currently, the uart bridge only support HW flow control. However, only other platform, SW control is needed because of lacking hardware connectives between RTL8196E and radio coprocessor. Could you please add flow control type that can be selected between hw and sw? And can be specified in device tree?

Thanks!

[jnilo1]

Hi @hlyi,

Done — uart-bridge v1.2 implements this, bench-verified, ships in the next release.

What changed

flow_control is now tri-state, selectable at runtime and in the device tree:

Value	Meaning
0 / none	no flow control (also the EFR32-flash setting, see below)
1 / hw	RTS/CTS — the default, unchanged
2 / sw	XON/XOFF, handled by the bridge itself

Device tree side, the board DTS gains an optional node the driver reads at boot to seed its defaults (module parameters still override):

radio-bridge {
        compatible = "realtek,rtl8196e-uart-bridge";
        nrst-gpios = <&gpio0 12 (GPIO_ACTIVE_LOW | GPIO_OPEN_DRAIN)>;
        flow-control = "sw";    /* "hw" | "sw" | "none" */
};

Readback of the sysfs knob stays numeric (0/1/2) so existing tooling (flash_efr32.sh) keeps working unmodified.

How sw mode works

The bridge's hot path bypasses the tty line discipline, so termios IXON/IXOFF would be inert — the bridge handles XON/XOFF itself. In sw mode it scans the radio→host stream for bare 0x11/0x13 (a software-flow-control radio firmware escapes data-plane occurrences, so bare ones are genuine flow control), strips them from the TCP stream, and gates the TCP→UART direction: pause on XOFF, resume on XON, bounded 1 s fail-open if XON never comes (counted in a new tx_pause_timeouts stat). Two more counters, xoff/xon, let you watch the mechanism live in parameters/stats.

A welcome side effect of consuming the control bytes in the bridge: a remote host (Z2M over TCP) sees a clean ASH stream and needs no software-flow-control support of its own.

The flow control is deliberately asymmetric: the bridge honors the radio's XOFF but never emits one toward the radio — the SoC drains a 16-byte UART FIFO at these baud rates without ever falling behind, and the UART→TCP direction keeps its drop-and-count semantics.

Verified on the bench

I built a one-off NCP-UART-SW variant for the Lidl EFR32MG1B (GSDK 4.5.0, SL_IOSTREAM_USART_VCOM_FLOW_CONTROL_TYPE = uartFlowControlSoftware) and ran EZSP sessions through the bridge in sw mode — clean traffic both directions, zero drops. One honest caveat: I could not provoke an actual bare XOFF on this bench — the NCP drains its RX buffer faster than a 115200 host can fill it, so its buffer-full XOFF never fires. The xoff/xon counters are there precisely so you can confirm the mechanism on your G4 under real load.

Two questions for your G4

1. Which radio firmware will the G4 run — a GSDK/Simplicity build where you control the flow-control setting, or the Sengled stock NCP? If stock: do you know whether it actually uses XON/XOFF, or just runs with no flow control at all?
2. If it runs with no flow control (quite common — ASH's own ACK window bounds the in-flight data), then flow_control=0/"none" is all you need; sw only matters if the radio genuinely emits XON/XOFF.

One operational note: during an EFR32 flash, flow control must be 0 in all modes — Xmodem payloads contain raw 0x11/0x13 bytes, and sw mode would eat them.

[hlyi]

@jnilo1 you are so great implementing new features!

I built radio firmware based on your GSDK setup with manually hacks to enable sw flow control, the built went through. But to be honest with you, I haven’t tested it yet, as I need bootloader support mentioned in #121 to flash it. Actually it brings me to another enhancement request: could you please add BOARD support to radio firmware build similar to the one you did for kernel device tree?

do you mind sharing your enhancement?

Thanks again!

[jnilo1]

Hi @hlyi,

Great that your sw-flow build went through — and good news on the blocker: v3.10.0 is out and ships everything you were waiting for from #121/#123: the configurable nRST (nrst-gpios in the DTS or the nrst_gpio runtime parameter) and bridge v1.2 with flow_control=sw. flash_efr32.sh should now work end-to-end on your G4 once your DTS names the right nRST line.

The sw-flow-control firmware delta

Happy to share — it is smaller than it looks. Starting from our NCP project (GSDK 4.5.0), the whole change is one configuration value:

/* config/sl_iostream_usart_vcom_config.h */
#define SL_IOSTREAM_USART_VCOM_FLOW_CONTROL_TYPE   uartFlowControlSoftware

(equivalently, the SL_IOSTREAM_USART_VCOM_FLOW_CONTROL_TYPE entry in the .slcp configuration). The iostream-usart init template then does the rest: it programs the USART with hwFlowControl = None and enables iostream-level software flow control, which emits XOFF when the RX buffer fills and XON when it drains (sl_iostream_uart.c). No RTS/CTS pin routing is needed at all in this mode, which is presumably the point for your G4 wiring. ASH escapes any data-plane 0x11/0x13, so the bare ones the bridge strips are genuine flow control.

That is exactly what my bench one-off was; if your manual hacks ended up at the same define, you already have the right firmware.

BOARD= for the radio firmware builds

Legitimate ask — I answered it in #126 with a concrete proposal (per-board config directory under the EFR32 build scripts, with lidl as the in-tree reference and the g4 definition contributed/validated on your hardware, since the G4's EFR32MG13P is a different chip we cannot test here). Let's keep that thread in #126.

Once you have the G4 running in sw mode under real Zigbee load, I am very interested in your xoff/xon counters (parameters/stats) — you will be the first to exercise the pause/resume path against a radio that actually emits XOFF.

[hlyi]

@jnilo1 thanks for the enhancement. I will work on radio enhancement after getting full linux build up and running. BTW, I don't know native zigbee protocol Sengled has, my intention is only using custom build firmware for NCP and RCP for OTBR. One thing that I would need to flash custom firmware is to support entering bootloader mode. As you can see in PR #127, I added blmode-gpios definition. need your help to implement in param_set_nrst_pulse function. When it is presented, the reset sequence would be

• set blmode-gpios to active mode ( new)
• set nrst-gpios to active mode ( same as in current code)
• delay 100ms ( same as in current mode )
• set nrst-gpios to inactive mode ( same as in current code)
• delay 5 seconds ( new)
• set blmode-gpios to inactive mode ( new)

Thanks a lot!

[jnilo1]

Hi @hlyi,

Good context on your goal (custom NCP / OT-RCP only, no need to speak Sengled's native protocol) — that confirms pin-driven bootloader entry is your only path for the first flash over the stock firmware, since universal-silabs-flasher can't ask a non-EZSP firmware to launch the bootloader.

Yes — but as a separate trigger, not inside nrst_pulse

We'll implement your sequence in the bridge driver (v1.3), with one design change: it will be a new write-only trigger (working name blmode_pulse), alongside the existing nrst_pulse, rather than changing nrst_pulse's behaviour whenever blmode-gpios is present.

The reason: nrst_pulse is also the "reset the EFR32 back into the application" path — flash_efr32.sh and recover_efr32 rely on it after a flash completes. If the bridge asserted blmode on every reset whenever the GPIO is described in the DT, every reset on your board would land in the Gecko bootloader and there would be no way left to start the application. So:

• nrst_pulse — unchanged: plain application reset (blmode never touched);
• blmode_pulse — exactly your sequence:
  1. set blmode-gpios active
  2. set nrst-gpios active
  3. delay 100 ms
  4. set nrst-gpios inactive
  5. delay 5 s (blmode held through the bootloader's pin-sampling window)
  6. set blmode-gpios inactive

Your PR #127 DTS already declares blmode-gpios with the property name we had reserved for this, so nothing to change on your side — the driver will claim it as an optional GPIO at probe (boards without it simply get -ENODEV on the trigger).

One thing worth double-checking on your bench when this lands: the active-low + open-drain polarity you declared matches how the Sengled bootloader actually samples the pin (we are implementing your empirical spec — we have no way to verify it on the MG13).

This lands on the v3.11.0-pre integration branch together with the rest of the G4 batch (see #126 and the PR #127 review for the branch logistics), and ships as v3.11.0 once validated on both boards.

[hlyi]

@jnilo1 Thanks for creating blmode_pulse. What you said make senses. One question: due to new separated trigger, any of your scripts flashing radio firmware need to be updated to use new blmode_pulse?

One thing worth double-checking on your bench when this lands: the active-low + open-drain polarity you declared matches how the Sengled bootloader actually samples the pin (we are implementing your empirical spec — we have no way to verify it on the MG13).

Yes, it worked on my board. The EFR32 was able to enter bootloader mode by issue command echo 1 > blmode_pulse. BTW, in PR#128, I also reduced blmode hold time from 5s to 1s. A even lower delay could work, but I don't think optimizing further is needed, if let me know if you disagree.

[jnilo1]

Hi @hlyi,

Excellent — thanks for confirming blmode_pulse works on the real pin. And agreed on the hold time: 1 s with margin over the pin-sampling window is exactly where it should be; shaving it further buys nothing (the write blocks ~1.1 s total, once per flash). Your 5 s → 1 s reduction is merged as-is.

Do the flash scripts need blmode_pulse? No — by design

flash_efr32.sh enters the bootloader in-band: universal-silabs-flasher probes the running application (EZSP / CPC / Spinel) and sends its bootloader-launch command, and if the chip is already sitting in the bootloader (empty app slot), the script's first probe detects that directly at bootloader:115200. Neither path involves the reset pins, so nothing to update.

blmode_pulse covers the one case in-band entry cannot: a radio firmware that speaks none of those protocols — i.e. your first flash over the Sengled stock firmware (or recovering a bricked app). The procedure on the G4 today:

1. stop whatever holds the bridge port, then echo 1 > .../blmode_pulse;
2. run flash_efr32.sh normally — the chip is in the bootloader, so the script's existing already-in-bootloader probe picks it up and flashes;
3. every flash after that is in-band (our NCP/OT-RCP firmwares all support bootloader launch), and nrst_pulse keeps meaning "boot the application".

If you think it's worth it, I can add an automatic fallback to flash_efr32.sh for v3.11.0: when no application protocol answers and the board's DT declares blmode-gpios, trigger blmode_pulse and retry. It only matters for the first-flash/recovery scenario, so manual may be perfectly fine — your call.

Answered your #129 baud question over there — short version: you caught a documentation bug, the Gecko bootloader is 115200 on both boards; fixed in the tree.

[hlyi]

@jnilo1 Thanks for clarification! That's great. I will try it out. I will close this thread as original request of supporting SW flow control has been implemented 👍