3.4.2.1. PRU Getting Started Labs

3.4.2.1.1. Introduction

The PRU Getting Started Labs demonstrate how to write and compile PRU firmware that is written in C, assembly, or mixed C and assembly. Steps are provided for compiling the firmware from Linux, or from Code Composer Studio (CCS).

The Getting Started Labs also demonstrate how to initialize the PRU from CCS, another processor core running Linux, another processor core running RTOS, or another processor core that runs bare metal code (no OS).

NOTE: In this guide commands to be executed for each step will be marked in BOLD.

3.4.2.1.1.1. Supported Processors

AM335x, AM437x, AM57xx, AM64x, AM65x

3.4.2.1.1.2. Required Hardware and Software

The following hardware and software are required to complete the PRU Getting Started Labs.

Note

If you are using a Linux Processor SDK, check which version of the PSSP you are using:

  • SDK 7.x (Linux kernel 5.4): compatible with PSSP tags v5.?.? - v5.9.0
  • SDK 8.x (Linux kernel 5.10): compatible with PSSP tags v6.0.0 onwards

3.4.2.1.1.3. Last Tested Configuration

The PRU Getting Started Labs were last tested with:

  • CCSv10
  • AM335x Processor SDK Linux 7.3 with BeagleBone Black
  • AM64x Processor SDK Linux 8.0 with AM64x General Purpose EVM

3.4.2.1.2. Lab 1: How to Create a PRU Project

Introduction

This lab shows how to create a PRU project in CCS, or in the Linux terminal. The CCS section and the Linux section are totally independent.

In order to create a PRU project in CCS, follow section Creating a CCS PRU Project.

In order to create a PRU project using the Linux terminal, follow section Creating a Linux PRU Project.

3.4.2.1.2.1. Creating a CCS PRU Project

  1. Launch CCS and select the default Workspace.

  2. Create a new PRU project.

    1. Select File -> New -> Project -> Code Composer Studio -> CCS Project. Click Next.

    2. In the upper left dropdown next to “Target”, select the target processor family. In the upper right dropdown, select the desired board.

      • AM335x example: Select AM33xx - Cortex A8 in the upper left dropdown. Select BeagleBone_Black in the upper right dropdown.
      • AM64x example: Select Part Family in the upper left dropdown. Select Board in the upper right dropdown.
      • If your board is not defined, select the processor you are using in
        the second dropdown.

    3. Select the PRU tab. Specify a Project Name (such as “pru_add”).

    4. Verify that a Compiler version is listed (e.g., TI v2.3.3).

    Note

    If the PRU compiler is not currently installed, select the Cancel button. Go to View->CCS App Center and install the PRU Compiler. Then redo the previous steps.

    1. Select an “Empty Projects” template. Since we will be copying our own files into the project, select Empty Project.
    2. Select Finish

Go to Lab 2: How to Write PRU Firmware to start writing the PRU firmware.

3.4.2.1.2.2. Creating a Linux PRU Project

  1. Navigate to the PSSP examples directory for your specific processor.

    • AM335x example:

      $ cd <PSSP_PATH>/examples/am335x

    • AM64x example:

      $ cd <PSSP_PATH>/examples/am64x

  2. The PSSP is a git repo. Create a new development branch. Switch over to the new branch (i.e., “checkout” the new branch).

    $ git branch getting_started_labs
    $ git checkout getting_started_labs

  3. Create a new project by copying one of the existing project folders.

    • Will your project use RPMsg to communicate with the Linux ARM core on the processor?

      • If yes, copy the RPMsg_Echo project for whichever core you are programming.
      • If no, copy the Halt project. The PRU Getting Started Labs do not use RPMsg.

    • Example: AM335x with RPMsg on PRU0, project name PRU_Add:

      $ cp -r PRU_RPMsg_Echo_Interrupt0 PRU_Add

    • Example: AM64x on RTU1, no RPMsg, project name RTU_Add:

      $ cp -r RTU_Halt RTU_Add

  4. check that you copied over all the files properly:

    $ ls <source project>
    $ ls <destination project>

Go to Lab 2: How to Write PRU Firmware to start writing the PRU firmware.


3.4.2.1.3. Lab 2: How to Write PRU Firmware

This lab will explain how to write firmware for a simple PRU program. The example PRU program will continuously add two numbers and save the result.

PRU cores run bare metal software (i.e., TI does not support running an operating system on the PRU cores). PRU firmware may be written in C code, or in assembly code.

  • C code is compiled into machine code by the TI PRU C/C++ Compiler. C code provides the benefits of a high level language. For example, C code is typically easier to read and write than Assembly code.
  • Assembly code allows you to precisely control the PRU core and the timing of the PRU core. For example, if the PRU is implementing a custom communication protocol, it may make sense to read the input signals and write the output signals with assembly code.
  • C code and assembly code can be combined to provide the benefits of both forms of programming.

See also

More information about the TI PRU Code Generation Tools (including the TI PRU C/C++ Compiler and Assembly Language Tool) can be found at:

TI PRU Code Generation Tools

Note

The C compiler can be used to generate assembly code from C code. Generated assembly code may be a helpful starting point for assembly code development. See Generating Assembly Code from C Code

Start this lab with either Writing C Code, or with Writing Assembly Code.

If you are interested in writing mixed C and assembly programs, go through the “Writing C Code” and “Writing Assembly Code” sections first. Then, you can go through Writing Mixed C and Assembly Code and Writing Mixed C and Inline Assembly Code.

3.4.2.1.3.1. Writing C Code

If the PRU project was created in CCS, follow section Writing C Code in CCS.

If the PRU project was created in the Linux terminal, follow section Writing C Code in Linux.

3.4.2.1.3.1.1. Writing C Code in CCS

Start with the empty PRU project created in Creating a CCS PRU Project.

Add the main C file

The PRU project needs a .c file for the firmware C code. We will use “Add Files” to copy the main.c file from <PSSP_PATH>/labs/Getting_Started_Labs/c_code/.

  1. Select Project->Add Files…
    • If you have multiple projects open in CCS, make sure to select the correct project in the Project Explorer view before adding the file.

Note

Many steps that involve Project->something can also be done by clicking on the Project Explorer view. For example, “Add Files” can also be accessed by right clicking on the project top-level folder and selecting Add Files. To keep things simple, later steps will only document Project->Add Files…. Use whichever process you prefer.

  1. Navigate to <PSSP_PATH>/Getting_Started_Labs/c_code folder. Select main.c.
  2. Select Copy files and click OK.
  3. Go to the Project Explorer view and double click on main.c. The text in the file should match the text in <PSSP_PATH>/labs/Getting_Started_Labs/c_code/main.c

Add the linker command file

PRU projects require a linker command file to…

  1. If a linker command file was added to the project folder automatically, delete that linker command file. The automatically generated linker files are not updated like the linker files in the PSSP.

    • Example: AM335x. Look for AM335x_PRU.cmd and delete it.

  2. Delete the include link that points to automatically generated linker files:

    1. Select Project->Properties.
    2. Select Build->PRU Compiler->Include Options.
    3. In the box marked “Add dir to #include search path”, select ${CCS_BASE_ROOT}/pru/include
    4. Delete the include path by clicking the file icon with a red X.
    5. Save the changes by clicking Apply and close.

  3. Select Project->Add Files….

  4. Navigate to the <PSSP_PATH>/Getting_Started_Labs/linker_cmd folder. Select the linker command file that matches the PRU core you are using.

    • Example: AM335x PRU: Select AM335x_PRU.cmd

      • Example: AM64x TX_PRU0: Select AM64x_TX_PRU0.cmd

