SYSBIOS HWI example for C2000

From Texas Instruments Wiki
Jump to: navigation, search

SYSBIOS HWI example for C2000

This article will provide a step-by-step procedure for enabling and implementing a SYSBIOS HWI and targeting this implementation for the C2000 family of microcontrollers. In addition, the article will highlight the Code Composer Studio v4 (CCSv4) Integrated Development Environment which is based on Eclipse.

SYSBIOS Documentation

Prerequisite Software

The following host software development tools and target contect components were used with this example.

  • Code Composer Studio v4.2.1.00004
  • C2000 Code Generation Tools v5.2.9
  • SYSBIOS v6.31.00.18
  • XDCTools v3.20.06.81
  • C2833x/C2823x C/C++ Header and Peripheral Examples

Example Project ZIP Archive

The entire example has been captured in the ZIP archive for reference. In addition, one of the steps of the example is to author a source file, which can be extracted from the ZIP archive. This example also requires to use of the C2833x/C2823x C/C++ Header and Peripheral Examples for the TMS320F28335 as there are a few files referenced.

File:SYSBIOS Hwi example for

Getting Started

As mentioned, this article will feature the Code Composer Studio v4 Integrated Development Environment (CCS) which is based on the Eclipse IDE technology. In this example, we will start from an empty workspace to create a new project. There is no significance to starting with an empty workspace other than to illustrate there is no pre-existing example which was used.

There are other resources which also describe getting started with CCSv4 and C2000 which can be found here. This example will use many of the same procedures.

Select a workspace

When you first open CCSv4, a dialog box may appear and prompt you to select a workspace. This is a folder where all of your CCSv4 custom settings will be saved for your specific personal computer. This includes all of your project settings, macros, and views when you shut down CCSv4. For instance, if you have several projects + memory windows + graph window + watch variables that you were working with when you closed CCSv4, these same projects and settings will be available when you re-open CCSV4.

SYSBIOS HWI Example C2000 1 select workspace.png

Workspaces save automatically when you close CCSv4. If you don't want to overwrite the settings you have for a current workspace, you can open/ switch to a new workspace by going to: "File-> Switch Workspace".

Note that workspaces are not portable in CCSv4 because they contain data specific to your computer system. So you cannot save a workspace, zip it up, and send it to another user.

In addition to selecting the appropriate workspace, we also want to make sure that the CCS environment pulls in any software components which were separately downloaded and installed on the host PC from when CCS was installed. This would include any updated Code Generation Tools, SYSBIOS, etc that were not installed in the default location, but rather in an user-specified location. In order to "tell" CCS where to find these components, select the Menu "Window->Preferences..." option.

Expand the CCS->RTSC->Products category. You will see the default location for CCS to find the various software components. If perhaps, the user installed updated software components into a different directory than what is listed in the "Tool discovery path:" window pane, select the "Add..." button to add the path to the additional software components. In this example, new versions of SYSBIOS was installed in the C:\ti\sysbios directory on the host PC.

Once this path has been added, the list of Discovered tools will be updated to include these additional software components.

SYSBIOS HWI Example C2000 2 select workspace.png

Click "Apply" and then click "OK".

This same procedure would be used if newer versions of the Code Generation Tools were installed and to be used. In that case, expand the CCS->Code Generations Tools category.

Create a New Project

At this point, we need to create a new project. Select Menu "File->New->CCS Project" to launch a wizard.

Choose a name for the project such as hwi_example.

SYSBIOS HWI Example C2000 1 new project.png

Click "Next >".

Select C2000 for the Project Type field.

SYSBIOS HWI Example C2000 2 new project.png

Click "Next >".

SYSBIOS HWI Example C2000 3 new project.png

Click "Next >" in the Additional Project Settings dialog box.

In the Project Settings dialog box, we want to specify the particular Device Varient by using the provided filter and then selecting the specific device. In this example, the TMS320F28335 was targeted.

SYSBIOS HWI Example C2000 4 new project.png

Click "Next >".

In the Project Templates, we have an opportunity to start with a completely empty project, or use one of the pre-existing SYSBIOS exampe. In this example, we choose the SYSBIOS->28x Examples->Idle Example to base the exercise on. This example has a minimum amount of SYSBIOS services included.

SYSBIOS HWI Example C2000 5 new project.png

Click "Next >".

An RTSC Platform will need to be selected. This platform information will provide memory map information to the Code Generation Tools among other platform configuration data.

SYSBIOS HWI Example C2000 6 new project.png

Click "Finish".

The newly created project called hwi_example will be active and highlighted in the CCS C/C++ perspective's C/C++ Projects window pane.

SYSBIOS HWI Example C2000 7 new project.png

Build the project (Project -> Build Project).

A target configuration must be specified to CCS to describe the hardware. If this has not already been performed, select Target -> New Target Configuration... and add the .ccxml file to the project.

Then download to the target hardware to run (Target -> Debug Active Project). Enable viewing the ROV (Runtime Object Viewer) by choosing Tools -> ROV. Open the Raw Logs view by choosing Tools -> RTA -> Raw Logs.

SYSBIOS HWI Example C2000 8 new project.png

Add a HWI object

In this section, we will add a HWI object to the project and connect an Interrupt Service Routine to the event. The example will use one of the ePWM peripherals to generate the interrupt to the CPU. The resultant Interrupt Service Routine (ISR) will then increment a variable.

Since the C2000 uses a Peripheral Interrupt Expansion (PIE) module to aggregate many interrupt sources into finite set of interrupts supported by the C2xxx CPU core, this example will need to use the C28x family specific HWI module from SYSBIOS.

