am243x : add configuration of pulse per revolution

[a1248924]

signed-off by Ayushman a-ayushman@ti.com

[qodo-code-review]

PR Summary by Qodo

Add PPR-Based QPOSMAX and Pulse-Loss Detection for AM243x

✨ Enhancement 🐞 Bug fix 📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Bounds each PRU position counter using configurable PPR-derived QPOSMAX.
• Publishes modulus and edge direction through DMEM for reliable R5F diagnostics.
• Adds optional pulse-loss detection, documentation, and AM243x-LP project metadata.

Diagram

graph TD
  ENC["Encoder A/B"] --> PRU["Six PRU Cores"] --> DMEM[("Shared DMEM")] --> R5F["R5F Polling"] --> DIAG["EQEP Diagnostics"]
  CFG["Build Constants"] --> PRU

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Runtime per-channel QPOSMAX configuration

• ➕ Supports different encoder PPR values across the six channels.
• ➕ Allows PPR changes without rebuilding and reflashing PRU firmware.
• ➖ Requires a validated startup handshake before edge capture begins.
• ➖ Adds ownership, synchronization, and invalid-value handling to the shared-memory protocol.

2. Generate the shared-memory ABI

• ➕ Prevents C and assembly offset definitions from drifting apart.
• ➕ Makes future shared fields easier to add consistently across all channels.
• ➖ Introduces generation tooling into both PRU and R5F build paths.
• ➖ Requires build-system integration beyond this example's current scope.

Recommendation: The compile-time QPOSMAX cached by each PRU is appropriate for deterministic edge processing and a fixed-encoder example. Retain this approach for the current PR, but consider generating the shared-memory layout to reduce offset drift; adopt runtime per-channel configuration only if heterogeneous encoders or field reconfiguration become requirements.

Files changed (15) +443 / -177

Enhancement (5) +308 / -151

macros.incDefine QPOSMAX and pulse-loss firmware settings +6/-0

Define QPOSMAX and pulse-loss firmware settings

• Adds a PPR-derived QPOSMAX build constant with a default value of 3999. Adds a compile-time switch for optional firmware pulse-loss counting.

examples/pru_eqep/firmware/include/macros.inc

memory.incExtend the PRU/R5F shared-memory layout +19/-0

Extend the PRU/R5F shared-memory layout

• Reserves a register for cached QPOSMAX and defines per-channel DMEM offsets for QPOSMAX, last direction, and pulse-loss counters.

examples/pru_eqep/firmware/include/memory.inc

main.asmBound QPOS and publish direction diagnostics +37/-0

Bound QPOS and publish direction diagnostics

• Publishes and caches QPOSMAX at startup, then wraps position within zero through QPOSMAX in both capture paths. It also publishes the last edge direction and optionally counts decrement events for forward-only pulse-loss testing.

examples/pru_eqep/firmware/main.asm

eqep_diagnostic.hAdd shared QPOSMAX, direction, and pulse-loss state +42/-25

Add shared QPOSMAX, direction, and pulse-loss state

• Extends each ABZ channel configuration with pointers and local state for firmware-published QPOSMAX, last direction, and pulse-loss diagnostics. It also normalizes comments for coding-style compliance.

examples/pru_eqep/mcuplus/eqep_diagnostic.h

pru_eqep_example.cConsume firmware QPOSMAX and pulse-loss diagnostics +204/-126

Consume firmware QPOSMAX and pulse-loss diagnostics

• Maps the new shared-memory fields, reads QPOSMAX after firmware startup, and uses firmware-published direction instead of an ambiguous position delta. Adds optional pulse-loss tracking, status output, and a local flag-clear API while cleaning up comments.

examples/pru_eqep/mcuplus/pru_eqep_example.c

Documentation (3) +117 / -7

pulse_loss_detection_flow_chart.pngAdd pulse-loss detection flowchart +0/-0

Add pulse-loss detection flowchart

• Adds a visual reference explaining the optional phase-and-direction pulse-loss detection workflow.

examples/pru_eqep/images/pulse_loss_detection_flow_chart.png

readme.mdDocument QPOSMAX configuration and pulse-loss testing +113/-7

Document QPOSMAX configuration and pulse-loss testing

• Expands the example overview, PPR/QPOSMAX configuration instructions, pulse-loss limitations, phase-error behavior, execution steps, and validated environment. It also documents the revised direction mechanism and shared-memory layout.

examples/pru_eqep/readme.md

readme.mdRegister PRU EQEP in the examples catalog +4/-0

Register PRU EQEP in the examples catalog

• Adds the PRU EQEP example description and marks AM243x as its supported processor.

examples/readme.md

Other (7) +18 / -19

example.projectspecIdentify the PRU0 project as EQEP firmware +2/-2

Identify the PRU0 project as EQEP firmware

• Renames the generic empty project title and description to identify the PRU EQEP firmware.

examples/pru_eqep/firmware/am243x-lp/icss_g0_pru0_fw/ti-pru-cgt/example.projectspec

example.projectspecIdentify the PRU1 project as EQEP firmware +2/-2

Identify the PRU1 project as EQEP firmware

• Replaces the generic empty-project metadata with PRU EQEP firmware naming.

examples/pru_eqep/firmware/am243x-lp/icss_g0_pru1_fw/ti-pru-cgt/example.projectspec