Note

AM335x, AM57x, K2G: Use the same linker command file for all PRU cores.

AM437x: Use AM437x_PRU_SS0.cmd for PRU cores in PRU-ICSS0. Use AM437x_PRU_SS1.cmd for PRU cores in PRU-ICSS1.

AM64x, AM65x: Use PRU0.cmd for PRU0 in any PRU_ICSSG. Use PRU1.cmd for PRU1 in any PRU_ICSSG. Similarly, use RTU0.cmd for any RTU0, RTU1.cmd for any RTU1, TX_PRU0.cmd for any TX_PRU0, and TX_PRU1.cmd for any TX_PRU1.

Include the header files (optional)

TI provides header files for the PRU. Header files simplify development by providing easy names for registers and register bits. This lab will show how to include the header files, even though the header files are not actually used in the Getting Started Labs. The header files are used in projects in <PSSP_PATH>/examples and <PSSP_PATH>/labs/Hands_on_Labs.

  1. Add the include path for the PRU header files so that the compiler can find the header files.

    1. Select Project->Properties.

    2. Select Build->PRU Compiler->Include Options.

    3. In the box marked “Add dir to #include search path”, click the file icon with a green +.

    4. Specify the directory to the include file

      • Example: AM335x header files are at <PSSP_PATH>/include/am335x

  2. Include any header files used by the project in the main.c file.

    • Example: AM335x using header file pru_intc.h

      #include <pru_intc.h>

Add the INTC configuration file (optional)

Will the PRU project be loaded by a core running Linux kernel 5.10 or later?

Starting in Linux kernel 5.10, the Linux RemoteProc driver can initialize the PRU interrupt controller (PRU INTC) using a specific INTC map structure.

Add an INTC configuration file if:

  • the PRU project will be loaded by Linux core running Linux kernel 5.10 or later, AND
  • The project requires INTC configuration

The PRU Getting Started Labs do not use an INTC configuration file. However, these steps are provided as a resource for customers who will use an INTC configuration file in their projects. Reference <PSSP_PATH>/examples/PROCESSOR/PRU_Direct_Connect0 for an example project that uses an INTC configuration file.

  1. Add the INTC map file to the project. Use this file as a template: <PSSP_PATH>/examples/<processor>/PRU_Direct_Connect0/intc_map_0.h

  2. Include the INTC map file in the main.c file.

    • Example: AM64x using INTC map file “intc_map_0.h”

      #include "intc_map_0.h"

  3. Add the INTC map structure to the linker command file. Reference <PSSP_PATH>/examples/<processor>/PRU_Direct_Connect0/xxx_PRU0_intc.cmd

    /* Specify the sections allocation into memory */
SECTIONS {

  ...

  .pru_irq_map (COPY) :
  {
          *(.pru_irq_map)
  }
}

  4. Write the INTC mapping settings following the comments in the template INTC map file.

Add the resource table (optional)

Will the PRU project be loaded by a core running Linux kernel 5.4 or earlier?

Will the PRU project be loaded by a core running Linux kernel 5.10 or later?

If you got to this step, then the project does not need a resource table. Check which version of PSSP you are using:

  • v6.0.0 or later: No additional steps are needed. Jump to section Write the PRU firmware

  • v5.9.0 or earlier: An empty resource table is included by default in these versions of the PSSP.

    1. Go to the main.c file

    2. Comment out the resource table include:

      /* #include "resource_table_empty.h" */

    3. Jump to section Write the PRU firmware

Add the resource table with Linux 5.4 or earlier

A resource table is required if the PRU project is loaded by a Linux core running Linux kernel 5.4 or earlier.

Note

PSSP projects for Linux 5.4 or earlier have different resource tables than PSSP projects for Linux 5.10 or later. Check the tag on your PSSP to make sure you are using PSSP v5.9.0 or earlier.

Does the PRU project use RPMsg?

  • Yes –> Refer to <PSSP_PATH>/examples/<processor>/xxx_RPMsg_Echo_InterruptX

  • No –>

    • Does the PRU project configure the INTC?

      • Yes –> Refer to the AM335x example at

      <PSSP_PATH>/examples/am335x/PRU_Direct_Connect0

      • No –> If the project does not use RPMsg, or configure the INTC, then

      use an empty resource table. The getting started labs include empty resource tables.

  1. Add the resource table file to the project.

    1. Select Project->Add Files…

    #. Navigate to <PSSP_PATH>/Getting_Started_Labs/c_code folder. Select resource_table_empty.h.

    1. Select Copy files and click OK.

  2. Check that the main.c file includes the resource table file:

    #include "resource_table_empty.h"

  3. Check that the linker command file includes a section for the resource table.

    • Example: AM335x PRU0

      .resource_table > PRU_DMEM_0_1, PAGE 1

    • Example: AM64x RTU1

      /* Ensure resource_table section is aligned on 8-byte address for
       ARMv8 (64-bit) kernel */
    .resource_table : ALIGN (8) >  RTU1_DMEM_1, PAGE 1

  4. The resource table includes rsc_types.h. Add the appropriate include path:

    1. Select Project->Properties.
    2. Select Build->PRU Compiler->Include Options.
    3. In the box marked “Add dir to #include search path”, click the file icon with a green +.
    4. Specify the directory <PSSP_PATH>/include.

  5. Modify the resource table as needed. The empty resource table that is used in the PRU Getting Started Guide does not need to be modified.

Jump to section Write the PRU firmware

Add the resource table with Linux 5.10 or later (optional)

This section documents the case that the PRU project is loaded by a Linux core running Linux kernel 5.10 or later.

Note

PSSP projects for Linux 5.4 or earlier have different resource tables than PSSP projects for Linux 5.10 or later. Check the tag on your PSSP to make sure you are using PSSP v6.0.0 or later.

Will the PRU project use RPMsg to communicate with the Linux core?

  • Yes –> A resource table is required. continue reading.
  • No –> If the PRU project does not use RPMsg, then a resource table is not required. Jump to section Write the PRU firmware

The PRU Getting Started Labs do not use RPMsg, so they do not have a resource table. These steps are provided as a resource for customers who will use a resource table in their projects. Reference <PSSP_PATH>/examples/processor/xxx_RPMsg_EchoX for an example project that uses a resource table.

Note

If the PRU project for Linux 5.10 or later uses RPMsg, then the project requires both a resource table and an INTC configuration file. Reference section Add the INTC configuration file (optional) for steps on adding the INTC configuration file.

  1. Add the resource table file to the project.

    1. Select Project->Add Files…
    2. Navigate to <PSSP_PATH>/examples/<processor>/xxx_RPMsg_Echo_InterruptX folder. Select resource_table.h.
    3. Select Copy files and click OK.

  2. Include the resource table in the main.c file:

    #include "resource_table.h"

  3. Add the resource table to the linker command file. Reference <PSSP_PATH>/examples/<processor>/xxx_RPMsg_Echo_InterruptX/xxx_PRU0_intc_rscTbl.cmd

    • Example: AM335x PRU0

      .resource_table > PRU_DMEM_0_1, PAGE 1

    • Example: AM64x RTU1

      /* Ensure resource_table section is aligned on 8-byte address for
       ARMv8 (64-bit) kernel */
    .resource_table : ALIGN (8) >  RTU1_DMEM_1, PAGE 1

  4. The resource table includes rsc_types.h. Add the appropriate include path:

    1. Select Project->Properties.
    2. Select Build->PRU Compiler->Include Options.
    3. In the box marked “Add dir to #include search path”, click the file icon with a green +.
    4. Specify the directory <PSSP_PATH>/include.

