Application Note 194
Using the Real-Time Agent

Revision 1.4 - June 2007

This Application Note explains how to configure and work with the Real-Time Agent that is available with the ULINK2 USB-JTAG Adapter and the RealView Microcontroller Development Kit.

Information in this file, the accompany manuals, and software is
Copyright © KEIL - An ARM Company.
All rights reserved.

 

Revision History

• Revision 1.1 - January 2007: Initial Revision
• Revision 1.2 - March 2007: Added polled mode information to Application Configuration section / Added Extended API information to Programmer Interface (API) section
• Revision 1.3 - May 2007: Added Upgrading the Real-Time Agent section / Updated Custom Interrupt Controllers section with default interrupt macros / Updated Real-Time Agent template and file paths for new locations
• Revision 1.4 - June 2007: Updated for Real-Time Agent v2.4 / Added Quick Start Guide

Contents

1.      Overview

2.      Quick Start Guide

3.      Application Configuration

4.      Programmer Interface (API)

5.      Example Programs

6.      Custom Interrupt Controllers

7.      Upgrading the Real-Time Agent

8.      Technical Support

9.      Contact Details

 

IMPORTANT NOTICE FOR RTX KERNEL AND RL-ARM USERS

Integration of the Real-Time Agent with the RTX Kernel and RL-ARM is preliminary in RealView MDK 3.10. As such, the RTX_Config.c templates in <KEIL installation directory>\ARM\Startup have not been updated with the required changes for the Real-Time Agent. If you wish to use the Real-Time Agent with RTX Kernel and RL-ARM, please use an RTX_Config.c file taken from the example projects in <KEIL installation directory>\ARM\RT Agent , or merge the changes from one of these files into your RTX_Config.c.

 

Overview

The Real-Time Agent extends the ULINK2 USB-JTAG Adapter with the following features:

• Read and write memory during program execution. The Memory Window and Watch Window display application data while the program is executing, and if View – Periodic Window Update is enabled, these windows refresh automatically.
• Terminal emulation via the ULINK2 for user I/O. Either STDIO (printf, scanf, etc) can be routed to the Real-Time Agent Terminal Window, or the debug I/O functions (RTA_printf, RTA_scanf) can be used.
• Task switch monitoring when used with the RTX kernel.

The Real-Time Agent is implemented in a compact C source file that is added to the user application. It complies to less than 1.5kB, and is optimized to be as resource light as possible.

 

Quick Start Guide

Project with RTX Kernel or RL-ARM Library

• If you created your project with an earlier version of RealView MDK than 3.10, replace your RTX_Config.c file with a new one from <KEIL installation directory>\ARM\Startup, merging in any changes you have made.
• Open your RTX_Config.c file, select the Configuration Wizard tab and tick the Real-Time Agent option.
• Recompile your project.

Project without RTX Kernel or RL-ARM Library

• Add a copy of RTA_Config.c from <KEIL installation directory>\ARM\RT Agent\Template\, to your project.
• Select the Configuration Wizard tab of this file and and tick the Real-Time Agent option, and select your hardware in the Hardware Type option.
• Recompile your project.

 

Application Configuration

The following steps describe how to add the Real-Time Agent to a user application. If you are using RTX or RL-ARM there is no need to copy or add files to your project, just skip straight to the Configure section.

Copy the configuration template file to your project

• Copy <KEIL installation directory>\ARM\RT Agent\Template\RTA_Config.c to your project directory.

Add the configuration file to your project

• Create a new Group for the files in your Project Workspace called 'Real-Time Agent'.
• Add the file RTA_Config.c to this Group.
• Right click the new Group and select 'Options for Group 'Real-Time Agent'. Under the C/C++ tab, select Optimization Level 3.

Configure

The Real-Time Agent contains a Configuration Wizard to make it easy to compile with different features and for different hardware platforms. The Configuration Wizard is accessed by opening the RTA_Config.c file (or RTX_Config.c in the case of RTX or RL-ARM) in µVision and clicking the Configuration Wizard tab. It provides the following options:

Option	Description
Real-Time Agent	Enables or disables the Real-Time Agent. If it is disabled, calls to it's functions are replaced by NOPs using the ARM RealView linker __weak link functionality.
Hardware Type (RTA_Config.c)	Select the type of hardware that you are using. This option is necessary for non RTX or RL-ARM projects. If your hardware is not available, you have two options: If the ARM Debug Communication Channel interrupts are connected to your target device's interrupt controller, you can implement your own hardware macros (Custom Interrupt Controllers) If the ARM Debug Communication Channel interrupts are not connected to your target device's interrupt controller, you can use the Real-Time Agent in polled mode.
Output Buffer Size (bytes)	Size of the buffer used for Real-Time Agent data travelling from target to host. Increase this for slower JTAG connections, or if data is being lost due to buffer overruns in the target.
Invalid Memory Pattern	Sets the memory pattern that is returned to µVision when accessing invalid memory locations.
Enable Real-Time Agent Terminal	Enables or disables the Real-Time Agent terminal emulation. Disabling saves code and memory space when terminal emulation is not required.
Echo Characters Automatically	If enabled, characters typed in the Real-Time Agent Terminal Window in µVision are automatically echoed back. This is needed when using standard library functions such as scanf().
Block on Write	If enabled, calling RTA_TermPutChar() will block if there is insufficient buffer space to send the character immediately, therefore terminal data will not be lost. If disabled, data will be discarded when calling RTA_TermPutChar() if there is insufficient buffer space, providing better real-time performance on the target. If terminal data is being lost when Block on write is disabled, increasing the Output Buffer Size may solve the problem.
Task Switch Monitoring (RTX_Config.c)	Enables or disables RTX Kernel task switch monitoring. NOTE: This option is only available for RTX or RL-ARM projects.
I/O Retargeting	Enables or disables I/O retargeting. If it is disabled, calls to printf(), scanf(), etc. are handled using the default semihosting method, rather than I/O retargeting.
STDIO Routing	Select the routing of the STDIN, STDOUT and STDERR streams (ie printf(), scanf(), etc).
External file operations defined	If implementing a file system, you may want to use I/O retargeting to access that file system. In this case, implement the functions __fopen, __fclose, __write, __flushbuf, __read, __setfpos, __get_flen, and enable this option. An example of this usage of I/O retargeting can be found in <KEIL installation directory>\ARM\RTL\FlashFS\Examples\File_ex1. Note: linking will fail if this option is enabled and the above functions are not defined.

NOTE: The 'COM Port 1' stream option in STDIO Routing expects the following functions to be defined in your code:

• int sendchar (int ch): Write a character to the serial port.
• int getkey (void): Get a character from the serial port (blocking).

An example implementation of these functions for the Keil MCB21XX development boards can be found in <KEIL installation directory>\ARM\RT Agent\MCB21xx\Measure\serial.c.

NOTE: I/O Retargeting requires a small amount of heap memory on the target (approximately 256 bytes), make sure enough heap is allocated in Startup.s for standard library use.

Modify your project files

Startup.s

• Comment out the default DAbt Handler.
• Add an EXTERN for the DAbt Handler.

An example of the changes is shown below:

;/*****************************************************************************/

;/* STARTUP.S: Startup file                                                   */

;/*****************************************************************************/

...

                EXTERN  DAbt_Handler

Undef_Handler   B       Undef_Handler

SWI_Handler     B       SWI_Handler

PAbt_Handler    B       PAbt_Handler

;DAbt_Handler    B       DAbt_Handler

IRQ_Handler     B       IRQ_Handler

FIQ_Handler     B       FIQ_Handler 

...

main()  Function

Add a call to RTA_Init() at the start of your main() function. This should be before any code other than essential device initialisation.

NOTE: This is not required if you are using RTX or RL-ARM.

Polled Mode

There are two situations where you may want to use the Real-Time Agent in polled mode:

• The target hardware does not support interrupt driven mode.
• Very fine control of real-time performance of the target is required.

To enable polled mode, select 'Polled Mode' for Hardware Type in the Configuration Wizard. In polled mode, you decide when to send and receive data via the Real-Time Agent. In some real-time critical applications, this can be useful because it provides more deterministic performance; you only give CPU time to the Real-Time Agent when you can.

For the Real-Time Agent to operate in polled mode, you must:

• Periodically call the RTA_tx_word_ext() and RTA_rx_word_ext() functions from a regular timer interrupt in your application code.
• Implement the void RTA_irq_enable_ext(void) and void RTA_irq_disable_ext(void) functions. These functions should disable and enable the timer interrupt set up in the step above.

To achieve the maximum data rate possible, call these functions once every 250μs. Calling the functions less often may result in data loss in the form of transmit buffer overruns in the target (μVision will notify you in the Real-Time Agent area of the status bar if data is being lost). Calling the functions more often will not cause harm, but will not increase the data rate either.

A pseudo-code example of the Polled Mode changes is shown below:

void __irq periodic_timer(void) {

   /* Perform periodic tasks   */

   /* User tasks */

   UserTask1();

   UserTask2();

   ...

   /* Transfer Real-Time Agent data */

   RTA_rx_word_ext();

   RTA_tx_word_ext();

}

void RTA_irq_enable_ext(void) {

   ENABLE_PERIODIC_TIMER_IRQ();

}

void RTA_irq_disable_ext(void) {

   DISABLE_PERIODIC_TIMER_IRQ();

}

ATMEL AT91SAM7Sx System Interrupt Configuration (ATMEL AT91SAM7Sx MCUs only)

In AT91SAM7Sx microcontrollers, the COMMRX and COMMTX interrupts (ARM DCC interrupts used by the Real-Time Agent) are OR'd with other system interrupts to produce a single input to the System Interrupt (interrupt source 1 on the Advanced Interrupt Controller (AIC)). This means the Real-Time Agent code cannot deal with these interrupts internally, and the user is required to implement calls to the Real-Time Agent interrupt handlers from within their System Interrupt handler.

Also, the System Interrupt must be configured as level triggered, because an edge triggered interrupt will cause interrupts to be missed. If edge triggered, an interrupt would be missed when one source triggers the System Interrupt, and between this time and when the interrupt is acknowledged, another source triggers - in this case the edge will be missed.

An example of the System Interrupt configured with the Real-Time Agent and Periodic Interval Timer (PIT) is shown below:

#include "RT_Agent.h" 

__irq void system_int (void) {              /* System Interrupt Handler */

  volatile AT91S_PITC * pPIT = AT91C_BASE_PITC;

  // Process COMMRX interrupt if any (Real-Time Agent) 

  if (*AT91C_DBGU_CSR & *AT91C_DBGU_IMR & AT91C_US_COMM_RX) {

    RTA_rx_word_ext();

  }

  // Process COMMTX interrupt if any (Real-Time Agent)

  if (*AT91C_DBGU_CSR & *AT91C_DBGU_IMR & AT91C_US_COMM_TX) {

    RTA_tx_word_ext();

  }

  // Process PIT interrupt if any

  if (pPIT->PITC_PISR & AT91C_PITC_PITS) {  /* Check PIT Interrupt */

    /* Perform timer related task interrupt task */

    pPIT->PITC_PIVR;                        /* Ack PIT Interrupt */

  }

  *AT91C_AIC_EOICR = 0;                     /* Signal end-of-interrupt to the AIC */

}

void init_system_int (void) {               /* Setup System Interrupt */

  AT91S_AIC * pAIC = AT91C_BASE_AIC;

  pAIC->AIC_SMR[AT91C_ID_SYS] = AT91C_AIC_SRCTYPE_INT_LEVEL_SENSITIVE | 7;

  pAIC->AIC_SVR[AT91C_ID_SYS] = (unsigned long) system_int;

  pAIC->AIC_IECR = (1 << AT91C_ID_SYS);

  *AT91C_PITC_PIMR = AT91C_PITC_PITIEN |    /* PIT Interrupt Enable */

                     AT91C_PITC_PITEN  |    /* PIT Enable */

                     PIV;                   /* Periodic Interval Value */

}

A working example for the Atmel AT91SAM7S-EK development board can be found in <KEIL installation directory>\ARM\RT Agent\AT91SAM7S-EK.

Compile and Test

• Compile, download and start execution.
• Set a watch on a variable that is known to be changing. A good example is the write index for the Real-Time Agent output buffer (<Project>-->RT_Agent-->rta-->out-->wr_idx in the Symbol Window).
• Enable Periodic Window Update from the View menu.
• If the variable in the Watch Window is changing, then the Real-Time Agent has been successfully integrated into your application!

Troubleshooting

If you encounter any problems integrating the Real-Time Agent, working examples for several boards can be found in <KEIL installation directory>\ARM\RT Agent. Most examples have versions that can be run in the KEIL simulator if you do not own the hardware.

