Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide

http://www.ti.com

MMWAVE SDK User Guide

Product Release 3.5

Release Date: Sept 30, 2020
Document Version: 1.0

1
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

DOCUMENT LICENSE
This work is licensed under the Creative Commons Attribution-Share Alike 3.0 United States License (CC BY-SA 3.0). To view a copy of this license,
visit http://creativecommons.org/licenses/by-sa/3.0/us/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco,
California, 94105, USA.

COPYRIGHT
Copyright (C) 2014 - 2020 Texas Instruments Incorporated - http://www.ti.com

DISCLAIMER
This mmWave SDK User guide is generic and contains details about all the mmWave devices that are supported by TI in general. However, note that
not all mmWave devices may be supported in a given mmWave SDK release. Please refer to the mmWave SDK Release notes to understand the list
of devices/platforms supported in a given mmWave SDK release.

NOTICE: This software product is used to configure TI’s mmWave devices, including RF emissions parameters for such devices. Note
that many countries or regions impose regulations governing RF emissions. Users are responsible for understanding local RF emission
regulations and operating the product within those regulations.

2
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

CONTENTS

1 Out-of-box mmWave Experience

2 System Overview
2.1 mmWave Suite
2.2 mmWave Demos
2.3 External Dependencies
2.4 Terms used in this document
2.5 Related documentation/links
3 Getting started
3.1 Programming mmWave devices
3.2 Loading images onto mmWave EVM
3.2.1 Demonstration Mode
3.2.2 CCS development mode
3.3 Running the Demos
3.3.1 mmWave Demo
3.3.2 mmWave demo with LVDS-based instrumentation
3.4 Configuration (.cfg) File Format
3.5 Running the prebuilt unit test binaries (.xer4f and .xe674)
4 How-To Articles
4.1 How to identify the COM ports for mmWave EVM
4.2 How to flash an image onto mmWave EVM
4.3 How to erase flash on mmWave EVM
4.4 How to connect mmWave EVM to CCS using JTAG
4.4.1 Emulation Pack Update
4.4.2 Device support package Update
4.4.3 Target Configuration file for CCS (CCXML)
4.4.3.1 Creating a CCXML file
4.4.3.2 Connecting to mmWave EVM using CCXML in CCS
4.5 Developing using SDK
4.5.1 Build Instructions
4.5.2 Setting up build environment
4.5.2.1 Windows
4.5.2.2 Linux
4.5.3 Building demo
4.5.3.1 Building demo in Windows
4.5.3.2 Building demo in Linux
4.5.4 Advanced build
4.5.4.1 Building drivers/control/alg components
4.5.4.2 "Error on warning" compiler and linker setting
5 MMWAVE SDK deep dive
5.1 System Deployment
5.2 Typical mmWave Radar Processing Chain
5.3 Typical Programming Sequence
5.3.1 RF Control Path
5.3.1.1 Single RF Control (MSSRADARSS or DSSRADARSS)
5.3.1.2 Co-operative RF control ((MSS+DSS)<->RADARSS)
5.3.2 Data Path
5.3.2.1 Data processing flow with local domain control
5.3.2.2 Data processing flow with remote domain control
5.3.2.3 Distributed Data processing flow and control
5.4 mmWave SDK - TI components
5.4.1 Demos
5.4.1.1 mmWave Demo
5.4.2 Drivers
5.4.3 OSAL
5.4.4 mmWaveLink
5.4.5 mmWave API
5.4.5.1 Full configuration
5.4.5.2 Minimal configuration
5.4.6 Datapath Interface (DPIF)
5.4.7 Data Processing Units (DPUs)
5.4.8 Data Path Manager (DPM)
5.4.9 Data processing chain (DPC)
5.4.10 mmWaveLib
5.4.11 Group Tracker
5.4.12 Board/EVM Configuration
5.4.13 RADARSS Firmware
5.4.14 CCS Debug Utility

3
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5.4.15 HSI Header Utility

5.4.16 Secondary Bootloader
5.4.17 mmWave SDK - System Initialization
5.4.17.1 ESM
5.4.17.2 SOC
5.4.17.3 Pinmux
5.4.18 Usecases
5.4.18.1 Data Path tests using Test vector method
5.4.18.2 CSI-2 based streaming of ADC data
5.4.18.3 Basic configuration of Front end and capturing ADC data in L3 memory
6 Appendix
6.1 Memory usage
6.2 Register layout
6.3 Enable DebugP logs
6.4 Shared memory usage by SDK demos
6.5 mmWave Device Image Creator
6.6 mmw Demo: cryptic message seen on DebugP_assert
6.7 How to execute Idle instruction in idle task when using SYSBIOS
6.8 Range Bias and Rx Channel Gain/Offset Measurement and Compensation
6.9 Guidelines on optimizing memory usage
6.10 How to add a .const (table) beyond L3 heap in mmWave application where overlay is enabled
6.11 Enabling L3 cache for DSP/C674x on mmWave devices
6.12 DSPlib integration in mmWave C674x based application (Using 2 libraries simultaneously)
6.12.1 Integrating individual functions from each library
6.12.2 Patching the installation
6.13 SDK Demos: miscellaneous information
6.14 Data size restriction for a given session when sending data over LVDS
6.15 CCS Debugging of real time application
6.15.1 Inter-chirp debugging
6.15.2 Inter-frame debugging
6.15.3 Using non-real time chain test code
6.15.4 Using printfs in real time
6.15.5 Viewing hardware registers
6.15.6 Viewing expressions/memory in real time
6.16 Size of Enum

LIST OF FIGURES

Figure 1: mmWave Demo Visualizer- mmWave Device Connectivity

Figure 2: Chirp Diagram

Figure 3: mmWave EVM PC Connectivity - Device Manager - COM Ports
Figure 4: Creating a mmWave device CCXML in CCS
Figure 5: Connecting to mmWave Device in CCS

Figure 6: Autonomous mmWave sensor (Standalone mode)

Figure 7: SDK Layered block diagram
Figure 8: Typical mmWave radar processing chain
Figure 9: Typical mmWave radar processing chain using mmWave SDK components
Figure 10: Scalable data processing chain using mmWave SDK
Figure 11: Typical mmWave radar control flow
Figure 12: mmWave Isolation mode: Detailed Control Flow (Init sequence)
Figure 13: mmWave Isolation mode: Detailed Control Flow (Config sequence)
Figure 14: mmWave Isolation mode: Detailed Control Flow (start sequence)
Figure 15: mmWave Co-operative Mode: Detailed Control Flow (Init sequence)
Figure 16: mmWave Co-operative Mode: Detailed Control Flow (Config sequence)
Figure 17: mmWave Co-operative Mode: Detailed Control Flow (Start sequence)
Figure 18: Typical mmWave Detection Processing Layers
Figure 19: Data processing flow with local domain control (init/config)
Figure 20: Data processing flow with local domain control (start/chirp/frame/stop)
Figure 21: Data processing flow with remote domain control (init/config)
Figure 22: Data processing flow with remote domain control (start/chirp/frame/stop)
Figure 23: Distributed Data processing flow and control (init/config)
Figure 24: Distributed Data processing flow and control (start/chirp/frame/stop)
Figure 25: mmWave SDK Drivers - Internal software design
Figure 26: mmWaveLink - Internal software design
Figure 27: mmWave API - Internal software design
Figure 28: mmWave API - 'Minimal' Config - Sample flow (mmWave devices with MSS and DSS cores and module in co-operative mode)
Figure 29: mmWave API - 'Minimal' Config - Sample flow (mmWave devices with single core or when module is used in isolation mode)
Figure 30: DPU - Internal software design
Figure 31: DPU - typical call flow

4
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

Figure 32: Datapath manager (DPM) - internal software design

Figure 33: Sample ROV log with debug prints

LIST OF TABLES

Table 1: mmWave SDK Demos - CLI commands and parameters

Table 2: Supported drivers and their functionality

5
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

1. Out-of-box mmWave Experience

To experience the mmWave technology offered by TI, you will need to procure the following

Hardware
1. mmWave TI EVM
2. Power supply cable as recommended in TI EVM user guide
3. PC
Software
1. Pre-flashed mmWave Demo running on TI EVM (See instructions in this user guide on how to update the flashed demo)
2. Chrome browser running on PC

Next, to visualize the data flowing out of TI mmWave devices, follow these steps

1. Connect the EVM to a power outlet via the power cable and to the PC via the included USB cable. EVM should be powered up and
connected to PC now.
2. On your PC, browse to https://dev.ti.com/mmWaveDemoVisualizer in Chrome browser and follow the prompts to install one-time software.
[No other software installation is needed at this time]
3. The Visualizer app should detect and connect to your device via COM ports automatically (except for the very first time where users will need
to confirm the selection via OptionsSerial Port). Select the right Platform and SDK version and start your evaluation!
a. Hint : Use HelpAbout to know your Platform and SDK version

For details on how to evaluate, any troubleshooting needs and/or to understand the know-how behind these steps, continue reading this SDK User
Guide...

If the flashed demo on the EVM is an old version and you would like to upgrade to latest demo, continue reading this SDK User Guide...

6
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

2. System Overview
The mmWave SDK is split in two broad components: mmWave Suite and mmWave Demos.

2. 1. mmWave Suite
mmWave Suite is the foundational software part of the mmWave SDK and would encapsulate these smaller components:

Drivers
OSAL
mmWaveLink
mmWaveLib
mmWave API
Data processing layer (manager, processing units)
RADARSS Firmware
Board Setup and Flash Utilities

2. 2. mmWave Demos
SDK provides demos that depict the various control and data processing aspects of a mmWave application. Data visualization of the demo's output on
a PC is provided as part of these demos. These demos are example code that are provided to customers to understand the inner workings of the
mmWave devices and the SDK and to help them get started on developing their own application.

mmWave Processing Demo with TI Gallery App - "mmWave Demo Visualizer"

2. 3. External Dependencies
All tools/components needed for building mmWave sdk are included in the mmwave sdk installer. But the following external components (for
debugging) are not included in the mmWave SDK.

CCS (for debugging)

DCA100EVM CLI in mmWave Studio

Please refer to the mmWave SDK Release Notes for detailed information on these external dependencies and the list of platforms that are supported.

2. 4. Terms used in this document

Terms Comment
used

xWR This is used throughout the document where that section/component/module applies to both AWR and IWR variants

BSS This is used in the source code and sparingly in this document to signify the RADARSS. It is also interchangeably referred to as the
mmWave Front End.

MSS Master Sub-system. It is also interchangeably referred to as Cortex R4F.

DSS DSP Sub-system. It is also interchangeably referred to as DSS or C674x core.

2. 5. Related documentation/links
Other than the documents included in the mmwave_sdk package the following documents/links are important references.

SoC links:
Automotive mmWave Sensors
Industrial mmWave Sensors
Evaluation Modules (EVM) links:
Automotive Evaluation modules (Booster Pack, DEVPACK)
Industrial Evaluation modules (Booster Pack, ISK)

7
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

3. Getting started
The best way to get started with the mmWave SDK is to start running one of the various demos that are provided as part of the package. TI mmWave
EVM comes pre-flashed with the mmWave demo. However, the version of the pre-flashed demo maybe older than the SDK version mentioned in this
document. Users can follow this section and upgrade/run the flashed demo version. The demos (source and pre-built binaries) are placed at mmwave_
sdk_<ver>/packages/ti/demo/<platform> folder.

mmWave Demo

This demo is located at mmwave_sdk_<ver>/packages/ti/demo/<platform>/mmw folder. The millimeter wave demo shows some of the radar sensing
and object detection capabilities of the SoC using the drivers in the mmWave SDK (Software Development Kit). It allows user to specify the chirping
profile and displays the detected objects and other information in real-time. A detailed explanation of this demo is available in the demo's docs folder
and can be browsed via mmwave_sdk_<ver>/docs/mmwave_sdk_module_documentation.html. This demo ships out detected objects and other real-
time information that can be visualized using the TI Gallery App - 'mmWave Demo Visualizer' hosted at https://dev.ti.com/mmWaveDemoVisualizer.
The version of the mmWave Demo running on TI mmWave EVM can be obtained from the Visualizer app using the HelpAbout menu.

Device AWR1843AOP xWR1843 xWR6843AOP xWR6443 xWR6843 xWR1642

Support
(QM/SIL2/ASILB) xWR6843 (QM/SIL2 (QM/SIL2/ASILB)
/ASILB)

Demo ti\demo\xwr18xx\mmw ti\demo\xwr18xx ti\demo\xwr64xx\mmw ti\demo\xwr64xx ti\demo\xwr68xx ti\demo\xwr16xx

Directory \mmw \mmw \mmw \mmw

Binary xwr18xxAOP_mmw_demo xwr18xx_mmw_demo xwr64xxAOP_mmw_demo xwr64xx_mmw_demo xwr68xx_mmw_demo xwr16xx_mmw_demo

prefix

EVM AWR1843AOP EVM xwr18xx BoosterPack IWR6843AOP EVM xWR68xx ISK IWR68xx ISK xwr16xx BoosterPack

Platform xwr18xx_AOP xwr18xx xwr68xx_AOP xwr64xx xwr68xx xwr16xx

selection
in
Visualizer

Following sections describe the general procedure for booting up the device with the demos and then executing it.

3. 1. Programming mmWave devices

Here is a little insight into the mmWave devices and the programmable cores they offer. For more detailed information, please refer to the Technical
reference manual for the respective mmWave device. These details are needed when loading the binaries using CCS and/or to understand the
various terminologies that exist in the "Getting started" section.

xWR14xx

xWR14xx has one cortex R4F core available for user programming and is referred to in this section as MSS or R4F. The demos and the unit tests
executable are provided to be loaded on MSS/R4F.

xWR16xx/xWR18xx/xWR68xx/xWR64xx

These devices have one cortex R4F core and one DSP C674x core available for user programming and are referred to as MSS/R4F and DSS/C674X
respectively. The demos have 2 executables - one for MSS and one for DSS which should be loaded concurrently for the demos to work. See Running
the Demos section for more details. The unit tests may have executables for either MSS or DSS or both. These executables are meant to be run in
standalone operation. This means MSS unit test executable can be loaded and run on MSS R4F without downloading any code on DSS. Similarly,
DSS unit test execuable can be loaded and run on DSS C674x without downloading any code on DSS. The exceptions to this are the Mailbox unit test
named "test_mss_dss_msg_exchange", mmWave unit tests under full and minimal and datapath manager (DPM) unit tests.

3. 2. Loading images onto mmWave EVM

User can choose either one of these modes for loading images onto the EVM.

3. 2. 1. Demonstration Mode
This mode should be used when either upgrading the factory flashed binaries on the EVM to latest SDK version using the pre-built binaries provided in
the SDK release or for field deployment of mmWave sensors.

1. Follow the procedure mentioned in the section (How to flash an image onto mmWave EVM). Use the mmwave_sdk_<ver>/packages/ti/demo
/<platform>/<demo> /<platform>_<demo>.bin as the METAIMAGE1 file name.
2. Remove the "SOP2" jumper or toggle the SOP2 switch to OFF and reboot the device to run the demo image every time on power up. No
other image loading step is required on subsequent boot to run the demo.

3. 2. 2. CCS development mode

8
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

This mode should be used when debugging with CCS is involved and/or developing an mmWave application where the .bin files keep changing
constantly and frequent flashing of image onto the board is not desirable. This mode allows you to flash once and then use CCS to download a
different image to the device's RAM on every boot.

This mode is the recommended way to run the unit tests for the drivers and components which can be found in the respective test directory for that
component. See section mmWave SDK - TI components for location of each component's test code

boot-up sequence

When the mmWave device boots up in functional mode, the device bootloader starts executing and checks if a serial flash is attached to
the device. If yes, then it expects valid MSS application (and a valid RADARSS firmware and/or DSS application) to be present on the
flash. During development phase of mmWave application, flashing the device with the application under development for every small
change can be cumbersome. To overcome this, user should perform a one-time flash as mentioned in the steps below. The actual user
application under development can then be loaded and reloaded to the MSS program memory (TCMA) and/or DSP L2/L3 memory (only for
mmWave devices with DSP) directly via CCS in the device's functional mode.

Refer to Help inside Code Composer Studio (CCS) to learn more about connecting, loading, running the cores, in general.

1. EVM and CCS setup

a. Follow the procedure mentioned in the section: How to flash an image onto mmWave EVM. Use mmwave_sdk_<ver>/packages/ti
/utils/ccsdebug /<platform>_ccsdebug.bin as the METAIMAGE1 filename for the one-time flash.
b. Follow the steps in How to connect mmWave EVM to CCS using JTAG to setup the environment for CCS connectivity.
2. With "SOP2" jumper removed or SOP2 switch toggled to off, after every power cycle/reboot of the EVM, follow these steps to load the
application:
a. Power up the EVM
b. Launch ccxml file created in step 1.b above.
c. If the test requires an application to run on MSS
i. Connect CCS to Cortex_R4_0
ii. Load the MSS program. (for example: xwr16xx_<module>_mss.xer4f prebuilt executables provided in the SDK release
package)
d. If the test requires an application to run on DSP
i. Connect CCS to C674X_0
ii. Load the DSS program. (for example: xwr16xx_<module>_dss.xe674 prebuilt executables provided in the SDK release
package)
e. Run the R4 and/or C674 cores
f. To reload, disconnect the connected cores, power cycle and connect again

3. 3. Running the Demos

Follow this subsection to experience the mmWave functionality using the out-of-box mmWave demo. Before you proceed further, make sure that you
have loaded the right demo binary using the section above, set the EVM to functional mode and powered up the device. Connect the EVM to the PC
using its XDS110 micro-USB port/cable.

3. 3. 1. mmWave Demo

3. 3. 1. 0. 1Figure 1: mmWave Demo Visualizer- mmWave Device Connectivity

1. Power on the EVM in functional mode with right binary loaded (see section above) and connect it to the PC as shown above with the USB
cable.
2. Browse to the TI gallery app "mmWave Demo Visualizer" at http://dev.ti.com/gallery or use the direct link https://dev.ti.com
/mmWaveDemoVisualizer. Use HelpREADME.md from inside this app for more information on how to run/configure this app.

9
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
2.
http://www.ti.com

First Time Setup

a. If this is the first time you are using this App, you may be requested to install a plug-in and the TI Cloud Agent Application. This
step will also install the right XDS110 drivers needed for UART port detection.
b. Once the demo is running on the mmWave sensors and the USB is connected from the board to the PC, the app will try to
automatically detect the COM ports for your device.
i. If auto-detection doesn't work, then you will need to configure the serial ports in this App. Run the device manager on
the PC and locate the following COM ports as shown in the section "How to identify the COM ports for mmWave EVM"
below. In the Visualizer App, go to the Menu->Options->Serial Port and perform the settings as shown below.
CFG_port: Use COM port number for "XDS110 Class Application/User UART": Baud: 115200. This is the
port where CLI (command line interface) runs for all the demos.
Data_port: Use COM port "XDS110 Class Auxiliary Data port": Baud: 921600. This is the port on which
binary data generated by the processing chain in the mmWave demo will be received by the PC. This is the
detected object list and its properties (range, doppler, angle, etc). User can leverage higher baud rates than
921600 by selecting "custom" in the Baud Rates drop down and setting the desired value (max: 3125000).
Recommended values are: 1834000 or 3125000. Note that the sensor should be in stopped or rebooted state
for the changes to take effect. Visualizer communicates with the sensor over CLI port to configure it to the user
provided baud rate in this dialog box.

COM Port

Please note that the COM port numbers on your setup maybe different from the one shown below. Please
use the correct COM port number from your setup for following steps.

a. At this point, this app will automatically try to connect to the target (mmWave Sensor). Note that depending on mmWave SDK
version (mmWave SDK 3.3 and prior) running on the device, only the CFG_port will show connected on successful operation while
the DATA_port may show as "connecting..". DATA_port will be marked connected only after device is configured and sending out
detected point cloud. If CFG_port does not connect or if the connection fails, you should try to connect to the target by clicking in the
bottom left corner of this App. If that fails as well, redo the serial port configuration as shown in "First time Setup" panel above.

b. After the App is connected to the target, you can select the configuration parameters (Frequency Band, Platform, etc) in the "Setup
details" and "Scene Selection" area of the CONFIGURE tab.
c. Besides selecting the configuration parameters, you should select which plots you want to see. This can be done using the "check
boxes" in the "Plot Selection" area. Adjust the frame rate depending on number of plots you want to see. For selecting heatmap
plots, set frame rate to less than or equal to 4 fps. When selecting frame rate to be 25-30fps, for better GUI performance, select only
the scatter plot and statistics plot.
d. Once the configuration is selected, you can send the configuration to the device (use "SEND CONFIG TO MMWAVE DEVICE"
button).
e. After the configuration is sent to the device, you can switch to the PLOTS view/tab and the plots that you selected will be shown.
f. You can switch back from "Plots" tab to "Configure" tab, reconfigure your "Scene Selection", "Object Detection" and/or "Plot
Selection" values and re-send the configuration to the device to try a different profile. After a new configuration has been selected,
just press the "SEND CONFIG TO MMWAVE DEVICE" button again and the device will be reconfigured. This can be done without
rebooting the device. If you change the parameters in the "Setup Details", then you will need to take further action before trying the
new configurations

i. If Platform is changed: make sure the COM ports match the TI EVM/platform you are trying to configure and visualizer
ii. If SDK version is changed: make sure the mmW demo running on the connected TI EVM matches the selected SDK
version in the GUI
iii. If Antenna Config is changed: make sure the TI EVM is rebooted before sending the new configuration.
3. If board is rebooted, follow the steps starting from 1 above.

10
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com
3.

COM port after reboot

Whenever TI EVM is power-cycled (rebooted), you will need to use the bottom left serial port connection icon inside TI gallery app
"mmWave Demo Visualizer" for disconnecting and reconnecting the COM ports. Note that if you used the CLI COM port directly to
send the commands (instead of TI gallery app) you will have to close the CLI teraterm window and open a new one on every
reboot.

Inner workings of the GUI

In the background, GUI performs the following steps:

Creates or reads the configuration file and sends to the mmWave device using the COM port called CFG_port. It saves the information
locally to be able to make sense of the incoming data that it will display. Refer to the CFG Section for details on the configuration file
contents.
Receives the data generated by the demo on the visualization/Data COM port and processes it to create various displays based on the
GUI configuration in the cfg file.
The format of the data streamed out of the demo is documented in mmw demo's doxygen mmwave_sdk_<ver>\packages\ti\demo\
<platform>\mmw\docs\doxygen\html\index.html under section: "Output information sent to host".
On every reconfiguration, it sends a 'sensorStop' command to the device first to stop the active run of the mmWave device. Next, it sends
the command 'flushCfg' to flush the old configuration before sending the new configuration. It is mandatory to flush the old configuration
before sending a new configuration. Additionally, it is mandatory to send all the commands for that demo/platform even if the user desires
the functionality to be disabled i.e. no commands are optional.