Write the PRU firmware

Look for the TODO comments in your main.c code for guidance on completing the example code. The complete solution for the main.c code can be found in <PSSP_PATH>/labs/Getting_Started_Labs/c_code/solution.

Ready to compile the PRU firmware? Go to Lab 3: How to Compile PRU Firmware.

3.4.2.1.3.1.2. Writing C Code in Linux

Creating a Linux PRU Project. Start in the same directory as in Lab 1: <PSSP_PATH>/examples/<processor>

Add the main C file

The PRU project needs a .c file for the firmware C code.

  1. The basic PRU project should already have a main.c file. Delete the existing main.c file.

    • Example: AM335x with PRU0:

      $ cd PRU_Add
        $ ls
        $ rm main.c

    • Example: AM64x with RTU1:

      $ cd RTU_Add
        $ ls
        $ rm main.c

  2. Copy the main.c file from <PSSP_PATH>/labs/Getting_Started_Labs/c_code/ to the current directory.

    $ cp ../../../labs/Getting_Started_Labs/c_code/main.c .

  3. The main.c file in the current directory should match the main.c file in labs/Getting_Started_Labs/c_code/.

    • Example: AM335x with PRU0, based on PRU_Halt:

      $ diff ../../../labs/Getting_Started_Labs/c_code/main.c main.c
        # there should be no output

        $ diff ../PRU_Halt/main.c main.c
        # main.c in PRU_Halt should be different

Add the linker command file

PRU projects require a linker command file to…

  1. The basic PRU project should already have a linker command file. Make sure that the linker command file matches the PRU core you are using.

    • Example: AM335x PRU: Select AM335x_PRU.cmd

      • Example: AM64x TX_PRU0: Select AM64x_TX_PRU0.cmd

Note

AM335x, AM57x, K2G: Use the same linker command file for all PRU cores.

AM437x: Use AM437x_PRU_SS0.cmd for PRU cores in PRU-ICSS0. Use AM437x_PRU_SS1.cmd for PRU cores in PRU-ICSS1.

AM64x, AM65x: Use PRU0.cmd for PRU0 in any PRU_ICSSG. Use PRU1.cmd for PRU1 in any PRU_ICSSG. Similarly, use RTU0.cmd for any RTU0, RTU1.cmd for any RTU1, TX_PRU0.cmd for any TX_PRU0, and TX_PRU1.cmd for any TX_PRU1.

  1. Make sure that the project Makefile LINKER_COMMAND_FILE matches the linker command file used:

    1. Open the Makefile in a text editor.

    2. If LINKER_COMMAND_FILE does not match the project linker command file, update it.

      • Example: AM335x using AM335x_PRU.cmd:

                 LINKER_COMMAND_FILE=./AM335x_PRU.cmd

* Example: AM64x TX_PRU0 using AM64x_TX_PRU0.cmd:

        LINKER_COMMAND_FILE ?= ./AM64x_TX_PRU0.cmd

    3. If the Makefile required changes, save the changes. Close the Makefile.

Include the header files (optional)

TI provides header files for the PRU. Header files simplify development by providing easy names for registers and register bits. This lab will show how to include the header files, even though the header files are not actually used in the Getting Started Labs. The header files are used in projects in <PSSP_PATH>/examples and <PSSP_PATH>/labs/Hands_on_Labs.

  1. Add the include path for the PRU header files so that the compiler can find the header files.

    1. Open the Makefile in a text editor.

    2. Ensure that the project Makefile INCLUDE points to the directory to the include file.

      • Example: AM335x header files are at <PSSP_PATH>/include/am335x:

        INCLUDE=--include_path=../../../include --include_path=../../../include/am335x

    3. If the Makefile required changes, save the changes. Close the Makefile.

  2. Include any header files used by the project in the main.c file.

    1. Open the main.c file in a text editor.

      • Example: AM335x using header file pru_intc.h

        #include <pru_intc.h>

    2. If the main.c file required changes, save the changes. Close the main.c file.

Add the INTC configuration file (optional)

Will the PRU project be loaded by a core running Linux kernel 5.10 or later?

Starting in Linux kernel 5.10, the Linux RemoteProc driver can initialize the PRU interrupt controller (PRU INTC) using a specific INTC map structure.

Add an INTC configuration file if:

  • the PRU project will be loaded by Linux core running Linux kernel 5.10 or later, AND
  • The project requires INTC configuration

The PRU Getting Started Labs do not use an INTC configuration file. However, these steps are provided as a resource for customers who will use an INTC configuration file in their projects. Reference <PSSP_PATH>/examples/PROCESSOR/PRU_Direct_Connect0 for an example project that uses an INTC configuration file.

  1. Add the INTC map file to the project. Use this file as a template: <PSSP_PATH>/examples/<processor>/PRU_Direct_Connect0/intc_map_0.h

  2. Include the INTC map file in the main.c file.

    • Example: AM64x using INTC map file “intc_map_0.h”

      #include "intc_map_0.h"

  3. Add the INTC map structure to the linker command file. Reference <PSSP_PATH>/examples/<processor>/PRU_Direct_Connect0/xxx_PRU0_intc.cmd

    /* Specify the sections allocation into memory */
SECTIONS {

  ...

  .pru_irq_map (COPY) :
  {
          *(.pru_irq_map)
  }
}

  4. Open the INTC map file. Write the INTC mapping settings following the comments in the template INTC map file.

Add the resource table (optional)

Will the PRU project be loaded by a core running Linux kernel 5.4 or earlier?

Will the PRU project be loaded by a core running Linux kernel 5.10 or later?

If you got to this step, then the project does not need a resource table. Check which version of PSSP you are using:

  • v6.0.0 or later: No additional steps are needed. Jump to section Write the PRU firmware

  • v5.9.0 or earlier: An empty resource table is included by default in these versions of the PSSP.

    1. Go to the main.c file

    2. Comment out the resource table include:

      /* #include "resource_table_empty.h" */

    3. Jump to section Write the PRU firmware

Add the resource table with Linux 5.4 or earlier

A resource table is required if the PRU project is loaded by a Linux core running Linux kernel 5.4 or earlier.

Note

PSSP projects for Linux 5.4 or earlier have different resource tables than PSSP projects for Linux 5.10 or later. Check the tag on your PSSP to make sure you are using PSSP v5.9.0 or earlier.

Does the PRU project use RPMsg?

  • Yes –> Refer to <PSSP_PATH>/examples/<processor>/xxx_RPMsg_Echo_InterruptX

  • No –>

    • Does the PRU project configure the INTC?

      • Yes –> Refer to the AM335x example at

      <PSSP_PATH>/examples/am335x/PRU_Direct_Connect0

      • No –> If the project does not use RPMsg, or configure the INTC, then

      use an empty resource table. The getting started labs include empty resource tables.

  1. The basic PRU project should already have an empty resource table file. The getting started labs use an empty resource table, so no changes are needed. If you need an empty resource table, you can find one at <PSSP_PATH>/Getting_Started_Labs/linker_cmd.

  2. Check that the main.c file includes the resource table file:

    #include "resource_table_empty.h"

  3. Check that the linker command file includes a section for the resource table.

    • Example: AM335x PRU0

      .resource_table > PRU_DMEM_0_1, PAGE 1

    • Example: AM64x RTU1

      /* Ensure resource_table section is aligned on 8-byte address for
       ARMv8 (64-bit) kernel */
    .resource_table : ALIGN (8) >  RTU1_DMEM_1, PAGE 1

  4. The resource table includes rsc_types.h. Add the include path for rsc_types.h so that the compiler can find the header file.

    1. Open the Makefile in a text editor.

    2. Ensure that the project Makefile INCLUDE points to the directory with rsc_types.h.

      • Example: AM335x:

        INCLUDE=--include_path=../../../include --include_path=../../../include/am335x

    3. If the Makefile required changes, save the changes. Close the Makefile.

  5. Modify the resource table as needed. The empty resource table that is used in the PRU Getting Started Guide does not need to be modified.

