Converting from INTC to BIOS

Introduction

The purpose of this article is to be an example on how to migrate from a project that uses INTC interrupt module to BIOS.

INTC is an interrupt controller module that comes with the processor’s CSL (Chip Support Library). It is described in item 1.7 and chapter 10 of the document C6455_CSL_APIREFERENCE supplied with the C6455 CSL software (see next section how to download this document).

DSP/BIOS is a scalable real-time kernel that can be used in more complex multi-thread real-time systems. It is described in the document TMS320 DSP/BIOS User’s Guide.

When you download CSL, a lot of the example projects use the INTC module that comes with it. Sometimes, developers use examples as a starting point for more complex projects. Depending on the complexity of the project, developers might want to take advantage of a more complex real-time scheduler than the INTC module. At this point, migration from INTC to DSP/BIOS is requested.

This article describes how the migration from INTC from DSP/BIOS can be done for two CSL examples: one for the C6455 processor and the other for the C6727 processor.

CAUTION - do not use the CSL INTC module in the same program as DSP/BIOS - this will fail - see this Kbase article for details.

Process for C6455 Project

Downloading CSL

The CSL for the C6455 processor can be downloaded at at the page:

Chip Support Library for 6455

After you download it, you can find documentation at the folder:

...\6455_default_package\default_package

And examples at the folder:

...\6455_default_package\default_package\csl_c6455\example

EDMA project

The project chosen can be found at:

...\6455_default_package\default_package\csl_c6455\example\edma\edma_interrupt

In this project, an EDMA transfer is manually triggered. The transfer is configured to generate an interrupt when it is completed. The interrupt just clears the TCC bit. After the end of the interrupt, the transfer is checked and the program ends.

More information about EDMA can be found at the document: TMS320C645x DSP Enhanced DMA (EDMA3) Controller User’s Guide.

Migration Steps

Checking the original project

First thing to do is to get familiar with the original example provided. Check the source files, read the code and understand it.

Also make sure that the original project is compiling. Depending on the folder the example was put when downloaded, the project might not find some files because the path to them might have changed.

After compiling with success, test the original program putting breakpoints, make sure that it is interrupting, and take a look at the value of variables.

When sure that the project is 100% working and you are ready to modify it, MAKE A COPY!

The project was copied from the folder:

...\6455_default_package\default_package\csl_c6455\example\edma\edma_interrupt

To the folder:

...\6455_default_package\default_package\csl_c6455\example\edma\myedma_interrupt

This way the original project is not lost, and can be used for comparison.

Adding a DSP/BIOS Configuration File

To open DSP/BIOS Configuration File, go to File -> New -> DSP/BIOS Configuration.... Choose the platform ti.plataforms.dsk6455. The configuration file created was named <myedma_interrupt.tcf>, saved at ...\6455_default_package\default_package\csl_c6455\example\edma\myedma_interrupt\build, and added to the project.

The original project contains the file <c6455.cmd>. It is necessary to migrate the memory configurations from this file to the DSP/BIOS Configuration File. This includes the memory sections, heap, stack, etc...; After that, <c6455.cmd> can be removed from the new project. Now, DSP/BIOS Configuration file (.tcf) will generate a cmd (<myedma_interruptcfg.cmd>) file that needs to be added to the project.

Also, to maintain coherence with the original project, it is necessary to create and add to the project a small cmd file with the custom memory sections that cannot be configured at the DSP/BIOS Configuration file (in this case csl_vect and testMem).

Other than the memory sections, the file <c6455.cmd> contains configurations for heap and stack:

-heap  0x1000
-stack 0x3000

The stack size (0x3000) can be configured at the properties of MEM - Memory Section Manager, General tab, field Stack Size (MAUs). The heap can be configured at the same tab, by unchecking the option No Dynamic Memory Heaps. After that, it is necessary to go to the properties of the IRAM (internal RAM) memory and check the option create a heap in this memory, put the size 0x1000. The last step for configuring the heap is to go back to properties of MEM - Memory Section Manager, General tab, and select IRAM at the drop-down list at the fields Segment For DSP/BIOS Objects and Segment For malloc() / free().

In this case, it is necessary to exclude <rts64plus.lib> from Project -> Build Options, at the Linker tab, Category Libraries. This library is included by the tcf file, so including the library twice will spawn linker errors.

