MIDAS OCT v1.0 Demo

From Texas Instruments Wiki
Jump to: navigation, search

Overview

Texas Instruments' Medical Imaging Demo Application Starter (MIDAS) illustrates the integration of key medical imaging algorithm modules on Texas Instruments (TI) DSPs and System-on-Chips. The MIDAS Optical Coherence Tomography (OCT) v1.0 demo illustrates a system level implementation of OCT signal processing on a homogenous C6678 eight-core Multicore TI DSP and a PC. We use the TI C6678 Low-cost EVM interfaced via an Ethernet-Ethernet connection to the PC. The TMS320C6678 EVM consists of eight high-performance C66 DSP cores, each of which can run up to a speed of 1.25 GHz and approximately 11 watts of power consumption, held together by a high speed switch fabric. The C6678 provides 4MB of shared memory and provides an internal mechanism for sharing data amongst cores. The on-chip DMA Engine allows automated movement of data between peripherals and memory. The device also contains high speed I/O ports such as PCIE, SRIO and Gigabit Ethernet. This in integration with the PC provides a power-efficient solution to handle both system controller and signal processing functions in diagnostic OCT systems for a fraction of the power needed by Graphics Processing Units (GPU's). The demo example discussed here on these devices can be leveraged in several applications on a variety of multicore devices.

Figure 1 below, showcases the function of the cores on the C6678 and the PC. This version incorporates the Optical Coherence Tomography(OCT) v1.0 demo which integrates components from the OCT signal chain including Background Subtraction, Re-sampling, Real-to-Complex FFT, Magnitude Computation and Log Compression from the Embedded Processor Software Toolkit for Medical Imaging on the TMS320C6678 EVM. The Software Toolkit includes both the source code and detailed documentation for these kernels.

LogicalPartiioning OCTDemo.PNG

The sample raw data sets used in this demo are tumor/ bladder and skin data which have been provided by Dr. Boppart's lab at the University of Illinois at Urbana Champagne. Each frame of raw data includes 1000 scanlines, 2048 samples/scanline. This input data is initially stored on DDR. The input data is then fed in at a set acquisition interval rate of 25 fps in this case (the acquisition interval can be customized based on the application and memory requirements), which is then processed through the modules as shown above before the final image is displayed on the PC.

This wiki document covers various aspects of the demo, including a discussion on the software design as well as step-by-step instructions to obtain the source code, and setup your development environment to build and run the demo.

Source Code Hosting (GForge Project Portal)

MIDAS source code is hosted on TI's GForge project portal.

Software Implementation

This section discusses the software implementation for OCT v1.0 and showcases how TI's software components including Multicore Software Development Kit (MCSDK), Codec Engine (CE), Digital Media Application Interface (DMAI) and iUniversal APIs can be leveraged by developers to create applications for such systems.

The block diagram showcases the TI production software components that the Multicore DSP application relies on.

Software Components1.JPG


TI's SYS/BIOS 6.x is a highly configurable, real-time operating system that caters to a variety of embedded processors and is included as part of TI’s Code Composer Studio integrated development environment. SYS/BIOS provides some key features that enable easy memory management, preemptive multitasking and real-time analysis. Based on the application's requirements, developers can optimize their final runtime image by including/excluding specific SYS/BIOS modules.

The Multicore Software Development Kit (MCSDK) includes key components that ease multicore development including the chip support library, low level drivers, platform software (PDK), Network Developer's Kit (NDK), etc. The Codec Engine, which we describe in more detail later provides a framework and APIs to easily plug-and-play algorithms, and handle Inter-Processor Communication (IPC) under the hood.

Multicore DSP (Mid End)

The software application that runs on C6678 is based on a Master/Slave model, where Core 0 acts as the centralized controlling core aka the Master core, and Core 1 to Core 7 act as the Slave cores. Note that in this demo we utilize six of the eight cores to demonstrate our use case. Core 0 which serves as the master takes care of the synchronization and sets up buffer pointers. The signal processing modules are run across Core 1 - Core 5. Cores 6 and 7 are idle. Note however that even though distribution is done statically, the assignment of algorithms to cores is done outside of the main application. It is easy to modify this distribution of processing to allow more frame per second of operations or to allow additional functionalities. This allows easy reconfiguration and at the application software level, the developer can be agnostic to which core is running which algorithm.

Functional Overview

The software application on C6678's Core 0 is designed to integrate the following functional blocks: Front End Interface, Mid End Controller, Mid End Processing and Back End Interface.

