3.4.2.3. RPMsg Quick Start Guide¶

3.4.2.3.1. Introduction¶

RPMsg is a method of passing messages and data between the PRU cores and the ARM core running Linux. RPMsg is enabled by a combination of remoteproc and the virtio framework. For more information about remoteproc, reference RemoteProc. For more information abour RPMsg, reference RPMsg.

This Quick Start Guide will walk you through every step necessary to run your first RPMsg example, from downloading the Linux Processor SDK, all the way up to communicating with the PRUs from user space.

If you are familiar with the Linux Processor SDK from Texas Instruments then portions of this guide will seem elementary or possibly redundant. If this is the case, feel free to skip over the early sections and get directly to the RPMsg parts. The intent of this guide is to provide a single straight through process to run an RPMsg example and then show where to modify and rebuild code in order to start PRU/RPMsg development.

If you have any questions or corrections while going through this guide please post them on the E2E Forum here.

3.4.2.3.2. Getting the Linux Processor SDK¶

The first step is to download and install the Linux Processor SDK onto your host computer that is running Ubuntu Linux.

1. Download the SDK that corresponds to the evaluation board that you have

   • Linux Processor SDK for AM335x
   • Linux Processor SDK for AM437x
   • Linux Processor SDK for AM572x
   • Linux Processor SDK for AM65x
   • Linux Processor SDK for K2G

   You only need to download the ti-processor-sdk-linux-<DEV>-evm-<VERSION>-Linux-x86-Install.bin file from this page

2. Navigate to the newly downloaded bin file and make it executable

   • cd path/to/downloaded/SDK/bin/file/
   • chmod +x ti-processor-sdk-linux-<DEV>-evm-<VERSION>-Linux-x86-Install.bin

3. Launch the installer

   • ./ti-processor-sdk-linux-<DEV>-evm-<VERSION>-Linux-x86-Install.bin

4. Follow the steps in the installer to complete the installation

   • The remainder of this guide assumes that the default installation directory was selected - /home/user/ti-processor-sdk-linux-<DEV>-evm-<VERSION>/

You now have the Linux Processor SDK installed on your Linux host computer. This version of the SDK includes the PRU Software Support Package in the ‘example-applications/pru-icss-x.y.z’ folder. This software support package includes examples, libraries, and PRU Hands-on Labs to help you get started with your PRU development process. This guide will use one of the PRU RPMsg examples included in that software support package.

3.4.2.3.3. Configuring and Building the Linux Kernel with RPMsg Support¶

The Linux kernel config that ships with this version of the Linux Processor SDK already has RPMsg module support enabled. The rest of this section is to show how/where to enable/disable the modules using menuconfig and how to rebuild the modules and kernel if you would like to make any changes to the modules, kernel, or device tree.

In the interest of simplicity, this guide will follow the full procedure found in the Linux SDK Kernel Users Guide even though some of these steps may not be absolutely necessary for our purposes.

1. Navigate to the Linux kernel source directory in the Linux Processor SDK that we previously installed (this guide assumes the default installation directory was chosen)

   • cd /home/user/ti-processor-sdk-linux-<DEV>-evm-<VERSION>/board-support/linux-x.x.x+gitAUTOINC+YYY-ZZZ/

2. Place the cross-compiler toolchain in your PATH environment variable

   export PATH=/home/user/ti-processor-sdk-linux-<DEV>-evm-<VERSION>/linux-devkit/sysroots/x86_64-arago-linux/usr/bin:$PATH
   

3. Clean the kernel sources

   • make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- distclean

4. Set the kernel configuration to the default configuration included in the Processor SDK for the device you are using

   • make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- tisdk_<DEV>-evm_defconfig

5. Enable RPMsg support using menuconfig

   1. make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- menuconfig

   2. Type ‘m’ next to the following two configurations to build them as kernel modules (beginning with Linux Processor SDK v02.00.02.11 these modules will be enabled by default)

      • Device Drivers > Remoteproc Drivers > TI PRUSS remoteproc support
      • Device Drivers > Rpmsg drivers > PRU RPMsg Communication driver

      If you type ‘y’ instead of ‘m’ next to these modules then your board will pause for a long time during the boot procedure and the PRU loading process will fail

   3. Save the configuration and exit menuconfig

6. Build the Linux kernel

   • make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- zImage

7. Build the device tree binary file

   • make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- am335x-boneblack.dtb

   Example .dtb name given above is for the BeagleBone Black. To find the .dtb name for a different board use the list found at :ref:`kernel_users_guide_compiling_the_device_tree_binaries`.

8. Build the modules

   • make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- modules

3.4.2.3.4. Creating a Bootable SD Card with RPMsg Support¶

This section of the guide will walk you through using a script that is included in the Linux Processor SDK. This script will format your micro SD card and load the default images for the Linux kernel, device tree, and filesystem. Once we’ve created the default SD card we will overwrite the kernel, device tree, and modules with the newly built versions from the previous section of this guide. At the end of this section we will have a bootable SD card (that includes RPMsg support) that we can plug into a board, turn on power, and get to a Linux login prompt.

1. Plug your micro SD card into your Ubuntu host computer

   • If your computer doesn’t have an SD card reader you will need a USB card reader

2. Change to the ‘bin’ directory in the Processor SDK

   • cd /home/user/ti-processor-sdk-linux-<DEV>-evm-<VERSION>/bin/

