USB Device Drivers - Beaglebone Black

This report summarizes the work that I have done throughout the Google Summer of Code 2021 internship program with RTEMS Project.

Project Overview

The project aims to improve the Beagle BSP (Board Support Package) in RTEMS by adding support for USB devices.

Project Objectives

  1. Add/Port CDC ECM Driver (Ethernet Over USB)
  2. Add/Port CDC ACM Driver (Serial Over USB)
  3. Add/Port CDC MSC Driver (Mass Storage Device)

Mentors

  1. Christian Mauderer
  2. Vijay Kumar Banerjee

Summary

In this project, we have completed importing and documenting the CDC Ethernet driver to RTEMS LibBSD. I have summarized below the work I did in each phase and also the changes and challenges that were encountered.

This project’s aims was to add support for USB Modem, USB Serial and Mass Storage support for the Beagle BSP.

Ticket : #2891
Project Proposal : Google Doc
RTEMS Wiki : Wiki
Github Repo : rtems-libbsd | rtems-docs

Phase One

Phase one of the project is to add support for CDC Ethernet and documenting the driver. The CDC Ethernet USB device template is ported from FreeBSD to LibBSD. The ucom, cdce and other modules required for the CDC Ethernet were already ported to LibBSD. Phase one was completed as planned.

Driver

Commit 1 : Import USB Device Driver & CDC Ethernet Template
Commit 2 : Configure
Commit 3 : Create the Module and Add it to the Buildset
Commit 4 : Enable the Module in Beagle

The patches were tested against both the master and 6-freebsd-12 branches. The patches are verified by the mentors and the other project maintainers and they are ready to be committed. But my commits are not applied yet due to some other commits in the review stage which is better to be applied before my commits to avoid merge conflicts. Phase one pathces will be committed soon as it’s done.

I have explained each of these commit in another post.

Documentation

Commit 1: LibBSD Quick Start Guide
Commit 2: Index page for LibBSD
Commit 3: Configuration and Waf script for the LibBSD
Commit 4: Enable LibBSD Doc Build
Commit 3: USB Template Driver

To get an idea of the performance of the driver see this. I hope to add a TTCP benchmarking of the CDCE later here.

NOTE: These patches are not commited. The LibBSD is documented in the rtems-libbsd repository as README and text files but it isn’t documented under the RTEMS Documentation Project. There is a discussion about how and where to document the LibBSD library.

Phase Two

Phase two didn’t go as smooth as expected. The plan for the phase two was to add CDC ACM and CDC MSC device support. However I was only able to get the CDC ACM up and running partially.

I’ll explain the steps I took till the end of the phase two and the blockers encountered.

Commit 1: Import CDC ACM Template
Commit 2: Include template to be initialized
Commit 3: Configure Beagle Nexus Bus for CDC ACM
Commit 4: Add CDC ACM template to libbsd.py

Note: These changes are only in my Github branch.

I used the media01 testsuite to debug the driver. See this commit to get the modified code. Read the JTAG Debugging Setup For Beaglebone Black post to setup the hardware debugging Environment.

After thesee commits the host detects a CDC ACM device and a device file (ttyACM0) is created.

dmesg

In the device side cuaU0(Call-out port) and ttyU0(Call-in port) devices with their respective lock (the configurations which shouldn’t be modified by other programs or users are defined here in FreeBSD) and init (initialization configuration file for the terminal here in FreeBSD) files are created.

rtems-devices

First thing I tried is running a cat command on ttyU0 and wrote some characters to the ttyACM0 device from the host. The RTEMS didn’t print any data in it’s shell but it echoed back the data to the host.

Then instead of a cat we tried to attach a shell to the ttyU0 terminal. When we tried to open the device, the open function didn’t return. While looking through the debugger it seems to be waiting for the tty_wait function to return. The tty_wait didn’t return because it was waiting for a DCD (Data Carrier Detect) signal in tty.c:356.

After some reading I found that the call-in ports (ttyU*) are used for terminals. Call-in ports require the “Data Carrier Detect” signal to work correctly. The call-out ports (cuaU*) are usually not used for terminals, but are used for modems. The call-out port can be used if the serial cable or the terminal does not support the “Data Carrier Detect” signal.[1]

I ran the cat command on the cuaU0 through the console shell. Now when I write from the host, I can see the characters in RTEMS shell. We can attach a shell as well. The CDC ACM is few configurations away from being complete. Next step is to find out how to access the shell from the host.

Resource which might be useful to dig more into the driver:
Implementing USB communication device class (CDC) on EFM32GG MCUs

Acknowledgement

I would like to thank my mentors Christian Mauderer and Vijay Kumar Banerjee for encouraging and guiding me throughout the project.

Also thanks to the RTEMS community for giving me this amazing oppurtunity. I learned a lot from the community and it really motivated me to engage more with open source projects.

Special thanks to:
Dr Chandana Gamage
Ishan Somasiri
Thakee Nathees

What’s next?

I’m interested in contributing more to the RTMES and other opensource projects. I’ll continue to contribute after the GSoC ends, specially to the Beagle BSP. There is always something new to learn from an opensource from which I’ll improve my knowledge and skills.