AETLIB

Advanced Event Triggering Target Library (AETLIB)

Introduction

The AET target library is designed to allow the user to program advanced event triggering jobs from within c64, 64+ target code. The AET target library uses the Advanced Event Triggering hardware. AETLib is a part of the CToolsLib collection of target libraries. This can be downloaded fromthe links on the following page: CToolsLib.

The AET Target library is designed to allow the user to configure the generation of AET Triggers from within their application code. By itself, the AET Target Library allows the user to configure triggers that generate CPU halts and Software Interrupts. It also allows use of the AET couters and finite state machine. But, it is most powerful when combined with the use of XDS560 Trace. Using AETLIB with trace can be accomplished in two ways. It can be used with an XDS560T while connected with Code Composer Studio. It can also be used in a stand alone application on devices with an embedded trace buffer. in order to use it stand alone, the application must also make use of the Trace Library and ETB Library.

AETLIB Package

AetLib is released in 3 separate packages.

• aet_target_lib_xx_yy_zz-Setup.exe - Windows Installer of AET Target Library version xx_yy_zz (Binaries and Examples)
• aet_target_lib-xx_yy_zz-Linux-x86-Install - Linux Installer of AET Target Library version xx_yy-zz (Binaries and Examples)
• aet_target_lib_src-xx_yy_zz-Setup.exe - Windows Installer of AET Target Library version xx_yy_zz (Full Source Code)

Directory Structure

The directory structure for the binaries and examples install, with files of interest noted.

ti
 |
 --sdo
    |
    --aet
       |
       --doc - Documentation Directory
       |  |
       |  --html - html documentation directory
       |  |   |
       |  |   -- index.html - Index file for HTML documentation
       |  |
       |  --win - windows documentation directory
       |  |  |
       |  |  -- aetlib.chm - Windows Help File
       |  |   
       |  -- readme.txt - Readme with revision information, known issues
       |  |
       |  -- aetlib_profiling_stats.txt - Profiling information on AETLIB API's
       |  |
       |  -- aetlib_size_stats.txt - AETLIB code size information
       |
       --examples - AETLIB Example Projects
       |
       --include - AETLIB Include Files
       |
       --lib - Binary Library files

Frequently Asked Questions

What are the advantages to programming AET with Aetlib over programming it with the CCStudio Plugin?

• Dynamic programming and reuse of AET resources
  • AET resources can be reclaimed and reprogrammed at run time. Programming AET from Code Composer Studio requires load-time configuration and no reuse. With CCS, all addresses must be known at load time, which makes it impossible to trigger on execution of a dynamically allocated thread or task.
• Context based AET use
  • AET can be enabled/disabled based on a particular context (i.e. single thread, etc)

Where can I find Documentation and Examples for using Aetlib?

All of the necessary documentation and examples are included in the release package. See the Help documents under the doc folder and a number of examples under the examples folder.

Can Aetlib be used to allow AET to trigger interrupts?

AETLIB can be used to generate an interrupt based on an AET event. There's an example included with AETLIB that accomplishes this. It's called slice_watchpoint_in_range, and uses the slice applicaiton to generate an interrupt when a specified data range is written to.

A few things to keep in mind....`

• The only interrupt that can be generated by AET is the RTOS interrupt. Many people ask if they can generate an NMI or some other interrupt with AET, but that's not possible.
• Due to a design flaw in the 64x (Kelvin) devices, you must use an emulator/debugger. With the 64x+ (Joule/Full-Gem) devices, it can be used entirely without an emulator attached.

Which ISAs does AETLIB support?

At present AETLIB supports the c64x and c64xPlus Instruction Set Architectures.

Can all of the system events be used as the trigger event when using TRACE ON EVENT?

Yes, any of the system events can be used as the trigger event when using TRACE ON EVENT. Keep in mind that during a single session you can only use events from the same family. There are 3 families, Memory Events, Stall Events, and Miscellaneous/System Events

For the AETLib, some functions are invalid on C64x DSPs. Do we have a list to clarify which functions are invalid on C64x DSPs

Any functions which are not supported by the AET hardware on a 64x DSP are obviously not supported on the 64x device. These include triggering on events and anything that uses the watermark counter.

If a data breakpoint is set with datasize as BYTE|HALFWORD, and an access occurs with access size WORD, will it trigger the breakpoint?

No, it will not trigger the breakpoint. If you want "ANY" write to trigger the breakpoint, then you must logically OR all of the write sizes together in the datasize value.(NOTE: This FAQ applies to AET, but not AETLIB specifically. In AETLIB, there is no ability to specify the write size. AETLIB always uses "ANY" as the write size. This is a limitation that was consciously chosen in order to align with the majority of use cases, and to reduce the complexity and memory footprint of AETLIB)

When an AET Job is configured with an RTOS trigger, is it re-armed by AET logic or does it have to be re-armed explicitly by application? If so, what is the procedure to re-arm?

Yes, once the "RTOS" interrupt is triggered, it should be cleared in the Interrupt Service Routine that services it. There is an API provided in aet.h to enable this. The API is AET_CLEAR_RTOS_INT();

Once an AET_releaseJob() is issued, are those resources available to be reused by the application or is it also necessary to issue an AET_release() command before those resources can be reassigned?

The AET_releaseJob() API reclaims all resources used in the job being released so that they can be used again in future jobs. The AET_release() API releases ownership of the AET unit So, the answer to this specific question is yes, as soon as AET_releaseJob() is called, the resources from the job being released are immediately available to be reassigned.