example.projectspecIdentify the RTU PRU0 project as EQEP firmware +2/-2

Identify the RTU PRU0 project as EQEP firmware

• Updates the project title and description to reflect its EQEP firmware purpose.

examples/pru_eqep/firmware/am243x-lp/icss_g0_rtu_pru0_fw/ti-pru-cgt/example.projectspec

example.projectspecIdentify the RTU PRU1 project as EQEP firmware +2/-2

Identify the RTU PRU1 project as EQEP firmware

• Updates the project metadata from an empty template to PRU EQEP firmware.

examples/pru_eqep/firmware/am243x-lp/icss_g0_rtu_pru1_fw/ti-pru-cgt/example.projectspec

example.projectspecIdentify the TX PRU0 project as EQEP firmware +2/-2

Identify the TX PRU0 project as EQEP firmware

• Labels the project and its description as PRU EQEP firmware.

examples/pru_eqep/firmware/am243x-lp/icss_g0_tx_pru0_fw/ti-pru-cgt/example.projectspec

example.projectspecIdentify the TX PRU1 project as EQEP firmware +2/-2

Identify the TX PRU1 project as EQEP firmware

• Replaces generic empty-project metadata with PRU EQEP firmware metadata.

examples/pru_eqep/firmware/am243x-lp/icss_g0_tx_pru1_fw/ti-pru-cgt/example.projectspec

example.syscfgSimplify and accelerate diagnostic UART logging +6/-7

Simplify and accelerate diagnostic UART logging

• Disables CSS logging, removes unused shared and memory log settings, and configures the diagnostic UART for 921600 baud.

examples/pru_eqep/mcuplus/am243x-lp/r5fss0-0_freertos/example.syscfg

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

⚠️ 2 lower-priority findings omitted to fit the comment size limit; re-run the review or view the findings in the Qodo portal.

1. Diagonal pulse losses go unreported ✓ Resolved 🐞 Bug ≡ Correctness

Description

The TEST_PULSE_LOSS polling block sets pulse_loss_flag only when the firmware decrement counter
changes, despite phase errors being tracked separately immediately above it. When a missed forward
pulse creates a diagonal transition, firmware increments only the phase-error counter and the
pulse-loss-only status output remains clear.

Code

examples/pru_eqep/mcuplus/pru_eqep_example.c[R433-436]