OCT Demo Application Design.png

Mid End Controller

As the name suggests, the Mid End Controller is responsible for initializing and initiating the other blocks.

Front End Interface

The Front End Interface serves two primary functions: it provides periodic events that mark the availability of incoming input data and it provides functions to access this data that has arrived. Since this version of the demo, OCT v1.0 showcases processing blocks post data acquisition, and has no front-end implementation, it becomes necessary to mimic the function of the OCT front-end as in a real system, where input frames would be continuously received at a set acquisition frame rate. The Front End Interface serves this role, where in it fires an INPUT_RDY event every (1/acquisition rate) seconds. The acquisition rate is set in our demo through a parameter file described later in this document. The clock ticks are derived from the SYS/BIOS Timer module. Note here that though in this design we use a frame-based processing model, where the frame boundary defines the input block size, it is also possible to have partial frames as input boundaries.

Mid End Processing

The Mid End Processing function block is pending on the INPUT_RDY event from the Front End Interface and as soon as a new frame is “received,” it initiates processing on that input block. Mid End Processing acts as the Client in the Codec Engine (CE) framework and uses the iUniversal interface to call upon Algorithm Servers that correspond to various functions within the OCT midend processing signal chain. In this implementation, there are multiple algorithm servers implemented, one for each core (Core 1 through Core n).

Let us now look at the primary execution threads that define the data flow through the Mid End Processing block. The figure below shows multiple primary tasks that utilize the MessageQ IPC module for message passing. The messages provide pointers to the data and trigger the execution of tasks in the receiving functions. The actual message buffer is setup in shared memory that both the message sender and the message receiver can access. In this case, the process_scatter() pends on a new input frame. When data becomes available, the process_scatter() allocates memory for the message from heap, and assigns the message pointer to the input data. Using the MessageQ_put blocking call, the process_scatter() passes the input data pointers to the process_gather(). The process_gather() use the corresponding oct_wait calls to pend on the signal processing in each core. Once a new frame is received, these tasks call the UNIVERSAL_process API provided by Codec Engine, to invoke the oct c1 through oct cn processing algorithms on Core 1 through Core n respectively. Once the data is processed, the octCluster() use the MessageQ_put API to pass the output data pointers to the Send_data_to_host(). The Send_data_to_host() ensures that data atomicity is maintained, so that input data that corresponds to a particular frame always stays together.

Note that the control tasks that involve data scattering and gathering, viz. process_scatter(), process_gather() and Send_data_2_host() are all running on Core 0, the Master core, and only the specific algorithm tasks are running on Core 1 through Core n. It is important to note here that the IPC between cores is handled under the hood via CE and by using MessageQ, the developer is agnostic to this fact and can simply call the MessageQ APIs for passing data pointers between cores.


FunctionalTasks OCTDemo.PNG

Back End Interface

Once the output data is ready for display, it is time to pass the data to the PC that handles the backend processing and display. The Mid End application's Back End Interface block provides functions to communicate with the PC back end. For this example implementation, we use the ethernet ports on both device EVMs to interface the two together. To implement the communication protocol in software, we use RDSP, an application written on top of the MCSDK's Network Development Kit (NDK), that allows easy passing of data and parameters between the C6678 and the PC.

CE Implementation Details

To better understand this, we delve into a brief discussion on CE. The CE framework is essentially a set of APIs used to instantiate and run XDAIS-compliant algorithms. XDAIS is an algorithm standard that DSP programmers should follow to ensure that their algorithms easily plug-and-play with other algorithms and can be called using CE APIs. In multicore environments, CErequires two essential components to operate in tandem: a CE Client and a CE Algorithm Server. In this demo, the master core, Core 0, serves as the CE Client and uses CE APIs to make "remote procedure calls" to CE Algorithm Servers running on Core 1 through Core 5. Essentially, the CE Algorithm Server combines the core codec (Each core runs the same code on a different set of contiguous lines of the input data) along with the other infrastructure pieces (SYS/BIOS, IPC, etc) to produce an executable (.x64P) that is callable by Core 0, the CE Client. The application on Core 0 invokes the remote algorithms on Core 1 through Core 7 using the iUniversal interface, which is a set of APIs used to provide an easy way for XDAIS-compliant, non-VISA (Video, Image, Speech, Audio) algorithms to run using CE

