Update all READMEs, port HW UART & MAC C code examples from PSSP#132
Open
nsaulnier-ti wants to merge 6 commits into
Open
Update all READMEs, port HW UART & MAC C code examples from PSSP#132nsaulnier-ti wants to merge 6 commits into
nsaulnier-ti wants to merge 6 commits into
Conversation
Review Summary by Qodo(Agentic_describe updated until commit c1493d3)Port HW UART and MAC C examples from PSSP and standardize repository documentation
WalkthroughsDescription• **Port HW UART and MAC C code examples from PSSP**: Added two new firmware projects (uart_loopback and mac_c) ported from the PRU Software Support Package, demonstrating UART peripheral loopback and MAC (Multiply-Accumulate) hardware accelerator functionality • **Comprehensive build infrastructure**: Added makefiles, linker configurations, and CCS project specifications for multiple processor variants (AM62x-SK, AM64x-EVM) and PRU cores (PRU0, PRU1) • **Updated all README files**: Standardized documentation across the repository with consistent structure including Introduction, Supported Combinations, and Validated HW & SW sections with hardware/software version tables • **Enhanced academy and examples documentation**: Updated parent README files to reference new projects and improved formatting consistency across all example and academy project documentation • **Build system integration**: Updated academy makefile to include new projects in the build system • **Note**: Ported code has not been tested on silicon yet Diagramflowchart LR
PSSP["PSSP Projects<br/>UART & MAC"]
PORT["Port to<br/>OpenPRU"]
UART["UART Loopback<br/>Project"]
MAC["MAC C<br/>Project"]
BUILD["Build Infrastructure<br/>Makefiles & Configs"]
DOCS["Standardized<br/>Documentation"]
PSSP -- "Port code" --> PORT
PORT --> UART
PORT --> MAC
UART --> BUILD
MAC --> BUILD
BUILD --> DOCS
File Changes1. academy/uart/uart_loopback/firmware/main.c
|
Code Review by Qodo
Context used 1. Validated HW & SW TODOs
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+18
to
+25
| | Processor | Hardware | Software | | ||
| | --------- | -------- | --------------------------------------- | | ||
| | am243x | TODO | MCU PLUS SDK TODO, OpenPRU TODO | | ||
| | am261x | TODO | MCU PLUS SDK TODO, OpenPRU TODO | | ||
| | am263x | TODO | MCU PLUS SDK TODO, OpenPRU TODO | | ||
| | am263px | TODO | MCU PLUS SDK TODO, OpenPRU TODO | | ||
| | am62x | TODO | OpenPRU TODO | | ||
| | am64x | TODO | MCU PLUS SDK TODO, OpenPRU TODO | |
There was a problem hiding this comment.
1. todo markers in readmes 📘 Rule violation ⚙ Maintainability
New documentation introduces multiple TODO placeholders, which violates the requirement to use only FIXME markers for pending work. This reduces searchability/standardization of pending-work annotations across the repo.
Agent Prompt
## Issue description
New/updated documentation contains `TODO` placeholders, but the repository standard requires using only `FIXME` markers for pending work.
## Issue Context
Several “Validated HW & SW” tables were added with placeholder values like `TODO` and `MCU PLUS SDK TODO`.
## Fix Focus Areas
- academy/getting_started_labs/assembly_code/solution/readme.md[18-25]
- academy/crc/crc/readme.md[32-36]
- examples/empty/readme.md[20-25]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+1
to
+6
| /* | ||
| * AM62x_PRU0.cmd | ||
| * | ||
| * Example Linker command file for linking programs built with the C compiler | ||
| * on AM62x PRU0 cores | ||
| */ |
There was a problem hiding this comment.
2. linker.cmd missing ti copyright 📘 Rule violation ⚙ Maintainability
New linker command files include a filename header but omit the required Texas Instruments copyright statement. This creates a licensing/traceability compliance gap for newly added source files.
Agent Prompt
## Issue description
New `linker.cmd` files lack the required Texas Instruments copyright statement.
## Issue Context
These files were added as part of new example ports and should carry the standard TI copyright header.
## Fix Focus Areas
- academy/mac/mac_c/firmware/am62x-sk/pruss0_pru0_fw/ti-pru-cgt/linker.cmd[1-6]
- academy/uart/uart_loopback/firmware/am62x-sk/pruss0_pru0_fw/ti-pru-cgt/linker.cmd[1-6]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+1
to
+4
| /* | ||
| * Copyright (C) 2024-2024 Texas Instruments Incorporated - http://www.ti.com/ | ||
| * | ||
| * |
There was a problem hiding this comment.
3. main.c header missing filename 📘 Rule violation ⚙ Maintainability
New C firmware files include a TI copyright/license block but do not include a file-name header as required. This reduces traceability and violates the mandated header format.
Agent Prompt
## Issue description
New C sources include the TI license but not a file-name header line.
## Issue Context
The compliance checklist requires both (1) a file name header and (2) a TI copyright statement.
## Fix Focus Areas
- academy/uart/uart_loopback/firmware/main.c[1-4]
- academy/mac/mac_c/firmware/main.c[1-4]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+8
to
+14
| * | ||
| * * Redistributions of source code must retain the above copyright | ||
| * notice, this list of conditions and the following disclaimer. | ||
| * | ||
| * * Redistributions in binary form must reproduce the above copyright | ||
| * notice, this list of conditions and the following disclaimer in the | ||
| * documentation and/or other materials provided with the |
There was a problem hiding this comment.
4. Tabs in main.c 📘 Rule violation ⚙ Maintainability
New C source files include tab characters in the header/comment formatting, violating the whitespace standard that disallows tabs. This can lead to inconsistent formatting across tooling and editors.
Agent Prompt
## Issue description
Tab characters are present in new C source files, violating the whitespace standard.
## Issue Context
The standard requires spaces-only indentation/whitespace for source and documentation.
## Fix Focus Areas
- academy/mac/mac_c/firmware/main.c[8-15]
- academy/uart/uart_loopback/firmware/main.c[8-15]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+123
to
+127
| - [AM64x](https://software-dl.ti.com/mcu-plus-sdk/esd/AM64X/latest/exports/docs/api_guide_am64x/CCS_PROJECTS_PAGE.html) | ||
| - [AM243x](https://software-dl.ti.com/mcu-plus-sdk/esd/AM243X/latest/exports/docs/api_guide_am243x/CCS_PROJECTS_PAGE.html) | ||
| - [AM261x](https://software-dl.ti.com/mcu-plus-sdk/esd/AM261X/latest/exports/docs/api_guide_am261x/CCS_PROJECTS_PAGE.html) | ||
| - [AM263Px](https://software-dl.ti.com/mcu-plus-sdk/esd/AM263PX/latest/exports/docs/api_guide_am263px/CCS_PROJECTS_PAGE.html) | ||
| - [AM263x](https://software-dl.ti.com/mcu-plus-sdk/esd/AM263X/latest/exports/docs/api_guide_am263x/CCS_PROJECTS_PAGE.html |
There was a problem hiding this comment.
5. Broken am263x link 🐞 Bug ≡ Correctness
README.md’s AM263x MCU+ SDK documentation link is missing the closing ')', breaking the markdown link rendering for that bullet (and potentially affecting subsequent markdown parsing in some renderers).
Agent Prompt
### Issue description
The AM263x markdown link in the root README is missing a closing `)`.
### Issue Context
This breaks link rendering in the main repository README.
### Fix Focus Areas
- README.md[123-127]
### Suggested change
Add the missing `)` at the end of the AM263x link so it matches the other bullets.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
pratheesh-ti
requested review from
dhavaljk,
manojKoppolu,
pratheesh-ti and
tleyrer
manojKoppolu
requested changes
Apr 6, 2026
| /* Perform numMacs MAC operations */ | ||
| for (i = 0; i < numMacs; i++) { | ||
| result += (uint64_t)buf[i].op1 * (uint64_t)buf[i].op2; | ||
| } |
Member
There was a problem hiding this comment.
mac firmware based example uses broadside accelerator to do multiplication
But mac_c example, multiplication code ( (uint64_t)buf[i].op1 * (uint64_t)buf[i].op2 ) code in main.c file will get split into series of additions in generated assembly file, should we consider documenting this ?
| This project was tested on hardware with these software versions: | ||
|
|
||
| | Processor | Hardware | Software | | ||
| | --------- | -------- | --------------------------------------- | |
Member
There was a problem hiding this comment.
Do we plan to replace these TODO with specific hardware and MCU PLU SDK verision, OpenPRU version at which this example is supported before merging this PR ?
nsaulnier-ti
force-pushed
the
a0226750_ai_import_pssp
branch
from
34e250f to
622958a
Compare
Review Summary by QodoPort UART and MAC C examples from PSSP and update all repository documentation
WalkthroughsDescription• Port HW UART loopback project from PRU Software Support Package (PSSP) with firmware implementation for AM62x processor • Port MAC (Multiply-Accumulate) C code example from PSSP with support for AM62x and AM64x processors • Add comprehensive build configuration files (makefiles, linker scripts, CCS project specifications) for both new projects across multiple processor variants • Standardize and update all README files across the repository to align with OpenPRU v2026.01.00 • Add "Training" section to main README with links to PRU Academy resources • Improve build instructions documentation with dedicated "Building MCU+ projects in CCS" subsection • Standardize documentation format across all academy labs and examples with consistent "Validated HW & SW" sections • Update academy project registry and build system to include new MAC C and UART loopback projects Diagramflowchart LR
PSSP["PSSP Examples<br/>UART & MAC"]
UART["UART Loopback<br/>Firmware"]
MAC["MAC C<br/>Firmware"]
BUILD["Build Config<br/>Makefiles & Linker"]
DOCS["README Updates<br/>Standardization"]
REGISTRY["Academy Registry<br/>& Build System"]
PSSP -->|"Port"| UART
PSSP -->|"Port"| MAC
UART -->|"Configure"| BUILD
MAC -->|"Configure"| BUILD
BUILD -->|"Document"| DOCS
UART -->|"Register"| REGISTRY
MAC -->|"Register"| REGISTRY
DOCS -->|"Update"| REGISTRY
File Changes1. academy/uart/uart_loopback/firmware/main.c
|
|
Persistent review updated to latest commit 622958a |
Comment on lines
+28
to
+36
| ## Validated HW & SW | ||
|
|
||
| This project was tested on hardware with these software versions: | ||
|
|
||
| | Processor | Hardware | Software | | ||
| | --------- | -------- | --------------------------------------- | | ||
| | am261x | TODO | MCU PLUS SDK TODO, OpenPRU TODO | | ||
| | am263px | TODO | MCU PLUS SDK TODO, OpenPRU TODO | | ||
| | am263x | TODO | MCU PLUS SDK TODO, OpenPRU TODO | |
There was a problem hiding this comment.
1. validated hw & sw todos 📎 Requirement gap ⚙ Maintainability
Multiple project READMEs claim hardware validation but leave the tested hardware/software versions as TODO, which does not document the actual tested SDK versions for the current changes. This can mislead users about what environment was truly validated.
Agent Prompt
## Issue description
Several project READMEs include a `Validated HW & SW` section but still contain `TODO` placeholders instead of the actual SDK/version(s) that were built and tested on real hardware.
## Issue Context
Compliance requires documenting the *actual* tested SDK versions for the current changes; placeholders are not acceptable.
## Fix Focus Areas
- academy/crc/crc/readme.md[28-36]
- academy/getting_started_labs/c_code/solution/readme.md[13-24]
- examples/fft/README.md[17-25]
- examples/custom_frequency_generator/README.md[17-24]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+1
to
+2
| export OPEN_PRU_PATH?=$(abspath ../../../../../../..) | ||
| include $(OPEN_PRU_PATH)/imports.mak |
There was a problem hiding this comment.
2. open_pru_path cwd-dependent 📘 Rule violation ☼ Reliability
The new makefiles derive OPEN_PRU_PATH using $(abspath ../../...), which depends on the caller's working directory and can break includes when invoked from other locations. This violates the portability requirement for computing repo root relative to the makefile directory.
Agent Prompt
## Issue description
`OPEN_PRU_PATH` is computed using `$(abspath ../../...)`, which can break if the makefile is invoked from a different working directory.
## Issue Context
Compliance requires computing repo-root paths relative to the current makefile location, not the invocation directory.
## Fix Focus Areas
- academy/mac/mac_c/firmware/am62x-sk/pruss0_pru0_fw/ti-pru-cgt/makefile[1-2]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+143
to
+151
| /* Because we are doing loopback, wait until LSR.DR == 1 | ||
| * indicating there is data in the RX FIFO */ | ||
| while ((CT_UART.LSR1_bit.DR == 0x0)); | ||
|
|
||
| /* Read the value from RBR */ | ||
| buffer[cnt] = CT_UART.RBR_bit.DATA; | ||
|
|
||
| /* Wait for TX FIFO to be empty */ | ||
| while (!((CT_UART.IIR_bit.INTID) == 0x1)); |
There was a problem hiding this comment.
3. Uart while loops unbounded 📘 Rule violation ☼ Reliability
The new UART loopback firmware uses busy-wait while loops with no timeout, which can hang indefinitely if UART state never changes. This violates the requirement that loops have explicit termination conditions for deterministic PRU firmware.
Agent Prompt
## Issue description
UART polling uses unbounded busy-wait loops (`while (...) ;`) with no timeout.
## Issue Context
On PRU firmware, unbounded loops can break determinism and hang the core if the peripheral never reaches the expected state.
## Fix Focus Areas
- academy/uart/uart_loopback/firmware/main.c[143-151]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+57
to
+60
| 1. Clocking, pin-mux configuration and interrupts are specified graphically using | ||
| sysconfig tool and example.syscfg file located in folder | ||
| "\path\to\open-pru\examples\LCD_interface\am243x-lp\r5fss0-0_freertos". | ||
|
|
There was a problem hiding this comment.
4. Docs use backslashes 📘 Rule violation ⚙ Maintainability
Documentation includes Windows-style backslashes in a path example, which is not portable and violates the requirement to use forward slashes for paths/links. This can confuse users and may break copy/paste on non-Windows environments.
Agent Prompt
## Issue description
The README uses Windows-style backslashes in an example path.
## Issue Context
Documentation paths must be portable across environments and use forward slashes.
## Fix Focus Areas
- examples/LCD_interface/readme.md[57-60]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| | m_transfer_packet_spi_master_gpo_sclk | SPI Master side macro to read 1 data packet and write 1 data packet concurrently through the SPI interface. | (4+d1)+(6+d2) cycles | 27.77MHz | d1 =9, d2 =7 | 12.8MHz | ||
| ## Overview | ||
| ### Timing Parameters | ||
| All cycle level frequency calculations are based on a 333MHz PRU System clock, which gives 3ns per instruction cycle, i.e $t_{f} = 3ns$ |
There was a problem hiding this comment.
5. i.e. used 📘 Rule violation ⚙ Maintainability
Documentation uses i.e. instead of the prescribed terminology that is. This violates the required documentation terminology standard.
Agent Prompt
## Issue description
The SPI loopback README uses `i.e.` which is disallowed terminology.
## Issue Context
Docs/comments must use prescribed terminology (`that is`, `for example`, `and so on`).
## Fix Focus Areas
- examples/spi_loopback/readme.md[10-10]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Import PRU Software Support Package (PSSP) project https://git.ti.com/cgit/pru-software-support-package/pru-software-support-package/tree/examples/am62x/PRU_MAC_Multiply_Accum https://git.ti.com/cgit/pru-software-support-package/pru-software-support-package/tree/examples/am64x/PRU_MAC_Multiply_Accum into the OpenPRU repository. This is a test of new documentation to guide AI agents to perform specific actions in the OpenPRU project. This project tested the action "create a new OpenPRU project", when the project does not require any pinmux, SysConfig, etc. The project creation was done by claude code. However, I had to code quite a few manual fixes after the initial project creation. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Import PRU Software Support Package (PSSP) project https://git.ti.com/cgit/pru-software-support-package/pru-software-support-package/tree/examples/am62x/PRU_Hardware_UART into the OpenPRU repository. This is a test of new documentation to guide AI agents to perform specific actions in the OpenPRU project. This project tested the action "create a new OpenPRU project", when the project does not require any pinmux, SysConfig, etc. The project creation was done by claude code. However, I had to code quite a few manual fixes after the initial project creation. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Add the new mac_c and uart projects to the academy/makefile & academy/readme.md files. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
These projects are used as the template for most new projects created in the OpenPRU repository. Update the README template to look the way we expect new project README files to look. Additionally, point to central documentation for creating a new project or building a project, instead of replicating that information per-project. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Standardize the README format to match examples/empty. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
Standardize the README format to match examples/empty. Signed-off-by: Nick Saulnier <nsaulnier@ti.com>
nsaulnier-ti
force-pushed
the
a0226750_ai_import_pssp
branch
from
622958a to
c1493d3
Compare
|
Persistent review updated to latest commit c1493d3 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Update all README files in the OpenPRU repository to align with the latest OpenPRU v2026.01.00.
Port the HW UART project from the PRU Software Support Package (PSSP) as well as the C code version of the MAC example.
The project ports were used to test the behavior of AI agents based on #130.
This pull request should be merged in before #128
Ported code has not been tested on silicon yet
The README updates are the first step to addressing #42