+            if (curr_pulse_loss_count != ABZHandle[ch]->pulse_loss_count_last_seen)
+            {
+                ABZHandle[ch]->pulse_loss_flag = 1;
+                ABZHandle[ch]->pulse_loss_count_last_seen = curr_pulse_loss_count;

Evidence

Firmware routes LUT value 3 to PHASE_ERR_CNT_OFFSET and exits before the decrement path, while
only LUT value 2 reaches the new pulse-loss counter increment. The host detects phase-counter
changes into phase_error_flag, but its new pulse-loss block watches only pulse_loss_count, and
pulse-loss mode prints only pulse_loss_flag; the new guide explicitly says diagonal phase errors
are pulse-loss evidence.

examples/pru_eqep/firmware/main.asm[180-204]
examples/pru_eqep/mcuplus/pru_eqep_example.c[393-439]
examples/pru_eqep/mcuplus/pru_eqep_example.c[467-475]
examples/pru_eqep/readme.md[207-217]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The pulse-loss diagnostic sets `pulse_loss_flag` only for changes to `pulse_loss_count`, so diagonal transitions recorded through the phase-error counter do not appear as pulse losses.

## Fix Focus Areas
- examples/pru_eqep/mcuplus/pru_eqep_example.c[398-439]

## Recommended Fix
When the phase-error counter changes, also set `pulse_loss_flag` under `TEST_PULSE_LOSS`. Trigger this from the counter-change event rather than the sticky `phase_error_flag`, so `EQEP_PRU_clearPulseLossFlag()` can clear the loss indication independently without it being immediately restored by an old phase error.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Pulse-loss reports use stale times ⊘ Outdated 🐞 Bug ≡ Correctness

Description

The diagnostic logs cur_ts before EQEP_Get_Speed_ABZ refreshes it from the current write
pointer. The first event can therefore show zero, and any event below the four-edge processing
threshold or at the start of a new batch shows a previous batch's timestamp.

Code

examples/pru_eqep/mcuplus/pru_eqep_example.c[R413-415]

+            if (ABZHandle[ch]->direction == -1 || ABZHandle[ch]->phase_error_flag == 1)
+            {
+                DebugP_log("Pulse loss detected for channel %d at timestamp %d \n",ch,ABZHandle[ch]->cur_ts);

Evidence

The log occurs before the threshold check and speed-function call, while cur_ts is assigned only
inside that later function after its write pointer is updated.

examples/pru_eqep/mcuplus/pru_eqep_example.c[411-422]
examples/pru_eqep/mcuplus/pru_eqep_example.c[459-465]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The pulse-loss diagnostic prints the cached speed-processing timestamp before that value is refreshed, so the report does not identify when the detected event occurred. The timestamp remains zero or stale when fewer than four edges have accumulated.

## Fix Focus Areas
- examples/pru_eqep/mcuplus/pru_eqep_example.c[411-421]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[459-465]

## Recommended Fix
Capture the timestamp associated with the detected transition directly from the current ring-buffer entry before emitting the diagnostic. Do not depend on the later threshold-gated speed calculation to update the value used by the report.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Brief pulse losses go undetected ✓ Resolved 🐞 Bug ≡ Correctness

Description

The pulse-loss check reads only the firmware's single last-edge direction byte, which is overwritten
on every processed edge. When a decrement caused by lost pulses is followed by a normal forward edge
before the host polls, the forward value replaces the evidence and the decrement-only loss is never
reported.

Code

examples/pru_eqep/mcuplus/pru_eqep_example.c[R411-414]

+#ifdef TEST_PULSE_LOSS
+            /* Assuming that the direction set for this test is positive/forward (+1)*/
+            if (ABZHandle[ch]->direction == -1 || ABZHandle[ch]->phase_error_flag == 1)
+            {

Evidence

The host samples one latest-direction value and tests it for decrement, while firmware stores a new
value at the same address after every increment or decrement. There is no history or counter
preserving a decrement after a subsequent forward edge.

examples/pru_eqep/mcuplus/pru_eqep_example.c[400-415]
examples/pru_eqep/firmware/main.asm[140-158]
examples/pru_eqep/readme.md[210-215]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The pulse-loss test relies on a last-edge direction byte that a subsequent forward edge can overwrite before the host observes the decrement. This causes decrement-only pulse losses to be missed whenever multiple encoder edges occur between host polls.

## Fix Focus Areas
- examples/pru_eqep/mcuplus/pru_eqep_example.c[411-417]
- examples/pru_eqep/firmware/main.asm[140-158]

## Recommended Fix
Publish a persistent unexpected-decrement event counter or event record from firmware instead of relying solely on the latest direction byte. Have the host compare that counter with its last-seen value and report every newly recorded event.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View high (5)

4. Three encoder channels lose direction ✗ Dismissed 🐞 Bug ≡ Correctness

Description

The new qposmax_base and last_dir_base pointers for channels 3–5 derive from baseMemAddr1,
which always points at pru1DramBase, although those firmware builds select C24/PRU0 DRAM. Whenever
slice-1 firmware publishes the added metadata, the host reads the alternate bank, so QPOSMAX is
cached incorrectly and direction output for those three channels remains unset.

Code

examples/pru_eqep/mcuplus/pru_eqep_example.c[R300-302]

+    ABZHandle[3]->last_dir_base = (uint8_t *)((uint32_t)(ABZHandle[3]->baseMemAddr1) + CH0_LAST_DIR_OFFSET);
+    ABZHandle[4]->last_dir_base = (uint8_t *)((uint32_t)(ABZHandle[4]->baseMemAddr1) + CH0_LAST_DIR_OFFSET);
+    ABZHandle[5]->last_dir_base = (uint8_t *)((uint32_t)(ABZHandle[5]->baseMemAddr1) + CH0_LAST_DIR_OFFSET);

Evidence

The host initializes every baseMemAddr1 from pru1DramBase, then the added code derives all six
metadata pointers from it. Firmware definitions instead select C25 for channels 0–2 and C24 for
channels 3–5, and the new firmware stores use that selected DMEM1; the polling loop consequently
reads direction for channels 3–5 from a bank their firmware does not update.

examples/pru_eqep/mcuplus/pru_eqep_example.c[259-265]
examples/pru_eqep/mcuplus/pru_eqep_example.c[290-302]
examples/pru_eqep/firmware/include/memory.inc[127-173]
examples/pru_eqep/firmware/main.asm[64-67]
examples/pru_eqep/firmware/main.asm[189-201]
examples/pru_eqep/mcuplus/pru_eqep_example.c[394-403]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Channels 3–5 read QPOSMAX and last-direction metadata from PRU1 DRAM, while their firmware writes those fields through C24 into PRU0 DRAM.

## Fix Focus Areas
- examples/pru_eqep/mcuplus/pru_eqep_example.c[259-302]
- examples/pru_eqep/firmware/include/memory.inc[127-173]

## Recommended Fix
Select the shared metadata DRAM base according to the firmware core: use PRU1 DRAM for channels 0–2, whose firmware selects C25, and PRU0 DRAM for channels 3–5, whose firmware selects C24. Derive the QPOSMAX and last-direction pointers from that selected base while preserving each channel's four-byte offset.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Large pulse counts cannot be configured ✗ Dismissed 🐞 Bug ≡ Correctness

Description

main loads the 32-bit QPOSMAX into qposmax_reg with the 16-bit ldi instruction, and the
second underflow path repeats that instruction when reloading QPOS. Any documented PPR above
16,384 produces a maximum above 0xFFFF, so the firmware cannot build with or correctly apply that
configuration across overflow and decrement wrap.

Code

examples/pru_eqep/firmware/main.asm[71]

+    ldi   qposmax_reg, QPOSMAX

Evidence

The README permits setting QPOSMAX to (PPR × 4) − 1 without a 16-bit limit. The firmware already
uses ldi32 to publish QPOSMAX and in the first underflow path, while the new cache initialization
and duplicated second underflow path use ldi, demonstrating inconsistent immediate widths for the
same configurable value.

examples/pru_eqep/readme.md[183-197]
examples/pru_eqep/firmware/main.asm[64-71]
examples/pru_eqep/firmware/main.asm[152-154]
examples/pru_eqep/firmware/main.asm[195-197]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The configurable QPOSMAX can exceed the 16-bit immediate range accepted by `ldi`, preventing larger pulse-per-revolution values from being represented correctly.

## Fix Focus Areas
- examples/pru_eqep/firmware/main.asm[71-71]
- examples/pru_eqep/firmware/main.asm[197-197]

## Recommended Fix
Load the cached maximum with `ldi32 qposmax_reg, QPOSMAX`. In the underflow paths, copy the already cached 32-bit value into `QPOS` with `mov QPOS, qposmax_reg` or consistently use `ldi32`, ensuring every documented 32-bit QPOSMAX value is handled identically.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Idle direction stays nonzero ✗ Dismissed 🐞 Bug ≡ Correctness

Description

The polling loop unconditionally converts the firmware's sticky last-edge byte into ±1, overriding
the zero assigned for “no change” on every idle pass. After the first encoder edge, status and
position APIs therefore continue reporting motion direction indefinitely while the shaft is
stationary.

Code

examples/pru_eqep/mcuplus/pru_eqep_example.c[R404-406]

+            uint8_t last_dir = HW_RD_REG8((uint32_t)ABZHandle[ch]->last_dir_base);
+            if      (last_dir == 1) ABZHandle[ch]->direction =  1;
+            else if (last_dir == 2) ABZHandle[ch]->direction = -1;

Evidence

The host establishes zero as the no-change result, then always overwrites it when the persistent
byte is 1 or 2. Firmware writes LAST_DIR only in processed transition paths and has no idle-loop
clear, while the second host reader likewise maps the retained byte to ±1.

examples/pru_eqep/mcuplus/pru_eqep_example.c[370-371]
examples/pru_eqep/mcuplus/pru_eqep_example.c[397-406]
examples/pru_eqep/firmware/main.asm[140-158]
examples/pru_eqep/firmware/main.asm[183-201]
examples/pru_eqep/mcuplus/pru_eqep_example.c[569-575]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`LAST_DIR` records the last processed edge and is not cleared when no edge occurs, so reading it unconditionally makes an idle channel retain ±1 instead of reporting zero.

## Issue Context
The main loop explicitly resets direction to zero for no change, but the sticky firmware byte immediately overwrites it. `EQEP_Get_position_ABZ` has the same behavior. Add a firmware-owned edge sequence/change indicator so R5F applies `LAST_DIR` only when a new edge has occurred since its previous sample; avoid having R5F clear PRU-owned memory.

## Fix Focus Areas
- examples/pru_eqep/firmware/main.asm[147-158]
- examples/pru_eqep/firmware/main.asm[190-201]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[397-406]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[569-575]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. Unsynced QPOSMAX read ✓ Resolved 🐞 Bug ☼ Reliability

Description

R5F reads qposmax immediately after starting the PRU cores, but there is no handshake/ready flag
ensuring the PRU has executed its boot-time sbco publish yet. If the read happens first (DMEM is
zeroed at init), modulus becomes 1 and the new direction wrap logic produces incorrect direction
results.

Code

examples/pru_eqep/mcuplus/pru_eqep_example.c[R318-325]

+    /* Read QPOSMAX once, after firmware start: PRU publishes it to DMEM
+     * during its own init block (before the capture loop begins), so it
+     * is guaranteed valid here. Read once, not per-poll, since firmware
+     * never rewrites it again after boot. */
+    for (int i = 0; i < 6; i++)
+    {
+        ABZHandle[i]->qposmax = HW_RD_REG32((uint32_t)ABZHandle[i]->qposmax_base);
+    }

Evidence

PRU publishes QPOSMAX at boot, but R5F reads it immediately after core enable without any
synchronization; since ABZ_PRU_ICSS_Init clears PRU data RAM to 0, an early read can return 0 and
invalidate the modulus-based direction calculation.

examples/pru_eqep/firmware/main.asm[64-68]
examples/pru_eqep/mcuplus/pru_eqep_example.c[141-208]
examples/pru_eqep/mcuplus/pru_eqep_example.c[318-325]
examples/pru_eqep/mcuplus/pru_eqep_example.c[210-218]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
R5F reads `ABZHandle[i]->qposmax` right after `EQEP_pruss_load_run_fw()`, assuming PRU has already published `QPOSMAX` into DMEM1. However, core enable is asynchronous and DMEM is explicitly zeroed during init, so this read can return `0` transiently. That makes `modulus = qposmax + 1` equal `1` and breaks the new modulus-based direction computation.

### Issue Context
- PRU publishes QPOSMAX once at boot via `sbco`.
- R5F enables PRU cores and immediately reads QPOSMAX.
- PRU data RAM is cleared to 0 before firmware start.

### Fix Focus Areas
- examples/pru_eqep/mcuplus/pru_eqep_example.c[141-208]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[318-325]
- examples/pru_eqep/firmware/main.asm[64-68]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[210-218]

### Suggested fix
Implement a simple readiness handshake, e.g.:
1) Reserve a DMEM1 `READY` word per channel (or reuse an existing safe location).
2) PRU writes `QPOSMAX` and then writes `READY=0xA5A5A5A5`.
3) R5F loops with a timeout waiting for `READY` before reading `QPOSMAX` (or loops until `qposmax != 0`).
4) If timeout, log an error and fall back to a safe default (or abort).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