Jump to section Write the PRU firmware

Add the resource table with Linux 5.10 or later (optional)

This section documents the case that the PRU project is loaded by a Linux core running Linux kernel 5.10 or later.

Note

PSSP projects for Linux 5.4 or earlier have different resource tables than PSSP projects for Linux 5.10 or later. Check the tag on your PSSP to make sure you are using PSSP v6.0.0 or later.

Will the PRU project use RPMsg to communicate with the Linux core?

  • Yes –> A resource table is required. continue reading.
  • No –> If the PRU project does not use RPMsg, then a resource table is not required. Jump to section Write the PRU firmware

The PRU Getting Started Labs do not use RPMsg, so they do not have a resource table. These steps are provided as a resource for customers who will use a resource table in their projects. Reference <PSSP_PATH>/examples/processor/xxx_RPMsg_Echo_InterruptX for an example project that uses a resource table.

Note

If the PRU project for Linux 5.10 or later uses RPMsg, then the project requires both a resource table and an INTC configuration file. Reference section Add the INTC configuration file (optional) for steps on adding the INTC configuration file.

  1. Add the resource table file to the project.

    1. Copy the resource table from <PSSP_PATH>/examples/<processor>/xxx_RPMsg_Echo_InterruptX folder.

      • Example: AM335x PRU0 with RPMsg:

        cp ../PRU_RPMsg_Echo_Interrupt0/resource_table.h .

  2. Include the resource table in the main.c file:

    #include "resource_table.h"

  3. Add the resource table to the linker command file. Reference <PSSP_PATH>/examples/<processor>/xxx_RPMsg_Echo_InterruptX/xxx_PRU0_intc_rscTbl.cmd

    • Example: AM335x PRU0

      .resource_table > PRU_DMEM_0_1, PAGE 1

    • Example: AM64x RTU1

      /* Ensure resource_table section is aligned on 8-byte address for
       ARMv8 (64-bit) kernel */
    .resource_table : ALIGN (8) >  RTU1_DMEM_1, PAGE 1

  4. The resource table includes rsc_types.h. Add the include path for rsc_types.h so that the compiler can find the header file.

    1. Open the Makefile in a text editor.

    2. Ensure that the project Makefile INCLUDE points to the directory with rsc_types.h.

      INCLUDE=--include_path=../../../include --include_path=../../../include/am335x

    3. If the Makefile required changes, save the changes. Close the Makefile.g

Write the PRU firmware

Look for the TODO comments in your main.c code for guidance on completing the example code. The complete solution for the main.c code can be found in <PSSP_PATH>/labs/Getting_Started_Labs/c_code/solution.

Ready to compile the PRU firmware? Go to Lab 3: How to Compile PRU Firmware.

3.4.2.1.3.2. Writing Assembly Code

If the PRU project was created in CCS, follow section Writing Assembly Code in CCS.

If the PRU project was created in the Linux terminal, follow section pru_getting_started_labs_writing_assembly_code_in_linux.

3.4.2.1.3.2.1. Writing Assembly Code in CCS

Start with the empty PRU project created in Creating a CCS PRU Project.

Add the main ASM file

The PRU project needs a .asm file for the firmware assembly code. We will use “Add Files” to copy the main.asm file from <PSSP_PATH>/labs/Getting_Started_Labs/assembly_code/.

  1. Select Project->Add Files…
    • If you have multiple projects open in CCS, make sure to select the correct project in the Project Explorer view before adding the file.

Note

Many steps that involve Project->something can also be done by clicking on the Project Explorer view. For example, “Add Files” can also be accessed by right clicking on the project top-level folder and selecting Add Files. To keep things simple, later steps will only document Project->Add Files…. Use whichever process you prefer.

  1. Navigate to <PSSP_PATH>/Getting_Started_Labs/assembly_code folder. Select main.asm.
  2. Select Copy files and click OK.
  3. Go to the Project Explorer view and double click on main.asm. The text in the file should match the text in <PSSP_PATH>/labs/Getting_Started_Labs/assembly_code/main.asm

Add the linker command file

PRU projects require a linker command file to…

  1. If a linker command file was added to the project folder automatically, delete that linker command file. The automatically generated linker files are not updated like the linker files in the PSSP.

    • Example: AM335x. Look for AM335x_PRU.cmd and delete it.

  2. Delete the include link that points to automatically generated linker files:

    1. Select Project->Properties.
    2. Select Build->PRU Compiler->Include Options.
    3. In the box marked “Add dir to #include search path”, select ${CCS_BASE_ROOT}/pru/include
    4. Delete the include path by clicking the file icon with a red X.
    5. Save the changes by clicking Apply and close.

  3. Select Project->Add Files….

  4. Navigate to the <PSSP_PATH>/Getting_Started_Labs/linker_cmd folder. Select the linker command file that matches the PRU core you are using.

    • Example: AM335x PRU: Select AM335x_PRU.cmd

      • Example: AM64x TX_PRU0: Select AM64x_TX_PRU0.cmd

Note

AM335x, AM57x, K2G: Use the same linker command file for all PRU cores.

AM437x: Use AM437x_PRU_SS0.cmd for PRU cores in PRU-ICSS0. Use AM437x_PRU_SS1.cmd for PRU cores in PRU-ICSS1.

AM64x, AM65x: Use PRU0.cmd for PRU0 in any PRU_ICSSG. Use PRU1.cmd for PRU1 in any PRU_ICSSG. Similarly, use RTU0.cmd for any RTU0, RTU1.cmd for any RTU1, TX_PRU0.cmd for any TX_PRU0, and TX_PRU1.cmd for any TX_PRU1.

Add the INTC configuration file (optional)

Add the resource table (optional)

Will the PRU project be loaded by a core running Linux kernel 5.4 or earlier?

Will the PRU project be loaded by a core running Linux kernel 5.10 or later?

  • Yes –> Ensure the PSSP version is v6.0.0 or later. No additional steps are needed. Jump to section Write the PRU firmware.
  • No –> Continue reading.

If you got to this step, then the PRU project will not be loaded by a core running Linux. The project does not need a resource table.

Check which version of PSSP you are using:

  • v6.0.0 or later: No additional steps are needed. Jump to section Write the PRU firmware.

  • v5.9.0 or earlier: An empty resource table is included by default in these versions of the PSSP.

    1. Go to the main.asm file

    2. Delete the resource table lines:

      ; Resource table needed for remoteproc Linux driver
        .global        ||pru_remoteproc_ResourceTable||
        .sect  ".resource_table:retain", RW
        .retain
        .align 1
        .elfsym        ||pru_remoteproc_ResourceTable||,SYM_SIZE(20)
||pru_remoteproc_ResourceTable||:
        .bits  1,32                    ; pru_remoteproc_ResourceTable.base.ver @ 0
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.num @ 32
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.reserved[0] @ 64
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.reserved[1] @ 96
        .bits  0,32                    ; pru_remoteproc_ResourceTable.offset[0] @ 128

    3. Jump to section Write the PRU firmware.

Add the resource table with Linux 5.4 or earlier

A resource table is required if the PRU project is loaded by a Linux core running Linux kernel 5.4 or earlier.

Note

