BeagleBoard/GSoC/2023 Proposal/BeagleBone Cape add-on board compatibility layer

Cape Compatibility layer for BeagleBone Black, AI, AI-64, PocketBeagle and BeaglePlay

Student: | LIM SOON WEI
Mentors: Deepak Khatri (lorforlinux)
Proposal: https://elinux.org/BeagleBoard/GSoC/2023_Proposal/BeagleBone_Cape_add-on_board_compatibility_layer

Status

This project is currently just a proposal.

Proposal

Completed all the requirements listed on the ideas page. the code for the cross-compilation task can be found here submitted through the pull request #178.

About you

Github: limsoonweiutm
School: University of Technology Malaysia
Country: Malaysia
Primary language: English, Chinese
Typical work hours: 7PM - 11PM(Weekdays) & 9AM - 6PM(Weekends) Malaysia Standard Time UTC +8
Previous GSoC participation: This is my first time attending GSoC.
Reason for participation: I am very interested in the learning new things in using Linux OS and device tree is new to me which will be fun learning how to construct device tree and add to the board to supports the cape and clickboards. Therefore, I would like to be involved in updating the cape compatibility layer for BeaglePocket Cape, which are Tech Lape Cape and GamePup Cape. In addition, for the clickboards compatibility parts will be updated on BeaglePlay with Interface category such as PWM, CAN, I2C, etc.

About your project

Project name: Cape Compatibility layer for BeagleBone Black, AI, AI-64, PocketBeagle and BeaglePlay

Description

This project include enabling the overlay compatibility and support for the board BeagleBone Black, AI, AI-64 under kernel v5.10 and implement device tree overlays for PocketBeagle's capes which are Tech Lape Cape and GamePup Cape while for BeaglePlay, the clickboards compatibility parts will be updated with Interface category such as PWM, CAN, I2C, etc and other Categories such as Wireless Connectivity, Sensors, etc.

Enabling overlay compatibility:

BeagleBone boards utilize U-Boot as their Tertiary Program Loader (TPL) to load the Linux kernel, Flattened Device Tree (FDT), and Initial Ram File System (initramfs) into DRAM. U-Boot is responsible for managing boot time MUX_MODE for the GPIOs, symlinks for peripherals, and other hardware-specific configurations by loading particular FDT. By updating the FDT for the hardware we want to support, we can regulate the configuration(s). Boot-time device tree overlays can enable device compatibility, such as Cape compatibility, which can be found in most capes from the bb.org-overlays repository. Achieving cape compatibility will require creating device tree overlays and loading them at boot time. To load the necessary driver for the hardware at boot time, the uEnv.txt file must be edited. Required overlays can be exported at boot time, and the hardware will be compatible immediately upon board boot. Most capes utilize EEPROM to store CAPE-related hardware information, and individual pin configuration details can be extracted from the EEPROM, making it simpler to manage.

Previous Work

Deepak Khatri has developed a method to enable P8 and P9 connectors on the BeagleBone AI (am572x) with the same pin assignments as the BeagleBone Black (am335x). This involves three steps: creating a symlink in the device tree of the AI that corresponds to other BeagleBones, using this symlink in udev rules to create the symbolic link, and configuring the pinmux to adjust the behavior of peripherals depending on the application. A universal device tree overlay is utilized to select the appropriate peripheral from multiple choices in the pinmux, and the user can choose the desired peripheral for each Cape by changing the device tree overlay used.

Problems and Solutions

The current implementation is facing some problems as mentioned below, but this proposal aims to resolve these issues.

Port Over Supports on BeagleBone Black, BeagleBone AI and BeagleBone AI-64 under kernel v5.10.

