Add reusable modem modules and generic modem driver

[bjarki-trackunit]

Modem subsystem for Zephyr RTOS

Introduction

The modem subsystem adds Zephyr implementations of the widely used Linux programs: chat and pppd, and a CMUX module.

What issue will the modem subsystem solve?

Modems on Zephyr RTOS currently offer limited capabilities and features compared to the capabilities and features offered by the modems. The main limiting factor lies with the Zephyr Device Driver model, which is not flexible enough to support the extensive and ever expanding feature set of modems. Even if it could, making a generic API for modems would itself be an extensive task, which may never be realized.

How will the modem subsystem solve the issue?

The modem modules are simple and abstract, allowing users to either implement the entire modem driver in the application layer, or create an out-of-tree modem driver easily. This allows users to create their own tailored modem drivers, with potential out-of-tree device driver APIs. This strategy encourages collaborating on the complex, sharable parts of the drivers, the modem modules, while giving users full flexibility regarding business logic of their modem drivers, which is often proprietary.

The modem modules can also be used to create more general drivers for modems like the ublox-r4 and quectel-bg9x.

Isn't this already implemented in Zephyr?

Zephyr currently has a working device driver, gsm_ppp, which uses CMUX, PPP and a command handler. However, it is not built in a modular fashion. The objects used by the driver are tightly coupled together using public headers and Kconfigs, which makes them hard to test and reuse. The objects depend highly on Kconfigs to allocate lists of fixed lengths for objects and buffers to be allocated during runtime, which makes the configuration and use of said modules difficult. The objects referenced are:

• PPP L2 network device and PPP frame wrapper (drivers/net/ppp.c)
• gsm mux which sets up CMUX (drivers/console/gsm_mux.c)
• uart mux which creates a list of virtual devices using UART API (drivers/console/uart_mux.c)

Potentially for these reasons, of these objects, only the ppp.c is currently tested. After reviewing the gsm_ppp driver and dependencies, it became clear creating a novel modular subsystem for the modems using the newest features of Zephyr, which additionally mimics the daemons available on Linux, was a better approach than changing the existing implementation.

This decision allows the gsm_ppp driver and its dependencies and the novel subsystem to persist in parallel.

Modular design?

The modem modules in the modem subsystem are loosely coupled using the modem_pipe structure and API. This is a simple bytes in/bytes out pipe with a callback when data is ready. Decoupling the modules using this interface makes testing the modules independently staight forward, using mocks which implement the modem_pipe API. It also allows for easily switching "backends", like (modem_pipe -> UART API) could be switched for (modem_pipe -> IPC) and using a CMUX DLCI channel could be switched for using the modem UART directly. At this time, backends for UART, using the ISR and Async APIs, and TTY, using POSIX, are currently implemented.

Performance comparison

The comparison uses the newly introduced sample net/cellular_modem which uses a cellular modem to perform a DNS lookup, followed by transmitting and receiving 64 packets, calculating the average time from sending to receiving a packet. Packets of size 256 and 1024 bytes where tested. The echo time is the total transmission time from send_to() to returning from recv().

Test results

|  Property               |  Existing solution  |  Modem modules
|  Flash                  |  98296 bytes        |  101204 bytes
|  RAM                    |  42552 bytes        |  30416 bytes
|  Echo 256 bytes         |  195 ms             |  160 ms
|  Echo 1024 bytes        |  503 ms             |  401 ms
|  Throughput 256 bytes   |  4914 bytes/s       |  7708 bytes/s
|  Throughput 1024 bytes  |  N/A                |  8709 bytes/s

Note that the existing solution is exceptionally unstable, consistently failing to send more than a few packets larger than 256 bytes for some reason...

Summary

The modem modules consume 12000 bytes (28.5%) less RAM, with nearly identical ROM usage, while presenting a 58% higher transmit throughput :)

[carlescufi]

Architecture WG:

• @bjarki-trackunit presented the subsystem as per the description above

[rerickson1]

Adding a section to the docs and a sample using the basic driver would be good.

[bjarki-trackunit]

Patch note:

Addressed all comments

All review comments have now been addressed :)

Added throughput test to cellular sample

The cellular_modem sample now includes the following features:

• Power cycle modem
• Use DNS lookup to find address of test-endpoint.com
• Send UDP packet and await echo back from test-endpoint.com
• NEW: Send multiple UDP packets as fast as possible to test-endpoint.com, and await response from test-endpoint.com indicating how many packets where received, and if their payload was correct (payload is pseudo random). Throughput is calculated and shown in bytes/s

End to end tests performed

With the cellular_modem sample able to validate stability and measure transmit throughput, performance tests could be performed. Performance tests where performed for the modem_cellular.c driver and gsm_ppp.c driver for comparison. The RAM and Flash usage was noted as well.

Test setup

A b_u585i_iot02a board was used with a Quectel BG95 modem to perform the tests. The cellular_modem sample was altered slightly when testing the gsm_ppp.c driver as it doesn't support PM, and must be controlled using gsm_ppp_start().

Test results

|  Property               |  gsm_ppp.c          |  modem_cellular.c
|  Flash                  |  98296 bytes        |  101204 bytes
|  RAM                    |  42552 bytes        |  30416 bytes
|  Echo 256 bytes         |  195 ms             |  160 ms
|  Echo 1024 bytes        |  503 ms             |  401 ms
|  Throughput 256 bytes   |  4914 bytes/s       |  7708 bytes/s
|  Throughput 1024 bytes  |  N/A                |  8709 bytes/s

The gsm_ppp.c driver consistently deadlocked after sending a few packets during the throughout test and echo test when the packet size was more than 256 bytes. For the echo test, we get the transmit time for each echo, so I used the average of the few packets that where successfully sent before deadlocking, this was not an option for the throughput test, hence why its N/A on the test results.

Conclusion

The modem subsystem, the new modem driver, and the associated sample, I believe are now in a merge-able state. The modem subsystem has wide unit test coverage, and has proven stable through performance testing. The new modem driver is in a usable state after quite a bit of help from @rerickson1. Performance testing shows that the new subsystem uses 28% less RAM, while providing a transmit throughout 58% higher than the existing solution using gsm_ppp.c provides, while also providing better stability.

Special thanks to @rerickson1 for helping with developing the modem_cellular.c driver, and @rlubos, @jukkar and @rerickson1 for your thorough reviews :)

Please re-review this PR at your convenience :)

[rerickson1]

Great work on this!

[jukkar]

LGTM. One thing to think about after this is merged, is how to prepare the deprecation of the older modem files / drivers. We do not want to have multiple implementations of the same thing for too long.

[WilliamGFish]

LGTM. One thing to think about after this is merged, is how to prepare the deprecation of the older modem files / drivers. We do not want to have multiple implementations of the same thing for too long.

There may still be some work as the ESP_AT Wi-Fi driver is built around the Modem implementation...This looks great and it will be a shame to see the old SARA drivers being retired, it was hard work all that time ago.
@bjarki-trackunit Could use some help looking at this.

[bjarki-trackunit]

@WilliamGFish The gsm_ppp.c driver is replaced by the modem_cellular.c driver, which both use PPP and CMUX function, and it should therefore be deprecated. The SARA-R4 driver uses network offloading, and a bit of gpio handling, so there is an argument for keeping the driver. I do believe we should deprecate the old modem libraries like modem_cmd_handler which are replaceable by the new modem modules though, which then would require updating the existing modem drivers that depend on them. Is there interest in doing this update of drivers like the SARA-R4?

[WilliamGFish]

Is there interest in doing this update of drivers like the SARA-R4?

I think the SARA range is still going strong and the driver currently cover the U2 & R4 but may be able to be adapted to include the R5.