CEprovides some unique features that significantly eases the multicore DSP software development process. One of the primary advantages is that CE eliminates the need for the developer to manually code any Inter-Processor Communication (IPC) details. Once the developer configures memory for IPC, CE takes care of the rest of IPC under the hood. This is illustrated later in this section with code snippets. CE also captures some key TI hardware features, where resource management for memory and EDMA are done via CE. CE also enables code reuse and faster time to market since applications can be easily ported from one architecture to another. For more information on CE lease click on the relevant links in the References section.

Back End

This section describes in brief the software design on the PC for backend processing and display. The PC reads the parameter files, transmits and receives TCP-IP sockets via RDSP using a static IP. Before the data processing begins, the DSP uses the tftp server running on the PC to download the data files that are necessary. The PC gets the processed data from the DSP and displays it on the monitor. It is important to note that the sustained frame rate is PC dependent. Since windows is not a real time OS, there could be an issue in transferring the data in real-time at the desired frame rate. The frame rate can be modified in the parameter file.


Parameter Files

1. The acquisition interval in the parameter file represented by "acqInterval_us" in the parameter files provided in microseconds.

2. "beginProcNum" represents the core where the processing begins (first chuck of a frame)

3. "endProcNum"  represents the core where the processing ends (last chunk of a frame).

The processing is distributed equally among all cores numbered between beginProcNum and endProcNum inclusive. There are also additional parameters set in the parameter files that are specific to the algorithms implemented. Interested readers are requested to review documentations for Embedded Processor Software Toolkit for Medical Imaging for details on these parameters.

Get OCT v1.0

Both the prebuilt executables and the source code are available for MIDAS OCT v1.0.

If you would like to download the source code to study and play with and setup your development environment to build the demo from scratch, the source code package with build instructions are available, which is described in the section "Build from Source".

If you would like to just run the demo as-is for starters, you could use the prebuilt executables. The instructions for this are outlined in section "Using Prebuilt Executables" below.

Requirements

Common