The current device tree overlay is designed for kernel v4.19 and needs to be adapted for the most recent kernel version. In general, the current code can be used as is in the new kernel, but some modifications may be necessary. For instance, memory addresses in the device tree may have changed due to updates, which could result in conflicts with the existing code. Therefore, it is crucial to compile and test the code with the new kernel version to ensure compatibility. The proposed work will primarily focus on porting the code to v5.10, which is the latest stable kernel. If any missing device trees are required, they will be obtained from the older v4.19 kernel after verification.

Prerequisite Knowledge

Device Tree and Device Tree Overlay

A device tree overlay is a configuration file that describes additional hardware devices and their respective configurations to be added to the base device tree during runtime. For BeagleBone boards such as the BeagleBone Black, BeagleBone AI, BeagleBone AI-64, PocketBeagle, and BeaglePlay, device tree overlays are commonly used to add support for new hardware components and interfaces that are not included in the default device tree.

To create a device tree overlay for a BeagleBone board, we first need to define the hardware device or interface we want to add. This can include, for example, an I2C device, a PWM output, or a custom cape with specific pin configurations.

Once we have defined the hardware device or interface, we can create the device tree overlay file in the following format:

/dts-v1/;
/plugin/;
/ {
   compatible = "ti,beaglebone", "ti,beaglebone-black";
   fragment@0 {
       target = <&am33xx_pinmux>;
       __overlay__ {
           /* Define pin configuration for new device */
       };
   };
   fragment@1 {
       target = <&ocp>;
       __overlay__ {
           /* Define device configuration and properties */
       };
   };
};

In this example, the device tree overlay defines two fragments that modify the base device tree for the BeagleBone board. The first fragment targets the am33xx_pinmux node, which controls the pinmuxing and configuration of the pins on the board. Here, we can define the pin configuration for the new hardware device or interface we want to add.

The second fragment targets the ocp node, which represents the onboard parallel port, and can be used to add new devices to the board. Here, we can define the configuration and properties for the new device or interface we want to add.

Once we have defined the device tree overlay, we can compile and load it into the kernel at runtime using the dtc and dtoverlay commands. This will add the new hardware device or interface to the base device tree, and it will be available for use immediately.

Overall, device tree overlays are a powerful tool for extending the functionality of BeagleBone boards, and can be used to add support for a wide range of new hardware devices and interfaces.

Hardware Required:

1. BeagleBone Black
2. BeagleBone AI-64
3. BeaglePlay
   1. clickboards
      1. mikroBus cape
      2. WiFi Click
      3. CAN
      4. SPI
      5. ADC-DAC
      6. OLED
      7. SpeakUp Click
4. PocketBeagle
   1. PocketBeagle TechLab Cape
   2. PocketBeagle GamePup Cape

Timeline

