Getting Started Resources for Software Development On the OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

This application note provides useful resources for getting started with software

development when using the OSD335x, the AM335x System in Package, Family of

Devices.

The resources for software development on the AM335x System in Package OSD335x

application note walks through an overview of the available development platforms

and tools available to develop target applications as well as popular embedded Linux

build systems. All these components make it easier to develop AM335x software on

any OSD335x System in Package based product.

Notice: The information provided within this document is for informational use

only. Octavo Systems provides no guarantees or warranty to the information

contained.

2

Getting Started Resources for Software Development On the OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

Table of Contents

1 Introduction .................................................................................. 3

2 Developing AM335x Software for an OSD335x Prototype ........................... 4

2.1 Development Boards ............................................................................ 4 2.2 Understanding Boot ............................................................................. 5

2.2.1 U-Boot ......................................................................................... 6 2.2.2 U-Boot Customization through Board ID .................................................. 7 2.2.3 U-Boot Environment Customization through uEnv.txt .................................. 7 2.2.4 Hardware Configuration with Device Trees and Device Tree Overlays ............... 9 2.2.5 Linux Kernel ................................................................................. 10 2.2.6 Useful Software and Utilities .............................................................. 10

3 Linux Customization ....................................................................... 12

3.1 Yocto Project .................................................................................... 12 3.2 Buildroot.......................................................................................... 13

4 Conclusion ................................................................................... 14

5 Revision History ............................................................................. 14

3 Getting started Resources for Software Development On The OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

1 Introduction

Software development is crucial to turn an embedded system into a product. Because

embedded systems have limited hardware resources, software and software

optimization is key to implementing the necessary product requirements. In general,

software will require a significant investment of time and resources. Therefore,

saving time and resources on software development will create a significant

advantage for development schedule and cost of the product.

To provide a little context, the following figure shows the anatomy of a Linux based

Embedded System. The application is the piece of software that performs the

functions that the embedded system is designed to implement. In performing these

functions, the application can make use of system programs that are available as part

of a standard or customized Linux based operating system. The system programs and

the application interface with the kernel through the System Call Interface. The Linux

kernel is the core component of the operating system that performs critical tasks such

as scheduling and memory management. The kernel interacts with the hardware

through either built-in or loaded kernel modules. Finally, the bootloader is a small

piece of software that is responsible for hardware initialization and loading of the

Linux kernel into RAM.

4

Getting Started Resources for Software Development On the OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

This application note provides our applications engineers’ go-to references giving you

a head start when developing AM335x software for the OSD335x, the AM335x System

in Package, Family of Devices.

The application note is divided into 2 parts: Part 1 deals with software development

for a prototype based on OSD335x, a AM335x system in package; Part 2 discusses

Linux customization for production.

2 Developing AM335x Software for an OSD335x Prototype

When developing a prototype, it is useful to understand: 1) What development boards

are available? 2) What are hardware and software initialization steps that occur

before my application can run? This section will cover useful information to

understand when developing the AM335x software within an OSD335x Prototype.

2.1 Development Boards

There are several options available for developing an OSD335x prototype. While this

list is not exhaustive, these open hardware reference can help you get started

developing on the the OSD335x, the AM335x System in Package, Family of Devices.

1. Octavo Systems OSD335x-SM RED

Reference, Evaluation, Development Board for the OSD335x Families of SiP

Products:

https://octavosystems.com/octavo_products/osd3358-sm-red/

• Hardware Design Files:

i. OSD335x-SM:

https://octavosystems.com/files/osd3358-sm-red-eagle-files/

ii. OSD335x C-SiP:

https://octavosystems.com/files/osd3358-sm-red-c-sip-eagle-files/

• Features:

i. Comm: 10/100/1000 Ethernet, 4x USB Host, USB client

ii. Video: HDMI

iii. Sensors: 9-axis IMU, Barometer, Temperature Hub

iv. Storage: 16 GB eMMC; microSD card slot

v. Security: TPM + Secure NOR Flash

vi. Expansion: Headers provide access to a number of other

peripherals

• Support:

i. Forums:

5 Getting started Resources for Software Development On The OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

https://octavosystems.com/forums/forum/reference-evaluation-

development-boards/osd3358-sm-red/

ii. Application notes:

https://octavosystems.com/app_notes/#OSD3358-SM-RED

2. BeagleBoard.org® Single Board Computers

BeagleBoard.org®, a customer of Octavo Systems, has several Single Board Computers (SBC) boards that are excellent examples of using the OSD335x SiP in a design. The BeagleBoard.org® Foundation is a 501(3)c non-profit focused on education in and collaboration around the design and use of open-source software and hardware in embedded computing. BeagleBoard.org® has developed a strong and vibrant community around their families of boards. More information about the BeagleBoard.org® Single Board Computers built using OSD335x Based System in Package is located HERE.

2.2 Understanding Boot

There are many components in the boot process that are important to understand in

order to develop an embedded system. By understanding the Linux boot process,

changes and optimizations can be made as needed. The following resources provide a

good overview of the hardware initialization and Linux boot process:

1. Linux boot process with OSD335x from Octavo Systems Applications Notes:

https://octavosystems.com/app_notes/osd335x-design-tutorial/osd335x-lesson-2-

minimal-linux-boot/osd335x-lesson-2-linux-boot-process-with-the-osd335x/

2. Boot process for the AM335x from BeyondLogic.org, a learning resource:

https://wiki.beyondlogic.org/index.php/BeagleBoneBlack_Boot_Process

3. ‘Chapter 26: Initialization’ in AM335x Technical Reference Manual from Texas

Instruments:

http://www.ti.com/lit/spruh73

4. Embedded Linux booting process video tutorial from Pentester Academy

TV(YouTube):

https://www.youtube.com/watch?v=DV5S_ZSdK0s

This document will discuss and provide additional resources for a few key components

within the boot process: U-Boot; U-Boot Customization through Board ID; U-Boot

Environment Customization through uEnv.txt; Hardware Configuration with Device

Trees and Device Tree Overlays; Linux Kernel; and Useful Software and Utilities.

6

Getting Started Resources for Software Development On the OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

2.2.1 U-Boot

U-Boot (Universal Booth Loader), or Das U-Boot, is a popular open-source bootloader

for devices running embedded Linux. Its main function is to initialize hardware

(clocks, DDR, peripherals, boot sources, etc.), load the Linux kernel into memory, and

begin executing the Linux kernel. U-Boot is a popular choice for a bootloader because

it offers a variety of features like editable config files, ability to communicate with a

wide range of boot sources it’s shell like environment. For the OSD335x, the AM335x

System in Package, Family of Devices, U-Boot is a third stage bootloader and is

executed after the internal ROM code and the external SPL (Secondary Program

Loader).

In most cases, there is no need to modify U-Boot. However, there are several build

configurations available in the /configs/ directory that can enable different boot

sources and peripherals. Additionally, U-Boot can execute custom scripts that can be

programmed into environmental variables which can be saved and made persistent

between boots.

If more customization is needed, the U-Boot source code can be modified and the

bootloader rebuilt. Below is a list of folders within the U-Boot source code that

contain files that are specific to OSD335x/AM335x and can be modified to change the

bootloader behavior:

- u-boot/board/ti/am335x: Contains AM335x board specific files

- u-boot/configs: Contains configuration files (defconfig) for boards/settings

- u-boot/arch/arm/mach-omap2: Contains AM335x initialization code

- u-boot/include/configs: Contains AM335x configuration header files

The following references are helpful when working with U-Boot for the OSD335x

Family of devices:

1. U-Boot documentation maintained by DENX Software Engineering training

courses:

http://www.denx.de/wiki/U-Boot/Documentation

2. U-Boot source code:

https://github.com/u-boot/u-boot

3. Training session on U-Boot for the AM335x from Embedded Apprentice Linux

Engineer (E-ALE) Training Series:

https://e-ale.org/seminar/introduction-to-the-u-boot-bootloader-3/

4. Building U-Boot Materials from Digikey

https://www.digikey.com/eewiki/display/linuxonarm/BeagleBone+Black