Symptom	Solution
Real-Time Agent not responding (1).	Add RTA_Init() to the start of your main() function if not using RTX or RL-ARM.
Real-Time Agent not responding (2).	Not allocating enough heap memory on the target is a common problem. Make sure enough heap is allocated in Startup.s for standard library use (plus any extra for user heap requirements).
Real-Time Agent not responding (3).	The Real-Time Agent requires two interrupt vectors on the interrupt controller, check that the interrupts used do not conflict with interrupts used by your project (see <KEIL installation directory>\ARM\RV31\INC\RT_Agent.c - RTA Hardware Specific Section, for the interrupt vectors used on your hardware).
Real-Time Agent Terminal Window gets no data.	To use the Real-Time Agent Terminal Window and the RTA_printf() and RTA_scanf() macros, I/O retargeting must be enabled.
Initial printf() / RTA_printf() data is lost and not displayed inReal-Time Agent Terminal Window, or is displayed corrupted.	Initial terminal data from the target may be lost because µVision is not ready for it, either because it has stale data in it's buffer, or the debugger has not yet initialised fully. The first case is cause by code running in the target at the moment a new debug session is started and the board reset is issued.The second case can be due to a reset problem on some devices. In either case, the problem can be resolved by executing a blank printf() / RTA_printf(), then a sufficient delay, before executing the first real printf() / RTA_printf().
printf() / RTA_printf() data is lost.	Too much terminal data can overflow the Real-Time Agent output buffers. If (for example) a printf() is put in a tight loop of the main program code, it will generate too much data for the Real-Time Agent output buffers, and most data will be lost, resulting in unintelligible data in the Serial Window. In this case, enabling Block on Write in the Configuration Wizard will stop the data from being lost, but will affect real-time performance.
STDIO is redirected to the COM port, but appears in the Real-Time Agent Terminal Window.	This will happen when using the ARM RealView MicroLIB standard C library, because it does not support redirected file I/O. To solve this problem, use the normal standard libraries.
The Real-Time Agent reports 'Buffer Overrun in Target' or other data related errors in the μVision status bar.	This is caused because the data rate from target to host is too high, and is much more likely when using Task Switch Monitoring and a high target clock speed. It can be resolved in the following ways: If it occurs intermittently, increase the Output Buffer Size parameter for the buffer used for Real-Time Agent data travelling from target to host. This will account for bigger peaks in the data rate. Set the JTAG Clock Speed to Return Clock (RTCK) or the maximum available. This will increase the data rate between the target and μVision. Disable Task Switch Monitoring in the Configuration Wizard If the problem persists please report it.

 

Programmer Interface (API)

The Real-Time Agent API is defined and detailed in <KEIL installation directory>\ARM\RV31\INC\RT_Agent.h. It contains functions to initialise the Real-Time Agent, and to send user defined messages back to µVision (reserved for future use). The API is detailed below:

Real-Time Agent API

Function / Macro	Description	Notes
RTA_Init	Initialise Real-Time Agent.	Must be called before any other RTA function. Memory read and writes will not be available until this function has been called on the target.
RTA_Msg	Send a message to the host via Real-Time Agent.	Reserved for future use.
RTA_TermIsKey	Check is there is a character available in the RTA Terminal Window buffer.	This function is non-blocking.
RTA_TermGetChar	Get a character from the RTA Terminal Window buffer.	This function blocks until a character is available.
RTA_TermPutChar	Write a character to the RTA Terminal Window.	This function blocks until buffer space is available if and only if 'Block on Write' is enabled in the Configuation Wizard, otherwise it discards the character.
RTA_printf	Print a formatted string to the RTA Terminal Window.	Parameters are the same as those for printf(). I/O Retargeting must be implemented to use this macro.
RTA_scanf	Scan a formatted string from the RTA Terminal Window.	Parameters are the same as those for scanf(). I/O Retargeting must be implemented to use this macro.

Real-Time Agent Extended API (for Polled Mode and ATMEL AT91SAM7Sx only)

Function / Macro	Description	Notes
RTA_tx_word_ext	Transmits Real-Time Agent data.	Must be called periodically from an interrupt in Polled Mode, or in the system interrupt handler for the ATMEL AT91SAM7Sx (refer Application Configuration).
RTA_rx_word_ext	Receives Real-Time Agent data.	Must be called periodically from an interrupt in Polled Mode, or in the system interrupt handler for the ATMEL AT91SAM7Sx (refer Application Configuration).

 

Real-Time Agent Extended API (for Polled Mode only)

Function / Macro	Description	Notes
RTA_irq_enable_ext	This function must enable the periodic interrupt that calls RTA_tx_word_ext() and RTA_rx_word_ext().	Must be implemented in Polled Mode.
RTA_irq_disable_ext	This function must disable the periodic interrupt that calls RTA_tx_word_ext() and RTA_rx_word_ext().	Must be implemented in Polled Mode.

 

Example Programs

Example programs for several development boards are available in the folder <KEIL installation directory>\ARM\RT Agent.

 

Custom Interrupt Controllers

