GEL

From Texas Instruments Wiki
Jump to: navigation, search

Overview

GEL standards for General Extension Language (previously GODSP Extension Language).  GEL is the expression language that is used by the CCS debugger.  Everywhere you enter in a start address, variable name or condition on a breakpoint it is using GEL to evaluation that C-like expression.

GEL has been an essential feature of CCS from the beginning. Official documentation for GEL, including a list of all built-in GEL functions, is part of the on-line help that ships with CCS. This wiki topic focus on some of the changes to GEL starting with CCSv4.

Startup Files

Target configurations in CCS often specify a startup script.  These scripts are typically used to setup the memory map for the debugger, set any initial target state (via memory or register writes) that is necessary in order to connect the debugger. These scripts are usually written in GEL.  It is the OnStartup() function in the GEL file that is run when the debugger is launched.  There is also a OnTargetConnect() function that is called when the target is connected.  The startup scripts define these functions.

GUI Integration

In CCS there have been a number of ways in which GEL has been integrated with the CCS GUI.  This has changed somewhat in CCSv4+ compared to CCSv3.3 due to the fact that we are using a new GUI based on Eclipse.  While the GUI integration has changed all the core debug related functions are still available.  The information in this section describes the GEL GUI integration items that exist in CCSv4+.

Hotmenus
It is possible to associate a GEL function with a menu item.  These menu items will show up on the User Scripts menu in the Debug perspective in CCS.
Sliders
Sliders allow you to attach function that adjusts a variable to a GUI slider control.
Dialogs
GEL dialogs prompt you to enter a value that is used as a parameter to a GEL function.
Loaded GEL Files
You can view loaded GEL files by going to the Control Panel in CCS, from the tools menu select GEL Files.
GEL Console Output
In CCSv3.3 GEL_TextOut() output is directed to the GEL tab on the output window or sometimes to a specially named tab if a name was given in the GEL_TextOut() function. In CCSv4+ this function still works and the output is shown in the console view. One change here is that all of the output goes to the console view, you cannot create a separate tab with a custom name and direct output there.

Loading GEL Files

Startup GEL files defined in the target configuration file will be automatically loaded when a debug session is started. See the Creating Custom Target Configurations topic for more information on specifying a startup GEL file.

Additional GEL files can be loaded in CCSv4+ from the 'GEL Files' dialog (via 'Tools->GEL Files' menu).

Fig. 1: 'GEL Files' Menu

This will open the 'GEL Files' view. From this view, users can see all loaded GEL files for that debug session and have the option to open them in the editor, reload the GEL file, remove/unload the GEL file, and load additional GEL files. Right-click in the view and select 'Load GEL' to load a GEL file:

Fig. 2: 'GEL Files' View

When a new GEL file is loaded, it will appear in the 'GEL Files' view. If the load was successful, the status will be listed as 'Success'.

Fig. 3: GEL File Loaded

GEL Hotmenus/Menuitems

Any hotmenu, dialog, and slider functions contained in all loaded GEL files will be available from the 'Scripts' menu:

Fig. 4: 'Scripts' Menu

GEL Sliders

GEL sliders behave the same as in CCS 3.x. Selecting the GEL slider function from the 'Scripts' menu will pop up the GEL slider GUI.

Fig. 5: GEL Slider

GEL Dialogs

GEL dialogs behave the same as in CCS 3.x. Selecting the GEL dialog function from the 'Scripts' menu will pop up a GEL dialog box where a value may be entered to set the value of a GEL variable.

Fig. 6: GEL Dialog

GEL Automation

If you are using GEL for automation it is highly recommended that you convert these to Debug Server Scripting (DSS) scripts, as these scripts are much more robust, predictable and debuggable. However you can still use your existing GEL automation scripts.

Deprecated Functions

The following functions were supported in CCS3.x but have been deprecated in later CCS versions.
Project related functions
All functions that dealt with project related functions such as opening a project or building a project are not supported in CCSv4+. 
Functions for opening windows
In CCSv3.x there were a few functions that were used to open specific windows such as the memory window.  These functions are not supported in CCSv4+.  There are equivalent functions avialalble via the Scripting Console.
GEL_WatchAdd()
This function is not supported.
GEL_CloseWindow()
This function is not supported.

Debugging GEL

There are two enhancements introduced in CCS v5.1.1 to assist you debug GEL issues: enhanced run time error messages and GEL_Trace.

Enhanced run time error messages

When a run time error occurs, GEL outputs a detail error message with full call stack.
For example,

Test.gel:
    foo_cmd2( )
    {
       foo_cmd();
    }

    cmd()
    {
       foo_cmd4();
    }

Test2.gel:
    foo_cmd5( )
    {
       foo_cmd2();
    }

    foo_cmd4( )
    {
       foo_cmd7();
    }

Test3.gel:
    foo_cmd7( )
    {
       foo_cmd5();
    }

    foo_cmd()
    {
       GEL_TextOut( "address of cmd = %x\n", 0, 0, 0, 0, &cmd2 );
    }


Currently, evaluating cmd() in the CCS v5.1 scripting console, the user gets:
js:> eval('cmd()')
    Error evaluating "cmd()": identifier not found: cmd2