8. Rollover reverses reported direction ✓ Resolved 🐞 Bug ≡ Correctness

Description

The firmware now wraps QPOS from 3999 to 0 and from 0 to 3999, while both R5F readers determine
direction using subtraction modulo 2^32. A forward boundary crossing therefore produces a negative
difference and reports reverse, while a reverse crossing reports forward.

Code

examples/pru_eqep/firmware/main.asm[R135-136]

+    qbge    no_qpos_overflow0, QPOS, scratch2   ; jump if scratch2 >= QPOS (i.e. QPOS <= QPOSMAX)
+    ldi     QPOS, 0

Evidence

The added firmware code reloads QPOS to zero after its configured maximum and reloads QPOSMAX after
decrementing below zero. However, the polling reader explicitly documents and implements only 32-bit
rollover handling at pru_eqep_example.c lines 359-375, and EQEP_Get_position_ABZ repeats that
subtraction at lines 538-544; with QPOSMAX=3999, 3999→0 yields -3999 and 0→3999 yields +3999.

examples/pru_eqep/firmware/main.asm[131-146]
examples/pru_eqep/firmware/main.asm[173-188]
examples/pru_eqep/firmware/include/macros.inc[56-57]
examples/pru_eqep/mcuplus/pru_eqep_example.c[348-375]
examples/pru_eqep/mcuplus/pru_eqep_example.c[526-545]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Firmware now bounds QPOS using `QPOSMAX`, but R5F direction calculations still assume modulo-2^32 rollover. Update direction detection to use the configured counter modulus so crossings between zero and QPOSMAX preserve the actual direction.