1. C6678 EVM w/ power adapter: (http://www.ti.com/tool/tmdxevm6678)
2. Gigabit Network Switch
3. 1 x Ethernet Cables
4. USB cable for on-board emulator OR XDS560 Emulator w/ power adapter and cable
5. Windows PC w/ CCSv5 installed


Build from Source

Follow guidelines in this section if you would like to download the source code and setup a development environment to build the demo from source.

Multicore DSP C6678 (Mid End)

All development for the C6678 is done on the Windows PC.


1. TI Code Composer Studio IDE (CCS)
This version of the demo has been built and verified with CCS version 5.0.3. Later versions of CCS should work, but previous versions of CCS do not have C66x support and will therefore not be compatible with this demo release. You can follow the link to download CCS v5.0.3 from here and install under C:\ti\ccsv5.
If you install in this default location, your directory structure should be as below. Note the snapshot is of directory 'C:\ti\ccsv5\ccsv5'.

CCSInstall OCTDemo.PNG


2. PERL 7-Zip and Open CV
Perl, 7-Zip and Open CV are required to run the automated build script that will be discussed later.
a. Install Active Perl from http://www.perl.org/get.html. Installs at C:\Perl by default.
b. Once installation is complete, please ensure that C:\Perl\site\bin and C:\Perl\bin are in your Path. To check this, right click on My Computer --> Properties --> Advanced tab --> Environment Variables. The system variable Path should include these paths.
c. Install 7-Zip from http://www.7-zip.org/. Installs at C:\Program Files\7-Zip by default. Note that if you plan to install 7-zip in a different location, please update the 'build6678_oct.pl' perl script introduced later.
d. Install Open CV from http://sourceforge.net/projects/opencvlibrary/files/opencv-win/2.2/OpenCV-2.2.0-win32-vs2010.exe/download. Installs at C:/OpenCV2.2


3. Environment Variables
The following environment variables assume that the install packages will/have been installed in the recommended locations
a. Windows XP: Right-click on My Computer --> Properties --> Advanced tab --> Environment Variables --> New
b. Define new user variable, where variable name is TI_INSTALL_DIR and variable value is C:\ti
c. Define another new user variable, where variable name is DSPLIB_INSTALL_DIR_C66 and variable value is C:\ti\dsplib_c66x_3_0_0_8
d. Define new user variable, where variable name is CCS5_INSTALL_DIR and variable value is C:\ti\ccsv5. CCS5_INSTALL_DIR represents the location where CCS5 is installed. To verify what CCS5_INSTALL_DIR is, double check to see that CCS5_INSTALL_DIR\ccsv5\eclipse exists. e. Define another new user variable, where variable name is XDC_INSTALL_DIR and variable value is C:\ti\xdctools_3_22_00_09\packages
f. Add the following variables, if they don't exist, to 'Path' under Environment Variables --> System Variables:
C:\ti\ccsv5\ccsv5\utils\gmake
C:\Program Files\7-Zip
C:\Perl\site\bin
C:\Perl\bin
C:\OpenCV2.2\bin


4. TI Software Components Setup
Please note that the demo has been built and verified with the version numbers listed below. Please ensure that you download the correct versions.
It is assumed in the following steps that C:\ti is TI_INSTALL_DIR


a. MCSDK 2.0.0.11
http://software-dl.ti.com/sdoemb/sdoemb_public_sw/bios_mcsdk/02_00_00_11/index_FDS.html.
When asked to choose components, leave default setting i.e. all components checked. You will also need to indicate you CCS installation location.


b. Code Generation Tools v7.2.1
Download from https://www-a.ti.com/downloads/sds_support/TICodegenerationTools/download.htm.
Install at C:\ti.

c. XDC Tools 3.22.00.09
http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/rtsc/3_22_00_09/index_FDS.html.
Install at C:\ti


d. Codec Engine 3.21.00.19
http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/ce/3_21_00_19/index_FDS.html.
Extract at C:\ti


e. Sys-BIOS 6.31.05.31
http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/sysbios/6_31_05_31/index_FDS.html.
Install at C:\ti


f. Framework Components 3.21.01.26
http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/fc/3_21_01_26/index_FDS.html.
Extract at C:\ti


g. IPC 1.22.05.27
This should install as part of MCSDK. However, in case it doesn't exist for some reason, you can download it from the link below:
http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/ipc/1_22_05_27/index_FDS.html.
Install at C:\ti


5. tftpd32 server
tfpdd32 server Version 3.50(Standard Edition) available at http://tftpd32.jounin.net/


6. MS Visual Studio
MS Visual Studio Version 2008 available at http://www.microsoft.com/download/en/details.aspx?id=3713


7. Download the source code package. Click here to download the package from the MIDAS GForge project hosting portal


8. Unzip midas_oct_demo1_release.zip in TI_INSTALL_DIR. If using recommended paths, this would be unzipped at C:\ti\midas_oct_demo1_release

At the end of these steps, your TI_INSTALL_DIR (C:\ti if using recommended paths) should look similar to the snapshot below:


9. Start CCSv5.
Choose C:\ti\midas_oct_demo1_release\ccsv5_workspace as your workspace
Go to Window->Preferences->CCS->RTSC->Products. Add C:/ti (or equivalent TI_INSTALL_DIR) under "Tool Discovery Path".
This should populate "Discovered Tools." with the installed components.

CCS.JPG

Also verify that the code generation tool v7.2.1 is recognized by CCS. To do this, go to Window -> Preferences -> CCS -> Code Generation Tools.
If you don't see it listed, click on the 'Add' button and point to the path where you have installed the tools.

Codegentools.JPG

Close CCSv5.


10. We will now build the OCT RTSC package. Open a command window (Start -> Run -> 'cmd') and type the following commands (w/o quotation marks)
'cd C:\ti\midas_oct_demo1_release'
'makescript.bat'

11. In this step we will run the autobuild script to build the executables for all cores. This script imports the CCS projects corresponding to the cores, and builds the executable corresponding to the 'Release' profile.

Type the following command on the prompt:
'perl build6678_oct.pl'


12. Start CCSv5. Choose the same workspace as before, i.e. C:\ti\midas_usound_demo4_rel\ccsv5_workspace.
At this point you should see all three projects under 'C/C++ Projects' window in CCSv5 and all three executables should be available as:
Core 0: 'C:\ti\midas_oct_demo1_release\miDAS\oct\demo1\midend\midendapp\ccsProj_C6678\Release\midendappOct.out'
Core 1: 'C:\ti\midas_oct_demo1_release\miDAS\oct\demo1\midend\servers\server1\ccsProj_C6678\Release\server1.out'
Core 2: 'C:\ti\midas_oct_demo1_release\miDAS\oct\demo1\midend\servers\server2\ccsProj_C6678\Release\server2.out'
Core 3: 'C:\ti\midas_oct_demo1_release\miDAS\oct\demo1\midend\servers\server3\ccsProj_C6678\Release\server3.out'
Core 4: 'C:\ti\midas_oct_demo1_release\miDAS\oct\demo1\midend\servers\server4\ccsProj_C6678\Release\server4.out'
Core 5: 'C:\ti\midas_oct_demo1_release\miDAS\oct\demo1\midend\servers\server5\ccsProj_C6678\Release\server5.out'
Core 6: 'C:\ti\midas_oct_demo1_release\miDAS\oct\demo1\midend\servers\server6\ccsProj_C6678\Release\server6.out'
Core 7: 'C:\ti\midas_oct_demo1_release\miDAS\oct\demo1\midend\servers\server7\ccsProj_C6678\Release\server7.out'


Back End

In MS Visual Studio, from location 'C:\ti\midas_oct_demo1_release\miDAS\oct\demo1\backend\windows\octDemo\ build octDemo.sln

.

Using prebuilt executables

1. Follow the instructions in step 12 above

2. Follow the instructions in the backend section above

Setup and Run the Demo

6678 Setup

1. Connect ethernet wire from 6678 EVM to PC
2. Connect power adapter to the 6678 EVM
3. Connect emulator to 6678 EVM.
4. Download the 'CCSTargetConfigurations6678' from MIDASOCT1.0 release package here.
5. Copy the .ccxml files in the 'CCSTargetConfigurations' subfolder to location 'C:\Documents and Settings\<<username>>\user\CCSTargetConfigurations.'
The 'CCSTargetConfigurations' folder contains the .ccxml target configuration files for three different emulator options, that allow you to connect to the 6678 EVM and load the cores with the corresponding executables.
6. Start CCSv5, select a workspace directory as desired. Click on View -> Target Configurations. You should see the target configurations as shown in the snapshot:

CCS START.JPG
7. Depending on which emulator you have, you would use the corresponding target configuration. If you don't have any of the XDS560 external emulators you would use 'xds100_onboard_6678.ccxml.' Right click on the desired target configuration and click on 'Launch Selected Configuration.'
8. Select all 8 cores (C66x_0, C66x_1, C66x_2, C66x_3, C66x_4, C66x_5, C66x_6, C66x_7), right click and click on 'Connect Target':

CCS DEBUG.JPG
9. Load midendappOct.out in core0 and the server#.out in core#.  Currently only loading through CCS is supported. All 8 cores need to be loaded. When using the pre-built executables, you can use the .out files from the 'PrebuiltExecutables' subfolder you copied earlier

CCS CONNECT.JPG
10. Run the midend application through CCS (all cores must be running). Start the PC application (You may have to wait a few seconds bit to get the ethernet up and running).
11. On the PC side, a tftp server must be running to allow files to be downloaded to the DSP. When launching the tftpd32 server make sure your firewall is disabled temporarily. Set the current directory on the tftp server to point to the data directory, e.g., $(MIDAS_ROOT)\miDAS\oct\demo1\backend\windows\octDemo\data, where MIDAS_ROOT represent the directory where the whole medical imaging software kit from TI has been installed.
12. The PC TCP/IP address is to be set statically to 192.168.1.99. Ensure the PC has Gig Ethernet capabilities. Disable all other network connectivity (e.g., wireless).
13. From command prompt cd into location 'C:\ti\midas_oct_demo1_release\miDAS\oct\demo1\backend\windows\octDemo1\Release\ and run the octDemo.exe from a console and follow the instructions on the console.


Useful References

  • The data used for this demo has been provided by Dr. Boppart's team at the University of Illinois at Urbana Champagne http://biophotonics.illinois.edu/boppart/index.html
  • For more on DSP application development, application notes, white papers and information on TI's latest offerings, including the C66x keystone devices, the following are some useful references:

Multicore DSPs


Medical Imaging


Support and Questions

As noted in the disclaimer, software is licensed under BSD and is provided "as is". Please post questions to http://e2e.ti.com.


Disclaimer

System and equipment manufacturers and designers are responsible to ensure that their systems (and any TI devices incorporated in their systems) meet all applicable safety, regulatory and system-level performance requirements. All application-related information on this website (including application descriptions, suggested TI devices and other materials) is provided for reference only. This information is subject to customer confirmation, and TI disclaims all liability for system designs and for any applications assistance provided by TI. Use of TI devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless TI from any and all damages, claims, suits or expense resulting from such use.

All software is licensed under BSD with the following terms and conditions:

Copyright (C) 2011 Texas Instruments Incorporated - http://www.ti.com/
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Texas Instruments Incorporated nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.