Removing INTC library

Remove the INTC library, going to Project -> Build Options, at the Linker tab, Category Libraries, remove <csl_c64xplus_intc.lib>.

At the source files, comment out all the references to the INTC:

- include files that are used for INTC functions;

- global and local variables that are used just for INTC;

- all the function calls that are part of INTC library;

At the end, compile the project and make sure there are no errors. If you removed INTC library, and commented everything related to it, it should compile.

Configuring interrupt using DSP/BIOS

As showed in the datasheet table 7-10, page 120, the event number corresponding the region 1 used in this project is 72 (EDMA3CC_INT1). Therefore, in the tcf file (Scheduling, HWI), it is necessary to configure a hardware interrupt. INT4 was chosen, to be called by the interrupt event 72 and to call the ISR function with the proper argument (interrupt selection number = 72, function = _eventEdmaHandler). Also, make sure that in the Dispatcher tab, Use Dispatcher is checked (Arg: _hmodule).

In the function eventEdmaHandler() called by the interrupt, it is necessary to change the argument type from void *handle to CSL_Edma3Handle *hmodule. The reason for that is because when the argument was passed to INTC module, it was possible to put a cast changing hmodule type to void *. Now using BIOS, the argument passed cannot have a cast changing its type.

In addition, it is necessary to enable the interrupt calling the function C64_enableIER (C64_EINT4). To use this function, it is necessary to include the files:

#include "myedma_interruptcfg.h"
#include <C64.h>

Adapting the code

The INTC original project works entirely during main(): it configures EDMA and INTC, waits for the ISR to run ( while (intFlag) ), and at the end it checks the transfer. It is necessary to change the code because BIOS just starts working after main() ends. So main() will now just have the configuration of EDMA and INTC. A TSK was set up just to wait for the ISR to run and check the transfer.

It is necessary to be careful in this transition, since some variables that are local in main() need to become global. Again, because now the program will leave main() and start running, the local variables will be corrupted when main() returns. If they are used by the ISR function or at the TSK that checks the result, the program will have runtime errors. In this context, it is necessary to make two variables global:

CSL_Edma3Obj edmaObj;

CSL_Edma3ChannelHandle hChannel;

After that, the program should work: configuration correct, transfer made, interrupt run, transfer checked with no errors.

Results

With both the INTC and BIOS projects running, their code size was compared (L2 memory in map file):

- With INTC: 0xdfc0 (57280)

- With BIOS: 0x13e1a (81434)

The project with BIOS is around 42% bigger, but it has much more flexibility to build on. Also, these projects are very simple, for more complex projects BIOS size is relatively smaller (in terms of percentage of the total code).

Map files are generated by the linker (Project -> Build Options, Linker tab, Map Filename) and located at:

...\6455_default_package\default_package\csl_c6455\example\edma\edma_interrupt\obj

...\6455_default_package\default_package\csl_c6455\example\edma\myedma_interrupt\obj

Process for C6727 Project

Downloading Project

Comes with PADK.

SimpleAudioEffect project

The project chosen can be found at:

...\PADK\dsp\demos\mySimpleAudioEffect

In this project, audio samples from 4 input channels, coming through McASP, are processed to produce an audio effect, and put back out through McASP. This real-time data transfer uses dMAX - the equivalent to EDMA for C6727. The transfer from McASP to internal memory is configured to generate an interrupt when it is completed. In this interrupt the samples are processed.

More information about dMAX can be found at the document: TMS320C672x DSP Dual Data Movement Accelerator (dMAX) Reference Guide.

Migration Steps

Checking the original project

Again, first thing to do is to get familiar with the original example provided. Check the source files, read the code and understand it.

Also make sure that the original project is compiling. Depending on the folder the example was put when downloaded, the project might not find some files because the path to them might have changed.

After compiling with success, test the original program putting breakpoints, make sure that it is interrupting, and take a look at the value of variables.

When sure that the project is 100% working and you are ready to modify it, MAKE A COPY!

The project was copied from the folder:

...\PADK\dsp\demos\SimpleAudioEffect

To the folder:

...\PADK\dsp\demos\mySimpleAudioEffect

This way you do not loose anything, and can always compare with the original.

Adding a DSP/BIOS Configuration File