## Issue Context
Both polling and `EQEP_Get_position_ABZ()` use signed subtraction intended for `0xFFFFFFFF` rollover. Ensure the host and firmware obtain QPOSMAX from a synchronized definition or shared configuration rather than duplicating an independently editable value.

## Fix Focus Areas
- examples/pru_eqep/firmware/main.asm[131-146]
- examples/pru_eqep/firmware/main.asm[173-188]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[348-375]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[526-545]
- examples/pru_eqep/firmware/include/macros.inc[56-57]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

9. Users cannot find the R5F project ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The run guide names the application project pru_eqep_am243x-lp_r5fss0-0_freetos_ti-arm-clang, but
the project directory uses the freertos spelling. Following step 3 therefore points users to a
nonexistent project name before they can build the R5F application.

Code

examples/pru_eqep/readme.md[264]

+3. Now build the project pru_eqep_am243x-lp_r5fss0-0_freetos_ti-arm-clang (Here after will be called r5f project).

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The run instructions refer to `pru_eqep_am243x-lp_r5fss0-0_freetos_ti-arm-clang`, but the application project uses `freertos`, so users cannot locate the project named in step 3.

## Fix Focus Areas
- examples/pru_eqep/readme.md[264-264]

## Recommended Fix
Change `freetos` to `freertos` in the project name in step 3, preserving the rest of the documented project path and name.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

10. Loss totals omit diagonal events ✗ Dismissed 🐞 Bug ≡ Correctness

Description

pulse_loss_count is assigned only from the firmware's decrement counter even though the same host
block classifies phase errors as pulse losses. A diagonal transition takes the phase-error branch
before decrement handling, so that detected class sets the loss flag without increasing the field
documented as the total number of losses seen.

Code

examples/pru_eqep/mcuplus/pru_eqep_example.c[R438-439]

+            /* We can track the total number of times pulse loss was seen with pulse_loss_count field for each channel */
+            ABZHandle[ch]->pulse_loss_count = curr_pulse_loss_count;

Evidence

Both firmware paths branch directly from a phase error to capture_wrap, bypassing the newly added
decrement-counter increment. The host nevertheless treats phase_error_flag as a pulse loss but
copies only curr_pulse_loss_count into the field whose comment claims to track all times pulse
loss was seen.

examples/pru_eqep/firmware/main.asm[132-156]
examples/pru_eqep/firmware/main.asm[180-204]
examples/pru_eqep/mcuplus/pru_eqep_example.c[428-439]
examples/pru_eqep/readme.md[212-217]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The aggregate pulse-loss count includes decrement detections but excludes diagonal transitions detected through the phase-error counter.

## Fix Focus Areas
- examples/pru_eqep/firmware/main.asm[132-156]
- examples/pru_eqep/firmware/main.asm[180-204]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[393-440]

## Recommended Fix
Maintain the host-visible total from changes in both the firmware decrement counter and the phase-error counter. Increment it by each counter's newly observed delta, preserving the separate raw counters and avoiding double counting because phase-error transitions bypass decrement handling.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

11. Loss timestamps are never reported ✗ Dismissed 🐞 Bug ◔ Observability

Description

The startup message in pru_eqep_example_main promises a timestamp for each detected pulse loss,
but the enabled diagnostic output prints only six channel flags. When users investigate a loss, the
periodic status path provides neither an event timestamp nor the current channel timestamp.

Code

examples/pru_eqep/mcuplus/pru_eqep_example.c[367]

+    DebugP_log("Pulse loss test active, if pulse loss detected, the corresponding channel and timestamp at which Pulse loss happened will be logged below ...\r\n");

Evidence

The startup text explicitly promises a channel and timestamp, while the only pulse-loss status log
prints the six pulse_loss_flag values and has no timestamp argument.