Advanced GUI options

User can configure the device from their own configuration file or the saved app-generated configuration file by using the "LOAD CONFIG
FROM PC AND SEND" button on the PLOTS tab. Make sure the first two commands in this config file are "sensorStop" followed by
"flushCfg".
User can temporarily pause the mmWave sensor by using the "STOP" button on the plots tab. The sensor can be restarted by using the
"START" button. In this case, sensor starts again with the already loaded configuration and no new configuration is sent from the App.
User can simultaneously plot and record the processed/detected objects data coming out of the DATA_port using the "RECORD
START" button in the plots tab. Set the max limits for file size or record time as per your requirements to prevent infinite capturing of data.
The saving of data can be manually stopped using the "Record Stop" button (if the max limits are not reached). Sample python scripts to
parse the point cloud output of the demo are provided in mmwave_sdk_<ver>\packages\ti\demo\parser_scripts. mmw_demo_example_scr
ipt.py is the top level example script that uses the parser module provided in parser_mmw_demo.py. User can customize
the mmw_demo_example_script.py to parse their captured files and process it as per their requirements. As an example, the scripts
dumps the point cloud from all the frames in an xls file.
User can use the "PLAYBACK START" button to playback the data and config file recorded via "RECORD START" button in the plots
tab. User should make sure the data file and the config file used in this playback are the matching set. This feature can only be used when
sensor device is either not connected or stopped.
Once the demo has started and plots are active, user can tune the demo using the "Real Time tuning tab" or "Advanced commands" tab
and then save the tuned profile using "EXPORT TUNED PROFILE" button on the PLOTS tab.

11
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

Console Messages window in Visualizer

Console message window echoes the following debug information for the users

Every command that is sent to the TI mmWave EVM and the response back from the EVM
Any runtime assert conditions detected by the demo running on TI mmWave EVM after the sensor is started. This is helpful when mmW
demo is flashed onto the EVM and CCS connectivity is not available. It spits out file name and line number to allow users to browse to the
source code and understand the error.

At times, a negative error code is spit out in the error message (either in Visualizer console or in the CCS console window). To understand
or decode that error, please refer to the mmWave demo doxygen ((browse via mmwave_sdk_<ver>\docs\mmwave_sdk_module_documen
tation.html).
Init time calibration status after the first sensorStart is issued post reboot for debugging boot time or start failures

Here is an example of plots that mmWave Demo Visualizer produces based on the config that is passed to the demo application running on mmWave
sensor.

12
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

3. 3. 2. mmWave demo with LVDS-based instrumentation

To enable mmW demo in the instrumentation usecase where high bandwidth data is shipped from the device to a PC over ethernet and saved onto
the filesystem, please follow the following steps

1. Power on the EVM in functional mode with right binary loaded (see section above) and connect it to the PC as shown above with the USB
cable. Connect mmWave EVM to DCA1000 EVM by following DCA1000EVM Data Capture Card User's Guide. Place SW2.5 in
CONFIG_VIA_SW mode to be able to use the remainder of the instructions specified here.
2. Browse to the TI gallery app "mmWave Demo Visualizer" at http://dev.ti.com/gallery or use the direct link https://dev.ti.com
/mmWaveDemoVisualizer.
3. Default profile in Visualizer disables the LVDS streaming. To enable it, please export the chosen profile and set the appropriate enable bits in
lvdsStreamCfg command. See "Configuration (.cfg) File Format" section for details on the command format, usage and dependencies.

Example: Enable H/W and S/W stream with header

lvdsStreamCfg -1 1 1 1

4. Create a JSON file with any name but with extension .json with following parameters. See section "JSON Config File"
in TI_DCA1000EVM_CLI_Software_UserGuide.pdf. Sample JSON file is shown below.

13
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

datacard_config.json

{
"DCA1000Config": {
"dataLoggingMode": "multi",
"dataTransferMode": "LVDSCapture",
"dataCaptureMode": "ethernetStream",
"lvdsMode": 2,
"dataFormatMode": 3,
"packetDelay_us": 10,
"ethernetConfig": {
"DCA1000IPAddress": "192.168.33.180",
"DCA1000ConfigPort": 4096,
"DCA1000DataPort": 4098
},
"ethernetConfigUpdate": {
"systemIPAddress": "192.168.33.30",
"DCA1000IPAddress": "192.168.33.180",
"DCA1000MACAddress": "12.34.56.78.90.12",
"DCA1000ConfigPort": 4096,
"DCA1000DataPort": 4098
},
"captureConfig": {
"fileBasePath": "C:\\mySavedData",
"filePrefix": "datacard_record",
"maxRecFileSize_MB": 1024,
"sequenceNumberEnable": 1,
"captureStopMode": "infinite",
"bytesToCapture": 1025,
"durationToCapture_ms": 1000,
"framesToCapture": 5
},
"dataFormatConfig": {
"MSBToggle": 0,
"reorderEnable": 1,
"laneFmtMap": 0,
"dataPortConfig": [
{
"portIdx": 0,
"dataType": "complex"
},
{
"portIdx": 1,
"dataType": "complex"
},
{
"portIdx": 2,
"dataType": "complex"
},
{
"portIdx": 3,
"dataType": "complex"
},
{
"portIdx": 4,
"dataType": "complex"
}
]
}
}
}

This json file should match user's setup and the profile.cfg that is used to configure the mmW demo running on mmWave EVM.

a. User should customize "ethernetConfig" block to match their setup

b. "dataLoggingMode" in json file should be set to "raw" if header is disabled via <enableHeader> field in lvdsStreamCfg command in
profile.cfg. "dataLoggingMode" in json file should be set to "multi" if header is enabled via <enableHeader> field in lvdsStreamCfg co
mmand in profile.cfg.
c. "lvdsMode" in json file should be set to 2 since xwr16xx/xwr18xx/xwr68xx device have 2 lvds lanes.
d. "dataFormatMode" in json file should match the 12/14/16 bit selection in <numADCBits> field in "adcCfg" command in profile.cfg. As
one would realize, value of "dataFormatMode" is ("adcCfg""numADCBits" + 1) .
e. User should customize "captureConfig" as per their needs.
f. "MSBToggle" should be set to 0.
g. "reorderEnable" should be set to 1.
h. "dataPortConfig" should set all dataType to "complex" since mmW demo configures all CBUFF/LVDS session to be complex.
5.

14
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. Assuming the file created in previous step is called "datacard_config.json", invoke the following commands from a command prompt (DOS or
bash) on the PC to which the DCA1000 EVM is connected:
a. Windows:

How to get DCA1000 CLI Utility for Windows

The Windows based CLI (prebuilt binary) can be obtained from mmWave Studio package. Please download and install
mmWave Studio (MMWAVE-STUDIO) version 2.1 or later from http://www.ti.com/tool/MMWAVE-STUDIO and browse to
the installed folder: C:\ti\mmwave_studio_<ver>\mmWaveStudio\PostProc.

Documentation and source code for this utility is provided under C:

\ti\mmwave_studio_<ver>\mmWaveStudio\ReferenceCode\DCA1000 for reference.

Windows::DCA1000EVM CLI Commands

@REM configure DCA1000EVM

DCA1000EVM_CLI_Control.exe fpga datacard_config.json

@REM configure CLI application with the record related settings

DCA1000EVM_CLI_Control.exe record datacard_config.json

@REM start record and wait for the data over ethernet
DCA1000EVM_CLI_Control.exe start_record datacard_config.json

b. Linux:

How to get DCA1000 CLI Utility for Linux

The Linux based CLI sourcecode can be obtained from mmWave Studio package. Please download and install mmWave
Studio (MMWAVE-STUDIO) version 2.1 or later from http://www.ti.com/tool/MMWAVE-STUDIO and browse to the
installed folder: C:\ti\mmwave_studio_<ver>\mmWaveStudio\ReferenceCode\DCA1000. Copy the 'SourceCode' folder to
a linux machine and use the instructions from C:
\ti\mmwave_studio_<ver>\mmWaveStudio\ReferenceCode\DCA1000\Docs\TI_DCA1000EVM_CLI_Software_UserGuide.
pdf to build the utility for your linux distribution.

Linux::DCA1000EVM CLI Commands

# configure DCA1000EVM
./DCA1000EVM_CLI_Control fpga datacard_config.json

#configure CLI application with the record related settings

./DCA1000EVM_CLI_Control record datacard_config.json

#start record and wait for the data over ethernet

./DCA1000EVM_CLI_Control start_record datacard_config.json

6. See previous section for details on operating the Visualizer. Configure the mmW demo running on the mmWave EVM using the Visualizer
and profile.cfg that has lvds streaming turned on. To avoid getting timeout error from DCA1000EVM_CLI_Control, execute this step from the
Visualizer within 30 secs of sending the "start_record" command using DCA1000EVM_CLI_Control.
7. With successful invocation of DCA1000EVM_CLI_Control and Visualizer, the mmWave EVM will send UART stream to get plotted on the
Visualizer and LVDS stream to PC to be saved in a file as configured in "captureConfig" JSON block.
8. Use the following command to stop the LVDS stream capture before issuing "sensorStop" to the mmW demo running on mmWave EVM. One
could send the sensorStop to mmWave EVM followed by stop_record to DCA1000EVM_CLI_Control.exe however this would generate an
errorcode related to record process not running and it can be safely ignored.
a. Windows:

Windows::Stop DCA1000EVM_CLI

DCA1000EVM_CLI_Control.exe stop_record datacard_config.json

b. Linux

15
 b.
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

Linux::Stop DCA1000EVM_CLI

./DCA1000EVM_CLI_Control stop_record datacard_config.json

9. See section "Output Files" in C:

\ti\mmwave_studio_<ver>\mmWaveStudio\\ReferenceCode\DCA1000\Docs\TI_DCA1000EVM_CLI_Software_UserGuide.pdf to understand
the files saved during this transfer. On little endian PCs, <File_Prefix>_<Raw/Header Mode>_<iteration>.bin contains value in little endian
format. A fread of 16 bit on little endian PCs will read correct data with no more formatting required. For the high-level data format details
corresponding to the H/W session data format configurations, refer to the corresponding slides in mmwave_sdk_<ver>\docs\ti\drivers\cbuff\do
cs\CBUFF_Transfers.pptx. See section "Streaming data over LVDS" in mmW demo doxygen (browse via mmwave_sdk_<ver>\docs\mmwav
e_sdk_module_documentation.html) for details on data format of the streamed data.
a. For the "raw" mode, the data filename would be <File_Prefix>_Raw_<iteration>.bin. Raw mode is only supported for H/W session
and the saved data is directly payload with no header or extra bytes/padding.
b. For the "multi" mode (or the header enabled mode), see HSIHeader structure returned by HSIHeader_createHeader create API in
mmW demo for the header IDs used.
i. By default, for mmW demo, the first enabled stream (i.e. for H/W stream if H/W is enabled or for S/W stream if H/W is
enabled) will have the ID: HSI_HEADER_ID1 : 0x0CDA0ADC0CDA0ADCU and hence the filename would
be <File_Prefix>_hdr_0ADC_<iteration>.bin. See below for one such example file content and its interpretation.

Sample datacard_record_hdr_0ADC_0.bin for H/W session with CP_ADC_CQ format

ii. By default, for mmW demo, the second enabled stream (i.e. for S/W stream if H/W is also enabled) will have the
ID: HSI_HEADER_ID2 : 0x09CC0CC909CC0CC9U and hence the filename would be <File_Prefix>_hdr_0CC9_<iteration>.
bin. See below for one such example file content and its interpretation.

16
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

Sample datacard_record_hdr_0CC9_0.bin for S/W session

17
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

Sample Data parser implementation

Sample python based scripts are provided in mmwave_sdk_<ver>\packages\ti\demo\parser_scripts to help parse the demo output data file
saved by DCA1000 data card CLI. lvds_example_script.py is the top level example script that uses the parser module provided in
parser_lvds_demo_captured_file.py. User can customize the lvds_example_script.py to parse their captured files and process it as per their
requirements. As an example, the scripts dumps the point cloud from all the frames in an xls file.

Sample C code implementation of data parsing with header enabled is provided at mmwave_sdk_<ver>\packages\ti\utils\hsiheader\test\dat
a_card.cpp. Use the readme.txt in that location for build and run instructions. (Note that serialize.cpp is no longer required
if "reorderEnable" is set to 1).

data_card.out datacard_record_hdr_0ADC_0.bin

Debug: File: datacard_record_hdr_0ADC_0.bin

******************************************************************
Debug: [Detected] Data ID1 with mmWave SDK Version: 3.2.0.3 Platform: XWR16xx
Debug: Header size: 32 Padding size: 6
Debug: Channel-0123 Non-Interleaved Mode 16bit CP + ADC + CQ
Debug: Single Chirp Mode
Debug: ADC: 480 CP: 2
Debug: CQ0: 0 CQ1: 120 CQ2: 64
Debug: User1: 0 User2: 0 User3 : 0
Debug: Application Header: 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
CP [Channel 1] :: 0 0
ADC [Channel 1 First 8 bytes]:: 1696 1100 1456 756 1997 322 1091 -665
ADC [Channel 1 Last 8 bytes]:: -890 -43 332 1396 817 -594 -271 237
CP [Channel 2] :: 1 0
ADC [Channel 2 First 8 bytes]:: -1772 -1399 -1794 -469 -956 -79 -899 -355
ADC [Channel 2 Last 8 bytes]:: -884 324 94 938 799 -163 797 -809
CP [Channel 3] :: 2 0
ADC [Channel 3 First 8 bytes]:: 1182 3225 2220 3055 2561 1824 2152 555
ADC [Channel 3 Last 8 bytes]:: -692 827 -1 546 226 539 632 894
CP [Channel 4] :: 3 0
ADC [Channel 4 First 8 bytes]:: -444 -419 451 -85 -29 -719 -345 -131
ADC [Channel 4 Last 8 bytes]:: -730 383 244 -161 -435 550 765 -322
CQ1 :: 119 24929 27239 28009 30827 -31378 -26511 -24469 -24982 -23957 -23703 -23443 -23448
-22678 -21390 -21904 -21392 -20370 -20369 -21393 -21903 -22166 -22168 -22165 -22679 -22164 -21655 -21400
-18831 -18573 -18572 -18835 -19091 -19858 -20886 -20629 -21401 -21399 -20629 -21144 -20631 -19609 -19860
-18828 -17550 -19094 -20631 -19856 -18323 -19091 -18075 -18587 -18322 -17557 -18836 -18841 -19097 -19083
-17807 -18838 -20377 -20118 -19097 -20633 -19868 -17054 -17817 -18073 -19609 -20121 -19094 -19859 -20123
-20377 -20124 -17052 -18328 -21917 -21915 -21914 -22169 -20888 -20891 -21660 -21914 -20627 -22426 -22683
-22940 -22428 -20631 -21919 -21918 -22940 -22683 -20114 -21913 -23194 -23706 -22936 -23451 -23967 -22429
-21916 -22169 -22169 -22170 -22169 -21911 -21392 -23194 -23452 -23450 -22425 -20373 -24222 -24477 -23194
-21913 -22933
CQ2 :: 119 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 20784 -3576 32369 5283
******************************************************************

data_card.out datacard_record_hdr_0CC9_0.bin

Debug: File: datacard_record_hdr_0CC9_0.bin

******************************************************************
Debug: [Detected] Data ID2 with mmWave SDK Version: 3.2.0.3 Platform: XWR16xx
Debug: Header size: 56 Padding size: 30
Debug: No Channel Enabled Non-Interleaved Mode 16bit User
Debug: Continuous Mode
Debug: ADC: 0 CP: 0
Debug: CQ0: 0 CQ1: 0 CQ2: 0
Debug: User1: 4 User2: 464 User3 : 116
Debug: Application Header: 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0
User0 :: 1 0 0 58
User1 :: -28599 -16951 11112 16329
User2 :: 305 771 374 784
******************************************************************

3. 4. Configuration (.cfg) File Format

18
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

Each line in the .cfg file describes a command with parameters. The various commands and their arguments are described in the table below
(arguments are in sequence). For mmW demo, users can create their own config files from the Visualizer GUI by using the "Save Config to PC"
button or starting from the few sample profiles provided in the mmwave_sdk_<ver>\packages\ti\demo\<platform>\mmw\profiles directory.

Converting configuration from older SDK release to current SDK release

As new versions of SDK releases are available, there are usually changes to the configuration commands that are supported in the new
release. Now, users may have some hand crafted config file which worked perfectly well on older SDK release version but will not work as
is with the new SDK release. If user desires to run the same configuration against the new SDK release, then there is a script
mmwDemo_<platform>_update_config.pl provided in the mmwave_sdk_<ver>\packages\ti\demo\<platform>\mmw\profiles directory that
they can use to convert the configuration file from older release to a compatible version for the new release. Refer to the perl file for details
on how to run the script. Note that users will need to install perl on their machine (there is no strict version requirement at this time). For any
new commands inserted by the script, there will be a comment preceeding that line which is similar to something like this: "Inserting new
mandatory command. Check users guide for details."

Most of the parameters described below are the same as the mmwavelink API specifications (see doxygen mmwave_sdk_<ver>\packages\ti\control\m
mwavelink\docs\doxygen\html\index.html.) Additionally, users can refer to the chirp diagram below to understand the chirp and profile related
parameters or the appnote http://www.ti.com/litv/pdf/swra553

3. 4. 0. 0. 1Figure 2: Chirp Diagram

Configuration command Command details Command Parameters Usage in mmW demo

xwr16xx/xwr18xx/xwr64xx
/xwr68xx

dfeDataOutputMode The values in this command should not change

between sensorStop and sensorStart.
<modeType> only option 1 and 3 are
Reboot the board to try config with different set of 1 - frame based chirps supported
values in this command 2 - continuous chirping
3 - advanced frame config
This is a mandatory command.

channelCfg Channel config message to RadarSS. See

mmwavelink doxgen for details.
<rxChannelEn> 4 antennas supported
The values in this command should not change Receive antenna mask e.g for 4
between sensorStop and sensorStart. antennas, it is 0x1111b = 15

Reboot the board to try config with different set of

values in this command

This is a mandatory command.

19
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

<txChannelEn> Refer to the antenna layout on

Transmit antenna mask the EVM/board to determine
the right Tx antenna mask
needed to enable the desired
virtual antenna configuration.

For example, in IWR6843 ISK,

the 2 azimuth antennas can
be enabled using bitmask 0x5
(i.e. tx1 and tx3). The azimuth
and elevation antennas can
both be enabled using
bitmask 0x7 (i.e. tx1, tx2 and
tx3).

For example, in
xWR1642BOOST, the 2
azimuth antennas can be
enabled using bitmask 0x3 (i.
e. tx1 and tx2).

<cascading> n/a
SoC cascading, not applicable, set
to 0

adcCfg ADC config message to RadarSS. See mmwavelink

doxgen for details.
<numADCBits> only 16-bit is supported
The values in this command should not change Number of ADC bits (0 for 12-bits,
between sensorStop and sensorStart. 1 for 14-bits and 2 for 16-bits)

Reboot the board to try config with different set of <adcOutputFmt> only complex modes are
values in this command Output format : supported
0 - real
This is a mandatory command. 1 - complex 1x (image band filtered
output)
2 - complex 2x (image band
visible))

adcbufCfg adcBuf hardware config. The values in this

command can be changed between sensorStop
and sensorStart. <subFrameIdx> For legacy mode, that field
subframe Index should be set to -1.
This is a mandatory command.
For advanced frame mode, it
should be set to either the
intended subframe number or
-1 to apply same config to all
subframes.

<adcOutputFmt> only complex modes are

ADCBUF out format supported
0-Complex,
1-Real

<SampleSwap> only option 1 is supported

ADCBUF IQ swap selection:
0-I in LSB, Q in MSB,
1-Q in LSB, I in MSB

<ChanInterleave> only option 1 is supported

ADCBUF channel interleave
configuration:
0 - interleaved(only supported for
XWR14xx),
1 - non-interleaved

<ChirpThreshold> xwr16xx demo: Values 0-8 are

Chirp Threshold configuration used supported since it uses DSP
for ADCBUF buffer to trigger ping for 1D FFT. However, only
/pong buffer switch. value of 1 is supported when
LVDS streaming is enabled.
Valid values:
xwr64xx/xwr68xx/xwr18xx:
0-8 for demos that use DSP for 1D only value of 1 is supported
FFT and LVDS streaming is since these demos use HWA
disabled for 1D FFT

only 1 for demos that use HWA for

1D FFT

20
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

profileCfg Profile config message to RadarSS and datapath.

See mmwavelink doxgen for details.
The values in this command can be changed <profileId> Legacy frame
between sensorStop and sensorStart. profile Identifier (dfeOutputMode=1): could be
any allowed value but only
This is a mandatory command. one valid profile per config is
supported

txCalibEnCfg Field

This CLI command doesn't expose the Advanced frame

txCalibEnCfg field in the mmwavelink (dfeOutputMode=3): could be
structure. User should follow the mmwavelink any allowed value but only
documentation and update the CLI profileCfg one profile per subframe is
handler function accordingly. The current supported. However, different
handler sets the value to 0 for this field subframes can have different
(backward compatible mode) profiles

<startFreq> any value as per mmwavelink

"Frequency Start" in GHz (float doxgen/device datasheet but
Combination of numAdcSamples in values allowed) represented in GHz.
profileCfg (and numRangeBins),
numDopplerChirps = total number of Examples:
chirps/(num TX in MIMO mode) in
frameCfg or subFrameCfg, number of 77 Refer to the chirp diagram
TX and RX antennas in channelCfg and shown above to understand
61.38 the relation between various
chirpCfg determine the size of
Radarcube and other internal buffers profile parameters and inter-
/heap in the demo. It is possible that dependent constraints.
some combinations of these values
<idleTime> any value as per mmwavelink
result in out of memory conditions for
"Idle Time" in u-sec (float values doxgen/device datasheet but
these heaps and demo will reject such
allowed) represented in usec.
configuration. Refer to demo and DPC
doxygen to understand the data buffer Examples:
layout and use the system printfs on
sensorStart in CCS console window to 7 Refer to the chirp diagram
understand the exact heap usage for a shown above to understand
given configuration. 7.15 the relation between various
profile parameters and inter-
dependent constraints.

<adcStartTime> any value as per mmwavelink

"ADC Valid Start Time" in u-sec doxgen/device datasheet but
(float values allowed) represented in usec.

Examples:

7 Refer to the chirp diagram