3. Run the SD card creation script with sudo rights and enter your password when prompted

   • sudo ./create-sdcard.sh

4. Select the SD card from the list the script provides

   

5. Select that you would like to partition the drive with 2 partitions

6. Once partitioning is completed select ‘y’ and continue with installing the filesystem

7. Now choose ‘1’ to install the pre-built images from the SDK

At this point, we’ve used the SD card creation script to make a bootable SD card with the default, out-of-box, Linux kernel and filesystem as it ships in the Processor SDK. Now we just need to replace the kernel, device tree, and modules on the SD card with the ones that we rebuilt in the previous section. Let’s do that now.

1. The SD card creation script unmounts the SD card when it finishes. Unplug the SD card and then plug it back into your computer to re-mount it. In Ubuntu 14.04 the card auto-mounts the two partitions to the /media/user/boot/ and /media/user/rootfs/ directories.

2. The kernel and device tree file that the board will use to boot is located in the /media/user/rootfs/boot/ directory. If you check that directory now you will see that it is filled with default kernels, default device trees, and symbolic links. To make this guide simple and to also show that we are in fact booting our newly built kernel and device tree, let’s delete everything in this boot directory

   • sudo rm /media/user/rootfs/boot/*

3. Navigate to the Linux kernel source directory

   • cd /home/user/ti-processor-sdk-linux-<DEV>-evm-<VERSION>/board-support/linux-x.y.z+gitAUTOINC+YYY-ZZZ/

4. Copy the new kernel to the SD card

   • sudo cp arch/arm/boot/zImage /media/user/rootfs/boot/

5. Copy the new device tree binary to the SD card

   • sudo cp arch/arm/boot/dts/am335x-boneblack.dtb /media/user/rootfs/boot/

   Once again the example .dtb given above is for the BeagleBone Black. Check :ref:`kernel_users_guide_compiling_the_device_tree_binaries` and use the corresponding name if you are using a different board.

6. Install the newly built modules onto the SD card filesystem

   • sudo make ARCH=arm INSTALL_MOD_PATH=/media/user/rootfs/ modules_install

7. Synchronize the data on the disk with the memory to make sure all of the files have completed copying over to the SD card

   • sync

8. Unmount the two SD card partitions from your Ubuntu host computer

   • sudo umount -f /media/user/rootfs
   • sudo umount -f /media/user/boot

3.4.2.3.5. Booting the Board and Testing RPMsg¶

1. Make sure your board is set up to boot from the SD card

   If your board is not set up to boot from the SD card, follow the instructions on the bottom of this page Board is Not Set Up for SD Card Boot

2. Plug the SD card from the previous step into your evaluation board

3. Plug the serial cable from your evaluation board into your Ubuntu host computer

   • Reference your evaluation board getting started guide to determine which cable you will need and where you will need to plug it into the evaluation board
   • In the case of the BeagleBone Black you will need an FTDI to TTL cable like the one found here

4. Find out which tty device on your Ubuntu host computer corresponds to your evaluation board

   • ls /dev/ | grep ttyUSB*

   Depending on the evaluation board you may need to power the board up before the ttyUSBn device shows up on your Ubuntu computer

5. Use your favorite terminal emulator to connect to your evaluation board (in the example given below I use picocom and my device is on /dev/ttyUSB0)

   • sudo picocom -b 115200 /dev/ttyUSB0

6. Power up your evaluation board

   • Power up method (button press, power source, etc.) will also vary based on which board you are using

7. Wait for the board to complete booting and arrive at the ‘<DEV>-evm login:’ prompt and type ‘root’ to login as root

   • <DEV>-evm login: root

8. Use the remoteproc sysfs interface to specify the firmware name to boot and to start the PRU cores

   • echo ‘am335x-pru0-fw’ > /sys/class/remoteproc/remoteproc1/firmware
   • echo ‘am335x-pru1-fw’ > /sys/class/remoteproc/remoteproc2/firmware
   • echo ‘start’ > /sys/class/remoteproc/remoteproc1/state
   • echo ‘start’ > /sys/class/remoteproc/remoteproc2/state

9. List all of the devices under /dev/ and look for the two rpmsg_pru character devices

   • ls /dev/

   or

   • ls /dev/ | grep pru

10. Write to each of the character devices to test them out

    • echo “test30” > /dev/rpmsg_pru30
    • echo “test31” > /dev/rpmsg_pru31

11. Now read from each of the character devices to make sure that the PRUs echoed the test strings back

    • cat /dev/rpmsg_pru30

    You will need to press ‘Ctrl + c’ to stop reading and close the character device

    • cat /dev/rpmsg_pru31

    You will need to press ‘Ctrl + c’ to stop reading and close the character device

3.4.2.3.6. Getting Started with RPMsg Development¶

echo 'stop' > /sys/class/remoteproc/remoteproc1/state
echo 'stop' > /sys/class/remoteproc/remoteproc2/state

echo 'am335x-pru0-fw' > /sys/class/remoteproc/remoteproc1/firmware
echo 'am335x-pru1-fw' > /sys/class/remoteproc/remoteproc2/firmware

echo 'start' > /sys/class/remoteproc/remoteproc1/state
echo 'start' > /sys/class/remoteproc/remoteproc2/state

3.4.2.3.7. Common Issues¶