examples/pru_eqep/mcuplus/pru_eqep_example.c[366-368]
examples/pru_eqep/mcuplus/pru_eqep_example.c[467-475]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The pulse-loss startup message promises that detected losses will be logged with timestamps, but the diagnostic output only prints channel flags.

## Fix Focus Areas
- examples/pru_eqep/mcuplus/pru_eqep_example.c[366-368]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[467-475]

## Recommended Fix
Either remove the timestamp claim from the startup message, or capture and print an event timestamp when each pulse-loss counter changes. Keep the message aligned with the implemented output.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View medium (8)

12. Users cannot enable the loss test ✓ Resolved 🐞 Bug ≡ Correctness

Description

The configuration guide tells users to disable line 101 even though that line is an
already-commented TEST_PULSE_LOSS definition. Following the instruction leaves every test-specific
conditional block excluded from the build instead of enabling the diagnostic.

Code

examples/pru_eqep/readme.md[R199-203]

+### 8e. Enabling Pulse Loss test following phase/direction method 
+
+Disable line 101 in pru_eqep_example.c to enable pulse loss detection 
+
+`Note : This test assumes that the fixed direction is forward (+1)` 

Evidence

The source definition is commented out, and all new diagnostic behavior is guarded by `#ifdef
TEST_PULSE_LOSS`; disabling that line cannot activate those blocks.

examples/pru_eqep/readme.md[199-203]
examples/pru_eqep/mcuplus/pru_eqep_example.c[97-101]
examples/pru_eqep/mcuplus/pru_eqep_example.c[348-350]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The guide says to disable a line that is already commented out, but the diagnostic is enabled only when that definition is active. Users following the documented procedure cannot build the pulse-loss test.

## Fix Focus Areas
- examples/pru_eqep/readme.md[199-203]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[97-101]

## Recommended Fix
Tell users to uncomment `#define TEST_PULSE_LOSS` before rebuilding the example. Avoid referring only to a line number, which can change as the source is edited.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

13. Users get the wrong detection limits ✗ Dismissed 🐞 Bug ≡ Correctness

Description

The table classifies three missed forward edges as a reverse transition and four as a same-state
transition. In the documented four-state sequence, three missed edges return to the previous state
and four lead to an ordinary forward transition, so both cases are invisible to this detector.

Code

examples/pru_eqep/readme.md[R221-224]

+|1, 5, 9, ...	| Diagonal transition |	Phase error
+|2, 6, 10, ...	|Looks like a reverse step	| Direction = decrement
+|3, 7, 11, ...	|Looks like a reverse step	| Direction = decrement
+|4, 8, 12, ...	|Lands back on the same state	| Not detected

Evidence

Starting from 00 in the documented forward sequence, missing three intermediate edges makes the
next observed state 00, while missing four makes it 10. The transition table maps 00→00 to no
change and 00→10 to increment, neither of which satisfies the new decrement-or-phase-error
condition.

examples/pru_eqep/readme.md[205-224]
examples/pru_eqep/mcuplus/pru_eqep_example.c[519-526]
examples/pru_eqep/mcuplus/pru_eqep_example.c[411-416]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The pulse-loss table incorrectly describes the observed transition after three and four missed quadrature edges. This overstates which losses the phase-or-direction detector can identify.

## Fix Focus Areas
- examples/pru_eqep/readme.md[205-226]

## Recommended Fix
Change the three-missed-edge row to same-state and not detected, and change the four-missed-edge row to a normal forward transition and not detected. Update the following explanation to state that both same-state and normal-forward aliases can hide losses.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

14. One loss floods the diagnostic output ✓ Resolved 🐞 Bug ☼ Reliability

Description

The diagnostic tests the sticky phase_error_flag and calls DebugP_log on every pass through the
unbounded polling loop. After one phase error, the flag remains set and the same report is emitted
continuously, obscuring later events and slowing the loop that drains encoder data.

Code

examples/pru_eqep/mcuplus/pru_eqep_example.c[R413-416]

+            if (ABZHandle[ch]->direction == -1 || ABZHandle[ch]->phase_error_flag == 1)
+            {
+                DebugP_log("Pulse loss detected for channel %d at timestamp %d \n",ch,ABZHandle[ch]->cur_ts);
+            }  

Evidence

A phase-counter change sets the local flag to one, but the new diagnostic has no clear, state-change
check, or rate limit before logging inside while (1). The only clearing function is separate and
is not invoked by this path.

examples/pru_eqep/mcuplus/pru_eqep_example.c[354-387]
examples/pru_eqep/mcuplus/pru_eqep_example.c[411-417]
examples/pru_eqep/mcuplus/pru_eqep_example.c[590-594]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The pulse-loss block logs continuously after a sticky phase-error flag becomes set. A single error therefore generates unbounded duplicate UART messages from the polling loop.

## Fix Focus Areas
- examples/pru_eqep/mcuplus/pru_eqep_example.c[376-387]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[411-417]

## Recommended Fix
Trigger logging from a newly observed phase-error counter change rather than the sticky summary flag. Track the last reported event or counter value so each firmware event produces at most one message.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

15. Direction can mismatch position ✗ Dismissed 🐞 Bug ≡ Correctness

Description

pru_eqep_example_main reads the shared position and last_dir_base independently while firmware
publishes them with two separate stores and no snapshot protocol. If an encoder reverses between
either pair of accesses, the cached position can describe one edge while the reported direction
describes another, and the inconsistent pair reaches the channel status output and position helper.

