PROTOCOL SOLUTIONS GROUP 3385 SCOTT BLVD S ANTA CLARA, CA 95054 CATC Scripting Language Reference Manual Manual Version 1.
CATC Scripting Language Teledyne LeCroy Document Disclaimer The information contained in this document has been carefully checked and is believed to be reliable. However, no responsibility can be assumed for inaccuracies that may not have been detected. Teledyne LeCroy reserves the right to revise the information presented in this document without notice or penalty. Trademarks and Servicemarks Teledyne Lecroy is a trademark of Teledyne LeCroy.
CATC Scripting Language TABLE OF Table of Contents CONTENTS Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Features of CATC Scripting Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Literals . . . . . . . . . . . . . . . . . . . . . .
CATC Scripting Language Table of Contents 8 Preprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 9 Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 10 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 11 Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Call() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CATC SCRIPTING LANGUAGE CHAPTER 1 Reference Manual Introduction CHAPTER 1: INTRODUCTION CATC Scripting Language (CSL) was developed to create scripts that would allow users to do file-based decoding with CATC USBTracer, USBMobile, and USBAdvisor analyzers. CSL is used to edit CATC Decode Scripting (CDS) files. CATC analyzers are equipped with built-in decoders in addition to script-based decoders that can be modified by the users or implemented as-is.
CHAPTER 2 CATC Scripting Language Values CHAPTER 2: VALUES There are five value types that may be manipulated by a script: integers, strings, lists, raw bytes, and null. CSL is not a strongly typed language. Value types need not be pre-declared. Literals, variables and constants can take on any of the five value types, and the types can be reassigned dynamically. Literals Literals are data that remain unchanged when the program is compiled. Literals are a way of expressing hard-coded data in a script.
CHAPTER 2 CATC Scripting Language Values Escape Sequences These are the available escape sequences in CSL: Character Escape Sequence backslash Example Output \\ "This is a backslash: \\" This is a backslash: \ double quote \" "\"Quotes!\"" "Quotes!" horizontal tab \t "Before tab\tAfter tab" Before tab newline \n "This is how\nto get a newline." This is how to get a newline. single quote \' "\'Single quote\'" After tab 'Single quote' Table 2.
CHAPTER 2 CATC Scripting Language Values result = null; Variables Variables are used to store information, or data, that can be modified. A variable can be thought of as a container that holds a value. All variables have names. Variable names must contain only alphanumeric characters and the underscore ( _ ) character, and they cannot begin with a number. Some possible variable names are x _NewValue name_2 A variable is created when it is assigned a value.
CHAPTER 2 CATC Scripting Language Values will create a local variable called Local, which will only be visible within the function Function. Additionally, it will change the value of Global to "cat", which will be visible to all functions. This will also change its value type from an integer to a string. Local Variables Local variables are not declared. Instead, they are created as needed.
CHAPTER 3 CATC Scripting Language Expressions CHAPTER 3: EXPRESSIONS An expression is a statement that calculates a value. The simplest type of expression is assignment: x = 2 The expression x = 2 calculates 2 as the value of x. All expressions contain operators, which are described in Chapter 4, Operators, on page 9. The operators indicate how an expression should be evaluated in order to arrive at its value. For example x + 2 says to add 2 to x to find the value of the expression.
CHAPTER 3 CATC Scripting Language Expressions x = 10 Value_of_x = select { x < 5 : "Less than 5"; x >= 5 : "Greater than or equal to 5"; }; The above expression will evaluate to “Greater than or equal to 5” because the first true expression is x >= 5. Note that a semicolon is required at the end of a select expression because it is not a compound statement and can be used in an expression context. There is also a keyword default, which in effect always evaluates to true.
CHAPTER 4 CATC Scripting Language Operators CHAPTER 4: OPERATORS An operator is a symbol that represents an action, such as addition or subtraction, that can be performed on data. Operators are used to manipulate data. The data being manipulated are called operands. Literals, function calls, constants, and variables can all serve as operands. For example, in the operation x + 2 the variable x and the integer 2 are both operands, and + is the operator.
CHAPTER 4 CATC Scripting Language Operators The associative operator () is used to group parts of the expression, forcing those parts to be evaluated first. In this way, the rules of precedence can be overridden. For example, ( 4 + 9 ) * 5 causes the addition to be performed before the multiplication, resulting in a value of 65. When operators of equal precedence occur in an expression, the operands are evaluated according to the associativity of the operators.
CHAPTER 4 CATC Scripting Language Operators Operator Symbol += *= I= %= Associativity >>= <<= &= Right to left I= Table 4.
CHAPTER 4 CATC Scripting Language Operators Operator Operand Symbol Description Types Result Types Examples Index Operator [ ] Index or subscript Raw Bytes Integer Raw = '001122' Raw[1] = 0x11 List Any List = [0, 1, 2, 3, [4, 5]] List[2] = 2 List[4] = [4, 5] List[4][1] = 5 *Note: if an indexed Raw value is assigned to any value that is not a byte ( > 255 or not an integer), the variable will be promoted to a list before the assignment is performed.
CHAPTER 4 CATC Scripting Language Operators Operator Operand Symbol Description Types Result Types Examples Equality Operators == != Equal Not equal Integer-integer Integer 2 == 2 String-string Integer "three" == "three" Raw byte-raw byte Integer '001122' == '001122' List-list Integer [1, [2, 3]] == [1, [2, 3]] *Note: equality operations on values of different types will evaluate to false.
CHAPTER 4 CATC Scripting Language Operators Operator Operand Symbol Description Types Result Types Examples Bitwise Logical Operators ~ Bitwise complement Integer-integer Integer ~0b11111110 = 0b00000001 & Bitwise AND Integer-integer Integer 0b11111110 & 0b01010101 = 0b01010100 ^ Bitwise exclusive OR Integer-integer Integer 0b11111110 ^ 0b01010101 = 0b10101011 | Bitwise inclusive OR Integer-integer Integer 0b11111110 | 0b01010101 = 0b11111111 Shift Operators << Left shift Integer-
CHAPTER 4 CATC Scripting Language Operators Operator Operand Symbol Description Types Result Types Examples Assignment Operators (continued) &= Bitwise AND assignment Integer-integer Integer a = 0b11111110 a &= 0b01010101 = 0b01010100 ^= Bitwise exclusive OR assignment Integer-integer Integer e = 0b11111110 e ^= 0b01010101 = 0b10101011 |= Bitwise inclusive OR assignment Integer-integer Integer i = 0b11111110 i |= 0b01010101 = 0b11111111 Number of elements Any Integer sizeof([1, 2, 3])
CHAPTER 4 CATC Scripting Language Operators 15
CHAPTER 5 CATC Scripting Language for USB Comments CHAPTER 5: COMMENTS Comments may be inserted into scripts as a way of documenting what the script does and how it does it. Comments are useful as a way to help others understand how a particular script works. Additionally, comments can be used as an aid in structuring the program. Comments in CSL begin with a hash mark (#) and finish at the end of the line. The end of the line is indicated by pressing the Return or Enter key.
CHAPTER 5 CATC Scripting Language for USB Comments 17
CHAPTER 6 CATC Scripting Language for USB Keywords CHAPTER 6: KEYWORDS Keywords are reserved words that have special meanings within the language. They cannot be used as names for variables, constants or functions.
CHAPTER 6 CATC Scripting Language for USB Keywords 19
CHAPTER 7 CATC Scripting Language Statements CHAPTER 7: STATEMENTS Statements are the building blocks of a program. A program is made up of list of statements. Seven kinds of statements are used in CSL: expression statements, if statements, ifelse statements, while statements, for statements, return statements, and compound statements. Expression Statements An expression statement describes a value, variable, or function.
CHAPTER 7 CATC Scripting Language Statements if ( 3 - 3 || 2 - 2 ) Trace ( "Yes" ); else Trace ( "No" ); will cause “No” to be printed, because 3 - 3 || 2 - 2 will evaluate to False (neither 3 - 3 nor 2 - 2 is nonzero).
CHAPTER 7 CATC Scripting Language Statements The example for ( x = 2; x < 5; x = x + 1 ) Trace ( x, "\n" ); would output 2 3 4 The example above works out like this: the expression x = 2 is executed. The value of x is passed to x < 5, resulting in 2 < 5. This evaluates to true, so the statement Trace (x, "\n" ) is performed, causing 2 and a new line to print. Next, the third expression is executed, and the value of x is increased to 3.
CHAPTER 7 CATC Scripting Language Statements Trace ( HiThere() ); ... HiThere() { a = "Hi there"; return a; b = "Goodbye"; return b; } will output only Hi there because when return a; is encountered, execution of the function terminates, and the second return statement (return b;) is never processed. However, Trace ( HiThere() ); ... HiThere() { a = "Hi there"; b = "Goodbye"; if ( 3 != 3 ) return a; else return b; } will output Goodbye because the if statement evaluates to false.
CHAPTER 7 CATC Scripting Language Statements ... ; } An example of a compound statement is { x = 2; x + 3; } It's also possible to nest compound statements, like so: { x = 2; { y = 3; } x + 3; } Compound statements can be used anywhere that any other kind of statement can be used. if (3 && 3) { result = "True!"; Trace(result); } Compound statements are required for function declarations and are commonly used in if, if-else, while, and for statements.
CHAPTER 7 CATC Scripting Language Statements 25
CHAPTER 8 CATC Scripting Language Preprocessing CHAPTER 8: PREPROCESSING The preprocessing command %include can be used to insert the contents of a file into a script. It has the effect of copying and pasting the file into the code. Using %include allows the user to create modular script files that can then be incorporated into a script. This way, commands can easily be located and reused. The syntax for %include is this: %include “includefile.
CHAPTER 8 CATC Scripting Language Preprocessing 27
CHAPTER 9 CATC Scripting Language Context CHAPTER 9: CONTEXT The context is the mechanism by which transaction data is passed in and out of the scripts. There is an output context that is modified by the script, and there are possibly multiple input contexts that the script will be invoked on separately. A context serves two roles: firstly, it functions as a symbol table whose values are local to a particular transaction; secondly, it functions as an interface to the application.
CHAPTER 9 CATC Scripting Language Context 29
CHAPTER 10 CATC Scripting Language Functions CHAPTER 10: FUNCTIONS A function is a named statement or a group of statements that are executed as one unit. All functions have names. Function names must contain only alphanumeric characters and the underscore ( _ ) character, and they cannot begin with a number. A function can have zero or more parameters, which are values that are passed to the function statement(s). Parameters are also known as arguments.
CHAPTER 10 CATC Scripting Language Functions the parameter x will be assigned to 1, and the parameter y will be assigned to null, resulting in a return value of 1. But if add is called with more than two arguments add(1, 2, 3); x will be assigned to 1, y to 2, and 3 will be ignored, resulting in a return value of 3. All parameters are passed by value, not by reference, and can be changed in the function body without affecting the values that were passed in.
CHAPTER 11 CATC Scripting Language Primitives CHAPTER 11: PRIMITIVES Primitive functions are called similarly to regular functions, but they are implemented outside of the language. Some primitives support multiple types for certain arguments, but in general, if an argument of the wrong type is supplied, the function will return null.
CHAPTER 11 CATC Scripting Language Primitives Comments Format is used to control the way that arguments will print out. The format string may contain conversion specifications that affect the way in which the arguments in the value string are returned. Format conversion characters, flag characters, and field width modifiers are used to define the conversion specifications. Example Format("0x%02X", 20); would yield the string 0x14.
CHAPTER 11 CATC Scripting Language • Primitives • A space will insert a space before a positive signed integer. This only works with the conversion characters d and i. If both a space and a plus sign are used, the space flag will be ignored. • A hash mark (#) will prepend a 0 to an octal number when used with the conversion character o. If # is used with x or X, it will prepend 0x or 0X to a hexadecimal number. • A zero (0) will pad the field with zeros instead of with spaces.
CHAPTER 11 CATC Scripting Language Primitives result = C # The result is given in hexadecimal. The result in binary is 1100. In the call to GetNBits: starting at bit 2, reads 4 bits (1100), and returns the value 0xC. NextNBits() NextNBits () Parameter Meaning Default Value Comments bit_count integer Return value None.
CHAPTER 11 CATC Scripting Language Primitives Resolve() Resolve( ) Parameter Meaning Default Value Comments symbol_name string Return value The value of the symbol. Returns null if the symbol is not found. Comments Attempts to resolve the value of a symbol. Can resolve global, constant and local symbols. Spaces in the symbol_name parameter are interpreted as the ‘_’ (underscore) character since symbol names cannot contain spaces.
CHAPTER 11 CATC Scripting Language Primitives 37
CHAPTER 12 CATC Scripting Language Decoder Primitives CHAPTER 12: DECODER PRIMITIVES Abort() Abort() Parameter Meaning Default Value Comments N/A Return value An integer that should be passed back to the application unchanged. Comments Called when an input context renders the currently pending transaction done, but is not itself a member of that transaction. An example would be an input transaction that represents some sort of reset condition that renders all pending transactions invalid.
CHAPTER 12 CATC Scripting Language Parameter Meaning Decoder Primitives Default Value additional_info any Comments Used to create special cells or to modify cell attributes. The values are predefined constants, and zero or more of them may be used at one time. Possible values are: _COLLAPSED _ERROR _EXPANDED [_FIXEDWIDTH, w] _HIDDEN _MONOCOLOR _MONOFIELD _SHOWN (default) _WARNING Return value None. Comments Adds a display cell to the current output context.
CHAPTER 12 CATC Scripting Language Decoder Primitives AddCell( "Warning", "Value5", "Warning cell", 0x00BB22, _WARNING ); # Use the [_FIXEDWIDTH, w] value to create a cell with a fixed width of 20 in conjuction with the error value to create a fixed width cell with a red value field: AddCell( "Fixed Width 20", "Value6", "Fixed Width and Error cell", 0x001122, [_FIXEDWIDTH, 20], _ERROR ); The output of the example is: Figure 12-1: Example output for AddCell AddDataCell() AddDataCell(
CHAPTER 12 CATC Scripting Language Decoder Primitives Example # Creates a data cell with 2 dwords (32-bit integers) of data. AddDataCell( '0123456789ABCDEF', _DWORDS ); # Creates a data cell with 4 bytes. Integer data values are always interpreted as 32 bits of data.
CHAPTER 12 CATC Scripting Language Decoder Primitives AddSeparator() AddSeparator(, ...) Parameter Meaning Default Value additional_info any Comments Used to create special cells or to modify cell attributes. The values are predefined constants. Possible values are: _COLLAPSED _EXPANDED _HIDDEN _SHOWN (default) Return value None. Comments Creates a separator cell. _COLLAPSED, _EXPANDED, _HIDDEN, and _SHOWN are all interpreted the same is in a regular AddCell call.
CHAPTER 12 CATC Scripting Language Parameter Meaning Decoder Primitives Default Value value string Displays in the value field of the cell. description string or null color integer or list Comments Displays in tool tip. If not speci- Color can be specified as either a packed color fied, a default value in an integer, or as an array of RGB values color is used ranging from 0-255. Displays in the name field of the cell. additional_info any Used to create special cells or to modify cell attributes.
CHAPTER 12 CATC Scripting Language Decoder Primitives # This cell will be displayed when the red group is collapsed: AddCell( "Red is", "Collapsed", null, 0x0000ff, _COLLAPSED ); # This begins the nested blue group.
CHAPTER 12 CATC Scripting Language Decoder Primitives The output of the example is: Figure 12-4: Example output for BeginCellBlock with red group collapsed Figure 12-5: Example output for BeginCellBlock with red group expanded and blue group collapsed Figure 12-6: Example output for BeginCellBlock with red group expanded and blue group expanded Complete() Complete() Parameter Meaning Default Value Comments Return value An integer that should be passed back to the application unchanged.
CHAPTER 12 CATC Scripting Language Decoder Primitives EndCellBlock() EndCellBlock() Parameter Meaning Default Value Comments Return value None. Comments Ends a cell block that was started with BeginCellBlock(). Example See BeginCellBlock(). GetBitOffset() GetBitOffset() Parameter Meaning Default Value Comments N/A Return value None. Comments Returns the current bit offset that is used in NextNBits or PeekNBits.
CHAPTER 12 CATC Scripting Language Decoder Primitives PeekNBits() PeekNBits() Parameter Meaning Default Value Comments bit_count integer Return value None. Comments Reads bit_count bits from the data source. The difference between PeekNBits and NextNBits is that PeekNBits does not advance the global bit offset. PeekNBits can be used to make decisions about how to parse the next fields without affecting subsequent calls to NextNBits.
CHAPTER 12 CATC Scripting Language Decoder Primitives Return value An integer that should be passed back to the application unchanged. Comments This should be called when it has been decided that an input context has been accepted into a transaction, but that the transaction still requires further input to be complete. This function could be used to associate input contexts with the output context. The return value of this function should be returned to the application in the ProcessData function.
Ol:APTER 12 CATC Scripting Language for USB Decoder Primitives 49
CHAPTER 13 CATC Scripting Language Modules CHAPTER 13: MODULES Modules are a collection of functions and global data dedicated to decoding a certain type of transaction. Each module consists of one primary file (.dec), and possibly several included files (.inc). Module Functions Three functions are used as entry-points into a decoding module. They are called by the application and are used both in the initial transaction decoding phase, and each time that a transaction needs to be displayed.
CHAPTER 13 CATC Scripting Language Modules Module Data There are several standard global variables that should be defined in a module which are queried by the application to figure out what the module is supposed to do. ModuleType Required. A string describing the role of the script. Currently, only Transaction Decoder and DataBlock Decoder are valid. Example set ModuleType = "Transaction Decoder"; Transaction Decoder uses ProcessData(). DataBlock Decoder does not. OutputType Required.
CHAPTER 13 CATC Scripting Language Modules Icon Optional. File name of an icon to display on the toolbar. Must be a 19x19 pixel bitmap file. Example set Icon = "bitmap.
How to Contact Teledyne LeCroy Type of Service Call for technical support… Fax your questions… Write a letter … Send e-mail… Visit Teledyne LeCroy’s web site… Contract US and Canada: 1 (800) 909-7112 Worldwide: 1 (408) 653-1260 Worldwide: 1 (408) 727-6622 Teledyne LeCroy Protocol Solutions Group Customer Support 3385 Scott Blvd. Santa Clara, CA 95054-3115 psgsupport@teledynelecroy.com http://www.teledynelecroy.