7 Getting started Resources for Software Development On The OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

2.2.2 U-Boot Customization through Board ID

Using a Board ID stored in an inexpensive non-volatile storage device like an EEPROM

is a way for software to identify a particular embedded system or individual device.

The Linux images from BeagleBoard.org® that can be used on the OSD335x Family of

devices identify designs from a Board ID stored within an EEPROM attached to the

I2C0 bus. This board ID is used within U-Boot to configure the system during boot.

The OSD335x EEPROM During Boot application note

(https://octavosystems.com/app_notes/osd335x-eeprom-during-boot/) can help to

understand the role a board ID can play in the board boot process and how it can be

provisioned for a custom board

2.2.3 U-Boot Environment Customization through uEnv.txt

U-Boot environment variables can be set from an external file which is read and

loaded during boot. For the Linux images from BeagleBoard.org® that can be used on

the OSD335x Family of devices, this file is /boot/uEnv.txt. This file can be accessed

and modified from the standard Linux file system as superuser. An example of this file

is given below:

8

Getting Started Resources for Software Development On the OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

#Docs: http://elinux.org/Beagleboard:U-boot_partitioning_layout_2.0

uname_r=4.9.45-ti-r57

#uuid=

dtb=osd3358-bsm-refdesign.dtb

###U-Boot Overlays###

###Documentation: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian#U-Boot_Overlays

###Master Enable

enable_uboot_overlays=1

###

###Overide capes with eeprom

uboot_overlay_addr0=/lib/firmware/BB-SPIDEV0-00A0.dtbo

#uboot_overlay_addr1=/lib/firmware/<file1>.dtbo

#uboot_overlay_addr2=/lib/firmware/<file2>.dtbo

#uboot_overlay_addr3=/lib/firmware/<file3>.dtbo

###

###Additional custom capes

#uboot_overlay_addr4=/lib/firmware/<file4>.dtbo

#uboot_overlay_addr5=/lib/firmware/<file5>.dtbo

#uboot_overlay_addr6=/lib/firmware/<file6>.dtbo

#uboot_overlay_addr7=/lib/firmware/<file7>.dtbo

###

###Custom Cape

#dtb_overlay=/lib/firmware/<file8>.dtbo

###

###Cape Universal Enable

enable_uboot_cape_universal=1

###

###Debug: disable uboot autoload of Cape

#disable_uboot_overlay_addr0=1

#disable_uboot_overlay_addr1=1

#disable_uboot_overlay_addr2=1

#disable_uboot_overlay_addr3=1

###

###U-Boot fdt tweaks...

#uboot_fdt_buffer=0x60000

###U-Boot Overlays###

cmdline=coherent_pool=1M net.ifnames=0 quiet

#In the event of edid real failures, uncomment this next line:

#cmdline=coherent_pool=1M net.ifnames=0 quiet video=HDMI-A-1:1024x768@60e

##Example v3.8.x

#cape_disable=capemgr.disable_partno=

#cape_enable=capemgr.enable_partno=

##Example v4.1.x

#cape_disable=bone_capemgr.disable_partno=

#cape_enable=bone_capemgr.enable_partno=

##enable Generic eMMC Flasher:

##make sure, these tools are installed: dosfstools rsync

#cmdline=init=/opt/scripts/tools/eMMC/init-eMMC-flasher-v3.sh

9 Getting started Resources for Software Development On The OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

This file can be modified to change different aspects of the board boot process. For

example, the environment variable ‘dtb’ can be used to set the name of the device

tree binary that will be used to configure hardware drivers loaded by Linux. This

makes it easy to use a custom device tree.

The Linux images from BeagleBoard.org® that can be used on the OSD335x Family of

devices can also use Device Tree Overlays to configure hardware drivers loaded by

Linux. These overlays can be set in uEnv.txt by modifying a ‘uboot_overlay_addrX’

variable, where X can be 0 to 7. The ‘enable_uboot_overlays’ variable needs to be set

to ‘1’ to enable the use of Device Tree overlays.

Additionally, the environment variable ‘cmdline’ can be used to set the options used

to boot the Linux kernel. Some examples of changes to the ‘cmdline’ variable can be

seen in comments in the above file.

2.2.4 Hardware Configuration with Device Trees and Device Tree Overlays

In embedded systems, peripherals can be connected to the main processor with

busses like I2C, SPI, and UART, which do not support enumeration. Therefore, when

an embedded system uses an operating system, such as Linux, it is necessary to

convey the hardware configuration of the system, i.e. all the information about the

connected peripherals, to the OS in a standard form. The most common way to do this

in Linux is to use a Device Tree or Device Tree Overlay. A Device Tree is a data

structure that describes the hardware configuration of the system to the Linux

operating system. During boot, the Linux kernel will use the information in the Device

Tree to recognize, load appropriate drivers and manage the hardware devices in the

system.

The following resources can be used to understand Device Trees, Device Tree

Overlays, and how to build custom Device Trees for OSD335x based platforms:

1. OSD335x Lesson 2: Linux Device Tree:

https://octavosystems.com/app_notes/osd335x-design-tutorial/osd335x-lesson-2-

minimal-linux-boot/linux-device-tree/

2. OSD335x Lesson 2: Linux Device Tree Overlay:

https://octavosystems.com/app_notes/osd335x-design-tutorial/osd335x-lesson-2-

minimal-linux-boot/linux-device-tree-overlay/

3. OSD335x Device Tree source Github Repository:

https://github.com/octavosystems/OSD335x-Device-Tree

4. Device tree rebuilder:

https://github.com/RobertCNelson/dtb-rebuilder

10

Getting Started Resources for Software Development On the OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

5. Device Tree for Dummies:

https://events.static.linuxfound.org/sites/events/files/slides/petazzoni-device-tree-

dummies.pdf

In order to utilize peripherals within the OSD335x Family of devices, the pin

multiplexing must be properly configured in the Device Tree or Device Tree Overlay.

To better understand the pin multiplexing of the OSD335x Family of devices, the

PinMux for OSD335x Family and AM335x SoC application note can be used

(https://octavosystems.com/app_notes/osd335x_pinmux/).

2.2.5 Linux Kernel

Developing an embedded application in Linux can require an understanding of how the

kernel functions as well as the different capabilities it provides. Specifically, it is

important to understand: the Linux privilege / security model (i.e. how kernel and

user space are separated), Linux system services and process management, the Linux

file system, and Linux driver management (i.e. loading and unloading kernel modules)

and development to create an application. In addition, familiarity with command line

utilities is useful. The following references are not exhaustive but can help

understand and utilize the Linux kernel and its capabilities to create embedded

system applications:

1. How Linux Works, 2nd Edition: What Every Superuser Should Know Second

Edition, by Brian Ward: https://www.amazon.com/gp/product/1593275676/

2. Exploring BeagleBone®: Tools and Techniques for Building with Embedded

Linux 2nd Edition by Derek Molloy: https://www.amazon.com/Exploring-

BeagleBone-Techniques-Building-Embedded/dp/1119533163

3. Linux Driver Development for Embedded Processors - Second Edition: Learn to

develop Linux embedded drivers with kernel 4.9 LTS by Alberto Liberal de los

Rios: https://www.amazon.com/gp/product/1729321828/

2.2.6 Useful Software and Utilities

We encourage customers designing with the OSD335x family of devices to look at the

open-source software provided by BeagleBoard.org® as a starting point for their

systems. You’ll find useful software and helpful utilities that make tasks easier.

Below are references to resources that can help with application development:

1. Kernel Repository:

https://github.com/beagleboard/linux

2. Image Builder:

https://github.com/RobertCNelson/omap-image-builder

3. Java Script Examples on Cloud9:

https://github.com/beagleboard/cloud9-examples

11 Getting started Resources for Software Development On The OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

4. Bone101:

http://beagleboard.org/Support/bone101/

5. Getting Started:

https://beagleboard.org/getting-started

6. PRU Cook-Book:

https://github.com/beagleboard/PRUCookbook

7. Robot Control Library:

https://github.com/StrawsonDesign/librobotcontrol

8. Adafruit BBIO Python Library:

https://github.com/adafruit/adafruit-beaglebone-io-python

9. Useful tools and scripts:

https://github.com/RobertCNelson/boot-scripts

One of the useful boot scripts is the ‘init-eMMC-flasher-v3.sh’ shell script. It is used

to transfer the contents of MMC0 to MMC1. In many designs, MMC0 is used to interface

with an microSD card while MMC1 is used to interface with an eMMC which provides

non-volatile storage for the embedded system. Hence, this script can be used to

initialize or re-program the contents on the eMMC using the microSD card. This script

can be executed as part of the ‘uEnv.txt’ file as seen in the example file above.

12

Getting Started Resources for Software Development On the OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

3 Linux Customization

Every embedded system that runs Linux can have its own kernel configuration, device

tree, and customized root file system, known as a distribution. This level of

customization is extremely useful to optimize the boot time and code size of Linux for

a given embedded system. However, building all the components and including all the

required software packages can be a daunting task and can take a lot of time. In

order to tackle this problem, several open-source build systems have been developed.

The most prominent build systems are Yocto and Buildroot.

3.1 Yocto Project

The Yocto Project is a commonly used embedded Linux build system for a large

selection of target architectures and processors. It provides a ‘flexible toolset and

development environment that allows embedded device developers across the world

to collaborate through shared technologies, software stacks, configurations, and best

practices used to create these tailored Linux images’.

The following figure (from https://www.yoctoproject.org/software-overview/) shows the

components of the tool and the general workflow:

Figure 1: Components and workflow of the Yocto Project

13 Getting started Resources for Software Development On The OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

The Yocto Project has the following advantages:

1. Complete control of the distribution

2. Modular approach to the build process

3. Flexible image size

4. Comprehensive toolchain capabilities

5. Manages licenses for all the components of the image

The following references can help get started with Yocto Project for an OSD335x

based embedded system:

1. Yocto Project mega manual (comprehensive):

https://www.yoctoproject.org/docs/current/mega-manual/mega-manual.html

2. Yocto Project and OpenEmbedded Training from Bootlin:

https://bootlin.com/doc/training/yocto/yocto-slides.pdf

3. Labs for Yocto Project training from Bootlin:

https://bootlin.com/doc/training/yocto/yocto-labs.pdf

4. Meeting Yocto Project:

https://hacklabalmeria.net/recursos/2015-06-12/YPRealtrack.pdf

5. Getting started with Yocto Project from Yocto Project:

https://www.youtube.com/watch?v=zNLYanJAQ3s

6. Yocto Project overview from Mentor Embedded:

https://www.youtube.com/watch?v=AmsG18EyDY4

3.2 Buildroot

Buildroot is another popular embedded Linux build system that is said to be “a simple,

efficient and easy-to-use tool to generate embedded Linux systems through cross-

compilation”. In contrast to the Yocto Project, it is a kernel-like build experience

that does not take a long time to configure and generate images.

Buildroot has the following advantages:

1. Simple, easy to use

2. Produces small images suited for resource limited applications

3. Supports several thousand packages which are presented as options in the build

process

The following references can help get started with Buildroot for an OSD335x based

embedded system:

1. Buildroot user manual:

https://buildroot.org/downloads/manual/manual.pdf

2. Embedded Linux development with Buildroot Training from Boolin:

14

Getting Started Resources for Software Development On the OSD335x

Rev.1 6/19/2019

Octavo Systems LLC Copyright 2018

https://bootlin.com/training/buildroot/

3. Getting started with Buildroot (E-ale training including video, slides and lab

materials):

https://e-ale.org/seminar/getting-started-with-buildroot/

4 Conclusion

The topics and references provided in this document provide good starting point for

developing AM335x software for OSD335x based embedded systems. With the number

of resources available, using OSD335x to build a Linux-ready embedded system will

shorten your time to production. Please contact the team at Octavo Systems on the

forum to assist.

5 Revision History

Revision Number Revision Date Changes Author

1 6/19/2019 Initial Release Neeraj Dantu