To open DSP/BIOS Configuration File, go to File -> New -> DSP/BIOS Configuration... Choose the platform ti.plataforms.dsk6727. The configuration file created was named <SimpleAudioEffect.tcf>, saved at ...\PADK\dsp\demos\mySimpleAudioEffect, and added to the project.

The original project has the file <padk.cmd>. It is necessary to migrate the memory configurations from this file to the DSP/BIOS Configuration File. This includes the memory sections, heap, stack, etc...; After that, <padk.cmd> can be removed from the new project. Now, DSP/BIOS Configuration file (.tcf) will generate a cmd (<SimpleAudioEffectcfg.cmd>) file that needs to be added to the project.

The memory sections are configured at the .tcf file (DSP/BIOS Configuration) as described in the original <padk.cmd> file. The only section not included is the VEC section:

VEC  : origin = 0x10000000 length = 0x00000A00

This section was being used by the INTC CSL, so it is not necessary anymore as can be seen in the code below at the beginning of main():

/ * --------------------------------------------------------------- * /
/ * Set the base address of the Interrupt Vector Table            * /
/ * ---------------------------------------------------------------* /
   CSL_intcSetVectorPtr( 0x10000000 );

At Project -> Build Options (Linker tab, Basic), there are values for stack and heap (both 0x800). These values should be both removed from the build options and configured at the tcf file. The stack size (0x800) can be configured at the properties of MEM - Memory Section Manager, General tab, field Stack Size (MAUs). The heap can be configured at the same tab, by unchecking the option No Dynamic Memory Heaps. After that, it is necessary to go to the properties of the IRAM (internal RAM) memory and check the option create a heap in this memory, put the size 0x800. The last step for configuring the heap is to go back to properties of MEM - Memory Section Manager, General tab, and select IRAM at the drop-down list at the fields Segment For DSP/BIOS Objects and Segment For malloc() / free().

Removing INTC library

Remove the INTC library by right-clicking on the file <csl_intc.lib> (inside Libraries folder) and selecting Remove from Project.

At the source files, comment out all the references to the INTC:

- include files that are used for INTC functions;

- global and local variables that are used just for INTC;

- all the function calls that are part of INTC library;

At the end, compile the project and make sure there are no errors. If you removed INTC library, and commented everything related to it, it should compile.

Configuring interrupt using DSP/BIOS

As showed in the document TMS320C672x DSP Dual Data Movement Accelerator (dMAX) Reference Guide on page 46: if the TCINT bit in the event entry is set, at the end of transfer, dMAX will trigger a CPU interrupt (INT8), and if the interrupt is enabled, its interrupt service routine is executed. Therefore, in the tcf file (Scheduling, HWI), hardware interrupt INT8 was configured to call the function _dmax_isr(). Also, make sure that in the Dispatcher tab, Use Dispatcher is checked (no Arg for this particular case).

In addition, it is necessary to enable the interrupt by calling the function C62_enableIER(C62_EINT8) - according to document TMS320C6000 DSP/BIOS 5.32 Application Programming Interface (API) Reference Guide page 72. To use this function, it is necessary to include the files:

#include " SimpleAudioEffectcfg.h "
#include <C62.h>

Adapting the code

The first adaptation needed for this project is to remove the while(1) at the end of main.

The second is to remove the interrupt keyword in the function called by the HWI. When you use the interrupt keyword with the definition of the function, the compiler generates register saves based on the rules for interrupt functions and the special return sequence for interrupts. This information is in the document TMS320C6000 Optimizing Compiler User’s Guide page 128. Now that BIOS dispatcher is taking care of the interrupt, this word has to be removed in order to avoid conflicts.

After that, the program should work: configuration correct, transfer made, interrupt run.

Results

With both the INTC and BIOS projects running, their code size was compared (L2 memory in map file):

- with INTC: 14639

- with BIOS: 19a83

The project with BIOS is around 26% bigger, but it has much more flexibility to build on.

Map files are generated by the linker (Project -> Build Options, Linker tab, Map Filename) and were at:

...\PADK\dsp\demos\mySimpleAudioEffect\Debug

...\PADK\dsp\demos\SimpleAudioEffect\Debug

Files

EDMA Project

Myedma_interrupt.zip

PADK Project

Not available.