shown above to understand
7.34 the relation between various
profile parameters and inter-
dependent constraints.

<rampEndTime> any value as per mmwavelink

"Ramp End Time" in u-sec (float doxgen/device datasheet but
values allowed) represented in usec

Examples:

58 Refer to the chirp diagram

216.15 shown above to understand
the relation between various
profile parameters and inter-
dependent constraints.

<txOutPower> only value of '0' has been

Tx output power back-off code for tested within context of mmW
tx antennas demo

<txPhaseShifter> only value of '0' has been

tx phase shifter for tx antennas tested within context of mmW
demo

<freqSlopeConst> any value greater than 0 as

"Frequency slope" for the chirp in per mmwavelink doxgen
MHz/usec (float values allowed) /device datasheet but
represented in MHz/usec.
Examples:

68
Refer to the chirp diagram
16.83 shown above to understand
the relation between various
profile parameters and inter-
dependent constraints.

21
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

<txStartTime> any value as per mmwavelink

"TX Start Time" in u-sec (float doxgen/device datasheet but
values allowed) represented in usec.

Examples:

1 Refer to the chirp diagram

2.92 shown above to understand
the relation between various
profile parameters and inter-
dependent constraints.

<numAdcSamples> any value as per mmwavelink

number of ADC samples collected doxgen/device datasheet.
during "ADC Sampling Time" as
shown in the chirp diagram above

Examples: Refer to the chirp diagram

shown above to understand
256 the relation between various
profile parameters and inter-
224 dependent constraints.

<digOutSampleRate> any value as per mmwavelink

ADC sampling frequency in ksps. doxgen/device datasheet.

