AN 056: Using the Titanium LPDDR4 Debug Tool Example
Introduction
In memory management and performance optimization, precise settings play a crucial role in ensuring optimal system operation and reliability. Efinix provides a Python-based LPDDR4 Debug Tool example design for use with either the Titanium Ti375C529 Development Board, Titanium Ti375N1156 Development Board, Titanium Ti180 M484 Development Board, or Titanium Ti180 J484 Development Board. Use the example design to demonstrate how to use the LPDDR4 Debug Tool to help you obtain the optimal settings and debug the LPDDR4 controller in supported Titanium FPGAs.
Features
- Memory initialization and I/O calibration
- CA training
- Write leveling
- Gate training
- Read leveling
- Write DQ training
- Hardware memory tests with linear feedback shift register (LFSR) data patterns
- Valid timing window observation with memory test
- Mode Register Read (MRR) and Mode Register Write (MRW)
Notice: Refer to Using the LPDDR4 Debug Tool with Your Board for more
information when you want to use the LPDDR4 Debug Tool with other
boards.
Hardware and Software Requirements
- Titanium Ti375C529 Development Board, Titanium Ti375N1156 Development Board, Titanium Ti180 M484 Development Board, or Titanium Ti180 J484 Development Board
- USB cable
- Terminal software
- Efinity software v2025.1.110.1.5 or later (required for recompilation)
Download the LPDDR4 Debug Tool Example Design to the Board
About this task
The memory efficiency tester includes a bitstream file to get you started quickly. Download it to the board using these steps:
Procedure
- Download the file ti_lpddr4_debug_tool-v<version>.zip from the Support Center.
- Connect the development board to your computer using a USB cable.
- In the Efinity Programmer, under Programming Mode, select SPI Active using JTAG Bridge .
- Under Image, click the Select Image File button and select tools_core.hex file located in the ti_lpddr4_debug_tools\bsp\<device> directory.
- Click the Start Program button.
Running the LPDDR4 Debug Tool Example Design
About this task
To run LPDDR4 Debug Tool:
Procedure
-
Set up your Efinity environment:
-
In the terminal, change the path to:
ti_lpddr4_debug_tools\bsp\<dev>. -
Type the following command and press Enter:
efx_run tools_core.xml --flow interface(to generate the interface file, only necessary for the first time). - In the terminal, change to the extracted LPDDR4 Debug Tool directory.
- Run the console.py with the tool option and if applicable, the options arguments, then press enter. See LPDDR4 Debug Tool Arguments and Options for the list of available options and arguments.
-
In the terminal, change the path to:
ti_lpddr4_debug_tools\bsp\<dev>. -
Type the following command and press Enter:
efx_run tools_core.xml --flow interface(to generate the interface file, only necessary for the first time).
Example
Example 1: Execute the
Program
python3 console.py --dev TI180J484
==================================================================
======================EFINIX LPDDR4 Uility v2.0===================
==================================================================
Type: LPDDR4x
Data width: 16
Density: 4G bit
Frequency: 1066 Mhz
Rank: 1
Chip Select Map: 1
AXI1: 66.67 Mhz
--> Calibration item Menu:
----> init LPDDR4 initialization
----> io I/O Calibration
----> calvl CA Training
----> wrlvl Write Leveling
----> gatlvl Gate Leveling
----> rdlvl Read Leveling
----> wdqlvl Write DQ Leveling
----> all Run all above process
--> Memory Quick Test Menu:
----> mtest4 4MB Size Memory Test
----> mtest16 16MB Size Memory Test
----> mtest32 32MB Size Memory Test
----> mtest64 64MB Size Memory Test
----> mtest128 128MB Size Memory Test
----> mtest256 256MB Size Memory Test
----> mtest512 512MB Size Memory Test
----> mtest1024 1024MB Size Memory Test
--> Memory efficiency Test Menu:
----> eff Default Memory efficiency Test
--> Others Option:
----> mrw LPDDR4 Mode Register Write
----> mrr LPDDR4 Mode Register Read
Select Option:Example 2: Run All
>Select Option: all
Read Memory controller ID PASS
Read pi controller ID PASS
---DDR Initialization---
cs mapping = 1
Write CTL Register
Write PHY Register
Write PI Register
PLL locked
MC Initialization Done
PI PLL = True
---DDR Initialization Done---
---I/O Calibration---
IO pass 1 calibration done
IO pass 2 calibration done
CA Training result in (ps)
||===== CA =====||===== MIN =====||===== MAX ====||=== CENTER ===||== EYE WIDTH ==||== EYE WIDTH% ==||
|| CA0 || 1088.33 || 1830.37 || 1459.35 || 742.04 || 79 ||
[-------------------ooooooooooooo--------------------------------]
|| CA1 || 1071.84 || 1835.86 || 1453.85 || 764.03 || 81 ||
[-------------------ooooooooooooo--------------------------------]
|| CA2 || 1077.33 || 1830.37 || 1453.85 || 753.03 || 80 ||
[-------------------ooooooooooooo--------------------------------]
|| CA3 || 1066.34 || 1797.39 || 1431.87 || 731.05 || 77 ||
[-------------------oooooooooooo---------------------------------]
|| CA4 || 1055.35 || 1764.41 || 1409.88 || 709.06 || 75 ||
[------------------ooooooooooooo---------------------------------]
|| CA5 || 1099.32 || 1835.86 || 1467.59 || 736.54 || 78 ||
[-------------------ooooooooooooo--------------------------------]
MR12 = 0x20
CS0 Vref CA = 22.8% Range = 0
MR12 = 0x20
CS2 Vref CA = 22.8% Range = 0
---Write Leveling---
Write DQS Delay Slice0 = 120.93ps
Write DQS Delay Slice1 = 109.93ps
---Gate Leveling---
Gate DQS Delay slice 0 = 3832.96 ps
Gate DQS Delay slice 1 = 3832.96 ps
---Read Leveling---
Rising Read leveling result in (ps)
||===== DQ =====||===== MIN =====||===== MAX ====||=== CENTER ===||== EYE WIDTH ==||== EYE WIDTH% ==||
|| DQ0 || 43.97 || 461.71 || 252.84 || 417.74 || 89 ||
[--oooooooooooooo------------------------------------------------]
|| DQ1 || 65.96 || 461.71 || 263.83 || 395.76 || 84 ||
[---ooooooooooooo------------------------------------------------]
|| DQ2 || 43.97 || 461.71 || 252.84 || 417.74 || 89 ||
[--oooooooooooooo------------------------------------------------]
|| DQ3 || 43.97 || 461.71 || 252.84 || 417.74 || 89 ||
[--oooooooooooooo------------------------------------------------]
|| DQ4 || 21.99 || 461.71 || 241.85 || 439.73 || 93 ||
[-ooooooooooooooo------------------------------------------------]
|| DQ5 || 65.96 || 461.71 || 263.83 || 395.76 || 84 ||
[---ooooooooooooo------------------------------------------------]
|| DQ6 || 43.97 || 461.71 || 252.84 || 417.74 || 89 ||
[--oooooooooooooo------------------------------------------------]
|| DQ7 || 87.95 || 461.71 || 274.83 || 373.77 || 79 ||
[---ooooooooooooo------------------------------------------------]
|| DQ8 || 21.99 || 439.73 || 230.86 || 417.74 || 89 ||
[-ooooooooooooooo------------------------------------------------]
|| DQ9 || 65.96 || 439.73 || 252.84 || 373.77 || 79 ||
[---ooooooooooooo------------------------------------------------]
|| DQ10 || 21.99 || 439.73 || 230.86 || 417.74 || 89 ||
[-ooooooooooooooo------------------------------------------------]
|| DQ11 || 87.95 || 439.73 || 263.84 || 351.78 || 75 ||
[---ooooooooooooo------------------------------------------------]
|| DQ12 || 43.97 || 461.71 || 252.84 || 417.74 || 89 ||
[--oooooooooooooo------------------------------------------------]
|| DQ13 || 65.96 || 439.73 || 252.84 || 373.77 || 79 ||
[---ooooooooooooo------------------------------------------------]
|| DQ14 || 43.97 || 439.73 || 241.85 || 395.76 || 84 ||
[--oooooooooooooo------------------------------------------------]
|| DQ15 || 87.95 || 461.71 || 274.83 || 373.77 || 79 ||
[---ooooooooooooo------------------------------------------------]
Falling Read leveling result in (ps)
||===== DQ =====||===== MIN =====||===== MAX ====||=== CENTER ===||== EYE WIDTH ==||== EYE WIDTH% ==||
|| DQ0 || 21.99 || 329.8 || 175.9 || 307.81 || 65 ||
[-ooooooooooo----------------------------------------------------]
|| DQ1 || 43.97 |LPDDR4 Debug Tool Arguments and Options
You use the main.py script's arguments and options to run and customize the LPDDR4 Debug Tool features.
init
| Usage | init |
| Options | – |
| Description | Run DDR initialization. |
io
| Usage | io |
| Options | – |
| Description | Run I/O calibration. |
calvl
| Usage | calvl |
| Options | – |
| Description | Run CA leveling. |
wrlvl
| Usage | wrlvl |
| Options | – |
| Description | Run write leveling. |
gatlvl
| Usage | gatlvl |
| Options | – |
| Description | Run gate leveling. |
rdlvl
| Usage | rdlvl |
| Options | – |
| Description | Run read leveling. |
wdqlvl
| Usage | wdqlvl |
| Options | – |
| Description | Run write DQ leveling. |
mtest<size>
| Usage | mtest<size> |
| Options | |
| Description | Run hardware memory test with a data pattern. |
mrr
| Usage | mrr <addr> |
| Options |
<ADDR>: Mode register address to read |
| Description | Read the mode register. |
mrw
| Usage | mrw <ADDR> <DATA> |
| Options |
<ADDR>: Mode register address to write to<DATA>: Data to be written |
| Description | Write to the mode register. |
all
| Usage | all |
| Options | – |
| Description | Run full calibration with a single argument consisting of
init, io, calvl,
wrlvl, gatlvl, rdlvl,
and wdqlvl. |
eff
| Usage | eff |
| Options | – |
| Description | Run memory efficiency test. |
Using the LPDDR4 Debug Tool with Your Board
You need to modify some settings and recompile the LPDDR4 Debug Tool project file (tools_core.xml) if you want to use it for boards other than the Titanium Ti180 J484 Development Board. After modifying the settings, recompile the project with Efinity software v2025.1.110.1.5 or later. The following table summarizes the changes that you must consider:
| Settings | Description |
|---|---|
| PLL Settings | Modify the PLL resource and output clock according to your board design in the Interface Designer. |
| Project Settings | Select your FPGA in the Efinity Project Editor. |
Copy the defaulted project folder from /bsp and modify the new name that you want.
Example:
python3 console.py --dev<new_name>Revision History
| Date | Version | Description |
|---|---|---|
| July 2025 | 2.3 | Update Hardware and Software Requirements.
(DOC-2637) Update Download the LPDDR4 Debug Tool Example Design to the Board. (DOC-2637) Update Running the LPDDR4 Debug Tool Example Design. (DOC-2637) Update
Using the LPDDR4 Debug Tool with Your Board.
(DOC-2637) |
| April 2025 | 2.2 | Update Introduction. (DOC-2501) Update Hardware and Software Requirements.
(DOC-2501) Update Download the LPDDR4 Debug Tool Example Design to the Board.
(DOC-2501) |
| August 2024 | 2.1 | Fixed typo in Running the LPDDR4 Debug Tool Example Design. (DOC-2007) |
| January 2024 | 2.0 | Added Ti180 J484 Development Board in Introduction and Hardware and
Software Requirements. (DOC-1667) Updated section LPDDR4 Debug Tool
Arguments and Options and Using the LPDDR4 Debug Tool with Your
Board. Updated file location in section Download the
LPDDR4 Debug Tool Example Design to the Board. |
| July 2022 | 1.0 | Initial release. |