Code

examples/pru_eqep/mcuplus/pru_eqep_example.c[R401-403]

+            uint8_t last_dir = HW_RD_REG8((uint32_t)ABZHandle[ch]->last_dir_base);
+            if      (last_dir == 1) ABZHandle[ch]->direction =  1;
+            else if (last_dir == 2) ABZHandle[ch]->direction = -1;

Evidence

The firmware writes position and direction through separate stores, while both host paths load them
separately without a sequence counter, retry, or handshake. The status logger subsequently presents
the independently cached values together, establishing a concrete path for a reversal-time
inconsistent sample to become visible.

examples/pru_eqep/firmware/main.asm[140-158]
examples/pru_eqep/firmware/main.asm[183-201]
examples/pru_eqep/mcuplus/pru_eqep_example.c[383-405]
examples/pru_eqep/mcuplus/pru_eqep_example.c[420-425]
examples/pru_eqep/mcuplus/pru_eqep_example.c[557-571]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Firmware publishes position and last direction separately, and the host also reads them separately. Concurrent execution can therefore combine values from different edges during a direction reversal.

## Fix Focus Areas
- examples/pru_eqep/firmware/main.asm[143-158]
- examples/pru_eqep/firmware/main.asm[186-201]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[391-403]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[557-571]

## Recommended Fix
Add a shared sequence counter around each firmware position-and-direction update, marking the snapshot in progress before either store and complete afterward. Have both host readers retry until they read the same completed sequence value before and after loading position and direction.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

16. Z edges erase direction ✗ Dismissed 🐞 Bug ≡ Correctness

Description

The decrement fall-through unconditionally publishes qpos_update, so a Z-only transition whose A/B
LUT result is 0 overwrites LAST_DIR with 0. If this occurs after an A/B edge but before R5F polls,
both host readers ignore the 0 and retain an older/default direction instead of reporting the most
recent directional edge.

Code

examples/pru_eqep/firmware/main.asm[158]

+    sbco    &qpos_update, DMEM1, LAST_DIR_OFFSET, 1

Evidence

The firmware wakes for any masked A/B/Z change, while unchanged A/B states map to LUT value 0. The
new unconditional stores at the decrement fall-through therefore publish 0 for Z-only changes, and
the host only acts on values 1 and 2.

examples/pru_eqep/firmware/include/memory.inc[79-92]
examples/pru_eqep/firmware/main.asm[86-92]
examples/pru_eqep/mcuplus/pru_eqep_example.c[500-535]
examples/pru_eqep/firmware/main.asm[149-158]
examples/pru_eqep/mcuplus/pru_eqep_example.c[401-403]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A no-change A/B transition can overwrite `LAST_DIR` with zero because the store after `no_decrement0`/`no_decrement` executes even when `qpos_update` is neither increment nor decrement.

## Issue Context
The capture mask includes Z, so a Z-only edge enters the update path while A/B remains unchanged; LUT states 0x0 and 0xF return zero. `LAST_DIR` should retain the last directional A/B edge.

## Fix Focus Areas
- examples/pru_eqep/firmware/main.asm[147-158]
- examples/pru_eqep/firmware/main.asm[190-201]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

17. Direction flips on long stalls ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new modulus-based rewrap forces qpos_diff into [-modulus/2, modulus/2), which will report the
opposite direction if the polling loop is delayed long enough for QPOS to advance by more than half
the modulus between reads. This can happen during UART logging or task preemption, producing
deterministic wrong direction even without any counter wraparound.

Code

examples/pru_eqep/mcuplus/pru_eqep_example.c[R396-399]

+            int32_t modulus = (int32_t)ABZHandle[ch]->qposmax + 1;
            int32_t qpos_diff = (int32_t)(ABZHandle[ch]->QPOSCOUNT - ABZHandle[ch]->prev_QPOS);
+            if      (qpos_diff >  modulus / 2) qpos_diff -= modulus;
+            else if (qpos_diff < -modulus / 2) qpos_diff += modulus;

Evidence

The newly added modulus-rewrap code explicitly flips large deltas into the opposite sign, and the
same task contains potentially blocking UART logging—making it realistic for deltas to exceed
modulus/2 between reads and thus invert direction.

examples/pru_eqep/mcuplus/pru_eqep_example.c[390-402]
examples/pru_eqep/mcuplus/pru_eqep_example.c[410-427]
examples/pru_eqep/mcuplus/pru_eqep_example.c[561-573]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Direction is derived from a modulus-wrapped delta:
- Compute `qpos_diff = curr - prev`
- If `qpos_diff > modulus/2`, subtract modulus; if `< -modulus/2`, add modulus

If the task stalls (UART prints, preemption, interrupts), `curr-prev` can legitimately exceed `modulus/2` without any wrap, and the current logic will *flip the sign* and report the wrong direction.

### Issue Context
The main loop includes periodic `DebugP_log(...)` calls which can block long enough for many encoder edges to accumulate.

### Fix Focus Areas
- examples/pru_eqep/mcuplus/pru_eqep_example.c[390-402]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[410-427]
- examples/pru_eqep/mcuplus/pru_eqep_example.c[564-573]

### What to change
- Add an explicit ambiguity guard:
 - If `abs(qpos_diff) > modulus/2` (or `>=` depending on your convention), do **not** infer direction from the wrapped delta.
 - Instead set direction to 0/unknown, or keep the previous direction, or (best) fetch direction from a PRU-provided direction signal/metadata.
