RFC: Breaking API Change: drivers: can: rework support for manual bus-off recovery

[henrikbrixandersen]

Introduction

Many CAN controllers support two different modes for recovering from bus-off state:

• Automatic recovery after 128 occurrences of 11 consecutive recessive bits have been monitored on the bus.
• Manual recovery initiation, after which the CAN controller still waits until 128 occurrences of 11 consecutive recessive bits have been monitored on the bus.

The Zephyr CAN controller API supports both modes through the the CONFIG_CAN_AUTO_BUS_OFF_RECOVERY Kconfig option, which is enabled by default. The manual recovery API function can_recover() is only functional when CONFIG_CAN_AUTO_BUS_OFF_RECOVERY is disabled.

Problem description

Even though ISO11898-1 §6.15 states that no CAN node should automatically recover from bus-off events, manual recovery initiation is not consistently supported by the CAN controllers/drivers available in Zephyr.

This leads to incoherent behavior between drivers with CONFIG_CAN_AUTO_BUS_OFF_RECOVERY=n. Drivers supporting manual recovery initiation disable automatic bus-off recovery at driver initialization, while the ones not supporting manual recovery initiation keep it enabled regardless of CONFIG_CAN_AUTO_BUS_OFF_RECOVERY=n (there is no other option) and return -ENOTSUP from the mandatory can_recover() API function.

An overview of the currently supported CAN controllers along with their support manual/automatic bus-off recovery is shown in the table below.

Driver compatible	Automatic Recovery	Manual Recovery
atmel,sam0-can	X	X
atmel,sam-can	X	X
espressif,esp32-twai	X	X
infineon,xmc4xxx-can	X
kvaser,pcican	X	X
microchip,mcp2515	X
microchip,mcp251xfd	X
nuvoton,numaker-canfd	X	X
nxp,flexcan	X	X
nxp,lpc-mcan	X	X
nxp,s32-canxl	X	X
renesas,rcar-can	X	X
st,stm32-bxcan	X	X
st,stm32-fdcan	X	X
st,stm32h7-fdcan	X	X
ti,tcan4x5x	X	X
zephyr,can-loopback	(X)
zephyr,fake-can	(X)
zephyr,native-linux-can	(X)

Proposed change

Since all CAN controllers seem to support automatic recovery (for any future drivers for hardware without this hardware capability this can easily be implemented in the driver), change the Zephyr CAN controller API policy to:

• Always enable automatic bus recovery upon driver initialization, regardless of Kconfig options. Since CAN controllers are initialized in "stopped" state, no unwanted bus-off recovery will be started at this point.
• Invert and rename the Kconfig CONFIG_CAN_AUTO_BUS_OFF_RECOVERY, which is enabled by default, to CONFIG_CAN_MANUAL_RECOVERY_MODE, which is disabled by default. Enabling CONFIG_CAN_MANUAL_RECOVERY_MODE=y enables support for the can_recover() API function and a new manual recovery mode (see next bullet). Keeping this guarded by Kconfig allows keeping the flash footprint down for applications not using manual bus-off recovery.
• Introduce a new CAN controller operational mode CAN_MODE_MANUAL_RECOVERY. Support for this is only enabled if CONFIG_CAN_MANUAL_RECOVERY_MODE=y. Having this as a mode allows applications to inquire whether the CAN controller supports manual recovery mode via the can_get_capabilities() API function and either fail or rely on automatic recovery - and it allows CAN controller drivers not supporting manual recovery mode to fail early in can_set_mode() during application startup instead of failing when can_recover() is called at a later point in time.

Detailed RFC

Please see PR #69460.

Proposed change (Detailed)

Please see PR #69460.

Dependencies

None

Concerns and Unresolved Questions

None so far.

Alternatives

None so far.

[carlescufi]

Architecture WG:

• @henrikbrixandersen summarizes what is described in the PR description
• No objections