PSSP projects for Linux 5.4 or earlier have different resource tables than PSSP projects for Linux 5.10 or later. Check the tag on your PSSP to make sure you are using PSSP v5.9.0 or earlier.

Does the PRU project use RPMsg?

  • Yes –> TI only supports PRU RPMsg with C code. Steps for building a C code project (including how to add RPMsg Resource Tables) are at Writing C Code.

  • No –>

    • Does the PRU project configure the INTC?

      • Yes –> Refer to …
      • No –> If the project does not configure the INTC, then

      define an empty resource table.

The getting started labs include empty resource tables.

  1. Check that the main.asm file includes an empty resource table:

    ; Resource table needed for remoteproc Linux driver
        .global        ||pru_remoteproc_ResourceTable||
        .sect  ".resource_table:retain", RW
        .retain
        .align 1
        .elfsym        ||pru_remoteproc_ResourceTable||,SYM_SIZE(20)
||pru_remoteproc_ResourceTable||:
        .bits  1,32                    ; pru_remoteproc_ResourceTable.base.ver @ 0
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.num @ 32
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.reserved[0] @ 64
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.reserved[1] @ 96
        .bits  0,32                    ; pru_remoteproc_ResourceTable.offset[0] @ 128

  2. Check that the linker command file includes a section for the resource table.

    • Example: AM335x PRU0

      .resource_table > PRU_DMEM_0_1, PAGE 1

    • Example: AM65x PRU0

      /* Ensure resource_table section is aligned on 8-byte address for
       ARMv8 (64-bit) kernel */
    .resource_table : ALIGN (8) >  PRU0_DMEM_0, PAGE 1

  3. The resource table includes rsc_types.h. Add the appropriate include path:

    1. Select Project->Properties.
    2. Select Build->PRU Compiler->Include Options.
    3. In the box marked “Add dir to #include search path”, click the file icon with a green +.
    4. Specify the directory <PSSP_PATH>/include.
  1. Modify the resource table as needed. The empty resource table that is used in the PRU Getting Started Guide does not need to be modified.

Jump to section Write the PRU firmware

Write the PRU firmware

Look for the TODO comments in your main.asm code for guidance on completing the example code. The complete solution for the main.asm code can be found in <PSSP_PATH>/labs/Getting_Started_Labs/assembly_code/solution.

Ready to compile the PRU firmware? Go to Lab 3: How to Compile PRU Firmware.

3.4.2.1.3.2.2. Writing Assembly Code in Linux

Creating a Linux PRU Project. Start in the same directory as in Lab 1: <PSSP_PATH>/examples/<processor>

Add the main ASM file

The PRU project needs a .asm file for the firmware assembly code.

  1. The basic PRU project should already have a main.c file. Delete the existing main.c file.

    • Example: AM335x with PRU0:

      $ cd PRU_Add
        $ ls
        $ rm main.c

    • Example: AM64x with RTU1:

      $ cd RTU_Add
        $ ls
        $ rm main.c

  2. Copy the main.asm file from <PSSP_PATH>/labs/Getting_Started_Labs/assembly_code/ to the current directory.

    $ cp ../../../labs/Getting_Started_Labs/assembly_code/main.asm .

  3. The main.asm file in the current directory should match the main.asm file in labs/Getting_Started_Labs/assembly_code/.

    • Example: AM335x with PRU0, based on PRU_Halt:

      $ diff ../../../labs/Getting_Started_Labs/assembly_code/main.asm main.asm
        # there should be no output

Add the Makefile

The PRU project needs a Makefile in order to build the firmware through the Linux terminal.

  1. The basic PRU project should already have a Makefile. Delete the existing Makefile.

    • Example: AM335x with PRU0:

      $ cd PRU_Add
        $ ls
        $ rm Makefile

    • Example: AM64x with RTU1:

      $ cd RTU_Add
        $ ls
        $ rm Makefile

  2. Copy the Makefile file from <PSSP_PATH>/labs/Getting_Started_Labs/assembly_code/solution/<processor>/ to the current directory.

    • Example: AM335x with PRU0:

      $ cp ../../../labs/Getting_Started_Labs/assembly_code/solution/am335x/Makefile .

    • Example: AM64x with RTU1:

      $ cp ../../../labs/Getting_Started_Labs/assembly_code/solution/am64x/Makefile .

  3. The Makefile in the current directory should match the Makefile in labs/Getting_Started_Labs/assembly_code/solution/<processor>/.

    • Example: AM335x with PRU0, based on PRU_Halt:

      $ diff ../../../labs/Getting_Started_Labs/assembly_code/solution/am335x/Makefile Makefile
        # there should be no output

        $ diff ../PRU_Halt/Makefile Makefile
        # Makefile in PRU_Halt should be different

The Makefile may need modifications depending on which PRU core the project uses. See more information in Add the linker command file.

Add the linker command file

PRU projects require a linker command file to…

  1. The basic PRU project should already have a linker command file. Make sure that the linker command file matches the PRU core you are using.

    • Example: AM335x PRU: Select AM335x_PRU.cmd

      • Example: AM64x TX_PRU0: Select AM64x_TX_PRU0.cmd

Note

AM335x, AM57x, K2G: Use the same linker command file for all PRU cores.

AM437x: Use AM437x_PRU_SS0.cmd for PRU cores in PRU-ICSS0. Use AM437x_PRU_SS1.cmd for PRU cores in PRU-ICSS1.

AM64x, AM65x: Use PRU0.cmd for PRU0 in any PRU_ICSSG. Use PRU1.cmd for PRU1 in any PRU_ICSSG. Similarly, use RTU0.cmd for any RTU0, RTU1.cmd for any RTU1, TX_PRU0.cmd for any TX_PRU0, and TX_PRU1.cmd for any TX_PRU1.

  1. Make sure that the project Makefile LINKER_COMMAND_FILE matches the linker command file used:

    1. Open the Makefile in a text editor.

    2. If LINKER_COMMAND_FILE does not match the project linker command file, update it.

      • Example: AM335x using AM335x_PRU.cmd:

                 LINKER_COMMAND_FILE=./AM335x_PRU.cmd

* Example: AM64x TX_PRU0 using AM64x_TX_PRU0.cmd:

        LINKER_COMMAND_FILE=./AM64x_TX_PRU0.cmd
    1. If the Makefile required changes, save the changes. Close the Makefile.

Add the INTC configuration file (optional)

Add the resource table (optional)

Will the PRU project be loaded by a core running Linux kernel 5.4 or earlier?

Will the PRU project be loaded by a core running Linux kernel 5.10 or later?

  • Yes –> Ensure the PSSP version is v6.0.0 or later. No additional steps are needed. Jump to section Write the PRU firmware.
  • No –> Continue reading.

If you got to this step, then the PRU project will not be loaded by a core running Linux. The project does not need a resource table.

Check which version of PSSP you are using:

  • v6.0.0 or later: No additional steps are needed. Jump to section Write the PRU firmware.

  • v5.9.0 or earlier: An empty resource table is included by default in these versions of the PSSP.

    1. Go to the main.asm file

    2. Delete the resource table lines:

      ; Resource table needed for remoteproc Linux driver
        .global        ||pru_remoteproc_ResourceTable||
        .sect  ".resource_table:retain", RW
        .retain
        .align 1
        .elfsym        ||pru_remoteproc_ResourceTable||,SYM_SIZE(20)
||pru_remoteproc_ResourceTable||:
        .bits  1,32                    ; pru_remoteproc_ResourceTable.base.ver @ 0
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.num @ 32
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.reserved[0] @ 64
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.reserved[1] @ 96
        .bits  0,32                    ; pru_remoteproc_ResourceTable.offset[0] @ 128

    3. Jump to section Write the PRU firmware.