The Real-Time Agent uses Debug Communication Channel (DCC) interrupts on the target device. If your target device is not supported, but these interrupts are connected, you can add your own interrupt controller hardware support by following these steps:

• Select Hardware Type --> Custom Hardware in the Real-Time Agent Configuration Wizard.
• Add your custom hardware header file, and implement the C hardware MACROs in the RTA Hardware Specific Section / Custom Hardware section of <KEIL installation directory>\ARM\RV31\INC\RT_Agent.c.

The C hardware MACROs must be implemented as follows:

• TX_IRQ_INIT(): Initialise the DCC transmit interrupt to call RTA_tx_word() when it is triggered.
• TX_IRQ_ACK(): Perform actions to acknowledge DCC transmit interrupt.
• TX_IRQ_ENABLE(): Enable the DCC transmit interrupt.
• TX_IRQ_DISABLE(): Disable the DCC transmit interrupt.
• RX_IRQ_INIT(): Initialise the DCC receive interrupt to call RTA_rx_word() when it is triggered.
• RX_IRQ_ACK(): Perform actions to acknowledge DCC receive interrupt.
• RX_IRQ_ENABLE(): Enable the DCC receive interrupt.
• RX_IRQ_DISABLE(): Disable the DCC receive interrupt.
• DEF_IRQ_INIT(): Initialise the default IRQ interrupt to call RTA_def_irq() when it is triggered. This handles unexpected interrupts that can occur with some interrupt controllers.
• DEF_IRQ_ACK(): Perform actions to acknowledge default IRQ interrupt.
• TX_WORD(): This is for future use, currently it must read:

__asm { MCR p14, 0, tx_word, c1, c0 }

• RX_WORD(): This is for future use, currently it must read:

__asm { MRC p14, 0, rx_word, c1, c0 }

 

Upgrading the Real-Time Agent

The Real-Time Agent uses code both on the host in µVision and on the target. Between Real-Time Agent v1.0 and v2.x. major changes were made to the protocol that were necessarily incompatible with each other. As a result, from RealView MDK 3.10, the Real-Time Agent v1.0 is no longer supported. If your project uses this version, you will have to update to v2.x. The good news is that this is very simple.

Real-Time Agent Upgrade v1.0 --> v2.x

1.      Open the project to upgrade in µVision and note the current configuration of the Real-Time Agent v1.0. This can be found in the RT_Agent.c and Retarget.c file Configuration Wizards. Write down the configuration of the following options:

§         RT_Agent.c

§         Real-Time Agent

§         Hardware Type

§         Output Buffer Size

§         Invalid Memory Pattern

§         Enable Terminal Emulation

§         Echo Characters Automatically

§         Block on Write

§         Retarget.c

§         I/O Retargetting

§         STDOUT Destination

§         External file operations defined

2.      Remove the RT_Agent.c and Retarget.c files from the project.

3.      RTX or RL-ARM only: note the RTX_Config.c configuration options and any custom changes you have made to this file, then replace it with a new one from the template folder (<KEIL installation directory>\ARM\Startup) and re-add your custom changes to the new file.

4.      Follow the steps in Application Configuration using the settings recorded in step 1 (and step 3 for RTX or RL_ARM).

5.      Re-compile and run the project in the µVision debugger. If everything was successful, µVision will report 'Real-Time Agent v2.x: Connected' in the µVision status bar.

If you do not see 'Real-Time Agent v2.x: Connected' in the µVision status bar, follow the troubleshooting tips in Application Configuration.

 

Technical Support

At Keil Software, we are dedicated to providing you with the best development tools and technical support. That's why we offer numerous ways you can get the technical support you need to complete your embedded projects.

• Technical Support Knowledgebase
  More than 1500 technical support questions and answers are available in the Support Solutions Knowledgebase. When a new question arises, it is added to the knowledgebase which is continuously published to the Web. This enables you to get technical support at times when our support staff is unavailable.
• Application Notes
  Numerous Application Notes help you decipher complex features and implement robust applications.
• Example Programs and Files
  Utility programs, example code, and sample projects are regularly added to the Download File section of the web site.
• Discussion Forum
  Post questions, comments, and suggestions to the Keil Software Discussion Forum and interact with other Keil users around the world.

Many of the features of our Technical Support Knowledgebase and Web Site are the results of your suggestions. If you have any ideas that will improve them, please give us your feedback!

 

Contact Details

If you experience any problems or have any questions about this Application Note, contact one of our distributors or offices for assistance.

Copyright © KEIL - An ARM Company.
All rights reserved.
Visit our web site at www.keil.com.