(<numAdcSamples> /
<digOutSampleRate> = "ADC
Sampling Time") Refer to the chirp diagram
shown above to understand
Examples: the relation between various
profile parameters and inter-
5500 dependent constraints.

<hpfCornerFreq1> any value as per mmwavelink

HPF1 (High Pass Filter 1) corner doxgen/device datasheet
frequency
0: 175 KHz
1: 235 KHz
2: 350 KHz
3: 700 KHz

<hpfCornerFreq2> any value as per mmwavelink

HPF2 (High Pass Filter 2) corner doxgen/device datasheet
frequency
0: 350 KHz
1: 700 KHz
2: 1.4 MHz
3: 2.8 MHz

<rxGain> any value as per mmwavelink

OR'ed value of RX gain in dB and doxgen/device datasheet
RF gain target (See mmwavelink
doxgen for details)

chirpCfg Chirp config message to RadarSS and datapath.

See mmwavelink doxgen for details.
chirp start index any value as per mmwavelink
The values in this command can be changed doxygen
between sensorStop and sensorStart.
chirp end index any value as per mmwavelink
This is a mandatory command. doxygen

profile identifier should match the profileCfg-

>profileId

start frequency variation in Hz (float only value of '0' has been

values allowed) tested within context of mmW
demo

frequency slope variation in kHz/us only value of '0' has been

(float values allowed) tested within context of mmW
demo

idle time variation in u-sec (float only value of '0' has been
values allowed) tested within context of mmW
demo

ADC start time variation in u-sec only value of '0' has been
(float values allowed) tested within context of mmW
demo

22
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

tx antenna enable mask (Tx2,Tx1) See note under "Channel Cfg"

e.g (10)b = Tx2 enabled, Tx1 command above.
disabled.
Individual chirps should have
either only one distinct Tx
antenna enabled (MIMO) or
same TX antennas should be
enabled for all chirps

lowPower Low Power mode config message to RadarSS. See

mmwavelink doxgen for details.
<don’t_care> set to 0
The values in this command should not change
between sensorStop and sensorStart. ADC Mode use value of '0' or '1'
0x00 : Regular ADC mode (depending on profileCfg-
Reboot the board to try config with different set of 0x01 : Low power ADC mode (Not >digOutSampleRate)
values in this command. supported for xwr6xxx devices)

This is a mandatory command.

frameCfg frame config message to RadarSS and datapath.

See mmwavelink doxgen for details.
chirp start index (0-511) any value as per mmwavelink
dfeOutputMode should be set to 1 to use this doxgen but corresponding
command chirpCfg should be defined

The values in this command can be changed chirp end index (chirp start index- any value as per mmwavelink
between sensorStop and sensorStart. 511) doxgen but corresponding
chirpCfg should be defined
This is a mandatory command when
dfeOutputMode is set to 1. number of loops (1 to 255) any value as per mmwavelink
doxgen/device datasheet but
greater than or equal to 4.

For xwr16xx/xwr68xx demos

where DSP version of Doppler
DPU is used, the Doppler
chirps (i.e. number of loops)
should be a multiple of 4 due
to windowing requirement.

Note: If value of 2 is desired

for number of Doppler Chirps,
one must update the demo
/object detection DPC source
code to use rectangular
window for Doppler DPU
instead of Hanning window.

number of frames (valid range is 0 any value as per mmwavelink

to 65535, 0 means infinite) doxgen

frame periodicity in ms (float values any value as per mmwavelink

allowed) doxgen and represented in
msec. However frame should
not have more than 50% duty
cycle (i.e. active chirp time
should be <= 50% of frame
period). Also it should allow
enough time for selected
UART output to be shipped
out (selections based on
guiMonitor command) else
demo will assert if the next
frame start trigger is received
from the front end and current
frame is still ongoing. User
can use the output of stats
TLV to tune this parameter.

trigger select only option for Software

1: Software trigger trigger is supported
2: Hardware trigger.

Frame trigger delay in ms (float any value as per mmwavelink

values allowed) doxgen and represented in
msec.

advFrameCfg Advanced config message to RadarSS and

datapath. See mmwavelink doxgen for details. The
dfeOutputMode should be set to 3 to use this
command. See profile_advanced_subframe.cfg
profile in the mmW demo profiles directory for

23
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

example usage.
<numOfSubFrames> any value as per mmwavelink
Number of sub frames enabled in doxgen
The values in this command can be changed
this frame
between sensorStop and sensorStart.
<forceProfile> only value of 0 is supported
This is a mandatory command when Force profile
dfeOutputMode is set to 3.
<numFrames> any value as per mmwavelink
Number of frames to transmit (1 doxgen
frame = all enabled sub frames)

<triggerSelect> only option for Software

trigger select trigger is supported
1: Software trigger
2: Hardware trigger.

<frameTrigDelay> any value as per mmwavelink

Frame trigger delay in ms (float doxgen and represented in
values allowed) msec.

subFrameCfg Subframe config message to RadarSS and

datapath. See mmwavelink doxgen for details.
<subFrameNum> value of 0 to
The dfeOutputMode should be set to 3 to use this subframe Number for which this RL_MAX_SUBFRAMES-1
command. See profile_advanced_subframe.cfg command is being given
profile in the mmW demo profiles directory for
example usage <forceProfileIdx> ignored as <forceProfile> in
Force profile index advFrameCfg should be set to
The values in this command can be changed 0
between sensorStop and sensorStart.
<chirpStartIdx> any value as per mmwavelink
This is a mandatory command when Start Index of Chirp doxgen but corresponding
dfeOutputMode is set to 3. chirpCfg should be defined

<numOfChirps> any value as per mmwavelink

Num of unique Chirps per burst doxgen but corresponding
including start index number of chirpCfg should be
defined

<numLoops> any value as per mmwavelink

No. of times to loop through the doxgen but greater than or
unique chirps equal to 4

For xwr16xx/xwr68xx demos

where DSP version of Doppler
DPU is used, the Doppler
chirps (i.e. number of loops)
should be a multiple of 4 due
to windowing requirement.

Note: If value of 2 is desired

for number of Doppler Chirps,
one must update the demo
/object detection DPC source
code to use rectangular
window for Doppler DPU
instead of Hanning window.

<burstPeriodicity> any value as per mmwavelink

doxgen and represented in
Burst periodicty in msec (float msec but subframe should not
values allowed) and meets the have more than 50% duty
criteria cycle and allow enough time
burstPeriodicity >= ((numLoops)* for selected UART output to
(Sum total of time duration of all be shipped out (selections
unique chirps in that burst)) + based on guiMonitor
InterBurstBlankTime command)

<chirpStartIdxOffset> set it to 0 since demo

Chirp Start address increament for supports only one burst per
next burst subframe

<numOfBurst> set it to 1 since demo

Num of bursts in the subframe supports only one burst per
subframe

<numOfBurstLoops> set it to 1 since demo

Number of times to loop over the supports only one burst per
set of above defined bursts, in the subframe
sub frame

24
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

<subFramePeriodicity> set to same as

<burstPeriodicity> since demo
subFrame periodicty in msec (float supports only one burst per
values allowed) and meets the subframe
criteria
subFramePeriodicity >= Sum total
time of all bursts +
InterSubFrameBlankTime

guiMonitor Plot config message to datapath.

The values in this command can be changed
between sensorStop and sensorStart. All parameters below are flags (1 to
enable and 0 to disable)
This is a mandatory command.
<subFrameIdx> For legacy mode, that field
subframe Index should be set to -1 whereas
for advanced frame mode, it
should be set to either the
intended subframe number or
-1 to apply same config to all
subframes.

<detected objects> all values supported

1 - enable export of point cloud (x,y,
z,doppler) and point cloud sideinfo
(SNR, noiseval)

2 - enable export of point cloud (x,y,

z,doppler)

0 - disable

<log magnitude range> all values supported

1 - enable export of log magnitude
range profile at zero Doppler
0 - disable

<noise profile> all values supported

1 - enable export of log magnitude
noise profile
0 - disable

25
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

<rangeAzimuthHeatMap> or all values supported

<rangeAzimuthElevationHeatMap>
range-azimuth or range-azimuth-
elevation heat map related
information

<rangeAzimuthHeatMap>

This output is provided only in

demos that use AoA (legacy) DPU
for AoA processing
1 - enable export of zero Doppler
radar cube matrix, all range bins,
all azimuth virtual antennas to
calculate and display azimuth heat
map.

(The GUI computes the FFT of this

to show heat map)

0 - disable

< rangeAzimuthElevationHeatMap >

This output is provided in demos

that use AoA 2D DPU for AoA
processing (ex: mmW demo
for IWR6843AOP)

1 - enable export of zero Doppler

radar cube matrix, all range bins,
all virtual antennas to calculate and
display azimuth heat map.

(The GUI remaps the antenna

symbols and computes the FFT of
this stream to show azimuth heat
map only).

0 - disable

<rangeDopplerHeatMap> all values supported

range-doppler heat map
1 - enable export of the whole
detection matrix. Note that the
frame period should be adjusted
according to UART transfer time.
0 - disable

<statsInfo> all values supported

statistics (CPU load, margins,
device temperature readings, etc)
1 - enable export of stats data.
0 - disable

cfarCfg CFAR config message to datapath.

The values in this command can be changed <subFrameIdx> For legacy mode, that field
between sensorStop and sensorStart and even subframe Index should be set to -1 whereas
when the sensor is running. for advanced frame mode, it
should be set to either the
This is a mandatory command. intended subframe number or
-1 to apply same config to all
subframes.

<procDirection> all values supported; 2

Processing direction: separate commands need to
0 – CFAR detection in range be sent; one for Range and
direction other for doppler.
1 – CFAR detection in Doppler
direction

<mode> all values supported

CFAR averaging mode:
0 - CFAR_CA (Cell Averaging)
1 - CFAR_CAGO (Cell Averaging
Greatest Of)
2 - CFAR_CASO (Cell Averaging
Smallest Of)

26
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

<noiseWin> supported
noise averaging window length:
Length of the one sided noise
averaged cells in samples

Make sure 2*(noiseWIn+guardLen)

<numRangeBins for range direction
and 2*(noiseWIn+guardLen)
<numDopplerBins for doppler
direction.

<guardLen> supported
one sided guard length in samples

Make sure 2*(noiseWIn+guardLen)

<numRangeBins for range direction
and 2*(noiseWIn+guardLen)
<numDopplerBins for doppler
direction.

<divShift> CFAR_CA:
Cumulative noise sum divisor <divShift> = ceil(log2(2 x
expressed as a shift. <noiseWin>))
CFAR_CAGO/_CASO:
Sum of noise samples is divided by <divShift> = ceil(log2
2^<divShift>. Based on <mode>
and <noiseWin> , this value should (<noiseWin>))
be set as shown in next columns.
In profile_2d.cfg, value of 3
The value to be used here should means that the noise sum is
match the "CFAR averaging mode" divided by 2^3=8 to get the
and the "noise averaging window average of noise samples with
length" that is selected above. window length of 8 samples in
CFAR -CASO mode.
The actual value that is used for
division (2^x) is a power of 2, even
though the "noise averaging
window length" samples may not
have that restriction.

cyclic mode or Wrapped around supported

mode.
0- Disabled
1- Enabled

Threshold scale in dB using float Detection threshold is

representation. specified in dB scale.
This is used in conjuntion with the Maximum value allowed is
noise sum divisor (say x). 100dB
the CUT comparison for log input is:

CUT > (Threshold scale converted

from dB to Q8) + (noise sum / 2^x)

For example:

15

10.75

peak grouping supported

0 - disabled
1 - enabled

multiObjBeamForming Multi Object Beamforming config message to

datapath.
<subFrameIdx> For legacy mode, that field
This feature allows radar to separate reflections subframe Index should be set to -1 whereas
from multiple objects originating from the same for advanced frame mode, it
range/Doppler detection. should be set to either the
intended subframe number or
The procedure searches for the second peak after -1 to apply same config to all
locating the highest peak in Azimuth FFT. If the subframes.
second peak is greater than the specified threshold,
the second object with the same range/Doppler is <Feature Enabled> supported
appended to the list of detected objects. The 0 - disabled
threshold is proportional to the height of the highest 1 - enabled
peak.

The values in this command can be changed

between sensorStop and sensorStart and even
when the sensor is running.

27
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

This is a mandatory command. <threshold> supported

0 to 1 – threshold scale for the
second peak detection in azimuth
FFT output. Detection threshold is
equal to <thresholdScale>
multiplied by the first peak height.
Note that FFT output is magnitude
squared.

calibDcRangeSig DC range calibration config message to datapath.

Antenna coupling signature dominates the range <subFrameIdx> For legacy mode, that field
bins close to the radar. These are the bins in the subframe Index should be set to -1 whereas
range FFT output located around DC. for advanced frame mode, it
should be set to either the
When this feature is enabled, the signature is intended subframe number or
estimated during the first N chirps, and then it is -1 to apply same config to all
subtracted during the subsequent chirps. subframes.

During the estimation period the specified <enabled> supported

bins (defined as [negativeBinIdx, positiveBinIdx]) Enable DC removal using first few
around DC are accumulated and averaged. It is chirps
assumed that no objects are present in the vicinity 0 - disabled
of the radar at that time. 1 - enabled

This procedure is initiated by the following CLI <negativeBinIdx> supported

command, and it can be initiated any time while negative Bin Index (to remove DC
radar is running. Note that the maximum number of from farthest range bins)
compensated bins is 32.
Maximum negative range FFT
The values in this command can be changed index to be included for
between sensorStop and sensorStart and even compensation. Negative indices
when the sensor is running. are indices wrapped around from
far end of 1D FFT.
This is a mandatory command.
Ex: Value of -5 means last 5 bins
starting from the farthest bin

<positiveBinIdx> supported
positive Bin Index (to remove DC
from closest range bins)
Maximum positive range FFT index
to be included for compensation

Value of 8 means first 9 bins

(including bin#0)

<numAvg> The value must be power of 2,

number of chirps to average to and must be greater than the
collect DC signature (which will number of Doppler bins.
then be applied to all chirps beyond
this).

Value of 256 means first 256 chirps

(after command is issued and
feature is enabled) will be used for
collecting (averaging) DC signature
in the bins specified above. From
257th chirp, the collected DC
signature will be removed from
every chirp.

clutterRemoval Static clutter removal config message to datapath.

Static clutter removal algorithm implemented by <subFrameIdx> For legacy mode, that field
subtracting from the samples the mean value of the should be set to -1 whereas
input samples to the 2D-FFT subframe Index for advanced frame mode, it
should be set to either the
The values in this command can be changed intended subframe number or
between sensorStop and sensorStart and even -1 to apply same config to all
when the sensor is running. subframes.

This is a mandatory command. <enabled> supported

Enable static clutter removal
technique
0 - disabled
1 - enabled

aoaFovCfg Command for datapath to filter out detected points

outside the specified range in azimuth or elevation
plane

28
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

<subFrameIdx> For legacy mode, that field

The values in this command can be changed
should be set to -1 whereas
between sensorStop and sensorStart and even
subframe Index for advanced frame mode, it
when the sensor is running.
should be set to either the
intended subframe number or
This is a mandatory command.
-1 to apply same config to all
subframes.

<minAzimuthDeg> minimum azimuth angle (in

degrees) that specifies the
start of field of view

<maxAzimuthDeg> maximum azimuth angle (in

degrees) that specifies the
end of field of view

<minElevationDeg> minimum elevation angle (in

degrees) that specifies the
start of field of view

<maxElevationDeg> maximum elevation angle (in

degrees) that specifies the
end of field of view

cfarFovCfg Command for datapath to filter out detected points

outside the specified limits in the range direction or
doppler direction <subFrameIdx> For legacy mode, that field
should be set to -1 whereas
The values in this command can be changed subframe Index for advanced frame mode, it
between sensorStop and sensorStart and even should be set to either the
when the sensor is running. intended subframe number or
-1 to apply same config to all
This is a mandatory command. subframes.

<procDirection> both values supported but this

Processing direction: command should be given
0 – point filtering in range direction twice - one for range direction
1 – point filtering in Doppler and other for doppler direction
direction

<min (meters or m/s)> minimum limits for the range

or doppler below which the
the units depends on the value for detected points are filtered out
<procDirection> field above.

meters for Range direction and

meters/sec for Doppler direction

<max (meters or m/s)> maximum limits for the range

or doppler above which the
the units depends on the value for detected points are filtered out
<procDirection> field above.

meters for Range direction and

meters/sec for Doppler direction

compRangeBiasAndRxChanPhase Command for datapath to compensate for bias in

the range estimation and receive channel gain and
phase imperfections. <rangeBias> supported
Refer to the procedure mentioned here Compensation for range estimation
bias in meters
The values in this command can be changed
between sensorStop and sensorStart and even <Re(0,0)> <Im(0,0)> <Re(0,1)> <Im For xwr1843, xwr6843 and
when the sensor is running. (0,1)> ... <Re(0,R-1)> <Im(0,R-1)> xwr6443 demos: 12 pairs of
<Re(1,0)> <Im(1,0)> ... <Re(T-1,R- values should be provided
This is a mandatory command. 1)> <Im(T-1,R-1)> here since the device has 4
Rx and 3 Tx (total of 12 virtual
Set of Complex value representing antennas). Note the sign
compensation for virtual Rx reversal required for phase
channel phase bias in Q15 format. compensation coefficients
Pairs of I and Q should be provided in xwr6443 demo running on
for all Tx and Rx antennas in the IWR6843AOP device.
device
For xwr1642 demo: 8 pairs of
values should be provided
here since the device has 4
Rx and 2 Tx (total of 8 virtual
antennas)

measureRangeBiasAndRxChanPhase Command for datapath to enable the measurement

of the range bias and receive channel gain and
phase imperfections. Refer to the procedure
mentioned here

29
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

<enabled> supported
The values in this command can be changed
1 - enable measurement. This
between sensorStop and sensorStart and even
parameter should be enabled only
when the sensor is running.
using the profile_calibration.cfg
profile in the mmW demo profiles
This is a mandatory command.
directory
0 - disable measurement. This
should be the value to use for all
other profiles.

<targetDistance> supported
distance in meters where strong
reflector is located to be used as
test object for measurement. This
field is only used when
measurement mode is enabled.

<searchWin> supported
distance in meters of the search
window around <targetDistance>
where the peak will be searched

extendedMaxVelocity Velocity disambiguation config message to <subFrameIdx> For legacy mode, that field
datapath. subframe Index should be set to -1 whereas
A simple technique for velocity disambiguation is for advanced frame mode, it
implemented. It corrects target velocities up to should be set to either the
(2*vmax). The output of this feature may not be intended subframe number or
reliable when two or more objects are present in -1 to apply same config to all
the same range bin and are too close in azimuth subframes.
plane.
<enabled> supported.
The values in this command can be changed Enable velocity disambiguation
between sensorStop and sensorStart and even technique Only disabled is supported for
when the sensor is running. 0 - disabled xwr64xx demo running on
1 - enabled IWR6843AOP device.
This is a mandatory command.

CQRxSatMonitor Rx Saturation Monitoring config message for <profile> any value as per mmwavelink
Chirp quality to RadarSS and datapath. See Valid profile Id for this monitoring doxygen but corresponding
mmwavelink doxgen for details on configuration. This profile ID should profileCfg should be defined
rlRxSatMonConf_t. have a matching profileCfg.

<satMonSel> any value as per mmwavelink

The enable/disable for this command is controlled RX Saturation monitoring mode doxygen
via the "analogMonitor" CLI command.
<priSliceDuration> any value as per mmwavelink
The values in this command can be changed Duration of each slice, 1LSB=0. doxygen
between sensorStop and sensorStart. 16us, range: 4 -number of ADC
samples
This is a mandatory command
<numSlices> any value as per mmwavelink
primary + secondary slices ,range doxygen
1-127. Maximum primary slice is 64.

<rxChanMask> any value as per mmwavelink

RX channel mask, 1 - Mask, 0 - doxygen
unmask

CQSigImgMonitor Signal and image band energy Monitoring config <profile> any value as per mmwavelink
message for Chirp quality to RadarSS and Valid profile Id for this monitoring doxygen but corresponding
datapath. See mmwavelink doxgen for details on configuraiton. This profile ID should profileCfg should be defined
rlSigImgMonConf_t. have a matching profileCfg

The enable/disable for this command is controlled

via the "analogMonitor" CLI command.

The values in this command can be changed

between sensorStop and sensorStart.

This is a mandatory command

<numSlices> any value as per mmwavelink

primary + secondary slices, range doxygen
1-127. Maximum
primary slice is 64.

30
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

<numSamplePerSlice> any value as per mmwavelink

Possible range is 4 to "number of doxygen
ADC samples" in
the corresponding profileCfg. It
must be an
even number.

analogMonitor Controls the enable/disable of the various <rxSaturation> supported

monitoring features supported in the demos. CQRxSatMonitor enable/disable

The values in this command can be changed 1:enable

between sensorStop and sensorStart. 0: disable

This is a mandatory command. <sigImgBand> supported

CQSigImgMonitor enable/disable
1:enable
0: disable

lvdsStreamCfg Enables the streaming of various data streams <subFrameIdx> For legacy mode, that field
over LVDS lanes. When this feature is enabled, subframe Index should be set to -1 whereas
make sure chirpThreshold in adcbufCfg is set to 1. for advanced frame mode, it
should be set to either the
The values in this command can be changed intended subframe number or
between sensorStop and sensorStart. -1 to apply same config to all
subframes.
This is a mandatory command.
<enableHeader> supported
0 - Disable HSI header for all active
streams
1 - Enable HSI header for all active
streams

<dataFmt> supported
Controls HW streaming.
Specifies the HW streaming data When choosing
format. CP_ADC_CQ, please ensure
0-HW STREAMING DISABLED that CQRxSatMonitor and
1-ADC CQSigImgMonitor commands
4-CP_ADC_CQ are provided with appropriate
values and these monitors are
enabled using analogMonitor
command.

<enableSW> supported
0 - Disable user data (SW session)
1 - Enable user data (SW session)

<enableHeader> should be set to 1

when this field is enabled.

bpmCfg BPM MIMO configuration. <subFrameIdx> For legacy mode, that field
Every frame should consist of alternating chirps with subframe Index should be set to -1 whereas
pattern TXA+TxB and TXA-TXB where TXA and for advanced frame mode, it
TXB are two azimuth TX antennas. This is alternate should be set to either the
configuration to TDM-MIMO scheme and intended subframe number or
provides SNR improvement by running 2Tx -1 to apply same config to all
simultaneously. When using this scheme, user subframes.
should enable both the azimuth TX in the
chirpCfg. See profile_2d_bpm.cfg profile in the <enabled> supported
xwr16xx mmW demo profiles directory for 0-Disabled
example usage. 1-Enabled

This config is supported and mandatory only for <chirp0Idx> any value as per mmwavelink
demos that use Doppler DSP DPU (xwr16xx doxygen but corresponding
/xwr68xx). This config is not supported and is not chirpCfg should be defined
needed for demos that use Doppler HWA DPU BPM enabled:
(xwr18xx/xwr64xx). If BPM is enabled in previous
argument, this is the chirp index for
the first BPM chirp. It will have
phase 0 on both
TX antennas (TXA+ , TXB+). Note
that the chirpCfg command for this
chirp index must have both TX
antennas enabled.

BPM disabled:
If BPM is disabled, a BPM disable
command (set phase to zero on
both TX antennas) will be issued
for the chirps in the range
[chirp0Idx..chirp1Idx]

31
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

<chirp1Idx> any value as per mmwavelink

doxygen but corresponding
BPM enabled: chirpCfg should be defined
If BPM is enabled, this is the chirp
index for the second BPM chirp.It
will have phase 0 on TXA and
phase 180 on TXB (TXA+ , TXB-).
Note that the chirpCfg command
for this chirp index must have both
TX antennas enabled.

BPM disabled:
If BPM is disabled, a BPM disable
command (set phase to zero on
both TX antennas) will be issued
for the chirps in the range
[chirp0Idx..chirp1Idx].

calibdata Boot time RF calibration save/restore command. <save enable> supported

Provides user to either save the boot time RF 0 - Save enabled. Application will
calibration performed by the RadarSS onto the boot-up normally and configure the
FLASH or to restore the previously saved RF RadarSS to perform all applicable
calibration data from the FLASH and instruct boot calibrations during
RadarSS to not re-perform the boot-time mmWave_open. Once the
calibration. User can either save or restore or calibrations are performed,
perform neither operations. User is not allowed to application will retrieve the
simultaneous save and restore in a given boot calibration data from RadarSS and
sequence. save it to FLASH. User need to
specify valid <flash offset>
xwr18xx/60 Ghz devices: Boot time phase shift value. <restore enable> option
calibration data is also saved along with all other should be set to 0.
calibration data.

The values in this command should not change

between sensorStop and sensorStart. 1 - Save disabled.

Reboot the board to try config with different set of

values in this command

This is a mandatory command.

<restore enable> supported

0 - Restore enabled. Application

will check the FLASH for a valid
calibration data section. If present,
it will restore the data from FLASH
and provide it to RadarSS while
configuring it to skip any real-time
boot calibrations and use provided
calibration data. User need to
specify valid <flash offset> value
which was used during saving of
calibration data. <save enable>
option should be set to 0.

1 - Restore disabled.

<Flash offset> supported

Address offset in the flash to be

used while saving or restoring
calibration data.

Make sure the address doesn't

overlap the location in FLASH
where application images are
stored and has enough space for
saving rlCalibrationData_t
and rlPhShiftCalibrationData_t
(xwr18xx/60 Ghz devices only)

This field is don't care if both save

and restore are disabled

sensorStart sensor Start command to RadarSS and datapath.

Starts the sensor. This function triggers the
transmission of the frames as per the frame and
chirp configuration. By default, this function also
sends the configuration to the mmWave Front End
and the processing chain.

32
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

This is a mandatory command. Optionally, user can provide an supported

argument 'doReconfig'
0 - Skip reconfiguration and just
start the sensor using already
provided configuration.

<any other value> - not supported

sensorStop sensor Stop command to RadarSS and datapath. supported

Stops the sensor.
If the sensor is running, it will stop the mmWave
Front End and the processing chain.
After the command is acknowledged, a new config
can be provided and sensor can be restarted or
sensor can be restarted without a new config (i.e.
using old config). See 'sensorStart' command.

This is mandatory before any reconfiguration is

performed post sensorStart.

flushCfg This command should be issued after 'sensorStop'

command to flush the old configuration and provide
a new one.

This is mandatory before any reconfiguration is

performed post sensorStart.

configDataPort This is an optional command to change the baud <baudrate> supported

rate of the DATA_port. By default, the baud rate is
921600. The new baud rate for the
DATA_port. Any valid baud rate
This command will be accepted only when sensor upto max of 3125000.
is in init state or stopped state i.e. between
sensorStop and sensorStart. It is recommended to Recommended values: 921600,
use this command outside of the CFG file so that 1843200, 3125000.
PC tools can also be configured to accept data at
the desired baud rate. <ackPing> supported

0 - Do not send any bytes on data

port

1- Send 16 bytes of value '0xFF' to

ack/sync over the DATA_port
(binary) after change to baud rate
is applied.

queryDemoStatus This is an optional command that can be issued

anytime to get the sensor state (0-init,1-opened,2-
started,3-stopped) of the device and the current
baud rate of the DATA_port.

The response of this command is provided on the

CLI port.

% Any line starting with '%' character

is considered as comment line and
is skipped by the CLI parsing utility.

3. 4. 0. 0. 1Table 1: mmWave SDK Demos - CLI commands and parameters

3. 5. Running the prebuilt unit test binaries (.xer4f and .xe674)

Unit tests for the drivers and components can be found in the respective test directory for that component. See section "mmWave SDK - TI
components" for location of each component's test code. For example, UART test code that runs on TI RTOS is in mmwave_sdk_<ver>/packages/ti
/drivers/uart/test/<platform>. In this test directory, you will find .xer4f and .xe674 files (either prebuilt or build as a part of instructions mentioned in "Buil
ding drivers/control components"). Follow the instructions in section "CCS development mode" to download and execute these unit tests via CCS.

33
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

4. How-To Articles

4. 1. How to identify the COM ports for mmWave EVM

When the EVM is powered on and connected to Windows PC via the supplied USB cable, there should be two additional COM Ports in Device
Manager. See your mmWave devices' TI EVM User Guide for details on the COM port.

Troubleshooting Tip

If the COM ports don't show up in the Device Manager or are not working (i.e. no demo output seen on the data port), then one of these
steps would apply depending on your setup:

1. If you want to run the Out-of-box demo, simple browse to the Visualizer (https://dev.ti.com/mmWaveDemoVisualizer) and follow
the one-time setup instructions.
2. If you are trying to flash the board, using Uniflash tool and following the cloud or desktop version installation instructions would
also install the right drivers for the COM ports.
3. If above methods didnt work and if TI code composer studio is not installed on that PC, then download and install the standalone
XDS110 drivers.
4. If TI code composer studio is installed, then version of CCS and emulation package need to be checked and updated as per the
mmWave SDK release notes. See section Emulation Pack Update for more details.

After following the above steps, disconnect and re-connect the EVM and you should see the COM ports now. See the highlighted COM ports in the Fig
ure below

4. 1. 0. 0. 1Figure 3: mmWave EVM PC Connectivity - Device Manager - COM Ports

COM Port

Please note that the COM port numbers on your setup maybe different from the one shown above. Please use the correct COM port
number from your setup for following steps.

4. 2. How to flash an image onto mmWave EVM

You will need the mmWave Device TI EVM, USB cable and a Windows/Linux PC to perform these steps.

1. Setup the Booster Pack EVM for Flashing

Refer to the EVM User Guide to understand the bootup modes of the EVM and the SOP jumper/switch locations (See "Sense-on-Power
(SOP) Jumpers" section in mmWave device's EVM user guide). To put the EVM in flashing mode, power off the board and either place
jumpers on pins marked as SOP2 and SOP0 or toggle SOP0 and SOP2 switches to ON .

SOP2 SOP1 SOP0 Bootloader mode & operation

jumper jumper jumper

/switch /switch /switch

34
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

0 0 1 Functional Mode

Device Bootloader loads user application from QSPI Serial Flash to internal RAM and switches
the control to it

1 0 1 Flash Programming Mode

Device Bootloader spins in loop to allow flashing of user application to the serial flash.
2. Procure the Images
For flashing xWR1xxx devices, TI Uniflash tool should be used. Users can either use the cloud version available at https://dev.ti.com/uniflash/
or download the desktop version available at http://www.ti.com/tool/UNIFLASH. Detailed instructions on how to use the GUI are described in
the Uniflash document " UniFlash User Guide for mmWave Devices " located at http://processors.wiki.ti.com/index.php/Category:
CCS_UniFlash. This document talks about the steps from the perspective of desktop GUI but the flashing steps (except for installation)
should apply for cloud version as well. For the SDK packaged demos and ccsdebug utility, there is a bin file provided in their respective
folder: <platform>_<demo|ccsdebug>.bin which is the metaImage to be used for flashing. The metaImage already has the MSS, BSS
(RADARSS) and DSS (as applicable) application combined into one file. These bin files can be selected in Uniflash based on the working
mode. Users can use these instructions to flash the metaImage of their custom demo as well.
a. For demo mode, mmwave_sdk_<ver>\ti\demo\<platform>\mmw\<platform>_mmw_demo.bin should be selected.
b. For CCS development mode, mmwave_sdk_<ver>\ti\ utils\ccsdebug\<platform>_ccsdebug.bin should be selected.
3. Flashing procedure

Power up the EVM and check the Device Manager in your windows PC. Note the number for the serial port marked as "XDS110 Class
Application/User UART" for the EVM. Lets say for this example, it showed up as COM25. Use this COM port in the TI Uniflash tool. Follow
the remaining instructions in the " UniFlash v4 User Guide for mmWave Devices " to complete the flashing.
4. Switch back to Functional Mode

Refer to the EVM User Guide to understand the bootup modes of the EVM and the SOP jumpers (See "Sense-on-Power (SOP) Jumpers"
section in mmWave device's EVM user guide). To put the EVM in functional mode, power off the board and remove jumpers from "SOP2" pin
and leave the jumper on "SOP0" pin or toggle SOP0 switch to ON and SOP2 switch to OFF.

4. 3. How to erase flash on mmWave EVM

1. Setup the Booster Pack EVM for flashing as mentioned in step 1 of the section: How to flash an image onto mmWave EVM
2. Follow the instructions in " UniFlash v4 User Guide for mmWave Devices " section "Format SFLASH Button".
3. Switch back to Functional Mode as mentioned in step 4 of the section: How to flash an image onto mmWave EVM

4. 4. How to connect mmWave EVM to CCS using JTAG

Debug/JTAG capability is available via the same XDS110 micro-USB port/cable on the EVM. TI Code composer studio would be required for
accessing the debug capability of the device. Refer to the release notes for TI code composer studio and emulation pack version that would be
needed.

4. 4. 1. Emulation Pack Update

Refer to the mmWave SDK release notes for the emulation pack version that would be needed within CCS to connect to the EVM. Check if that
particular or its later version of "TI Emulators" is available within your CCS installation. If you have an older version on your system, refer to CCS help
on how to update software packages within CCS.

4. 4. 2. Device support package Update

To create the ccxml file for connecting to the EVM, you will need to first update the device support package within CCS. Refer to the mmWave SDK
release notes for the device support package version that would be needed within CCS to connect to the EVM. Check if that particular or its later
version of "mmWave Radar Device Support" is available within your CCS installation. If you have an older version on your system, refer to CCS help
on how to update software packages within CCS.

4. 4. 3. Target Configuration file for CCS (CCXML)

4. 4. 3. 1. Creating a CCXML file

Assuming you have updated the device support package and Emulation pack as mentioned in the section above, follow the steps mentioned below to
create a target configuration file in CCS.

1. If your CCS does not already show "Target Configurations" window, do View->Target Configurations
2. This will show the "Target Configurations" window, right click in the window and select "New Target Configuration"
3. Give an appropriate name to the ccxml file you want to create for the EVM
4. Scroll the "Connection" list and select "Texas Instruments XDS110 USB Debug Probe", when this is done, the "Board or Device" list will be
filtered to show the possible candidates, find and choose the mmWave device (AWR or IWR) of interest and check the box. Click Save and
the file will be created.

35
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

4. 4. 3. 1. 1Figure 4: Creating a mmWave device CCXML in CCS

4. 4. 3. 2. Connecting to mmWave EVM using CCXML in CCS

Follow steps in above section to create a ccxml file. Once created, the target configuration file will be seen in the "Target Configurations" list and you
can launch the target by selecting it and with right-click select the "Launch Selected Configuration" option. This will launch the target and the Debug
window will show all the cores present on the device. You can connect to the target with right-click and doing "Connect Target".

4. 4. 3. 2. 1Figure 5: Connecting to mmWave Device in CCS

36
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

4. 5. Developing using SDK

4. 5. 1. Build Instructions
Follow the mmwave_sdk_release_notes instructions to install the mmwave_sdk in your development environment (windows or linux). All the tools
needed for mmwave sdk build are installed as part of mmwave sdk installer.

4. 5. 2. Setting up build environment

4. 5. 2. 1. Windows
1. Create command prompt at <mmwave_sdk_<ver> install path>\packages\scripts\windows folder. Under this folder you should see a setenv.
bat file that has all the tools environment variables set automatically based on the installation folder. Review this file and change the few build
variables shown below (if needed) and save the file. Please note that the rest of the environment variables should not be modified if the
standard installation process was followed.

Build variables that can be modified (if needed) in setenv.bat

@REM ###############################################################################
@REM # Build variables (to be modified based on build need)
@REM ###############################################################################
@REM Select your device. Options (case sensitive) are: awr14xx, iwr14xx, awr16xx, iwr16xx, awr18xx, iwr18xx,
iwr68xx, awr68xx
set MMWAVE_SDK_DEVICE=iwr68xx

@REM If download via CCS is needed, set below define to yes else no
@REM yes: Out file created can be loaded using CCS.
@REM Binary file created can be used to flash
@REM no: Out file created cannot be loaded using CCS.
@REM Binary file created can be used to flash
@REM (additional features: write-protect of TCMA, etc)
set DOWNLOAD_FROM_CCS=yes

@REM If using a secure device this variable needs to be updated with the path to mmwave_secdev_<ver> folder
set MMWAVE_SECDEV_INSTALL_PATH=

@REM If using a secure device, this variable needs to be updated with the path to hsimage.cfg file that
@REM has customer specific certificate/key information. A sample hsimage.cfg file is in the secdev package
set MMWAVE_SECDEV_HSIMAGE_CFG=%MMWAVE_SECDEV_INSTALL_PATH%/hs_image_creator/hsimage.cfg

Refer to the MMWAVE-SECDEV User Guide to setup environment needed for builds for high secure (HS) devices. For non secure
devices the MMWAVE_SECDEV_INSTALL_PATH environment variable should be empty.

If you see the following line in the setenv.bat file then most probably the wrong installer was used (Linux installation being
compiled under Windows)

set MMWAVE_SDK_TOOLS_INSTALL_PATH=__MMWAVE_SDK_TOOLS_INSTALL_PATH__

In a proper installation the __MMWAVE_SDK_TOOLS_INSTALL_PATH__ would have been replaced with the actual installation
folder path

2. Run setenv.bat as shown below.

Run setenv.bat

setenv.bat

This should not give errors and should print the message "mmWave Build Environment Configured". The build environment is now setup.

4. 5. 2. 2. Linux

1.

37
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

1. Open a terminal and cd to <mmwave_sdk_<ver> install path>/packages/scripts/unix. Under this folder you should see a setenv.sh file that
has all the tools environment variables set automatically based on the installation folder. Review this file and change the few build variables
shown below (if needed) and save the file. Please note that the rest of the environment variables should not be modified if the standard
installation process was followed.

Build variables that can be modified (if needed) in setenv.sh

###############################################################################
# Build variables (to be modified based on build need)
###############################################################################
@REM Select your device. Options (case sensitive) are: awr14xx, iwr14xx, awr16xx, iwr16xx, awr18xx, iwr18xx,
iwr68xx, awr68xx
set MMWAVE_SDK_DEVICE=iwr68xx

# If download via CCS is needed, set below define to yes else no

# yes: Out file created can be loaded using CCS.
# Binary file created can be used to flash
# no: Out file created cannot be loaded using CCS.
# Binary file created can be used to flash
# (additional features: write-protect of TCMA, etc)
export DOWNLOAD_FROM_CCS=yes

# If using a secure device, this variable needs to be updated with the path to mmwave_secdev_<ver> folder
export MMWAVE_SECDEV_INSTALL_PATH=

# If using a secure device, this variable needs to be updated with the path to hsimage.cfg file that
# has customer specific certificate/key information. A sample hsimage.cfg file is in the secdev package
export MMWAVE_SECDEV_HSIMAGE_CFG=${MMWAVE_SECDEV_INSTALL_PATH}/hs_image_creator/hsimage.cfg

Refer to the MMWAVE-SECDEV User Guide to setup environment needed for builds for high secure (HS) devices. For non secure
devices the MMWAVE_SECDEV_INSTALL_PATH environment variable should be empty.

If you see the following line in the setenv.sh file then most probably the wrong installer was used (Windows installation being
compiled under Linux)

export MMWAVE_SDK_TOOLS_INSTALL_PATH=__MMWAVE_SDK_TOOLS_INSTALL_PATH__

In a proper installation the __MMWAVE_SDK_TOOLS_INSTALL_PATH__ would have been replaced with the actual installation
folder path

2. Assuming build is on a Linux 64bit machine, install modules that allows Linux 32bit binaries to run. This is needed for Image Creator binaries

sudo dpkg --add-architecture i386

3. Install build-essential package for 'make'. Install mono-complete package as one of the Image Creator binaries (out2rprc.exe) is a windows
executable that needs mono to run in Linux environment

sudo apt-get install build-essential

sudo apt-get --assume-yes install mono-complete

4. Run setenv.sh as shown below.

Run setenv.sh

source ./setenv.sh

This should not give errors and should print the message "mmWave Build Environment Configured". The build environment is now setup.

4. 5. 3. Building demo
To clean build a demo, first make sure that the environment is setup as detailed in earlier section. Then run the following commands. On successful
execution of the commands, the output is <demo>.xe* which can be used to load the image via CCS and <demo>.bin which can be used as the binary
in the steps mentioned in section "How to flash an image onto mmWave EVM".

4. 5. 3. 1. Building demo in Windows

38
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

Building demo in windows

REM Fill <device type> with appropriate device that supports demo in a particular release
cd %MMWAVE_SDK_INSTALL_PATH%/ti/demo/<device type>/mmw

REM Clean and build

gmake clean
gmake all

REM Incremental build

gmake all

REM For example to build the mmw demo for iwr68xx

cd %MMWAVE_SDK_INSTALL_PATH%/ti/demo/xwr68xx/mmw
gmake clean
gmake all
REM This will create xwr68xx_mmw_demo_mss.xer4f & xwr68xx_mmw_demo.bin binaries
REM under %MMWAVE_SDK_INSTALL_PATH%/ti/demo/xwr68xx/mmw folder

4. 5. 3. 2. Building demo in Linux

Building demo in linux

# Fill <device type> with appropriate device that supports demo in a particular release
cd ${MMWAVE_SDK_INSTALL_PATH}/ti/demo/<device type>/mmw

# Clean and build

gmake clean
gmake all

# Incremental build
gmake all

# For example to build the mmw demo for iwr68xx

cd ${MMWAVE_SDK_INSTALL_PATH}/ti/demo/xwr68xx/mmw
gmake clean
gmake all
# This will create xwr68xx_mmw_demo_mss.xer4f & xwr68xx_mmw_demo.bin binaries
# under ${MMWAVE_SDK_INSTALL_PATH}/ti/demo/xwr68xx/mmw folder

Each demo has dependency on various drivers and control components. The libraries for those components need to be available in their
respective lib folders for the demo to build successfully.

4. 5. 4. Advanced build
The mmwave sdk package includes all the necessary libraries and hence there should be no need to rebuild the driver, algorithms or control
component libraries. In case a modification has been made to any of these modules then the following section details how to build these components.

4. 5. 4. 1. Building drivers/control/alg components

To clean build driver, control, datapath or alg component and its unit test, first make sure that the environment is setup as detailed in earlier section.
Then run the following commands

39
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

Building component in windows

cd %MMWAVE_SDK_INSTALL_PATH%/ti/<component_path_under_ti>
gmake clean
gmake all

REM The command will create the following file

REM lib<component>_<device_type>.aer4f library under ti/<component_path_under_ti>/lib folder
REM If the module has unit test, it will also create
REM <device_type>_<component>_mss.xer4f unit test binary under ti/<component_path_under_ti>/test/<device_type>
folder
REM If the device has a DSP and the driver supports DSP then the command will also create
REM lib<component>_<device_type>.ae674 library for DSS under ti/<component_path_under_ti>/lib folder
REM If the module has unit test, it will also create
REM <device_type>_<component>_dss.xe674 unit test binary for DSS under ti/<component_path_under_ti>/test
/<device_type> folder
REM Above paths are relative to %MMWAVE_SDK_INSTALL_PATH%/

REM For example to build the adcbuf lib and unit test
cd %MMWAVE_SDK_INSTALL_PATH%/ti/drivers/adcbuf
gmake clean
gmake all

REM For example to build the mmwavelink lib and unit test
cd %MMWAVE_SDK_INSTALL_PATH%/ti/control/mmwavelink
gmake clean
gmake all

REM For example to build the aoaproc dpu lib

cd %MMWAVE_SDK_INSTALL_PATH%/ti/datapath/dpc/dpu/aoaproc
gmake clean
gmake all

REM Additional build options for each component can be found by invoking make help
gmake help

Building component in linux

cd ${MMWAVE_SDK_INSTALL_PATH}/ti/<component_path_under_ti>
gmake clean
gmake all

# The command will create the following file

# lib<component>_<device_type>.aer4f library under ti/<component_path_under_ti>/lib folder
# If the module has unit test, it will also create
# <device_type>_<component>_mss.xer4f unit test binary under ti/<component_path_under_ti>/test/<device_type> folder
# If the device has a DSP and the driver supports DSP then the command will also create
# lib<component>_<device_type>.ae674 library for DSS under ti/<component_path_under_ti>/lib folder
# If the module has unit test, it will also create
# <device_type>_<component>_dss.xe674 unit test binary for DSS under ti/<component_path_under_ti>/test
/<device_type> folder
# Above paths are relative to ${MMWAVE_SDK_INSTALL_PATH}/

# For example to build the adcbuf lib and unit test

cd ${MMWAVE_SDK_INSTALL_PATH}/ti/drivers/adcbuf
gmake clean
gmake all

# For example to build the mmwavelink lib and unit test

cd ${MMWAVE_SDK_INSTALL_PATH}/ti/control/mmwavelink
gmake clean
gmake all

# For example to build the aoaproc dpu lib

cd ${MMWAVE_SDK_INSTALL_PATH}/ti/datapath/dpc/dpu/aoaproc
gmake clean
gmake all
# Additional build options for each component can be found by invoking make help
gmake help

40
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

example output of make help for drivers and mmwavelink

********************************************************************
* Makefile Targets for the ADCBUF
clean -> Clean out all the objects
drv -> Build the Driver only
drvClean -> Clean the Driver Library only
test -> Builds all the unit tests for the SOC
testClean -> Cleans the unit tests for the SOC
********************************************************************

example output of make help for mmwave control and alg component

********************************************************************
* Makefile Targets for the mmWave Control
clean -> Clean out all the objects
lib -> Build the Core Library only
libClean -> Clean the Core Library only
test -> Builds all the Unit Test
testClean -> Cleans all the Unit Tests
********************************************************************

Please note that not all components are supported for all devices and not all components have unit tests. List of supported components for
each device is listed in the Release Notes.

4. 5. 4. 2. "Error on warning" compiler and linker setting

By default, the SDK build uses "–emit_warnings_as_errors" option to help users identify certain common mistakes in code that are flagged as warning
but could lead to unexpected results. If user desires to disable this feature, then please set the flag MMWAVE_DISABLE_WARNINGS_AS_ERRORS
to 1 in the above mentioned setenv.bat or setenv.sh and invoke that file again to update the build environment.

41
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. MMWAVE SDK deep dive

5. 1. System Deployment
A typical mmWave application would perform these operations:

Control and monitoring of RF front-end through mmaveLink

Transport of external communications through standard peripherals
Some radar data processing using DSP

Typical customer deployment for mmWave sensor is shown in Figure 6:

a. Application code for MSS and DSP-SS is downloaded from the serial flash memory attached to the mmWave device (via QSPI)
b. Optional high level control from remote entity
c. Sends low speed data output (objects detected) to remote entity
d. Optional high speed data (debug) sent out of device over LVDS

5. 1. 0. 0. 1Figure 6: Autonomous mmWave sensor (Standalone mode)

The above deployment can be realized using the mmWave SDK and it components in a layered structure as shown below:

5. 1. 0. 0. 1Figure 7: SDK Layered block diagram

42
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 2. Typical mmWave Radar Processing Chain

Following figure shows a typical mmWave Radar processing chain that accepts ADC data as input from mmWave Front End and then performs Range
and Doppler FFT followed by non-coherent detection using CFAR. Finally angle is estimated using 3D FFT and the detected points represent the point
cloud data. The point cloud data can then be post processed using higher layer algorithms such as Clustering, Tracking, Classification to represent
real world targets.

5. 2. 0. 0. 1Figure 8: Typical mmWave radar processing chain

Using mmWave SDK the above chain could be realized as shown in the following figure for devices with HWA or DSP as processing nodes. In the
following figure, green arrow shows the control path and red arrow shows the data path. Blue blocks are mmWave SDK components and yellow
blocks are custom application code. The hierarchy of software flow/calls is shown with embedding boxes. Depending on the complexity of the higher
algorithms (such as clustering, tracking, etc) and their memory/mips consumption, they can either be partially realized inside the mmWave device or
would run entirely on the external processor.

5. 2. 0. 0. 1Figure 9: Typical mmWave radar processing chain using mmWave SDK components

Each of the mmWave device offers different processing nodes to realize the mmwave processing. xWR14xx has HWA engine, xWR16xx has DSP
C674x core, xWR68xx and xWR18xx have HWA+DSP(C674x). For devices with multiple processing nodes, the mmWave detection processing chain
can exploit them as needed for performance and scalable reasons. Shown below is an example of detection processing chain that uses various data
processing units (DPUs) to perform the typical mmwave processing upto the point cloud. The mmwave data representation in mmWave device
memory forms an interface layer between the various DPUs. Each DPU can be realized independently using HWA or DSP processing node - the
choice is either driven by usecase or availability of that processing node on a given mmWave device. The various mmWave SDK components shown
below are described in the section "mmWave SDK - TI components" below.

43
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 2. 0. 0. 1Figure 10: Scalable data processing chain using mmWave SDK

Please refer to the code and documentation inside the mmwave_sdk_<ver>\packages\ti\demo\<platform>\mmw folder for more details and example
code on how this chain is realized using mmWave SDK components.

5. 3. Typical Programming Sequence

The above processing chain can be split into two distinct blocks: RF control path and data path.

5. 3. 1. RF Control Path
The control path in the above processing chain is depicted by the following blocks.

44
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 3. 1. 0. 1Figure 11: Typical mmWave radar control flow

Following set of figures shows how an application programming sequence would look like for setting up the typical control path - init, config, start. This
is a high level diagram simplified to highlight the main software APIs and may not show all the processing elements and call flow. For an example
implementation of this call flow, please refer to the code and documentation inside the mmwave_sdk_<ver>\packages\ti\demo\<platform>\mmw folder.

5. 3. 1. 1. Single RF Control (MSSRADARSS or DSSRADARSS)

In this scenario, the RF control path runs on either Master subsystem (Cortex-R4F) or DSP subsytem (C674x) and the application can simply call the
mmwave APIs in the SDK in isolation mode to realize most of the functionality.

45
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 3. 1. 1. 1Figure 12: mmWave Isolation mode: Detailed Control Flow (Init sequence)

46
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 3. 1. 1. 2Figure 13: mmWave Isolation mode: Detailed Control Flow (Config sequence)

47
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 3. 1. 1. 3Figure 14: mmWave Isolation mode: Detailed Control Flow (start sequence)

5. 3. 1. 2. Co-operative RF control ((MSS+DSS)<->RADARSS)

In this scenario the control path can runs in "co-operative" mode where RF control APIs can be interchangeably called by either domains (but the
sequence of API needs to be maintained). One such deployment could have the RF init and config initiated by the MSS and the start is initiated by the
DSS after the data path configuration is complete. In the figures below, control path runs on MSS entirely and MSS is responsible for properly
configuring the RADARSS (RF) and DSS (data processing). The mmWave unit tests provide a sample implementation of this co-operative mode.

48
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 3. 1. 2. 1Figure 15: mmWave Co-operative Mode: Detailed Control Flow (Init sequence)

5. 3. 1. 2. 2Figure 16: mmWave Co-operative Mode: Detailed Control Flow (Config sequence)

49
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 3. 1. 2. 3Figure 17: mmWave Co-operative Mode: Detailed Control Flow (Start sequence)

5. 3. 2. Data Path
The mmwave detection processing can be split into following layers of application code, control/management layer to manipulate the data processing
elements, processing chain that ties up individual modules to create a data flow and the low level data processing modules and interfaces.

5. 3. 2. 0. 4Figure 18: Typical mmWave Detection Processing Layers

mmWave devices present a few options on how the data processing layers can be realized using the various control/processing nodes within the
device. To allow ease of programming across these deployment types, data path manager (DPM) presents a simplified API structure to the application
while hiding the complexity of inter task and inter processor communications. As can be seen from the following figures, application would just need to
call the various DPM APIs to control the processing chain (seen as function calls in 'blue' in the ladder diagrams below) and re-act to the outcome of
these APIs in the report callback. Data processing chains (DPCs) also present a standardized API structure to the application via DPM and
encapsulate the realization of the data flow using data processing units (DPUs) within while presenting simple IOCTL based interface to configure and
trigger the data flow. Based on the usecase and the mmWave device hardware capabilities, application can choose from one of the following
deployments:

DPC runs on the same core as control core and the application can control the DPC via DPM in local mode. (See local domain config and pro
cessing figures below)

50
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

DPC runs on another core which is different from the controlling core and the application can control the DPC via DPM in remote mode. (See
remote domain config and processing figures below)
DPC is split between two cores and the application can control the DPC via DPM in distributed mode. (See distributed domain config and proc
essing figures below)

The following ladder diagrams show the flow for init, two different forms of config (one initiated on local core and other on remote core), start trigger,
chirps/frame events and stop trigger. The choice of MSS and DSS responsibilities are shown as one of the possible examples - their roles can be
interchanged as per application needs. These ladder diagrams don't show the corresponding MMWAVE/RF control calls to show independence
between RF control and datapath control. Having said that, typical application would follow the following flow for these two form of controls:

mmWave init and DPM init (order doesn't matter)

mmWave config and DPM IOCTL for DPC config (order doesn't matter)
DPM start and then mmWave start (note this is recommended as DPC should be in started state before the real time frame/chirp H/W events
occur due to mmWave start)
mmWave stop and then DPM stop (note this is recommended as DPC should be stopped after the real time frame/chirp H/W events stop due
to mmWave stop)

5. 3. 2. 1. Data processing flow with local domain control

In this deployment, the core (MSS or DSS) that runs the actual data processing chain (DPC) also controls it. Application calls DPM APIs for init, data
processing IOCTL for configuration, start and stop. DPM reports back status from DPC using the application registered report callback function.
Application provides an execution context (task) for the DPM/DPC to run. DPC provides back the processing results (point cloud, tracked objects, etc)
to the application in this execution context.

5. 3. 2. 1. 1Figure 19: Data processing flow with local domain control (init/config)

51
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 3. 2. 1. 2Figure 20: Data processing flow with local domain control (start/chirp/frame/stop)

5. 3. 2. 2. Data processing flow with remote domain control

In this deployment, the data processing chain runs on a chosen data core while the control for it exists on the other core. Application code on control
core and data core calls DPM APIs for init and sync'ing with each other. The control core calls data processing IOCTL for configuration, start and stop
APIs. The H/W events are received on the data core. DPM reports back status from DPC using the application registered report callback function on
both control and data cores. DPC provides back the processing results (point cloud, tracked objects, etc) to the data core application code which can
send the result to the control core using DPM send result API.

52
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 3. 2. 2. 1Figure 21: Data processing flow with remote domain control (init/config)

5. 3. 2. 2. 2Figure 22: Data processing flow with remote domain control (start/chirp/frame/stop)

5. 3. 2. 3. Distributed Data processing flow and control

In this deployment, the data processing chain is split across cores along with the control. Application code on both cores call DPM APIs for init and
sync'ing with each other. Either core can call data processing IOCTL for configuration, start and stop APIs. DPM reports back status from DPC using
the application registered report callback function on both cores. Partial results from the DPC running on one core can be passed onto the DPC
running on other core using the DPM relay result API. DPC can provide back the final processing results (point cloud, tracked objects, etc) to the same
core's application code which can then send the result to the application running on other core using DPM send result API. Following ladder diagrams
shows just one of the many ways of splitting the DPC across two cores.

53
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 3. 2. 3. 1Figure 23: Distributed Data processing flow and control (init/config)

5. 3. 2. 3. 2Figure 24: Distributed Data processing flow and control (start/chirp/frame/stop)

5. 4. mmWave SDK - TI components

The mmWave SDK functionality broken down into components are explained in next few subsections. For detailed documentation on each of these
modules, refer to the top level documentation located at mmwave_sdk_<ver>/docs/mmwave_sdk_module_documentation.html.

5. 4. 1. Demos

5. 4. 1. 1. mmWave Demo
This demo is located at mmwave_sdk_<ver>/packages/ti/demo/<platform>/mmw folder. The millimeter wave demo shows some of the radar sensing
and object detection capabilities of the SoC using the drivers in the mmWave SDK (Software Development Kit). It allows user to specify the chirping
profile and displays the detected objects and other information in real-time. A detailed explanation of this demo is available in the demo's docs folder
and can be browsed via mmwave_sdk_<ver>/docs/mmwave_sdk_module_documentation.html. This section captures the high level layout of the
demo supported on various mmWave devices. For details on individual components (control layer, datapath layer, etc), refer to the remaining sub-
sections under "mmWave SDK - TI components".

Device xWR1843 AWR1843AOP xWR6843AOP xWR6443 xWR6843 xWR1642

Support
(QM/SIL2/ASILB)

54
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

xWR6843 (QM
/SIL2/ASILB)

Demo Directory ti\demo\xwr18xx ti\demo\xwr18xx\mmw ti\demo\xwr64xx\mmw ti\demo\xwr64xx ti\demo\xwr68xx ti\demo\xwr16xx

\mmw \mmw \mmw \mmw

Binary prefix xwr18xx_mmw_demo xwr18xxAOP_mmw_demo xwr64xxAOP_mmw_demo xwr64xx_mmw_demo xwr68xx_mmw_demo xwr16xx_mmw_demo

EVM xwr18xx BoosterPack AWR1843AOP EVM IWR6843AOP EVM xWR68xx ISK IWR68xx ISK xwr16xx BoosterPack

Platform xwr18xx xwr18xx_AOP xwr68xx_AOP xwr64xx xwr68xx xwr16xx

selection in
Visualizer

mmWave API R4F (MSS) R4F (MSS) R4F (MSS) R4F (MSS) R4F (MSS) R4F (MSS)
/RF control

Instrumentation Yes Yes Yes Yes Yes Yes

via LVDS
based
streaming

Range Proc HWA based DPU HWA based DPU (driven HWA based DPU (driven HWA based DPU HWA based DPU DSP
DPU (driven by DSP) by DSP) by R4F) (driven by R4F) (driven by R4F)

Static Clutter DSP DSP R4F (MSS) R4F (MSS) DSP DSP
Removal

Doppler Proc HWA based DPU HWA based DPU (driven HWA based DPU (driven HWA based DPU DSP DSP
DPU (driven by DSP) by DSP) by R4F) (driven by R4F)

CFAR DPU CFAR-CA HWA CFAR-CA HWA based CFAR-CA HWA based CFAR-CA HWA CFAR-CA using CFAR-CA using
based DPU (driven DPU (driven by DSP) DPU (driven by R4F) based DPU (driven DSP DSP
by DSP) by R4F)

AoA DPU HWA based DPU HWA based DPU (driven HWA based DPU using HWA based DPU DSP DSP
(driven by DSP) by DSP) 2D FFT method (driven (driven by R4F)
by R4F)

5. 4. 2. Drivers
Drivers encapsulate the functionality of the various hardware IPs in the system and provide a well defined API to the higher layers. The drivers are
designed to be OS-agnostic via the use of OSAL layer. Following figure shows typical internal software blocks present in the SDK drivers. The source
code for the SDK drivers are present in the mmwave_sdk_<ver>\packages\ti\drivers\<ip> folder. Documentation of the API is available via doxygen
and placed at mmwave_sdk_<ver>\packages\ti\drivers\<ip>\docs\doxygen\html\index.html and can be browsed easily via mmwave_sdk_<ver>/docs
/mmwave_sdk_module_documentation.html.. The driver's unit test code, running on top of SYSBIOS is also provided as part of the package mmwave_
sdk_<ver>\packages\ti\drivers\<ip>\test\. The library for the drivers are placed in the mmwave_sdk_<ver>\packages\ti\drivers\<ip>\lib directory and
the file is named lib<ip>_<platform>.aer4f for MSS and lib<ip>_<platform>.ae674 for DSP.

5. 4. 2. 0. 1Figure 25: mmWave SDK Drivers - Internal software design

Drivers Platform Platform Driver Functionality Implemented in mmWave SDK

/Hardware supported supported
IP
for R4F for DSP
target C674x
target

('all' here
excludes
xwr14xx)

55
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

ADCBUF all all All features of IP (ADCBUF, CQ) are implemented in the driver

CAN all except - Following features of IP are implemented in the driver:

xwr68xx Configure Rx and Tx I/O Control registers
Configure DCAN mode of operation
Configure DCAN controller, interrupts, ECC, parity
Set bit time parameters
Configure Rx and Tx message objects
Receive and Transmit a CAN message
Retrieve Tx message object transmission status and Rx message object reception status
Check the validity of the received message

CANFD awr16xx - Following features of IP are implemented in the driver:

awr18xx Reset MCAN driver (not supported for 60Ghz devices)

Initialize MCAN clock stop controls, auto wakeup, MCAN mode - classic versus FD mode, transceiver delay
xwr68xx conpensation
Configure MCAN controller and global filters
Configure MCAN mode of operation
Set bit time parameters
Configure message filters, Rx/Tx FIFOs
Add and cancel Tx requests
Transmits a CAN message
Receive a CAN message
Check the validity of the received message
Configure interrupt multiplexer to service message objects
Retrieve interrupt line status, interrupt pending status, parity error status, bit error status, ECC diagnostics
status, ECC error status and MCAN error status
Clear interrupt pending status, ECC diagnostics error status, ECC error status and MCAN error status
Configure MCAN parity function, self test mode, ECC Diagnostic mode

CBUFF all all Following features of IP are implemented in the driver:

Supports Platform defined HSI: LVDS or CSI (IWR14xx only).
Initialize and setup the CBUFF Driver
Configure the Linked List and EDMA Channels to support the data transfer
Supports Interleaved and Non-Interleaved data mode
Supports the data formats: ADC, ADC_CP*, CP_ADC*, CP_ADC_CQ
Supports CRC

(*By default, prebuilt CBUFF driver library only supports ADC and CP_ADC_CQ formats but the driver library can
be rebuilt for additional formats ADC_CP and CP_ADC. See CBUFF driver doxygen documentation for more
details)

CBUFF all all Following features of IP are implemented in the driver:

(LVDS) LVDS driver supports the chirp and continuous mode of data transmission.
Supports only 2 and 4 lane configuration in Format0.
Supports transfer of S/W triggered user data over CBUFF/LVDS interface

CRC all all All features of IP are implemented in the driver including:
CRC-16
CRC-32
CRC-64

CRYPTO xwr16xx (HS) - The driver supports following AES mode of encryption:

awr18xx (HS) Electronic codebook mode (ECB)

Cipher-block chaining mode (CBC)
Cipher feedback mode (CFB)
Counter mode (CTR)
Integer counter mode (ICM)
Galios/counter mode (GCM)
Counter with CBC-MAC mode (CCM)

The driver supports following HMAC modes:

MD5
SHA-1
SHA-224
SHA-256

CSI-2 iwr14xx - Following features of IP are implemented in the driver:

Initialization and Setup of the Protocol Engine
Initialization and configuration of the DSI PHY
DSI Phy Parameters can be customized by the application

DMA all - Following features of IP are implemented in the driver:

software and hardware triggered transfer
frame based transfer
block based transfer
Addressing mode (Constant, Indexed, Post Increment)
FTC, BTC, LFS, HBC interrupts
channel chaining
auto-initiation mode
interrupt based and polling based channel completion APIs

EDMA all all All features of IP are implemented in the driver except "privilege" feature

56
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

ESM all all Default ESM FIQ Interrupt handler for R4F and hook function for DSP's NMI

Provide application to register callback functions on specific ESM errors.

GPIO all - All features of IP are implemented in the driver

HWA all except all except All features of IP are implemented in the driver
xwr16xx xwr16xx

I2C all - All features of IP are implemented in the driver

MAILBOX all all All features of IP are implemented in the driver.

OSAL all all Provides an abstraction layer for some of the common OS services:
Semaphore
Mutex
Debug
Interrupts
Clock
Memory

PINMUX all - All Pinmux fields can be set and all device pad definitions are available

QSPI all - All features of IP are implemented in the driver.

QSPIFLASH all - All features of IP are implemented in the driver.

RTI all all Part of TI RTOS offering

SOC all all Provides abstracted APIs for system-level initialization. See section "mmWave SDK - System Initialization" for
more details.

SPI (MIBSPI) all - All features of IP are implemented in the driver including:
4-wire Slave and master mode
3-wire Slave and Master mode
both polling mode and DMA mode for read/write
char length 8-bit and 16-bit.

VIM all - Part of TI RTOS offering

UART all all All features of IP are implemented in the driver including:
Standard Baud Rates: 9600, 14400, 19200 till 921600
Data Bits: 7 and 8 Bits
Parity: None, Odd and Even
Stop Bits: 1 and 2 bits
Blocking and Polling API for reading and writing to the UART instance
DMA support for read/write APIs

WATCHDOG all all All features of IP are implemented in the driver.

5. 4. 2. 0. 2Table 2: Supported drivers and their functionality

5. 4. 3. OSAL
An OSAL layer is present within the mmWave SDK to provide the OS-agnostic feature of the foundational components (drivers, mmWaveLink,
mmWaveAPI). This OSAL provides an abstraction layer for some of the common OS services: Semaphore, Mutex, Debug, Interrupts, Clock, Memory,
CycleProfiler. The source code for the OSAL layer is present in the mmwave_sdk_<ver>\packages\ti\drivers\osal folder. Documentation of the APIs
are available via doxygen and placed at mmwave_sdk_<ver>\packages\ti\drivers\osal\docs\doxygen\html\index.html. A sample porting of this OSAL
for TI RTOS is provided as part of the mmWave SDK. System integrators could port the OSAL for their custom OS or customize the same TI RTOS
port for their custom application, as per their requirements.

Examples of what integrators may want to customize:

MemoryP module - for example, choosing from among a variety of heaps available in TI RTOS (SYSBIOS), or use own allocator.
Hardware interrupt mappings. This case is more pronounced for the C674 DSP which has only 16 interrupts (of which 12 are available under
user control) whereas the events in the SOC are much more than 16. These events go to the C674 through an interrupt controller (INTC) and
Event Combiner (for more information see the C674x megamodule user guide at http://www.ti.com/lit/ug/sprufk5a/sprufk5a.pdf). The default
OSAL implementation provided in the release routes all events used by the drivers through the event combiner. If a user chooses to route
differently (e.g for performance reasons), they may add conditional code in OSAL implementation to route specific events through the INTC
and event combiner blocks. User can conveniently use event defines in ti/common/sys_common_*.h to acheive this.

5. 4. 4. mmWaveLink
mmWaveLink is a control layer and primarily implements the protocol that is used to communicate between the Radar Subsystem (RADARSS) and
the controlling entity which can be either Master subsystem (MSS R4F) and/or DSP subsystem (DSS C674x). It provides a suite of low level APIs that
the application (or the software layer on top of it) can call to enable/configure/control the RADARSS. It provides a well defined interface for the
application to plug in the correct communication driver APIs to communicate with the RADARSS. it acts as driver for Radar SS and exposes services
of Radar SS. It includes APIs to configure HW blocks of Radar SS and provides communication protocol for message transfer between MSS/DSS and
RADAR SS.

Link between application and Radar SS

Handles communication errors, Notifies exceptions

57
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

Platform and OS independent

Can work in single threaded (non OS) environment

Following figure shows the various interfaces/APIs of the mmWaveLink component. The source code for mmWaveLink is present in the mmwave_sdk_
<ver>\packages\ti\control\mmwavelink folder. Documentation of the API is available via doxygen placed at mmwave_sdk_<ver>\packages\ti\control\m
mwavelink\docs\doxygen\html\index.html and can be easily browsed via mmwave_sdk_<ver>/docs/mmwave_sdk_module_documentation.html. The
component's unit test code, running on top of SYSBIOS is also provided as part of the package: mmwave_sdk_<ver>\packages\ti\control\mmwavelink\
test\ .

5. 4. 4. 0. 3Figure 26: mmWaveLink - Internal software design

5. 4. 5. mmWave API
mmWaveAPI is a higher layer control running on top of mmWaveLink and LLD API (drivers API). It is designed to provide a layer of abstraction in the
form of simpler and fewer set of APIs for application to perform the task of mmWave radar sensing. In mmwave devices with dual cores, it also
provides a layer of abstraction over IPC to synchronize and pass configuration between the MSS and DSS domains. The source code for mmWave
API layer is present in the mmwave_sdk_<ver>\packages\ti\control\mmwave folder. Documentation of the API is available via doxygen placed at mmw
ave_sdk_<ver>\packages\ti\control\mmwave\docs\doxygen\html\index.html and can be easily browsed via mmwave_sdk_<ver>/docs
/mmwave_sdk_module_documentation.html.. The component's unit test code, running on top of SYSBIOS is also provided as part of the
package: mmwave_sdk_<ver>\packages\ti\control\mmwave\test\.

58
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 4. 5. 0. 4Figure 27: mmWave API - Internal software design

There are two modes of configurations which are provided by the mmWave module.

5. 4. 5. 1. Full configuration
The "full" configuration mode implements the basic chirp/frame sequence of mmWave Front end and is the recommended mode for application to use
when using the basic chirp/frame configuration. In this mode the application will use the entire set of services provided by the mmWave control
module. These features includes:-

Initialization of the mmWave Link

Synchronization services between the MSS and DSS
Asynchronous Event Management
Start & Stop services
Configuration of the RADARSS for Frame, advanced frame & Continuous mode
Configuration synchronization between the MSS and DSS

In the full configuration mode; it is possible to create multiple profiles with multiple chirps. The following APIs have been added for this purpose:-

Chirp Management:

MMWave_addChirp
MMWave_delChirp

59
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

Profile Management:

MMWave_addProfile
MMWave_delProfile

5. 4. 5. 2. Minimal configuration
For advanced users, that either need to use advanced frame config of mmWave Front End or need to perform extra sequence of commands in the
CONFIG routine, the minimal mode is recommended. In this mode the application has access to only a subset of services provided by the mmWave
control module. These features includes:-

Initialization of the mmWave Link

Synchronization services between the MSS and DSS on the dual core devices
Asynchronous Event Management
Start & Stop services

In this mode the application is responsible for directly invoking the mmWave Link API in the correct order as per their configuration requirements. The
configuration services are not available to the application; so in mmwave devices with multiple cores (ex: xwr16xx, xwr68xx, etc), the application is
responsible for passing the configuration between the MSS and DSS if required.

See sample call flow below:

5. 4. 5. 2. 1Figure 28: mmWave API - 'Minimal' Config - Sample flow (mmWave devices with MSS and DSS cores and module in co-operative mode)

60
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 4. 5. 2. 2Figure 29: mmWave API - 'Minimal' Config - Sample flow (mmWave devices with single core or when module is used in isolation mode)

mmWave Front End Calibrations

mmWave API, by default, enables all init/boot time time calibrations for mmWave Front End. There is a provision for user to provide custom
calibration mask in MMWave_open API and/or to provide a buffer that has pre-stored calibration data.

When application requests the one-time and periodic calibrations in MMWave_start API call, mmWave API enables all the available one-
time and periodic calibrations for mmWave Front End.

mmWave API doesn't expose the mmwavelink's LDO bypass API (rlRfSetLdoBypassConfig/rlRfLdoBypassCfg_t) via any of its API. If this
functionality is needed by the application (either because of the voltage of RF supply used on the TI EVM/custom board or from monitoring
point of view), user should refer to mmwavelink doxygen (mmwave_sdk_<ver>\packages\ti\control\mmwavelink\docs\doxygen\html\index.
html) on the usage of this API and call this API from their application before calling MMWave_open().

mmWave_open

Although mmWave_close API is provided, it is recommended to perform mmWave_open only once per power-cycle of the sensor.

5. 4. 6. Datapath Interface (DPIF)

DPIF defines the standard interface points in the detection processing chain that will correspond to the "blue" boxes in the scalable chain shown in the
figure above. Key interfaces defined in this layer are:

Input ADC data (contents of ADCbuf memory)

Radar Cube
Detection Matrix
Point cloud and its side info

The source code for DPIF is present in the mmwave_sdk_<ver>\packages\ti\datapath\dpif folder.

61
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 4. 7. Data Processing Units (DPUs)

Data Translating function(s) from one interface point to the other are called “Data Processing Units”. Splitting the data processing chain into
processing units promote re-use of certain processing blocks across multiple chains. Detailed documentation on these modules can be easily browsed
via mmwave_sdk_<ver>/docs/mmwave_sdk_module_documentation.html.

Range Processing (ADC data to Radar Cube): This processing unit performs (1D FFT+ optional DC Range Calib) processing on the chirp
(RF) data during the active frame time and produces the processed data in the radarCube. This processing unit is standardized in the
mmWave SDK. It provides implementation based on both HWA and DSP. HWA based implementation can be instantiated either on R4F or
C674x. The source code for Range DPU is present in the mmwave_sdk_<ver>\packages\ti\datapath\dpu\rangeproc folder. Documentation of
the API is available via doxygen and placed at mmwave_sdk_<ver>\packages\ti\datapath\dpu\rangeproc\docs\doxygen\html\index.html. The
component's unit test code, running on top of SYSBIOS is also provided as part of the package: mmwave_sdk_<ver>\packages\ti\ datapath\d
pu\rangeproc\test\ .
Static Clutter Processing (Radar Cube to Radar Cube): When enabled, this processing unit reads Range FFT out data from the radar cube
and performs static clutter removal before writing the data back to the radar cube during the interframe time. This processing unit is offered
as reference implementation and users of SDK could either re-use these as is in their application/processing chain or create variations of
these units based on their specific needs. It provides S/W based implementation and can be instantiated either on R4F or C674x. The source
code for StaticClutter DPU is present in the mmwave_sdk_<ver>\packages\ti\datapath\dpc\dpu\staticclutterproc folder. Documentation of the
API is available via doxygen and placed at mmwave_sdk_<ver>\packages\ti\datapath\dpc\dpu\staticclutterproc\docs\doxygen\html\index.html.
Doppler Processing (Radar Cube to Detection Matrix): This processing unit performs (2D FFT + Energy Sum) processing on the radar Cube
during the inter frame and produced detection matrix. This processing unit is offered as reference implementation and users of SDK could
either re-use these as is in their application/processing chain or create variations of these units based on their specific needs. It provides
implementation based on both HWA and DSP. HWA based implementation can be instantiated either on R4F or C674x. DSP based
implementation incorporates static clutter algorithm for optimal memory/mips usage and user can skip using the standalone static clutter
DPU. The source code for Doppler DPU is present in the mmwave_sdk_<ver>\packages\ti\datapath\dpc\dpu\dopplerproc folder.
Documentation of the API is available via doxygen and placed at mmwave_sdk_<ver>\packages\ti\datapath\dpc\dpu\dopplerproc\docs\doxyg
en\html\index.html.
CFAR + AoA (Detection Matrix to Point Cloud): They are offered as two independent DPUs and collectively run CFAR-CA algorithm, peak
grouping, field-of-view filtering, doppler compensation, max velocity enhancement and angle (azimuth+elevation) estimation on the detection
matrix during inter frame to produce the point cloud. These processing units are offered as reference implementation and users of SDK could
either re-use these as is in their application/processing chain or create variations of these units based on their specific needs. They provide
implementation based on both HWA and DSP. HWA based implementation can be instantiated either on R4F or C674x. For HWA
implementation, two different algorithms are provided for AoA processing - one is the legacy method that performs independent 1D FFT on
different antenna symbol rows to determine azimuth and elevation; other algorithm uses 2D FFT on the 2D antenna symbol array to create a
two-dimensional (azimuth and elevation dimensions) output in which peaks are searched for determining azimuth and elevation for the
detected objects.
The source code for CFAR-CA DPU is present in the mmwave_sdk_<ver>\packages\ti\datapath\dpc\dpu\cfarcaproc folder.
Documentation of the API is available via doxygen and placed at mmwave_sdk_<ver>\packages\ti\datapath\dpc\dpu\cfarcaproc\docs
\doxygen\html\index.html. The component's unit test code, running on top of SYSBIOS is also provided as part of the package: mmw
ave_sdk_<ver>\packages\ti\ datapath\dpc\dpu\cfarcaproc\test\.
The source code for AoA DPU is present in the mmwave_sdk_<ver>\packages\ti\datapath\dpc\dpu\aoaproc folder. Documentation
of the API is available via doxygen and placed at mmwave_sdk_<ver>\packages\ti\datapath\dpc\dpu\aoaproc\docs\doxygen\html\ind
ex.html. The component's unit test code, running on top of SYSBIOS is also provided as part of the package: mmwave_sdk_<ver>\p
ackages\ti\ datapath\dpc\dpu\aoaproc\test\ .
The source code for AoA DPU using 2D FFT method is present in the mmwave_sdk_<ver>\packages\ti\datapath\dpc\dpu\aoa2dproc
folder. Documentation of the API is available via doxygen and placed at mmwave_sdk_<ver>\packages\ti\datapath\dpc\dpu\aoa2dpr
oc\docs\doxygen\html\index.html.

Each DPU presents the following high level design:

5. 4. 7. 0. 3Figure 30: DPU - Internal software design

All external DPU APIs start with the prefix DPU_. DPU unique name follows next.
Ex: DPU_RangeProcHWA_init
Standard external APIs: init, config, process, ioctl, deinit are provided by each DPU.
Init: one time initialization of DPU
Config: complete configuration of the DPU: hardware resources, static and dynamic (if supported by DPU)

62
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

static config: config that is static during ongoing frames

dynamic config: config that can be changed from frame to frame but only when process is not ongoing - ideally interframe
time after DPC has exported the results for the frame
Process: the actual processing function of the DPU
Ioctl: control interface that allows higher layer to switch dynamic configuration during interframe time
De-init: de-initialization of DPU
All memory allocations for I/O buffers and scratch buffers are outside the DPU since mmWave applications rely on memory overlay technique
for optimization and that is best handled at application level
All H/W resources must be allocated by application and passed to the DPU. This helps in keeping DPU platform agnostic as well as allows
application to share the resources across DPU when DPU processing doesn't overlap in time.
DPUs are OS agnostic and use OSAL APIs for needed OS services.

A typical call flow for DPUs could be represented as follows. The timing of config and process API calls with respect to chirp/frame would vary
depending on the DPU functionality, its usage in the chain, DPC implementation and overlap of hardware resources.

5. 4. 7. 0. 4Figure 31: DPU - typical call flow

5. 4. 8. Data Path Manager (DPM)

DPM is the foundation layer that enables the "scalability" aspect of the architecture. This layer absorbs all the messaging complexities (cross core and
intra core) and provide standard APIs for integration at the application level and also for integrating any "data processing chain". Application layer will
be able to call the DPM APIs from any domain (MSS or DSS) and control the configuration and execution of the "data processing chain". The APIs
offered by DPM will be available on both MSS and DSS. The various deployments that it can cater to (but not limited to) are:

Datapath control on R4F and datapath execution is split between R4F/HWA and DSP (Distributed)
Datapath control on R4F and datapath execution is on R4F using HWA (Local)
Datapath control on R4F and datapath execution is on DSP (with and without HWA) (Remote)
Datapath control on DSP and datapath execution is on DSP+HWA (Local)
Datapath control on DSP and datapath execution is on DSP (Local)

63
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

5. 4. 8. 0. 5Figure 32: Datapath manager (DPM) - internal software design

The source code for DPM is present in the mmwave_sdk_<ver>\packages\ti\control\dpm folder. Documentation of the API is available via doxygen
and placed at mmwave_sdk_<ver>\packages\ti\ control\dpm\docs\doxygen\html\index.html. The component's unit test code, running on top of
SYSBIOS is also provided as part of the package: mmwave_sdk_<ver>\packages\ti\ control\dpm\test\ .

5. 4. 9. Data processing chain (DPC)

DPC is a separate layer within the datapath that encapsulates all the data processing needs of a mmwave application and provides a well defined
interface for integration with the application. In the SDK, there is a reference implementation that corresponds to the generic "object detection" chain
which was already a part of the OOB demo in past releases. This chain will conform to the standard DPM dictated API definitions. Internally this layer
will use the functionality exposed by Data processing units (DPUs), datapath interface and datapath manager (DPM) to realize the data flow needed
for the "object detection" chain. The source code for objectdetection DPC is present in the mmwave_sdk_<ver>\packages\ti\datapath\dpc\objectedetec
tion folder. Documentation of the API is available via doxygen placed at mmwave_sdk_<ver>\packages\ti\datapath\dpc\objectedetection\<deployment_
type>\docs\doxygen\html\index.html and can be easily browsed via mmwave_sdk_<ver>/docs/mmwave_sdk_module_documentation.html.. The
component's unit test code, running on top of SYSBIOS is also provided as part of the package mmwave_sdk_<ver>\packages\ti\datapath\dpc\objecte
detection\objdethwa\test\. See section on Data Path tests using Test vector method for more details on this test.

5. 4. 10. mmWaveLib
mmWaveLib is a collection of algorithms that provide basic functionality needed for FMCW radar-cube processing. This component is available only
for those mmWave devices that have DSP/C674 cores, It contains optimized library routines for C674 DSP architecture only. This component is not
available for cortex R4F (MSS). These routines do not encapsulate any data movement/data placement functionality and it is the responsibility of the
application code to place the input and output buffers in the right memory (ex: L2) and use EDMA as needed for the data movement. The source code
for mmWaveLib is present in the mmwave_sdk_<ver>\packages\ti\alg\mmwavelib folder. Documentation of the API is available via doxygen placed at
mmwave_sdk_<ver>\packages\ti\alg\mmwavelib\docs\doxygen\html\index.html and can be easily browsed via mmwave_sdk_<ver>/docs
/mmwave_sdk_module_documentation.html. The component's unit test code, running on top of SYSBIOS is also provided as part of the package: mm
wave_sdk_<ver>\packages\ti\alg\mmwavelib\test\ .

Functionality supported by the library:

Collection of algorithms that provide basic functionality needed for FMCW radar-cube processing.
Windowing (16-bit complex input, 16 bit complex output, 16-bit windowing real array)
Windowing (16-bit complex input, 32 bit complex output, 32-bit windowing real array)
log2 of absolute value of 32-bit complex numbers
vector arithmetic (accumulation)
CFAR-CA, CFAR-CASO, CFAR-CAGO (logarithmic input samples)
16-point FFT of input vectors of length 8 (other FFT routines are provided as part of DSPLib)
single DFT value for the input sequences at one specific index
Twiddle table generation for 32x32 and 16x16 FFTs: optimized equivalent functions of dsplib for generating twiddle factor
FFT Window coefficients generation
DFT sine/cosine table generation for DFT single bin calculation
Single bin DFT with windowing.
Variation of the windowing functions with I/Q swap since most of the fixed point FFT functions in DSPLib only support one format of
complex types.
CFAR algorithms
Floating-point CFAR-CA:
mmwavelib_cfarfloat_caall supports CFAR cell average, cell accumulation, SO, GO algorithms, with input signals in floating
point formats;
mmwavelib_cfarfloat_caall_opt implements the same functionality as mmwavelib_cfarfloat_caall except with less cycles,
but the detected objects will not be in the ascending order.

64
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

mmwavelib_cfarfloat_wrap implements the same functionality as mmwavelib_cfarfloat_caall except the noise samples for
the samples at the edges are the circular rounds samples at the other edge.
mmwavelib_cfarfloat_wrap_opt implements the same functionality as mmwavelib_cfarfloat_wrap except with less cycles,
but the detected objects will not be in the ascending order.
CFAR-OS: Ordered-Statistic CFAR algorithm
mmwavelib_cfarOS accepts fixed-point input data (16-bit log-magnitude accumulated over antennae). Search window size
is defined at compile time.
Peak pruning for CFAR post-processing
mmwavelib_cfarPeakPruning: Accepts detection matrix and groups neighboring peaks into one.
mmwavelib_cfarPeakQualifiedInOrderPruning: Accepts the list of CFAR detected objects and groups neighboring peaks
into one.
mmwavelib_cfarPeakQualifiedPruning: Same as mmwavelib_cfarPeakQualifiedInOrderPruning, but with no assumption for
the order of cfar detected peaks
Floating-point AOA estimation:
mmwavelib_aoaEstBFSinglePeak implements Bartlett beamformer algorithm for AOA estimation with single object detected, it also
outputs the variance of the detected angle.
mmwavelib_aoaEstBFSinglePeakDet implements the save functionality as mmwavelib_aoaEstBFSinglePeak without the variance of
detected angle calculation.
mmwavelib_aoaEstBFMultiPeak also implements the Bartlett beamformer algorithm but with multiple detected angles, it also
outputs the variances for every detected angles.
mmwavelib_aoaEstBFMultiPeakDet implements the same functionality as mmwavelib_aoaEstBFMultiPeak but with no variances
output for every detected angles.
DBscan Clustering:
mmwavelib_dbscan implements density-based spatial clustering of applications with noise (DBSCAN) data clustering algorithm.
mmwavelib_dbscan_skipFoundNeiB also implements the DBSCAN clustering algorithm but when expanding the cluster, it skips the
already found neighbors.
Clutter Removal:
mmwavelib_vecsum: Sum the elements in 16-bit complex vector.
mmwavelib_vecsubc: Subtract const value from each element in 16-bit complex vector.
Windowing:
mmwavelib_windowing16xl6_evenlen: Supports multiple-of-2 length(number of input complex elements), and
mmwavelib_windowing16x16 supports multiple-of-8 length.
mmwavelib_windowing16x32: This is updated to support multiple-of-4 length(number of input complex elements). It was multiple-of-
8 previously.
Floating-point windowing:
mmwavelib_windowing1DFltp: support fixed-point signal in, and floating point signal out windowing, prepare the floating point data
for 1D FFT.
mmwavelib_chirpProcWin2DFxdpinFltOut, mmwavelib_dopplerProcWin2DFxdpinFltOut: prepare the floating point data for 2D FFT,
with fixed point input. The difference is mmwavelib_chirpProcWin2DFxdpinFltOut is done per chip bin, while
mmwavelib_dopplerProcWin2DFxdpinFltOut is done per Doppler bin.
mmwavelib_windowing2DFltp: floating point signal in, floating point signal out windowing to prepare the floating point data for 2D
FFT.
Vector arithmetic
Floating-point and fixed point power accumulation: accumulates signal power. Alternate API to right shift the output vector along with
accumulation is also provided.
Histogram: mmwavelib_histogram right-shifts unsigned 16-bit vector and calculates histogram.
Right shift operation on signed 16-bit vector or signed 32-bit vector
mmwavelib_shiftright16 shifts each signed 16-bit element in the input vector right by k bits.
mmwavelib_shiftright32 shifts each signed 32-bit element in the input vector right by k bits.
mmwavelib_shiftright32to16 right shifts 32-bit vector to 16-bit vector
Complex vector element-wise multiplication.
mmwavelib_vecmul16x16: multiplies two 16-bit complex vectors element by element. 16-bit complex output written in place
to first input vector.
mmwavelib_vecmul16x32, mmwave_vecmul16x32_anylen : multiplies a 16-bit complex vector and a 32-bit complex vector
element by element, and outputs to the 32-bit complex output vector.
mmwave_vecmul32x16c: multiplies 32bit complex vector with 16bit complex constant.
Sum of absolute value of 16-bit vector elements
mmwavelib_vecsumabs returns the 32-bit sum.
Max power search on 32-bit complex data
mmwavelib_maxpow outputs the maximum power found and returns the corresponding index of the complex sample
mmwavelib_powerAndMax : Power computation combined with max power search
Peak search for Azimuth estimation on 32-bit float vector
mmwavelib_multiPeakSearch : Multiple peak search in the azimuth FFT output
mmwavelib_secondPeakSearch : Second peak search in the azimuth FFT output
DC (antenna coupling signature) Removal on 32-bit float complex vector
Vector subtraction for 16-bit vectors
Matrix utilities
Matrix transpose for 32-bit matrix: Similar to DSPLib function but optimized for matrix with rows larger than columns

5. 4. 11. Group Tracker

The algorithm is designed to track multiple targets, where each target is represented by a set of measurement points (point cloud output of CFAR
detection layer). Each measurement point carries detection information, for example, range, angle, and radial velocity. Instead of tracking individual
reflections, the algorithm predicts and updates the location and dispersion properties of the group. The group is defined as the set of measurements
(typically, few tens; sometimes few hundreds) associated with a real life target. This algorithm is provided for all mmWave devices except xwr14xx but
is supported for both R4F and C674x. The source code for gtrack is present in the mmwave_sdk_<ver>\packages\ti\alg\gtrack folder. Documentation

65
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

of the API is available via doxygen placed at mmwave_sdk_<ver>\packages\ti\alg\gtrack \docs\doxygen<2d|3D>\html\index.html and can be easily
browsed via mmwave_sdk_<ver>/docs/mmwave_sdk_module_documentation.html.. The component's unit test code, running on top of SYSBIOS is
also provided as part of the package: mmwave_sdk_<ver>\packages\ti\alg\gtrack\test\ .

5. 4. 12. Board/EVM Configuration

Board/EVM specific information such as antenna pattern are provided via files under mmwave_sdk_<ver>\packages\ti\board. User can use the SDK
provided default values by compiling the code under this directory directly with their application or user can define their own values by using the
interface defined by this module.

5. 4. 13. RADARSS Firmware

This is a binary (under mmwave_sdk_<ver>\firmware\radarss) that runs on Radar subsystem of the mmWave device and realizes the mmWave front
end. It exposes configurability via a set of messages over mailbox which is understood by the mmWaveLink component running on the MSS.
RADARSS firmware is responsible for configuring RF/analog and digital front-end in real-time, as well as to periodically schedule calibration and
functional safety monitoring. This enables the mmWave front-end to be self-contained and capable of adapting itself to handle temperature and ageing
effects, and to enable significant ease-of-use from an external host perspective. Features/enhancements information can be found in the platform
specific release notes under mmwave_sdk_<ver>\firmware\radarss.

5. 4. 14. CCS Debug Utility

This is a simple binary that can flashed onto the board to facilitate the development phase of mmWave application using TI Code Composer Studio
(CCS). See section CCS Development mode for more details. For xWR14xx, this binary is for R4F (MSS) and for other mmWave devices, there is an
executable for both R4F (MSS) and C674 (DSS) and is combined into one metaImage for flashing along with RADARSS firmware. Note that the CCS
debug application for C674 (DSS) has the L1 and L2 cache turned off so that new application that gets downloaded via CCS can enable it as needed,
without any need for cache flush operations, etc during switching of applications. CCS debug for MSS (R4F) has the while loop implemented using
ARM instruction set since its purpose is to allow users to load another application using CCS and the first instruction that the application would run will
be _c_int00 which is compiled only in ARM mode.

5. 4. 15. HSI Header Utility

An optional utility library is provided for user to create a header that it can attach to the data being shipped over LVDS. This library accepts the CBUFF
session configuration and creates a header with appropriate information filled in and passes it back to the calling application. The calling application
can then supply this created header to CBUFF APIs. This config inside the header is intended to help user parse the LVDS on the receiving end. The
source code for this utility is present in the mmwave_sdk_<ver>\packages\ti\utils\hsiheader folder. Documentation of the API is available via doxygen
placed at mmwave_sdk_<ver>\packages\ti\utils\hsiheader\docs\doxygen\html\index.html and can be easily browsed via mmwave_sdk_<ver>/docs
/mmwave_sdk_module_documentation.html..

5. 4. 16. Secondary Bootloader

A reference implementation of secondary bootloader is provided in the SDK to show the usecase of updating the application metaimage in the
SFLASH (outside of ROM bootloader) by receiving the image over any serial interface. Subsequent to successful flashing, it shows how to read the
individual core images from the flash/metaImage, load them onto respective core memories and then execute the application. In addition to the flash
read/write and metaImage parser functionality, it provides reference implementation for image validity and failsafe mechanisms. The source code for
this utility is present in the mmwave_sdk_<ver>\packages\ti\utils\sbl folder. Documentation of the SBL is available at mmwave_sdk_<ver>\packages\ti\
utils\sbl\docs.

5. 4. 17. mmWave SDK - System Initialization

Application should call init APIs for the following system modules (ESM, SOC, Pinmux) to enable correct operation of the device

5. 4. 17. 1. ESM
ESM_init should be the first function that is called by the application in its main(). Refer to the doxygen for this function at mmwave_sdk_<ver>\packag
es\ti\drivers\esm \docs\doxygen\html\index.html to understand the API specification.

5. 4. 17. 2. SOC
SOC_init should be the next function that should be called after ESM_init. Refer to the doxygen for this function at mmwave_sdk_<ver>\packages\ti\dri
vers\soc \docs\doxygen\html\index.html to understand the API specification. It primarily takes care of following things:

DSP un-halt

This applies for mmWave devices with DSP core. Bootloader loads the DSP application from the flash onto DSP's L2/L3 memory but doesnt un-halt
the C674x core. It is the responsibility of the MSS application to un-halt the DSP. SOC_init for MSS provides this optional functionality under its hood.
It is recommended to always unhalt the DSP when application needs to use the DSP for realizing its functionality. For applications that doesnt need
DSP completely can choose to leave the DSP in its original state i.e. either in halt state when this application is running from the flash and booted by
the bootloader OR in unhalted/while 1 loop state when this application is running from CCS in development mode.

RADARSS un-halt/System Clock

To enable selection of system frequency to use "closed loop APLL", the SOC_init function unhalts the RADARSS and then spins around waiting for
acknowledgement from the RADARSS that the APLL clock close loop calibration is completed successfully.

Note that this function assumes that the crystal frequency is 40MHz.

66
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

MPU (Cortex R4F)

MPU or Memory Protection Unit needs to be configured on the Cortex R4F of mmWave device for the following purposes:

Protection of memories and peripheral (I/O) space e.g not allowing execution in I/O space or writes to program (.text) space.
Controlling properties like cacheability, buferability and orderability for correctness and performance (execution time, memory bandwidth).
Note that since there is no cache on R4F, cacheability is not enabled for any region.

Default MPU settings has been implemented in the SOC module as a private function SOC_mpu_config() that is called by public API SOC_init() when
SOC_MPUCfg_CONFIG option is passed by the application. Doxygen of SOC (mmwave_sdk_<ver>\packages\ti\drivers\soc \docs\doxygen\html\index.
html) has SOC_mpu_config() documented with details of choice of memory regions etc. When MPU violation happens, BIOS will automatically trap
and produce a dump of registers that indicate which address access caused violation (e.g DFAR which indicates what data address access caused
violation). Note: The SOC function uses as many MPU regions as possible to cover all the memory space available on the respective device. There
may be some free MPU regions available for certain devcies (ex: xWR14xx) for the application to use and program as per their requirement. See the
function implementation/doxygen for more details on the usage and availability of the MPU regions. If the application needs for the MPU are different
than the default settings, it can pass SOC_MPUCfg_BYPASS_CONFIG to SOC_init function and then it can either pre-configure or post configure the
MPU using exported SOC_MPUxxx() functions. Application is responsible for the correct MPU settings when SOC_MPUCfg_BYPASS_CONFIG mode
is chosen.

A build time option called DOWNLOAD_FROM_CCS has been added which when set to yes prevents program space from being protected
in case of SOC owned default MPU settings. This option should be set to yes when debugging using CCS because CCS, by default,
attempts to put software break-point at main() on program load which requires it to change (temporarily) the instruction at beginning main to
software breakpoint and this will fail if program space is read-only. Hence the benefit of code space protection is not there when using CCS
for download. It is however recommended to set this option to no when building the application for production so that program space is
protected.

MARs ( DSP/C674x)

The cacheability property of the various regions as seen by the DSP (C674x) is controlled by the MAR registers. These registers are programmed as
per driver needs in in the SOC module as a private function SOC_configMARs() that is called by public API SOC_init(). See the doxygen
documentation of this function to get more details. Note that the drivers do not operate on L3 RAM and HS-RAM, hence L3/HS-RAM cacheability is
left to the application/demo code writers to set and do appropriate cache (writeback/invalidate etc) operations from the application as necessary,
depending on the use cases. The L3 MAR is MAR32 -> 2000_0000h - 20FF_FFFFh and HS-RAM MAR is MAR33 -> 2100_0000h - 21FF_FFFFh.

5. 4. 17. 3. Pinmux
Pinmux module is provided under mmwave_sdk_<ver>\packages\ti\drivers\pinmux with API documentation and available device pads located at mmw
ave_sdk_<ver>\packages\ti\drivers\pinmux\docs\doxygen\html\index.html and can be easily browsed via mmwave_sdk_<ver>/docs
/mmwave_sdk_module_documentation.html.. Application should call these pinmux APIs in the main() to correctly configure the device pads as per
their hardware design.

TI Pinmux Utility

TI Pinmux Tool available at https://dev.ti.com/pinmux supports mmWave devices and can be used for designing the pinmux configuration
for custom board. It also generates code that can be included by the application and compiled on top of mmWave SDK and its Pinmux
driver.

5. 4. 18. Usecases

5. 4. 18. 1. Data Path tests using Test vector method

The data path processing on mmWave device for 1D, 2D and 3D processing consists of a coordinated execution between the MSS, HWA/DSS and
EDMA. This is demonstrated as part of the object detection processing chain and millimeter wave demo. The demo runs in real-time and has all the
associated framework for RADARSS control etc with it.

The unit tests located at mmwave_sdk_<ver>\packages\ti\datapath\dpc \objectdetection\<chain_type>\test) are stand-alone tests that allow data path
processing chain to be executed in non real-time. This allows developer to use it as a debug/development aid towards eventually making the data
path processing real-time with real chirping. Developer can easily step into the code and test against knowns input signals. The core data path
processing source code in object detection chain and the processing modules (DPUs) is shared between this test and the mmw demo. Most of the
documentation is therefore shared as well and can be looked up in the object detection DPC and mmw demo documentation.

The tests also provide a test generator, which allows user to set objects artificially at desired range, doppler and azimuth bins, and noise level so that
output can be checked against these settings. It can generate one frame of data. The test generation and verification are integrated into the tests,
allowing developer to run a single executable that contains the input vector and also verifies the output (after the data path processing chain), thereby
declaring pass or fail at the end of the test. The details of test generator can be seen in the doxygen documentation of these tests located at mmwave_
sdk_<ver>\packages\ti\datapath\dpc \objectdetection\<chain_type>\test\docs\doxygen\html\index.html and can be easily browsed via mmwave_sdk_<v
er>/docs/mmwave_sdk_module_documentation.html..

5. 4. 18. 2. CSI-2 based streaming of ADC data

IWR14xx device has a high speed CSI-2 transmit interface that can be used to ship ADC data or 1D/2D processed data out of the device. An example
usecase on how to program the front end to generate the ADC samples and tie it up to CBUFF/CSI-2 interface for data shipment is provided under mm

67
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

wave_sdk_<ver>\packages\ti\drivers\test\csi_stream. Refer to the doxygen documentation located at mmwave_sdk_<ver>\packages\ti\drivers\test\csi_

stream\docs\doxygen\html\index.html for more details.

5. 4. 18. 3. Basic configuration of Front end and capturing ADC data in L3 memory
To access ADC data from mmWave sensors, user need to program various basic components within the device in a given sequence. In order to help
user understand the programming model needed to configure the device and generate ADC data in device's L3 memory, an example usecase is
provided under mmwave_sdk_<ver>\packages\ti\drivers\test\mem_capture. Refer to the doxygen documentation located at mmwave_sdk_<ver>\pack
ages\ti\drivers\test\mem_capture\docs\doxygen\html\index.html for more details.

68
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

6. Appendix

6. 1. Memory usage
The map files of demo and driver unit test application captures the memory usage of various components in the system. They are located in the same
folder as the corresponding .xer4f/.xe674 and .bin files. Additionally, the doxygen for mmW demo summarizes the usage of various memories
available on the device across the demo application and other SDK components. Refer to the section "Memory Usage" in the mmwave_sdk_<ver>\pac
kages\ti\demo\<platform>\mmw\docs\doxygen\html\index.html documentation.

6. 2. Register layout
The register layout of the device is available inside each hardware IP's driver source code. See mmwave_sdk_<ver>\packages\ti\drivers\<ip>\include\r
eg_*.h. The system level registers (RCM, TOPRCM, etc) are available under the SOC module (mmwave_sdk_<ver>\packages\ti\drivers\soc\include\re
g_*.h).

6. 3. Enable DebugP logs

The DebugP_log OSAL APIs in ti/drivers/osal/DebugP.h are used in the drivers and test/app code for debug streaming. These are tied to BIOS's
Log_* APIs and are well documented in SYSBIOS documentation. The logs generated by these APIs can be directed to be stored in a circular buffer
and observed using ROV in CCS (http://rtsc.eclipse.org/docs-tip/Runtime_Object_Viewer).

Following steps should be followed to enable these logs:

1. Enable the flag DebugP_LOG_ENABLED before the header inclusion as seen below.

#define DebugP_LOG_ENABLED 1
#include <ti/drivers/osal/DebugP.h>

2. Add the following lines in your SYSBIOS cfg file with appropriate setting of numEntries (number of messages) which will impact memory
space:

Application SYSBIOS cfg file

var Log = xdc.useModule('xdc.runtime.Log');

var Main = xdc.useModule('xdc.runtime.Main');
var Diags = xdc.useModule('xdc.runtime.Diags');
var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');
LoggerBuf.TimestampProxy = xdc.useModule('xdc.runtime.Timestamp');

/* Trace Log */
var loggerBufParams = new LoggerBuf.Params();
loggerBufParams.bufType = LoggerBuf.BufType_CIRCULAR; //BufType_FIXED
loggerBufParams.exitFlush = false;
loggerBufParams.instance.name = "_logInfo";
loggerBufParams.numEntries = 100; <-- number of messages this will affect memory consumption
// loggerBufParams.bufSection = ;
_logInfo = LoggerBuf.create(loggerBufParams);
Main.common$.logger = _logInfo;

/* Turn on USER1 logs in Main module (all non-module functions) */

Main.common$.diags_USER1 = Diags.RUNTIME_ON;

/* Turn on USER1 logs in Task module */

Task.common$.diags_USER1 = Diags.RUNTIME_ON;

A sample ROV log looks like below after code is re-build and run with above changes :

69
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

6. 3. 0. 0. 1Figure 33: Sample ROV log with debug prints

6. 4. Shared memory usage by SDK demos

Existing SDK demos (mmw) assigns all available banks of shared memory to L3 memory. No additional banks are added to MSS TCMA and TCMB;
they remain at the default memory size. See TRM for more details on the L3 memory layout and "xWR1xxx Image Creator User Guide" in SDK for
more details on shared memory allocation when creating flash images. Note that the image that is programmed into the flash of the mmWave device
determines the shared memory allocation. So in CCS development mode, it is the allocation defined in ccsdebug metaImage that applies and not the
application that you download via CCS.

In SDK code, one can change the environment variable MMWAVE_SDK_SHMEM_ALLOC to customize the shmem alloc settings. If this variable is
undefined, platform specific SDK common makefile (mmwave_sdk_<ver>\packages\ti\common\mmwave_sdk_<platform>.mak) will define the default
values. When this variable is changed, user should do a clean build of the demo or ccsdebug depending on the working mode. This setting will
influence

the size of L3 memory section in linker command files (mmwave_sdk_<ver>\packages\ti\platform\<platform>)

the sys_common defines for the L3, TCMA and TCMB memory sizes for the application code to use and size the buffers, heaps, etc
accordingly. (ex: SOC_XWR16XX_MSS_TCMA_SIZE, SOC_XWR16XX_MSS_L3RAM_SIZE, etc)
the shmem_alloc input parameter to generateMetaImage script in ccsdebug and mmw demo makefiles.

Since there is a chance for sys_common defines for the memories and metaImage bank allocation to go out of sync (due to user error such as failure
to do clean build), SOC module init does a sanity check of the hardware programmed L3 bank allocations (that are fed via metaImage header) and the
sys_common defines. If the sys_common defined memory size is greater than hardware programmed bank allocations, the module throws an assert.

6. 5. mmWave Device Image Creator

This section outlines the tools used for image creation needed for flashing the mmWave devices. The application executable generated after the
compile and link step needs to be converted into a bin form for the bootloader to understand and burn it onto the serial flash present on the device.
The demos inside the mmWave SDK already incorporate the step of bin file generation as part of their makefile and no further steps are required. This
section is helpful for application writers that do not have makefiles similar to the SDK demos. Once the compile and link step is done, application
image generation is described as follows.

The Application Image interpreted by the bootloader is a consolidated Multicore image file that includes the RPRC image file of individual subsystems
along with a Meta header. The Meta Header is a Table of Contents like information that contains the offsets to the individual subsystem RPRC images
along with an integrity check information using CRC. In addition, the allocation of the shared memory to the various memories of the subsystems also
has to be specified. The bootloader performs the allocation accordingly. It is recommended that the allocation of shared memory is predetermined and
not changed dynamically.

Use the generateMetaImage script present under mmwave_sdk_<ver>\packages\ scripts\windows or mmwave_sdk_<ver>\packages\ scripts\linux for
merging the MSS .xer4f, DSS .xe674 and RADARSS RPRC binaries into one metaImage and appending correct CRC. The RPRC image for MSS and
DSS are generated internally in this script from the input ELF formatted files for those subsystem (i.e. output of linker command - .xer4f, .xe674). Set
MMWAVE_SDK_INSTALL_PATH=mmwave_sdk_<ver>\packages in your environment before calling this script. This script needs 5 parameters:

70
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

FLASHIMAGE: [output] multicore file that will be generated by this script and should be used for flashing onto the board
SHMEM_ALLOC: [input] shared memory allocation in 32-bit hex format where each byte (left to right) is the number of banks
needed for RADARSS (BSS),TCMB,TCMA and DSS. Refer to the the TRM on details on L3 shared memory layout and "Image Creator User
Guide" in the SDK. It is advisable to pass MMWAVE_SDK_SHMEM_ALLOC environment variable here to keep the compiled code and
metaImage in sync. See Shared memory usage by SDK demos section for more details.
MSS_IMAGE_OUT: [input] MSS input image in ELF (.xer4f) format as generated by the linker. Use keyword NULL if not needed
BSS_IMAGE_BIN: [input] RADARSS (BSS) input image in RPRC (.bin) format, use keyword NULL if not needed. Use mmwave_sdk
_<ver>\firmware\radarss\<platform>_radarss_rprc.bin here. For xWR14xx, select xwr12xx_xwr14xx_radarss_rprc.bin.
DSS_IMAGE_OUT: [input] DSP input image in ELF (,xe674) format as generated by the linker. Use keyword NULL if not needed

The FLASHIMAGE file generated by this script should be used for the METAIMAGE1 during flashing step (How to flash an image onto mmWave EVM)
. Refer to "Image Creator User Guide" in the SDK docs directory for details on the internal layout and format of the files generated in these steps.

6. 6. mmw Demo: cryptic message seen on DebugP_assert

In mmw demo, the BIOS cfg file dss_mmw.cfg has below code at the end to optimize BIOS size. Because of some of these changes, exceptions, such
as those generated through DebugP_assert() calls may give a cryptic message instead of file name and line number that helps identify easily where
the exception is located. To be able to restore this capability, the user can comment out the lines marked with the comment "" below. For more
information, refer to the BIOS user guide.

/* Some options to reduce BIOS code and data size, see BIOS User Guide section
"Minimizing the Application Footprint" */
System.maxAtexitHandlers = 0; /* COMMENT THIS FOR FIXING DebugP_Assert PRINTS */
BIOS.swiEnabled = false; /* We don't use SWIs */
BIOS.libType = BIOS.LibType_Custom;
Task.defaultStackSize = 1500;
Task.idleTaskStackSize = 800;
Program.stack = 1048; /* for isr context */
var Text = xdc.useModule('xdc.runtime.Text');
Text.isLoaded = false;

6. 7. How to execute Idle instruction in idle task when using SYSBIOS

The idle function hook provided by SYSBIOS can be used to install application specific function which in turn could call the "idle" asm instruction. See
code snapshots below or refer to mmW demo for details.

BIOS CFG file

var Idle = xdc.useModule('ti.sysbios.knl.Idle');

Idle.addFunc('&MmwDemo_sleep');

WFI instruction for R4F

void MmwDemo_sleep(void)
{
/* issue WFI (Wait For Interrupt) instruction */
asm(" WFI ");
}

IDLE instruction for C674x

void MmwDemo_sleep(void)
{
/* issue IDLE instruction */
asm(" IDLE ");
}

6. 8. Range Bias and Rx Channel Gain/Offset Measurement and Compensation

Refer to the section "Range Bias and Rx Channel Gain/Offset Measurement and Compensation" in the mmwave_sdk_<ver>\packages\ti\datapath\dpc\
objectdetection\<chain_type>\docs\doxygen\html\index.html documentation for the procedure and internal implementation details. To execute the
procedure using Visualizer GUI, here are the steps:

Set the target as explained in the demo documentation and update the mmwave_sdk_<ver>\packages\ti\demo\<platform>\mmw\profiles\profil
e_calibration.cfg appropriately.
Set up Visualizer and mmW demo as mentioned in the section Running the Demos.
Use the "Load Config From PC and Send" button on plots tab to send the mmwave_sdk_<ver>\packages\ti\demo\<platform>\mmw\profiles\pr
ofile_calibration.cfg.

71
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

The Console messages window on the Configure tab will dump the "compRangeBiasAndRxChanPhase" command to be used for
subsequent runs where compensation is desired.
Copy and save the string for that particular mmWave sensor to your PC. You can use it in the "Advanced config" tab in the Visualizer and
tune any running profile in real time. Alternatively, you can add this to your custom profile configs and use it via the "Load Config From PC
and Send" button.

6. 9. Guidelines on optimizing memory usage

Depending on requirements of a given application, there may be a need to optimize memory usage, particularly given the fact that the mmWave
devices do not have external RAM interfaces to augment on-chip memories. Below is a list of some optimizations techniques, some of which are
illustrated in the mmWave SDK demos (mmW demo). It should be noted, however, that the demo application memory requirements are dictated by
requirements like ease/flexibility of evaluation of the silicon etc, rather than that of an actual embedded product deployed in the field to meet specific
customer user cases.

1. On R4F, compile your application with ARM thumb option (depending on the compiler use). If using the TI ARM compiler, the option to do
thumb is code_state=16 . Another relevant compiler option (when using TI compiler) to play with to trade-off code size versus speed is --
opt_for_speed=0-5 . For more information, refer to ARM Compiler Optimizations and ARM Optimizing Compiler User's Guide. The pre-
built drivers in the SDK are already built with the thumb option. The demo code and BIOS libraries are also built with thumb option. Note the
code_state=16 flag and the ti.targets.arm.elf.R4Ft target in the mmwave_sdk_<ver>\packages\ti\ common\mmwave_sdk.mak.
2. On C674X, compile portions of code that are not in compute critical path with appropriate -mfX option. The -mf3 options is presently used in
the SDK drivers, demos and BIOS cfg file. This option does cause compiler to favor code size over performance and hence some cycles
impact are to be expected. However, on mmWave device, using mf3 option only caused about 1% change in the CPU load during active and
interframe time and around 3-5% increase in config cycles when benchmarked using driver unit tests. For more details on the "mf" options,
refer to The TI C6000 compiler user guide at C6000 Optimizing Compiler Users Guide. Another option to consider is -mo (this is used in
SDK) and for more information, see section "Generating Function Subsections (--gen_func_subsections Compiler Option)" in the compiler
user guide. A link of references for optimization (both compute and memory) is at Optimization Techniques for the TI C6000 Compiler.
3. Even with aggressive code size reduction options, the C674X tends to have a bigger footprint of control code than the same C code compiled
on R4F. So if feasible, partition the software to use C674X mainly for compute intensive signal-processing type code and keep more of the
control code on the R4F. An example of this is in the mmw demo, where we show the usage of mmwave API to do configuration (of
RADARSS) from R4F instead of the C674X (even though the API allows usage from either domain). In mmw demo, this prevents linking of mm
wave (in mmwave_sdk_<ver>\packages\ ti\control ) and mmwavelink (in mmwave_sdk_<ver>\packages\ti\control ) code that is involved in
configuration (profile config, chirp config etc) on the C674X side as seen from the .map files of mss and dss located along with application
binary.
4. If using TI BIOS as the operating system, depending on the application needs for debug, safety etc, the BIOS footprint in the application may
be reduced by using some of the techniques listed in the BIOS User Guide in the section "Minimizing the Application Footprint". Some of
these are illustrated in the mmw demo on R4F and C674X. Some common ones are disabling system_printf (printf strings do contribute to
significant code size), choosing sysmin and using ROV for debugging, disabling assert (although this should be done only when variability in
driver configuration is not expected and existing configuration has been proven to function correctly). The savings from these features could
be anywhere from 2KB to 10KB but user would lose some perks of debuggability.
5. If there is no requirement to be able to restart an application without reloading, then following suggestions may be used:
a. one time/first time only program code can be overlaid with data memory buffers used after such code is executed. Note: Ability to
place code at function granularity requires to use the aforementioned -mo option.
b. the linker option --ram_model may be used to eliminate the .cinit section overhead. For more details, see compiler user guide
referenced previously. Presently, ram model cannot be used on R4F due to bootloader limitation but can be used on C674X. The
SDK uses ram model when building C674X executable images (unit tests and demos).
6. On C674X, smaller L1D/L1P cache sizes may be used to increase static RAM. The L1P and L1D can be used as part SRAM and part cache.
Smaller L1 caches can increase compute time due to more cache misses but if appropriate data/code is allocated in the SRAMs, then the
loss in compute can be compensated (or in some cases can also result in improvement in performance). In the demos, the caches are sized
to be 16 KB, allowing 16 KB of L1D and 16 KB of L1P to be used as SRAM. Typically, the L1D SRAM can be used to allocate some buffers
involved in data path processing whereas the L1P SRAM can be used for code that is frequently and more fully accessed during data path
processing. Thus we get overall 32 KB more memory. The caches can be reduced all the way down to 0 to give the full 32 KB as SRAM: how
much cache or RAM is a decision each application developer can make depending on the memory and compute (MIPS) needs.
7. When modeling the application code using mmW demo as reference code, it might be useful to trim the heaps in mmW demo to claim back
the unused portion of the heaps and use it for code/data memory. Ideally, a user can run their worst case profile that they would like to
support using mmW demo, record the heap usage/free metrics for (L1D, L2)/TCMB and L3 heaps on 'sensorStart'. These values can then be
used to resize or re-allocate heap globals (example: gDPC_ObjDetTCM, gMmwL3, etc) in mmwave_sdk_<ver>\packages\ti\demo\<platform>\
mmw. The freed up space in DSS could be used as follows:

a. Free heap space in L1D could be used to move some of the L2 buffers to L1D. The freed L2 space can be used for code/data.
b. Free heap space in L2 could be trimmed by changing the heap's global variable (ex: gMmwL2) definition and used for code/data
memory (note that code memory by default is L2 so no other change is required to get more code space).
c. Free heap space in L3 could be trimmed by changing the heap's global variable (ex: gMmwL3) definition and used for code/data
space.

When using TI compilers for both R4F and C674x, the map files contain a nice module summary of all the object files included in the application.
Users can use this as a guide towards identifying components/source code that could be optimized. See one sample snapshot below:

Module summary inside application's .map file

MODULE SUMMARY

Module code ro data rw data

------ ---- ------- -------

obj_xwr14xx/

72
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

main.oer4f 5191 0 263980

data_path.oer4f 8441 0 65536
config_hwa_util.oer4f 4049 0 0
post_processing.oer4f 2480 0 0
mmw_cli.oer4f 2308 0 0
config_edma_util.oer4f 1276 0 0
sensor_mgmt.oer4f 1144 0 24
+--+-------------------------------+--------+---------+---------+
Total: 24889 0 329540

6. 10. How to add a .const (table) beyond L3 heap in mmWave application where overlay is enabled
To achieve L3 heap overlaid with the code to be copied into L1P at init time, L3 heap is in PAGE 1 and code is in Page 0. PAGE 0 is the only loadable
page whereas PAGE 1 is just a dummy page to allocate uninitialized sections to implement overlay. As a result the ".const" section (which is loadable
section) cannot simply be allocated to PAGE 1 to go after the heap. If the .const is allocated in PAGE 0, then it will overlap the heap and will be
overwritten once heap is allocated. To resolve this, the HIGH feature of the linker could be used is used to push the const table to the highest address
ensuring no overlap with L3 heap. The suggested changes would be as follows:
1. Shrink the L3 heap by the size of the table (but L3 heap must still be bigger than the size of the L1P cache).
2. Place the table in a named section and allocate the named section in the HIGH space of PAGE 0 of L3RAM.

This ensures that the table will be allocated at the high address and will not be overlapping with L3 heap or the L1P intended code which are located
at the low address.

Sample code is shown below.

In application C file:

#define TABLE_LENGTH 4
#define TABLE_ALIGNMENT 8 /* bytes */

/*! L3 RAM buffer, shrunk by table */

#pragma DATA_SECTION(gMmwL3, ".l3data");
#pragma DATA_ALIGN(gMmwL3, 8);
uint8_t gMmwL3[SOC_XWR16XX_DSS_L3RAM_SIZE - TABLE_LENGTH*sizeof(float) - TABLE_ALIGNMENT];

#pragma DATA_SECTION(gArray, ".l3data_garray");

#pragma DATA_ALIGN(gArray, TABLE_ALIGNMENT);
const float gArray[TABLE_LENGTH] = {1.5, 3.2, 0.8, -9.6};

In linker command file:

.l3data_garray: load=L3SRAM PAGE 0 (HIGH)

6. 11. Enabling L3 cache for DSP/C674x on mmWave devices

In a given usecase for mmWave devices, if L3 RAM is not fully utilized for Radar Cube storage, then the remaining free L3 memory could ideally be
used for code and other internal data storages for the application. However, access to L3 memory from DSP/C674x core in mmWave devices is
slower than accessing L1/L2. The cache-based memory system of C674x can be efficiently used in such cases. Refer to C674x DSP Cache User
Guide (http://www.ti.com/lit/ug/sprug82a/sprug82a.pdf) for more details on the L1P/L1D/L2 two-level hierarchy that exists within the C674x memory
architecture. L1P, L1D and L2D can be partitioned into SRAM and cache. L1P, L1D and L2 cache size can be set through linker command file -please
refer to mmwave_sdk_<ver>/packages/ti/platform/<platform>/c674x_linker.cmd for more details. L2 SRAM addresses are always cached in L1P and
L1D. However, external memory addresses (ex: code/data in L3) by default are configured as non-cacheable in L1D and L2 caches. Cacheability for
external memory addressed (ex: L3) must first be explicitly enabled by the user using the MAR registers. Note that L1P cache is not affected by this
configuration and always caches external memory addresses.

Cache writeback: To maintain cache coherency between different masters (CPU, DMA, R4F, etc), content in cache needs to be written back
to memory after it is changed before triggering the other master to access that memory location.
Cache Invalidate: Before reading the content from the physical memory that was updated by another master, the content in cache needs to
be invalidated, so that updated data from memory can be loaded in cache.
APIs: User can use DSPICFGRegs directly from mmwave_sdk_<ver>/packages/ti/drivers/soc/include/reg_dspicfg.h or the TI BIOS cache
module APIs to perform these MAR settings, cache invalidates and cache writebacks.
Code in L3: mmWave code can be placed from L2 to L3 (via linker command file) with no explicit need for cache enablement and/or cache
operations during real time. The only setting that needs to be adjusted is the size of L1P cache and that should be balanced against the need
for L1P SRAM to place real time optimized functions (and avoid any cache misses, etc).
Data in L3: If data cache is enabled for L3 memory via the MAR registers, then at first, one needs to take care of cache invalidates and
writebacks for existing data structures in L3 memory. Radarcube and detection matrix are the primary data structures placed in L3 memory in
case of a typical mmwave application on our device. Typically Radarcube is accessed (read/write) only via EDMA during the Range and
Doppler FFT. Post that, it is more common for the DSP core to access the radarcube directly (i.e. no EDMA) and primarily it is a read access.
In such scenario, the Radarcube can be invalidated at the end of current frame but before the start of next frame (i.e. when EDMA master
begins to access radarcube). If the Radarcube was modified by the core directly (write operation) during the interframe time, then cache
writeback_invalidate is needed at the end of current frame but before the start of next frame. Same consideration would apply for detection
matrix. Next, mmWave internal data structures that are accessed purely by DSP can also be moved from L2 to L3 (via linker command file).
No explicit cache writeback/invalidations are required for such structures. If user chooses to place the frame results structures in L3 (point
cloud, etc) which are shared with MSS (R4F), then cache writeback+invalidate needs to be performed before signaling the MSS about

73
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

availability of frame results. Note: If the analysis of L3 data access pattern between the DSP, MSS and EDMA shows that cache writeback
/invalidate of all L3 data content can be done towards the end of the current frame, then performing writeback+invalidate on entire L1D cache
might be a better option than calling such API on individual structures.

6. 12. DSPlib integration in mmWave C674x based application (Using 2 libraries simultaneously)
The TI C674X DSP is a merger of C64x+ (fixed point) and C67x+ (floating point) DSP architectures and DSPlib offers two different flavors of library for
each of these DSP architectures. An application on C674X may need functions from both architectures. Normally this would be a straight-forward
exercise like integrating other TI components/libraries. However there is a problem during integration of the two DSPLib libraries in the same
application since the top level library API header dsplib.h has the same name and same relative path from the packages/ directory as seen below
in the installation:

C:\ti\dsplib_c64Px_3_4_0_0\packages\ti\dsplib\dsplib.h
C:\ti\dsplib_c674x_3_4_0_0\packages\ti\dsplib\dsplib.h

Typically when integrating TI components, the build paths are specified up to packages\ directory and headers are referred as below:

#include <ti/dsplib/dsplib.h>

However this will create an ambiguity when both libraries are to be integrated because the above path is same for both. There are a couple of ways to
resolve this:

6. 12. 1. Integrating individual functions from each library

In this case, the headers individual functions are included in the application source file and the build infrastructure (makefiles for example) refers to the
paths to the individual functions. This style of integration is illustrated in the following code snippets:

Sample DSPLib integration using individual functions

In application's makefile:

dss_mmw.mak

dssDemo: C674_CFLAGS += --cmd_file=$(BUILD_CONFIGPKG)/compiler.opt \

/* include path for DSP_fft16x16 */ \
-i$(C64Px_DSPLIB_INSTALL_PATH)/packages/ti/dsplib/src/DSP_fft16x16/c64P \
/* include path for DSP_fft32x32 */ \
-i$(C64Px_DSPLIB_INSTALL_PATH)/packages/ti/dsplib/src/DSP_fft32x32/c64 \
-i$(C674x_MATHLIB_INSTALL_PATH)/packages \

In application C file:

dss_data_path.c

#include "DSP_fft32x32.h"
#include "DSP_fft16x16.h"

The C674P library can be integrated in the above code similar to the how the C64P has been done, this will not create any conflict.

A variant of the above could be as follows where the paths are now in the .c and .mak only refers to the installation:

dss_mmw.mak

dssDemo: C674_CFLAGS += --cmd_file=$(BUILD_CONFIGPKG)/compiler.opt \

-i$(C64Px_DSPLIB_INSTALL_PATH)/packages \
-i$(C674x_MATHLIB_INSTALL_PATH)/packages \

dss_data_path.c

#include <ti/dsplib/src/DSP_fft16x16/c64P/DSP_fft32x32.h>
#include <ti/dsplib/src/DSP_fft16x16/c64P/DSP_fft16x16.h>

74
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

6. 12. 2. Patching the installation

The previous method can get cumbersome if there are many functions to be integrated from both libraries. Patching the installation to rename
/duplicate the top level API header dsplib.h allows a straight-forward integration. This prevents the name conflict of the two headers. So the
installation after patching would look like below for example:

C:\ti\dsplib_c64Px_3_4_0_0\packages\ti\dsplib\dsplib_c64P.h [one can retain the older dsplib.h if one wants to]
C:\ti\dsplib_c674x_3_4_0_0\packages\ti\dsplib\dsplib_c674x.h [one can retain the older dsplib.h if one wants to]

And the .mak and code will look like below:

Sample DSPLib integration after renaming header files

In application makefile:

dss_mmw.mak

dssDemo: C674_CFLAGS += --cmd_file=$(BUILD_CONFIGPKG)/compiler.opt \

-i$(C64Px_DSPLIB_INSTALL_PATH)/packages \ <-- C64P dsplib
-i$(C674x_DSPLIB_INSTALL_PATH)/packages \ <-- C674x dsplib
-i$(C674x_MATHLIB_INSTALL_PATH)/packages \

In application C file:

dss_data_path.c

#include <ti/dsplib/dsplib_c64P.h>
#include <ti/dsplib/dsplib_c674x.h>

The present dsplibs do not have name conflicts among their functions so they can both be integrated in the above manner.

6. 13. SDK Demos: miscellaneous information

A detailed explanation of the mmW demo is available in the demo's docs folder: mmwave_sdk_<ver>\packages\ti\demo\<platform>\mmw\docs\doxyge
n\html\index.html. Some miscellaneous details are captured here:

In demos that use HWA as the only processing node and elevation is enabled during run-time via configuration file, the number of detected
objects are limited by the amount of HWA memory that is available for post processing.
Demo's rov.xs file is provided in the SDK package to facilitate the CCS debugging of pre-built binaries when demo is directly flashed onto the
device (instead of loading via CCS).
When using non-interleaved mode for ADCBuf, the ADCBuf offsets for every RX antenna/channel enabled need to be multiple of 16 bytes.
Output packet of mmW demo data over UART is in TLV format and its length is a multiple of 32 bytes. This enables post processing
elements on the remote side (PC, etc) to process TLV format with header efficiently.

6. 14. Data size restriction for a given session when sending data over LVDS
For the current implementation of the CBUFF/LVDS driver and its intended usage, the CBUFF data size for a given session needs to be multiple of 8.

User should take care of this restriction when writing their custom application using the SDK LVDS driver. This alignment is taken care by the HSI
header library if the application uses the headers for LVDS streaming. If no header are used while streaming data over LVDS lanes, user should
calculate the total data size in bytes for the hardware triggered session (i.e. per chirp) and make sure it follows the rules mentioned above. Similar
rules apply for the user data sent during the software triggered session.

6. 15. CCS Debugging of real time application

It is relatively easier to debug code before real-time starts because single-stepping or adding break-points does not affect the debugging since there is
no real-time data and deadline to process the data. But once real-time starts, which is after sensor is started, such debugging can be intrusive and
problematic. Below are some tips that may be helpful in real-time debugging, some of them are relevant to the out of box demos but may be applied in
user applications if relevant.

6. 15. 1. Inter-chirp debugging

In out of box demos and many application specialized demos based on the SDK provided by TI (through the TI resource explorer), the inter-chirp
processing is based on either HWA or DSP but not a mix of the two. In the case of HWA, the CPU/CPUs are idling with respect to inter-chirp
processing so there is no need to halt. If one intends to stop and examine the state of HWA-EDMA during any of the intermediate processing steps,
the design would have to be changed to issue a HWA or EDMA interrupt to the CPU that configured these (typically MSS CPU) at this intermediate

75
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

state and the interrupt could read out some state and store in global variables that could be examined later. If code is halted using a break-point in the
interrupt, the EDMA will automatically halt but HWA will not unless HWA is waiting on EDMA, so HWA could continue to run even if the CPU is halted.
The current radar SoCs do not have the feature to halt the HWA when any of the CPUs are halted.

In case of DSP doing the inter-chirp processing, there can be a need to single-step/break the processing. However, (unlike the MSS CPU) when DSP
is halted, the RadarSS (front end) doesnt halt and the chirping activity does not stop. Because of this, the DSP will miss the chirp processing deadline
and the code is typically written to throw an exception. So basically halted debug is not useful unless a single chirp is configured and problem can be
recreated with a single chirp. There might be other limitations in the demo code that may prevent a single chirp configuration (e.g in the AWR1642
demo, minimum number of doppler bins is required to be 16 due to DSPLIB FFT function restrictions and there is an error check for this during config
validation - but this check may be disabled temporarily as it wouldn't affect the inter-chirp processing). Other techniques shown in below sections (real-
time logging, using non real-time unit test bench) may be more practical but have their own limitations. In most implementations however, 1D
processing uses a hardened component from the SDK - the range DPU - so the need for real-time debugging in the active chirping period is low.

6. 15. 2. Inter-frame debugging

As there is no RadarSS chirping activity when MSS CPU is halted, it is possible to do halted debug in MSS during inter-frame debugging without
running out of real-time. But on DSP, the device behavior is the opposite i.e the chirping will continue even if DSP is in halted state, so stepping in the
DSP will cause an inter-frame deadline miss exception when running the out of box demo and other special demos that are implemented similarly.
One technique that may be helpful in this situation is if the problem can be observed in the first frame itself, configure the chirping profile to do only
one frame (frameCfg CLI command). This way after the active frame period, there is no chirp overrun (of the next frame) pressure when single-
stepping in the inter-frame processing.

6. 15. 3. Using non-real time chain test code

See section "Data Path tests using Test vector method" on details about the non-real time chain that is provided with the mmWave SDK. Users can
use these tests to step through the OOB processing chain in non-real time mode and debug or learn the components of the OOB processing chain.

6. 15. 4. Using printfs in real time

This applies to SYSBIOS and debugging using CCS. Once the application starts real-time processing (i.e. once sensor start is issued), there should
ideally be no prints on the console because CCS will halt the processor (unless CIO is disabled) on which such prints are issued for as long as it takes
it to transfer the print string data from target to PC over JTAG and print the string on the PC (which can be of the order of seconds). This is true for any
real-time application that uses SYSBIOS on any SoC (not just mmWave SDK/devices). For logging in real-time, SYSBIOS offers other options like
LOG module, etc - although these will incur some memory overheads. For example, see "Enable DebugP logs" section. It is also possible in cfg file of
SYSBIOS based application to direct System_printfs to an internal log buffer (circular or saturate) which will also prevent the hiccup by CCS (See 'xdc.
runtime. SysMin' in SYSBIOS/XDC).

The out of box demos based on the DPC/DPU/DPM architecture have by default the DebugP type real-time logging enabled. In order to visualize the
logs, the CCS feature of Run Time Object Viewer (ROV) can be used. Instructions of how to use this feature can be seen at http://processors.wiki.ti.
com/index.php/Runtime_Object_View_(ROV). Below is a sample log for the xwr68xx out of box demo.

6. 15. 5. Viewing hardware registers

76
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

During debug, there may be a need to examine registers of HWA, EDMA, external I/O peripherals etc. These can be done using View->Registers
menu and when a core is selected, the register view will display all registers that the core can see organized into various categories. An example is
shown below:

Individual hardware entities can be expanded further in the view to see registers specific to the hardware entity. The following picture illustrates
viewing a certain PARAM set in instance #0 of the EDMA (TPCC0), note how the bit fields are automatically parsed and displayed in a user friendly
manner which saves the burden of manually parsing or developing special parsing tools and facilitates quick debugging. Default number formats of bit
fields are binary which is not always convenient, this can be changed by selecting the field/fields and right-clicking to see the number format menu as
shown in the example below where the A and B counts of EDMA are about to be chosen for Decimal format. Once chosen, the GUI will remember the
user choice for that specific field so user does not have to repeat this action in future debug sessions.

77
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

In the above picture, one can also see the "Watch" menu item. If this is selected, then the two fields of interest will appear in the Expressions view, this
is a convenient way to see some fields of interest during debug without having to navigate the register structure again (although when a particular
structure such as PARAM set #16 above is expanded, if the top level TPCC0 is shrunk and expanded again, thePARAM #16 is shown expanded as
before because GUI remembers sub-structure expansion/non-expansion state).

6. 15. 6. Viewing expressions/memory in real time

When debugging real time application (for example: mmw demo) in CCS, if the continuous refresh of variables in the Expression or Memory browser
window is enabled without enabling the silicon real-time mode as shown in the picture, the code may crash at a random time showing the message in
the console window. To avoid this crash, please put CCS in to “Silicone Real-time” mode after selecting the target core.

Continuous refresh:

Crash in Console window:

78
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

Enable “Silicone Real-time” mode:

6. 16. Size of Enum

79
Copyright (C) 2020, Texas Instruments Incorporated MMWAVE SDK User Guide
http://www.ti.com

If a variable of enum type is used to exchange information between ARM and DSP core, then it is necessary to make sure the enum size matches for
the same variable compiled on the two cores. TI ARM compiler's default type for enum is packed, which causes the underlying enumeration type to be
the smallest integer type that accommodates the enumeration constants. By default, the TI C6000 (DSP) compiler uses a 32-bit integer to store enum
objects with enumeration values smaller than 32 bits. This could cause an enum define that takes values 1 to 4 (for example) to be of size 1 byte on
R4F and of size 4 bytes on C66x. For devices where DSP and ARM coexist such as xwr16xx, they must be set to ensure that enum types are
consistent between ARM and DSP. For devices where DSP is not present (xwr14xx), it is not necessary to force enum types to be 32bit integers and if
forced, it may increase program memory usage. In mmWave SDK command makefile, flags R4F_XSFLAGS_ENUM_TYPE and
R4F_CFLAGS_ENUM_TYPE are used in conjunction to enforce that enum types are compiled as 32bit integers. It is necessary that all libraries and
the application code for a given core are compiled with the same compiler option for enum type else there will be a linker warning and one will
encounter errors that cannot be detected until run time.

Linker warning for incompatible enumeration type

warning #16027-D: object files have incompatible enumeration types ("xxxx" = packed, "yyyy" = 32-bit)

(xxxx and yyyy will be the names of actual object files that do not have matching enum type)

Please note that the R4F custom application using mmwave SDK pre-built libraries should be compiled with "--enum_type=int" option
specified to the compiler.

80