(C:\CCSv5\5.1.0.08018\ccsv5\eclipse\configuration\org.eclipse.osgi\bundles\361\1\.cp\resources\debugserver\expression.js#10)
js:>


Evaluating cmd() in the CCS v5.1.1 scripting console, the user will get:
js:> eval('cmd()')
    Error evaluating "cmd()": identifier not found: cmd2
        at GEL_TextOut("address of cmd = %x\n", 0, 0, 0, 0, &(cmd2)) [test3.gel:8]
        at foo_cmd() [test.gel:3]
        at foo_cmd2() [test2.gel:3]
        at foo_cmd5() [test3.gel:3]
        at foo_cmd7() [test2.gel:8]
        at foo_cmd4() [test.gel:8]
        at cmd()
(C:\CCSv5\5.1.0.08018\ccsv5\eclipse\configuration\org.eclipse.osgi\bundles\361\1\.cp\resources\debugserver\expression.js#10)
js:>

GEL_Trace

This feature allows you trace the execution of GEL scripts. You can control the feature by executing the GEL builtin function GEL_Trace( level )

where level is an integer 0, 1 or 2.
0 – no trace (default value)
1 – trace entry/exit of GEL functions
2 – trace execution of each statement in the functions (including entry/exit)

By default, the trace will be sent to the CCS console. You can redirect the output using GEL_EnableFileOutput and GEL_DisableFileOutput.

The following are some trace examples.


Tracing the GEL execution during the target launch
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:23   Enter function StartUp
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:25      GEL_LoadGel("$(GEL_file_dir)/CortexM3_util.gel")
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:27      GEL_MapOff()
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:28      GEL_MapReset()
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:29      GEL_MapOn()
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:30      F28M35H52C1_Memory_Map()
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:73      Enter function F28M35H52C1_Memory_Map
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:100        GEL_MapAddStr(0x0, 0, 0x10000, "R", 0)
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:101        GEL_MapAddStr(0x200000, 0, 0x80000, "R", 0)
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:102        GEL_MapAddStr(0x600000, 0, 0x10000, "R", 0)
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:103        GEL_MapAddStr(0x680000, 0, 0x00800, "R", 0)
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:104        GEL_MapAddStr(0x680800, 0, 0x00004, "R", 0)
…
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:241        GEL_MapAddStr(0xE000E000, 0, 0x1000, "R|W", 0)
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:243        GEL_TextOut("Memory Map Initialization Complete\n")
Cortex_M3_0: GEL Output: Memory Map Initialization Complete
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:243     Leave function F28M35H52C1_Memory_Map
Cortex_M3_0: GEL Trace: f28m35h52c1_m3.gel:30   Leave function StartUp
C28xx_0: GEL Trace: f28m35h52c1_c28.gel:21      Enter function StartUp
C28xx_0: GEL Trace: f28m35h52c1_c28.gel:0       Leave function StartUp
Tracing the GEL callbacks
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:65      Enter function OnHalt
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:66         GEL_TextOut("Halted!!!\n")
TMS470R2x_0: GEL Output: Halted!!!
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:66      Leave function OnHalt
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:65      Enter function OnHalt
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:66         GEL_TextOut("Halted!!!\n")
TMS470R2x_0: GEL Output: Halted!!!
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:66      Leave function OnHalt
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:6       Enter function load_module_symbol
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:7          GEL_TextOut("Loading  C:/Users/Documents/ptzfi.ko\n")
TMS470R2x_0: GEL Output: Loading  C:/Users/Documents/ptzfi.ko
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:12         GEL_TextOut("Relocate section .bss to 0xbf015964\n")
TMS470R2x_0: GEL Output: Relocate section .bss to 0xbf015964
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:13         GEL_SymbolShowSection("C:/Users/Documents/ptzfi.ko", ".bss", 0xbf015964, 0xbf015964)
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:14         GEL_TextOut("Relocate section .data to 0xbf015208\n")
TMS470R2x_0: GEL Output: Relocate section .data to 0xbf015208
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:15         GEL_SymbolShowSection("C:/Users/Documents/ptzfi.ko", ".data", 0xbf015208, 0xbf015208)
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:16         GEL_TextOut("Relocate section .data..cacheline_aligned to 0xbf015800\n")
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:83      Enter function OnFileLoaded
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:83      Enter function OnFileLoaded
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:83      Enter function OnFileLoaded
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:83      Enter function OnFileLoaded
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:83      Enter function OnFileLoaded
TMS470R2x_0: GEL Output: Relocate section .data..cacheline_aligned to 0xbf015800
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:17         GEL_SymbolShowSection("C:/Users/Documents/ptzfi.ko", ".data..cacheline_aligned", 0xbf015800, 0xbf015800)
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:84         GEL_TextOut("OnFileLoaded!!!\n")
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:84         GEL_TextOut("OnFileLoaded!!!\n")
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:84         GEL_TextOut("OnFileLoaded!!!\n")
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:84         GEL_TextOut("OnFileLoaded!!!\n")
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:84         GEL_TextOut("OnFileLoaded!!!\n")
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:18         GEL_TextOut("Relocate section .exit.text to 0xbf01268c\n")
TMS470R2x_0: GEL Output: OnFileLoaded!!!
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:84      Leave function OnFileLoaded
TMS470R2x_0: GEL Output: OnFileLoaded!!!
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:84      Leave function OnFileLoaded
TMS470R2x_0: GEL Output: OnFileLoaded!!!
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:84      Leave function OnFileLoaded
TMS470R2x_0: GEL Output: OnFileLoaded!!!
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:84      Leave function OnFileLoaded
TMS470R2x_0: GEL Output: OnFileLoaded!!!
TMS470R2x_0: GEL Trace: ccs_modsyms.gel:84      Leave function OnFileLoaded