Open the SYSBIOS configuration file which was created in the first phase of this example when establishing a New Project. The filename in this case was idle.cfg. When performing this action, 3 windows should update which is part of the XGCONF (graphical configuration utility integrated in CCSv4), the Available Package pane, the properties look at the idle.cfg file in the main editing window and the Outline. The Outline is what indicates which SYSBIOS modules and services are used in the project.

SYSBIOS HWI Example C2000 1 add hwi.png SYSBIOS HWI Example C2000 2 add hwi.png SYSBIOS HWI Example C2000 3 add hwi.png

To add a HWI object, first add the C28x family specific HWI module to the project. Go to the Available Package pane, expand the SYS/BIOS->Target Specific Support->C28 folders to show the HWI module. Right-click this module and select "Use Hwi", or drag and drop this module into the Outline pane.

SYSBIOS HWI Example C2000 4 add hwi.png SYSBIOS HWI Example C2000 5 add hwi.png

Add Software Support for Example

Now we included the C28 family specific HWI module to the project configuration. We need to actually write some code to implement an interrupt service routine before we instantiate an actual HWI instance.

This will require to take a side step at the moment of this example, since the furnished example project does not have this code available. As mentioned earlier in the article, we will target the ePWM peripheral as the source of our hardware interrupts through the PIE to the CPU. The main reason for this is that the example can be self-contained within the processor and not require any external stimulus. Once the ePWM performs a cycle it will generate an interrupt. When it generates an interrupt, our interrupt service routine will increment a count value. In fact, in this example, we will use a feature of the ePWM to actually generate 2 independent interrupts with a different rate.

For properly setting up the ePWM peripheral, we will leverage the C2833x/C2823x C/C++ Header and Peripheral Examples software which can be found by itself on, or included as a part of the C2000 controlSUITE software.

Download the aforementioned software. We will reference this software in the project and only copy over enough pieces into the example project as necessary. The C2833x/C2823x C/C++ Header and Peripheral Examples software includes a Quick Start document which provides steps on how to integrate into CCSv4 with and without BIOS support. For this example, we will clearly utilize the steps to integrate into a BIOS project. Section 5 of the Quick Start document describes the steps to integrate the peripheral software into our own project.

We will also author our own source file and header file for the purpose of this example. This will export API functions to be used by the application.

The files are provided in the zip archive associated with this article.

Create the new header file in the project with File -> New -> Header File. A dialog box will appear and ask for a name of the file. Use pwm.h and place it in the provided source folder hwi_example.

Add the following to the newly created pwm.h file.

void PWMInit(void);

That is all we need, therefore save and close the file.

Include the pwm.h file in the existing idle.c file. Add the following code in main() to perform the initialization of the ePWM. Save and close.

 * Print "Hello world" to a log buffer. 
Log_info0("Hello world\n");
PWMInit() ;
Log_info0("PWMs initialized\n");

We will now author the pwm.c source file. The pwm.c source file is too large to display on this page, but the source is included in the zip archive.

The key elements of the pwm.c source file is the definition of the PWMInit() routine referenced in idle.c. The interrupt service routines will be defined in pwm.c as will the variables which hold the count values. The pwm.c file will also include the references to the C/C++ Header and Peripheral software download.

Add the relevant C/C++ Header and Peripheral files to Project

Add the DSP2833x_GlobalVariableDefs.c from the C/C++ Headers and Peripheral software to the project. You can link to this source file rather than copy it over. We will not be editing this file.

Project -> Link Files to Active Project... Navigate to the location of the DSP2833x_GlobalVariableDefs.c which is <HEADER_FILE_INSTALL_DIR>\DSP2833x_headers\source.

Add the path to DSP2833x_Device.h to the CCSv4 C Compiler include path. Add the path to DSP2833x_EPwm_defines.h to the CCSv4 C Compiler include path.

Project -> Properties C/C++ Build category Tool Settings tab C2000 Compiler -> Include Options

Add the path to DSP2833x_Device.h in the #include search path list. (Found in DSP2833x_headers\include)
Add the path to DSP2833x_EPwm_defines.h in the #include search path list. (Found in DSP2833x_common\include)

SYSBIOS HWI Example C2000 6 add hwi.png

Add the DSP2833x_Headers_BIOS.cmd linker command file to the project. This file provide information to the linker regarding where the peripheral addresses are on the device which are used by the data structures repesenting the peripheral registers.

Project -> Link Files to Active Project... Navigate to the location of the DSP2833x_Headers_BIOS.cmd which is <HEADER_FILE_INSTALL_DIR>\DSP2833x_headers\cmd.

Instance HWI for each interrupt service routine

We can now create instances of HWIs for each interrupt service routine defined.

Right click on the in the Outline and select New Hwi.

This will spawn a dialog box to statically configure the HWI.

The intNum parameter is the Vector number for the particular interrupt of interest in the PIE. In the case of the ePWM1 is 48 and for ePWM2 is 49. This continues linerally through ePWM6 which is mapped to vector 53.

The hwiFxn parameter is the label for the interrupt service routine.

In this example, epwm1_timer_isr() is defined in pwm.c.

SYSBIOS HWI Example C2000 7 add hwi.png

Repeat this as desired.

The display results may show an incorrect label for the hwiFxn name. If you look at the source view, it is correct. This is an anomoly that has been reported.

Build and Test

We have demononstrated, through this article, the steps required to add support for SYSBIOS HWI (hardware interrupt) and register an interrupt service routine for the C2000 family.