Add the resource table with Linux 5.4 or earlier

A resource table is required if the PRU project is loaded by a Linux core running Linux kernel 5.4 or earlier.

Note

PSSP projects for Linux 5.4 or earlier have different resource tables than PSSP projects for Linux 5.10 or later. Check the tag on your PSSP to make sure you are using PSSP v5.9.0 or earlier.

Does the PRU project use RPMsg?

  • Yes –> TI only supports PRU RPMsg with C code. Steps for building a C code project (including how to add RPMsg Resource Tables) are at Writing C Code.

  • No –>

    • Does the PRU project configure the INTC?

      • Yes –> Refer to …
      • No –> If the project does not configure the INTC, then

      define an empty resource table.

The getting started labs include empty resource tables.

  1. Check that the main.asm file includes an empty resource table:

    ; Resource table needed for remoteproc Linux driver
        .global        ||pru_remoteproc_ResourceTable||
        .sect  ".resource_table:retain", RW
        .retain
        .align 1
        .elfsym        ||pru_remoteproc_ResourceTable||,SYM_SIZE(20)
||pru_remoteproc_ResourceTable||:
        .bits  1,32                    ; pru_remoteproc_ResourceTable.base.ver @ 0
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.num @ 32
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.reserved[0] @ 64
        .bits  0,32                    ; pru_remoteproc_ResourceTable.base.reserved[1] @ 96
        .bits  0,32                    ; pru_remoteproc_ResourceTable.offset[0] @ 128

  2. Check that the linker command file includes a section for the resource table.

    • Example: AM335x PRU0

      .resource_table > PRU_DMEM_0_1, PAGE 1

    • Example: AM65x PRU0

      /* Ensure resource_table section is aligned on 8-byte address for
       ARMv8 (64-bit) kernel */
    .resource_table : ALIGN (8) >  PRU0_DMEM_0, PAGE 1

  3. The resource table includes rsc_types.h. Add the include path for rsc_types.h so that the compiler can find the header file.

    1. Open the Makefile in a text editor.

    2. Ensure that the project Makefile INCLUDE points to the directory with rsc_types.h.

      • Example: AM335x:

        INCLUDE=--include_path=../../../include --include_path=../../../include/am335x

    3. If the Makefile required changes, save the changes. Close the Makefile.

  1. Modify the resource table as needed. The empty resource table that is used in the PRU Getting Started Guide does not need to be modified.

Jump to section Write the PRU firmware

Write the PRU firmware

Look for the TODO comments in your main.asm code for guidance on completing the example code. The complete solution for the main.asm code can be found in <PSSP_PATH>/labs/Getting_Started_Labs/assembly_code/solution.

Ready to compile the PRU firmware? Go to Lab 3: How to Compile PRU Firmware.

3.4.2.1.3.3. Writing Mixed C and Assembly Code

This section shows how to create a PRU project that combines C and assembly code. The main function of the PRU firmware will be written in C code. An external function will be written in assembly.

This section assumes that you have already read through Writing C Code and Writing Assembly Code.

Start with a blank project as per the steps in Lab 1: How to Create a PRU Project. This should be a different project than the projects created for Writing C Code and Writing Assembly Code.

The steps for Writing Mixed C and Assembly Code apply to both PRU projects that were created in CCS, and PRU projects that were created in the Linux terminal.

3.4.2.1.3.3.1. Write the Main Function in C

  1. Add the main.c file from <PSSP_PATH>/labs/Getting_Started_Labs/c_and_assembly/.

  2. Add the linker command file.

    • If the project was created in CCS:
      1. Remove any linker command file that was automatically added to the project.
      2. Delete the include link that points to automatically generated linker files.
      3. Add the linker command file that matches the PRU core you are using from <PSSP_PATH>/Getting_Started_Labs/linker_cmd.
    • If the project was created in the Linux terminal:
      1. Verify that the project linker command file matches the PRU core.

  3. Include header files if the project uses them. The Getting Started Labs do not use header files.

  4. Add the INTC configuration file if the PRU INTC will be configured by a Linux core running Linux kernel 5.10 or later. The Getting Started Labs do not configure the PRU INTC.

  5. Add the resource table if the project is loaded by a Linux core running Linux kernel 5.4 or earlier, or if the project is loaded by a Linux core running Linux kernel 5.10 or later AND the project uses RPMsg. The Getting Started Labs do not use RPMsg.

  6. Write the main.c firmware code:

    • Section Write the External Function in Assembly will explain how to ensure that the main.c file can find the external assembly function.

    • Look for the TODO comments in your main.c code for guidance on completing the example code. The complete solution for the main.c code can be found

      in <PSSP_PATH>/labs/Getting_Started_Labs/c_and_assembly/solution.

3.4.2.1.3.3.2. Write the External Function in Assembly

The PRU project’s main function, linker command file, INTC configuration file (optional) and resource table (optional) are all handled in the main.c file.

  1. Add the assm_add.asm file from <PSSP_PATH>/labs/Getting_Started_Labs/c_and_assembly/.
  2. Make sure that the following conditions are met. These conditions are required in order for the main.c file to be able to use the externally defined assembly function:
    • The .sect name must match the function declaration in main.c.
    • The section must be defined as .global

  1. write the assm_add.asm firmware code:

    • Look for the TODO comments in your assm_add.asm code for guidance on completing the example code. The complete solution for the assm_add.asm

      code can be found in <PSSP_PATH>/labs/Getting_Started_Labs/c_and_assembly/solution.

3.4.2.1.3.3.3. More Resources for Writing Mixed C and Assembly Code

For more information about writing mixed C and assembly code, reference …

3.4.2.1.3.4. Writing Mixed C and Inline Assembly Code

This section shows how to create a PRU project that combines C and assembly code. The main function of the PRU firmware will be written in C code. The C code will use an inline assembly function.

This section assumes that you have already read through Writing C Code and Writing Assembly Code.

Start with a blank project as per the steps in Lab 1: How to Create a PRU Project. This should be a different project than the projects created for Writing C Code and Writing Assembly Code.

The steps for Writing Mixed C and Inline Assembly Code apply to both PRU projects that were created in CCS, and PRU projects that were created in the Linux terminal.

3.4.2.1.3.4.1. Write the Main Function in C

  1. Add the main.c file from <PSSP_PATH>/labs/Getting_Started_Labs/c_and_inline_assembly/.

  2. Add the linker command file.

    • If the project was created in CCS:
      1. Remove any linker command file that was automatically added to the project.
      2. Delete the include link that points to automatically generated linker files.
      3. Add the linker command file that matches the PRU core you are using from <PSSP_PATH>/Getting_Started_Labs/linker_cmd.
    • If the project was created in the Linux terminal:
      1. Verify that the project linker command file matches the PRU core.

  3. Include header files if the project uses them. The Getting Started Labs do not use header files.

  4. Add the INTC configuration file if the PRU INTC will be configured by a Linux core running Linux kernel 5.10 or later. The Getting Started Labs do not configure the PRU INTC.

  5. Add the resource table if the project is loaded by a Linux core running Linux kernel 5.4 or earlier, or if the project is loaded by a Linux core running Linux kernel 5.10 or later AND the project uses RPMsg. The Getting Started Labs do not use RPMsg.

  6. Write the main.c firmware code:

    • Section Write the Inline Function in Assembly will explain how to ensure that the main.c file can find the external assembly function.

    • Look for the TODO comments in your main.c code for guidance on completing the example code. The complete solution for the main.c code can be found

      in <PSSP_PATH>/labs/Getting_Started_Labs/c_and_assembly/solution.