April 4	Proposal Deadline	Finish everything on proposal including taking ideas and suggestions from mentors in Slack gsoc before the due date.
April 5	Pre-work	Squeeze out extra time to learn on existing Enabling Compatibility Layer, Port over and make changes to new kernel version supports, Boards pins and documentations, device tree overlays and source coding of Beagle Boards
May 4	Pre-work2	Community Bonding Period and discussion on the project and resources available. GSoC contributors get to know mentors, read documentation, get up to speed to begin working on their projects Request Hardware as some are stated above on "Hardware Required" Hardware Setup Interaction with Capes and Boards source code especially on device tree overlays
May 29	Pre-work complete	Coding officially begins! All the boards and additional hardware will be available to me at this period of time and I should have set up my BeagleBone Black, AI, Play and Pocket boards i.e flashing up to date Linux image and Testing user-led blink code :) Initial checks for hardware like Techlap and Pup Capes and other clickboard devices will be completed and all the soldering related work will be done. Cape pin mapping and referencing for further use of BeaglePlay and PocketBeagle.
June 5	Milestone #1	Introductory YouTube video. To gain further insights into the setup process for the cape's software and hardware, I will be running user space examples and cape examples on the BeagleBone Black. This will enable me to gather additional information that can be referenced in the future. Start with support under kernel v5.10 for BeagleBone Black and AI
June 12	Milestone #2	Continue with support under kernel v5.10 for BeagleBone Black first Testing everything on BeagleBone Black.
June 19	Milestone #3	Continue with support under kernel v5.10 for BeagleBone Black Confirming the compatibility of the header pins between the BeagleBone AI and BeagleBone Black, and conducting additional tests on the submitted code to ensure its functionality on both the BeagleBone AI and BeagleBone AI-64.
June 26	Milestone #4	Testing the pin control using libgpiod. Running already available examples that demonstrate the proper working of pin control using libgpiod. Finalizing everything done till now and submitting the Phase 1 report for evaluation.
July 3	Milestone #5	Continue with support under kernel v5.10 for BeagleBone AI. Testing user space examples with BeagleBone AI. Taking notes and feedback from my mentor on the quality of code.
July 10	Milestone #6 Submitting Midterm Evaluation	Continue with support under kernel v5.10 for BeagleBone AI-64. Testing user space examples with BeagleBone AI-64.
July 17	Milestone #7 Mentors Guidance Project	Initial setup for using capes with BeagleBone AI and BeagleBone AI-64. Everything will be already available to me as the process is already complete for BeagleBone Black. Making the required fixes for running the userspace examples on BeagleBone AI. Testing Capes.
July 24	Milestone #8	Finalizing the device tree code and driver code under kernel v5.10. Testing Cape on BeagleBone AI and BeagleBone AI-64 using newly created device tree
July 31	Milestone #9	Fixing the code and making required changes for cape compatibility.
August 7	Milestone #10	Finished all the capes tested and fixed all bugs for BeagleBone Black, AI and AI-64 device tree code
August 14	Milestone #11	Proceed with PocketBeagle with new Capes Write new overlay according to PocketBeagle pin headers by referring to am355xx
August 21	Milestone #12	Completion YouTube video
August 21 - 28 18:00 UTC	Final week	Final week: GSoC contributors submit their final work product and their final mentor evaluation (standard coding period)
August 28 - September 4 18:00 UTC	Mentors submit final GSoC contributor evaluations (standard coding period)

Experience and approach

I have strong understanding and high grade on my C, C++ and python programming language. Finished my internship with Intel during second year(Extra) and third year(official) of my study. Currently, I also take Intel DV engineer job as my part time in order to learn more and sharpening my skill alongside to compete the position in Singapore in the future. As a Design Verification(DV) engineer I did a lot of scripting especially to automate the test processes using Python Scripting and Linux OS/Env has been very familiar to me. In addition, C++ is my future career path skill where I picked up since second year of my study, mostly mastered in OOP so I could venture into Embedded Software Programming Engineer Fresh Graduate position in Singapore. Going through a lot of mock interviews and problem questions by solving them using C++. Lastly, I also received award from my school of Electrical Engineering for being the best of track in Electrical Educational Theme where our team uses C to program Arduino and lead to the best of track.

Contingency

I believe that if I get stuck on my project and my mentor isn’t around, I will use the resources that are available to me. Some of those information portals are listed below.

1. Derek Molly's beagle bone guide provides all the information needed for getting up and running with my beagle.
2. Content on e-ALE.org is very useful for information that ranges from tutorials and walkthroughs to the level of very advanced stuff.
3. BeagleBone cookbook from Mark A. Yoder & Jason Kridner is the best source for test projects during the prototyping period.
4. The technical reference manuals provided by TI on am3358 and am5729 are the best source for getting the insights on the SoC used in Black and Ai.
5. Deepak Khatri (lorforlinux) source code on 2020 Beaglebone Cape Compatibility
6. Utilize technology nowadays such as ChatGPT

Benefit

I believe that the project is very important as:
# the adoption of the device tree
# support for BeagleBone Black, BeagleBone AI under kernel-64 
# execution of same user space examples 
# support for PocketBeagle Capes
# support for BeaglePlay clickboards