****************************************************************** _______ ________ ________ _______ ____ ____ _ |__ __| | ____\ \ / / ____| |__ __/ __ \ / __ \| | | | | |__ \ \_/ /| |__ | | | | | | | | | | | | | __| \ / | __| | | | | | | | | | | | | | |____ | | | |____ | | | |__| | |__| | |____ |_| |______| |_| |______| |_| \____/ \____/|______| ****************************************************************** Introduction -------------------------- The DDR margin firmware and supporting scripts are designed measure and visualize the amount of DDR margin on the system. A user must setup the target device and configure the DDR with their own configuration; once this is done the firmware can be loaded and then run to collect information on the margin of the system. In the process of running, the tool will change the contents of DDR and render it unusable for periods of time. Therefore, no other applications using DDR can be running when the firmware is active, otherwise error conditions will occur in the application due to invalid data. It is therefore recommended that the firmware is the only active code running on the device when the margin of a system is being measured. Contents provided -------------------------- - _TEye_A53_read.out The statically linked baremetal firmware that runs on the target device. This will the measure the amount of read margin the SoC has. - pip_freeze.txt Contains the python packages required to run the visualization python script, used in environment setup. - parse_eye_diagrams.py Python post processing script used to process logs from the firmware. Will calculate and visualize margin and print into a report. Installation and setup details -------------------------- Hardware required -------------------------- - Host PC(s) to connect to the target device at runtime and post-process the log output - One host PC can fulfill both roles, or the logs can be collected with one PC and then processed on another. - Compatible SoC - AM64x - AM62x - AM62A - AM62P - UART port pinned out on the board - AM64x - MAIN_UART0 (referred to as just "UART0" in the TRM) - AM62x - MAIN_UART0 (referred to as just "UART0" in the TRM) - AM62A - MAIN_UART0 (referred to as just "UART0" in the TRM) - AM62P - MAIN_UART0 (referred to as just "UART0" in the TRM) - UART connection to host PC - (Highly Recommended) JTAG connection to load code using CCS/Eclipse/Lauterbach/etc. - This is the easiest way to load the tool Python -------------------------- For the host PC that will run the post-processing scripts, the below steps are required: 1) Install Python 3.11.4 (https://www.python.org/downloads/release/python-3114/) 2) Make a new directory and paste pip_freeze.txt into it 3) To configure the python environment and packages, use the commands below: py -3.11 -m venv "teye_env" cd teye_env source Scripts/activate python -m pip install -r ../pip_freeze.txt 4) The virtual environment is now setup with all the required python packages. Serial Terminal -------------------------- For the host PC that will be connected to the target device during runtime, serial terminal software is required. Free software like TeraTerm or Putty are popular options. The below settings are configured by the firmware for UART serial communication: - 115200 Baud Rate - 8-bit data - No Parity - 1 Stop bit - No Flow control It is also recommended to increase the buffer size from the default value in your serial software. The firmware logs can be thousands of lines long, exceeding the default buffer setting in some programs. Target device software/requirements -------------------------- Requires the device PLLs and PSCs for an A53, the DDRSS, and UART0 to be enabled beforehand. In addition, the user must configure the DDR with their own configuration before running the firmware. This configuration is what will be tested by the firmware. *** For AM62x specifically, the M4F must be powered on. This is because the M4 internal memory is leveraged on that device. The firmware will handle all A53 core setup (bootcode, MMU, etc.) and configure the UART registers for communication over UART0. CCS (Optional) -------------------------- Code composer studio is an IDE provided by TI to allow quick development over JTAG for designs. It comes with out of the box support for Evaluation Boards (EVMs) and with a compatible JTAG debugger allows for seamless loading of code. Loading and running the firmware -------------------------- We will use an AM62A-SK-EVM as an example, but the same concepts apply to any EVM and any board. JTAG Load -------------------------- Loading the tool using CCS is the easiest method, as TI provides GEL files with CCS for all processors that can be used and adapted to initialize the power, clocks, and configure the DDRSS. EXAMPLE: SK-AM62A-LP EVM 1) Create a target configuration. CCS comes pre-populated with files for the SK-AM62A-LP EVM. a) Connection = XDS110 b) Board = AM62A_SK_EVM 2) Power on the board and launch the target configuration 3) Launch the serial application, like TeraTerm. a) Determining the COM port can be tricky, but it is usually the first non-XDS COM port available 4) Connect to the SMS0_TIFS_0 core b) On target connection, GELs will automatically run to configure clocks and power to the device 5) From the Scripts tab, highlight "DDR Init from SMS" and then click "Init_SKEVM_LPDDR4_from_SMS" 6) All of the pre-requisites for the tool are now completed, it can be loaded to any A53 core. a) Right click on A53SS0_CORE0_0 and click "Connect Target" b) From the Run tab, click "Load" and then "Load Program" c) Browse to the downloaded location of the firmware .out file, then click okay. 7) The firmware is now loaded to the A53. Hit the resume button (green play icon) and the firmware will now run. 8) Wait until the firmware has finished, then copy the output in the serial terminal to a text file. UART Load -------------------------- The firmware is like any other application and can be packaged to boot from any bootmode. It can be flashed using UNIFLASH or loaded via UART boot using scripts in the MCU+SDK. The tool still requires an application that will configure the power and clocks for an A53, UART, and DDRSS. The MCU+SDK is not required for functionality of the firmware, but for using the tools in for non-JTAG loading. As an example we will be loading the firmware over UART boot to an AM62A-SK-EVM. This method only requires using the UART connection on the J17 micro-USB connector. The overall concept extends to any board. EXAMPLE: SK-AM62A-LP EVM 1) Configure the device for UART boot using the bootmode switches 2) Download the latest MCU+SDK from the board product page (https://www.ti.com/tool/SK-AM62A-LP) 3) We will use the tools provided in the MCU+SDK to convert the firmware into an application image. Full details on these scripts can be found in the MCU+SDK documentation. .out -> .rprc -> .appimage a) node out2rprc/elf2rprc.js out2rprc/AM62A_AM62P_TEye_A53_read.out b) node multicoreImageGen/multicoreImageGen.js --devID 55 --out AM62A_AM62P_TEye_A53_read_unsigned.appimage AM62A_AM62P_TEye_A53_read.rprc@0 4) The application image can be loaded over UART boot using the uart bootloader python scripts. For example, for COM port x: python uart_bootloader.py -p COMx --bootloader=sbl_prebuilt/am62ax-sk/sbl_uart.release.tiimage --file=sbl_prebuilt/am62ax-sk/sbl_null.release.tiimage --file=../../tools/boot/AM62A_AM62P_TEye_A53_read_unsigned.appimage 5) Open up a serial terminal shortly to start capturing the tool output. This can be queued up after the python script, for COM port x: ; & "C:\Program Files (x86)\teraterm\ttermpro.exe" /C=x 6) Wait for the tool to complete, then save the serial output to a text file. Post-processing output -------------------------- The output of the tool can be processed using the provided python script. Copy the UART output from the serial terminal to a text file. Then from the directory of the virtual environment setup previously: 1) Activate virtual environment if not already active source Scripts/activate python parse_eye_diagrams.py 2) Report will be .pdf