3.4.2.1.3.4.2. Write the Inline Function in Assembly

  1. write the assm_add.asm firmware code:

    • Look for the TODO comments in your assm_add.asm code for guidance on completing the example code. The complete solution for the assm_add.asm

      code can be found in <PSSP_PATH>/labs/Getting_Started_Labs/c_and_assembly/solution.

3.4.2.1.3.4.3. More Resources for Writing Mixed C and Inline Assembly Code

For more information about writing mixed C and inline assembly code, reference …


3.4.2.1.4. Lab 3: How to Compile PRU Firmware

Intro here

3.4.2.1.4.1. Compiling From CCS

3.4.2.1.4.1.3. Generating Assembly Code from C Code

Compiling to a hex array file

  1. Right click your assembly project in the Project Explorer browser. Select Properties

2. Navigate to Build > PRU Linker > Advanced Options > Symbol Management In the box labled Specify program entry point for the output module enter the label for your main program (we mostly use “main” for our examples)

common/PRU-ICSS/../images/PRUCompileScreenshot1.png

Fig. 3.3 Screenshot of the symbol management window with main specified as program entry

3. Navigate to PRU Hex Utility and check the Enable PRU Hex Utility box. Then, under that subcategory, navigate to Output Format Options and check the Array output format box. Select Apply and Close to exit these settings.

common/PRU-ICSS/../images/PRUCompileScreenshot2.png

Fig. 3.4 Screenshot of the PRU Hex Utility Window after enabling and selecting array output format

4. Now when you build your PRU project, there should be a .hex file within the Debug folder. This .hex can be renamed to a .h and added to a Cortex project, which will allow the Cortex to load the PRU code to the IRAM of the PRU.

Compiling From Linux


3.4.2.1.5. Lab 4: How to Initialize the PRU

Initializing the PRU from CCS

Initializing the PRU from Linux Core

Initializing the PRU from RTOS Core

This guide was written using CCS 9.1.X

Contents

AM335X:

  1. Launch CCS and open a Workspace
  2. Go to File > New > CCS Project

3. Select your Target in the first dropdown menu and your Board in the second dropdown menu. Select your Connection in the third dropdown menu.

4. Select the Cortex A [ARM] tab and give your project a name. Select the GNU (Linaro) compiler.

5. Under Project templates and examples select SYS/BIOS and then GNU Target Examples and finally Typical.

common/PRU-ICSS/../images/PRURTOSScreenshot1.png

Fig. 3.5 Screenshot of sample CCS settings for a PRU loading project

6. Select Next >. Under Products and Repositories select am335x PDK, SYS/BIOS, and XDAIS.

  1. Select the Platform that you’re using from the drop down menu.
common/PRU-ICSS/../images/PRURTOSScreenshot10.png

Fig. 3.6 Screenshot of sample libraries selected for a PRU loading project on the BeagleBone Black Platform

8. Right click the project folder in the Project Explorer. Select Properties from the drop down menu. Select CCS Build > GNU Linker > Libraries

9. Select Add… in the top bar of the Libraries box. Click Browse. Navigate to: <PDK Directory>/packages/ti/osal/lib/tirtos/am335x/a8/release. You should see a file titled ti.osal.aa8fg. If you don’t see the file, make sure you’re browsing all file types. Select that file.

common/PRU-ICSS/../images/PRURTOSScreenshot4.png

Fig. 3.7 Screenshot of the library screen in the GNU Linker for a PRU loading project

10. Open your app.cfg file in the project. Copy the code found in pru-software-support-package/Getting_Started_Labs/PRU_FROM_RTOS/app335.cfg into your app.cfg:

There are a few things that should be noted in this configuration file:

var Mmu = xdc.useModule('ti.sysbios.family.arm.a8.Mmu');
Mmu.enableMMU = true;

/* Force peripheral section to be NON cacheable strongly-ordered memory */
var peripheralAttrs = {
type : Mmu.FirstLevelDesc_SECTION, // SECTION descriptor
tex: 1,
bufferable : false,                // bufferable
cacheable  : false,                // cacheable
shareable  : false,                // shareable
noexecute  : true,                 // not executable
};

/* Define the base address of the 1 Meg page the peripheral resides in. */
var peripheralBaseAddr = 0x4A300000;

/* Configure the corresponding MMU page descriptor accordingly */
Mmu.setFirstLevelDescMeta(peripheralBaseAddr,
                      peripheralBaseAddr,
                      peripheralAttrs);

In the above code: Mmu.enableMMU = true; enables the MMU. Mmu.setFirstLevelDescMeta sets the page of memory starting at peripheralBaseAddr to be non cacheable as described in peripheralAttrs.

var socType           = "am335x";

/* Load the PRUSS package */
var Pruss = xdc.loadPackage('ti.drv.pruss');
Pruss.Settings.socType = socType;

/* Load the uart package */
var Uart              = xdc.loadPackage('ti.drv.uart');
Uart.Settings.socType = socType;

/*use CSL package*/
var Csl = xdc.loadPackage('ti.csl');
Csl.Settings.deviceType = socType;

/* Load the board package */
var Board = xdc.loadPackage('ti.board');
Board.Settings.boardName = "<YOUR_BOARD_HERE>";

The above configuration code loads in the modules neccesary to load the PRU from the A8.

11. Board options for <YOUR_BOARD_HERE> can be found in <PDK>/Packages/ti/board/src. Change <YOUR_BOARD_HERE> to be one of those options listed.

12. You will need the PRU program that you wish to load to be in hex array format as a .h file that is included in your project folder. Instructions on how to do that can be found above in the Compiling to PRU section.

15. You’ll need to create a target configuration file in order to launch your board and initialize PRU-ICSS. You can do this by navigating to Window > Show View > Target Configurations. Then select New Target Configuration File. Select your Board and Connection type and select save.

common/PRU-ICSS/../images/PRURTOSScreenshot7.png

Fig. 3.8 Screenshot of a sample Target Configuration File setup screen for the BeagleBone Black.

  1. Right-click the newly created .ccxml file and select Launch selected configuration

17. Connect to the CortexA8, Reset the CPU, and then navigate to Scripts > PRU_ICSS > PRU_ICSS_INIT and select it.

  1. Load the PRU program and run it.
  2. Connect to the PRU and pause it. Navigate to Window > Show View > Disassembly and select it.
common/PRU-ICSS/../images/PRURTOSScreenshot14.png

Fig. 3.9 All of the selections that you need to make are highlighted. Hover over each one to see what it does.

  1. The PRU Program that you compiled into a hex array should now appear in the IRAM of the PRU.

AM437X:

  1. Launch CCS and open a Workspace
  2. Go to File > New > CCS Project

3. Select your Target in the first dropdown menu and your Board in the second dropdown menu. Select your Connection in the third dropdown menu.

4. Select the Cortex A [ARM] tab and give your project a name. Select the GNU (Linaro) compiler.

5. Under Project templates and examples select SYS/BIOS and then GNU Target Examples and finally Typical.

common/PRU-ICSS/../images/PRURTOSScreenshot2.png

Fig. 3.10 Screenshot of sample CCS settings for a PRU loading project

6. Select Next >. Under Products and Repositories select am437x PDK, SYS/BIOS, and XDAIS.

  1. Select the Platform that you’re using from the drop down menu. Select Finish.
common/PRU-ICSS/../images/PRURTOSScreenshot11.png

Fig. 3.11 Screenshot of sample libraries selected for a PRU loading project on the IDK_AM437 Platform