- Apply the same fix in both places where the modulus rewrap logic exists (main polling loop and `EQEP_Get_position_ABZ`).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

18. Unknown SysCfg property ✗ Dismissed 🐞 Bug ≡ Correctness

Description

The SysCfg file sets debug_log.enableCssLog, but this property is not used anywhere else in the
repo’s SysCfg examples, so SysCfg generation may fail or silently ignore the setting. If
ignored/failing, debug logging configuration will not match what the example expects.

Code

examples/pru_eqep/mcuplus/am243x-lp/r5fss0-0_freertos/example.syscfg[R100-101]

+debug_log.enableUartLog        = true;
+debug_log.enableCssLog         = false;

Evidence

The PR introduces debug_log.enableCssLog, but this key is unique in the repo, while other examples
configure debug_log without it—suggesting it may be unsupported and could break SysCfg processing.

examples/pru_eqep/mcuplus/am243x-lp/r5fss0-0_freertos/example.syscfg[100-110]
examples/spi_loopback/spi_loopback_app/am243x-lp/r5fss0-0_freertos/example.syscfg[62-69]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`example.syscfg` sets `debug_log.enableCssLog`, which appears to be an invalid/unknown configuration knob in this repo context (no other SysCfg uses it). This can break SysCfg generation or lead to the setting being ignored.

### Issue Context
Other example `.syscfg` files configure `debug_log` without any `enableCssLog` field.

### Fix Focus Areas
- examples/pru_eqep/mcuplus/am243x-lp/r5fss0-0_freertos/example.syscfg[100-105]

### What to change
- Confirm the correct SysCfg property name(s) for disabling CCS/shared-mem logging in the `debug_log` module used by this SDK version.
- Replace/remove `debug_log.enableCssLog` accordingly.
- If the intention is “UART-only logging”, align this file with patterns used in other examples (e.g., only `enableUartLog` + uart instance config), or explicitly set the actually-supported shared-mem log toggles.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

19. QPOSMAX reloaded per edge ✓ Resolved 🐞 Bug ➹ Performance

Description

The PRU hot path reloads the constant QPOSMAX via ldi32 on every increment path in both duplicated
LUT blocks, adding extra instructions to the edge-processing critical path. This reduces the maximum
sustainable encoder edge rate compared to loading QPOSMAX once at boot into a dedicated register.

Code

examples/pru_eqep/firmware/main.asm[R139-142]

+    ldi32   scratch2, QPOSMAX
+    qbge    no_qpos_overflow0, QPOS, scratch2   ; jump if scratch2 >= QPOS (i.e. QPOS <= QPOSMAX)
+    ldi     QPOS, 0
+no_qpos_overflow0:

Evidence

The increment paths in both duplicated update blocks perform ldi32 scratch2, QPOSMAX just to do
the wrap compare, despite QPOSMAX being constant and already available to load once in the init
block.

examples/pru_eqep/firmware/main.asm[138-142]
examples/pru_eqep/firmware/main.asm[179-184]
examples/pru_eqep/firmware/main.asm[64-68]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`ldi32 scratch2, QPOSMAX` is executed on every qualifying edge before the wrap compare, even though QPOSMAX is a compile-time constant.

### Issue Context
This firmware claims high-speed capture; adding avoidable instructions inside the per-edge loop reduces the headroom.

### Fix Focus Areas
- examples/pru_eqep/firmware/main.asm[64-68]
- examples/pru_eqep/firmware/main.asm[138-142]
- examples/pru_eqep/firmware/main.asm[179-184]

### Suggested fix
- Load QPOSMAX once during init into an unused register (e.g., `r29`/`r30` depending on conventions), and use that register for both wrap compares.
- Ensure both duplicated LUT-handling blocks use the same cached register so the hot path does not perform constant reloads.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

Review mode: 🚀 Fast: The push is localized to documentation updates and repeated project metadata descriptions, with no runtime logic or behavioral changes.

Tip of the day

💡 Did you know, you can enable the Remediation agent and Qodo fixes findings in a dedicated fix PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[a1248924]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit f8618ff

[a1248924]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit 2ba57e6

[qodo-code-review]

Code review by qodo was updated up to the latest commit 90136a2

[a1248924]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit a3ee65e

[qodo-code-review]

Code review by qodo was updated up to the latest commit 496e405

[qodo-code-review]

Code review by qodo was updated up to the latest commit 9dc4824

[qodo-code-review]

Code review by qodo was updated up to the latest commit f9b5117

[qodo-code-review]

Code review by qodo was updated up to the latest commit 49e2bb7

[a1248924]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit 11abf88

[qodo-code-review]

Code review by qodo was updated up to the latest commit 25cb16d

[qodo-code-review]

Code review by qodo was updated up to the latest commit 2d869e1

[a1248924]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit 2d869e1

[qodo-code-review]

Code review by qodo was updated up to the latest commit 1e8d622

[qodo-code-review]

Code review by qodo was updated up to the latest commit 2caa307

[qodo-code-review]

Code review by qodo was updated up to the latest commit 774f5b1

[qodo-code-review]

Code review by qodo was updated up to the latest commit 530185c

[qodo-code-review]

Code review by qodo was updated up to the latest commit 902a907