8. Right click the project folder in the Project Explorer. Select Properties from the drop down menu. Select CCS Build > GNU Linker > Libraries

9. Select Add… in the top bar of the Libraries box. Click Browse. Navigate to: <PDK Directory>/packages/ti/osal/lib/tirtos/am437x/a9/release. You should see a file titled ti.osal.aa9fg. If you don’t see the file, make sure you’re browsing all file types. Select that file.

common/PRU-ICSS/../images/PRURTOSScreenshot5.png

Fig. 3.12 Screenshot of the library screen in the GNU Linker for a PRU loading project

10. Open your app.cfg file in the project. Copy the code found in pru-software-support-package/Getting_Started_Labs/PRU_FROM_RTOS/app437.cfg into your app.cfg:

There are a few things that should be noted in this configuration file:

var Mmu = xdc.useModule('ti.sysbios.family.arm.a8.Mmu');
Mmu.enableMMU = true;

var peripheralAttrs = {
  type : Mmu.FirstLevelDesc_SECTION, // SECTION descriptor
  tex: 0,
  bufferable : false,                // bufferable
  cacheable  : false,                // cacheable
  shareable  : false,                // shareable
  noexecute  : true,                 // not executable
};




/* Define the base address of the 1 Meg page the peripheral resides in. */
var peripheralBaseAddr = 0x54400000;

/* Configure the corresponding MMU page descriptor accordingly */
Mmu.setFirstLevelDescMeta(peripheralBaseAddr,
                        peripheralBaseAddr,
                        peripheralAttrs);

System.SupportProxy = SysMin;

Mmu.enableMMU = true; enables the MMU. Mmu.setFirstLevelDescMeta sets the page of memory starting at peripheralBaseAddr to be non cacheable as described in peripheralAttrs. There is a quirk here where the A9 uses the A8’s MMU configuration. This is intended.

var socType           = "am437x";

/* Load the PRUSS package */
var Pruss = xdc.loadPackage('ti.drv.pruss');
Pruss.Settings.socType = socType;

/* Load the uart package */
var Uart              = xdc.loadPackage('ti.drv.uart');
Uart.Settings.socType = socType;

/*use CSL package*/
var Csl = xdc.loadPackage('ti.csl');
Csl.Settings.deviceType = socType;

/* Load the board package */
var Board = xdc.loadPackage('ti.board');
Board.Settings.boardName = "<YOUR_BOARD_HERE>";

The above configuration code loads in the modules neccesary to load the PRU from the A9.

11. Board options for <YOUR_BOARD_HERE> can be found in <PDK>/Packages/ti/board/src. Change <YOUR_BOARD_HERE> to be one of those options listed.

12. You will need the PRU program that you wish to load to be in hex array format as a .h file that is included in your project folder. Instructions on how to do that can be found above in the Compiling to PRU section.

15. You’ll need to create a target configuration file in order to launch your board and initialize PRU-ICSS. You can do this by navigating to Window > Show View > Target Configurations. Then select New Target Configuration File. Select your Board and Connection type and select save.

common/PRU-ICSS/../images/PRURTOSScreenshot9.png

Fig. 3.13 Screenshot of a sample Target Configuration File setup screen for the IDK_AM437X

  1. Right-click the newly created .ccxml file and select Launch selected configuration

17. Connect to the CortexA9, Reset the CPU, and then navigate to Scripts > PRU_ICSS > PRU_ICSS_INIT and select it.

  1. Load the PRU program and run it.
  2. Connect to a PRU in PRU-ICSS0 and pause it. Navigate to Window > Show View > Disassembly and select it.
common/PRU-ICSS/../images/PRURTOSScreenshot14.png

Fig. 3.14 All of the selections that you need to make are highlighted. Hover over each one to see what it does.

  1. The PRU Program that you compiled into a hex array should now appear in the IRAM of the PRU.

AM572X:

  1. Launch CCS and open a Workspace
  2. Go to File > New > CCS Project

3. Select your Target in the first dropdown menu and your Board in the second dropdown menu. Select your Connection in the third dropdown menu.

4. Select the Cortex A [ARM] tab and give your project a name. Select the GNU (Linaro) compiler.

5. Under Project templates and examples select SYS/BIOS and then GNU Target Examples and finally Typical.

common/PRU-ICSS/../images/PRURTOSScreenshot3.png

Fig. 3.15 Screenshot of sample CCS settings for a PRU loading project

6. Select Next >. Under Products and Repositories select am572x PDK, SYS/BIOS, and XDAIS.

  1. Select the Platform that you’re using from the drop down menu. Select Finish.
common/PRU-ICSS/../images/PRURTOSScreenshot12.png

Fig. 3.16 Screenshot of sample libraries selected for a PRU loading project on the IDK_AM572 Platform

8. Right click the project folder in the Project Explorer. Select Properties from the drop down menu. Select CCS Build > GNU Linker > Libraries

9. Select Add… in the top bar of the Libraries box. Click Browse. Navigate to: <PDK Directory>/packages/ti/osal/lib/tirtos/am572x/a15/release. You should see a file titled ti.osal.aa15fg. If you don’t see the file, make sure you’re browsing all file types. Select that file.

common/PRU-ICSS/../images/PRURTOSScreenshot6.png

Fig. 3.17 Screenshot of the library screen in the GNU Linker for a PRU loading project

10. Open your app.cfg file in the project. Copy the code found in pru-software-support-package/Getting_Started_Labs/PRU_FROM_RTOS/app572.cfg into your app.cfg:

There are a few things that should be noted in this configuration file:

var socType           = "am572x";

/* Load the PRUSS package */
var Pruss = xdc.loadPackage('ti.drv.pruss');
Pruss.Settings.socType = socType;

/* Load the uart package */
var Uart              = xdc.loadPackage('ti.drv.uart');
Uart.Settings.socType = socType;

/*use CSL package*/
var Csl = xdc.loadPackage('ti.csl');
Csl.Settings.deviceType = socType;

/* Load the board package */
var Board = xdc.loadPackage('ti.board');
Board.Settings.boardName = "<YOUR_BOARD_HERE>";

The above configuration code loads in the modules neccesary to load the PRU from the A15.

11. Board options for <YOUR_BOARD_HERE> can be found in <PDK>/Packages/ti/board/src. Change <YOUR_BOARD_HERE> to be one of those options listed.

12. You will need the PRU program that you wish to load to be in hex array format as a .h file that is included in your project folder. Instructions on how to do that can be found above in the Compiling to PRU section.

15. You’ll need to create a target configuration file in order to launch your board and initialize PRU-ICSS. You can do this by navigating to Window > Show View > Target Configurations. Then select New Target Configuration File. Select your Board and Connection type and select save.

common/PRU-ICSS/../images/PRURTOSScreenshot9.png

Fig. 3.18 Screenshot of a sample Target Configuration File setup screen for the IDK_AM572X

  1. Right-click the newly created .ccxml file and select Launch selected configuration

17. Connect to the CortexA15, Reset the CPU, and then navigate to Scripts > AM572X MULTICORE Initialization > AM572X_MULTICORE_EnableAllCores and select it.

  1. Load the PRU program and run it.
  2. Connect to a PRU in PRU-ICSS0 and pause it. Navigate to Window > Show View > Disassembly and select it.
common/PRU-ICSS/../images/PRURTOSScreenshot14.png

Fig. 3.19 All of the selections that you need to make are highlighted. Hover over each one to see what it does.

  1. The PRU Program that you compiled into a hex array should now appear in the IRAM of the PRU.

Initializing the PRU from non-OS Core