Document DisclaimerFile-based Decoding User Manual
Document Disclaimer
The information 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.
LeCroy reserves the right to revise the information in this document without notice or
penalty.
Trademarks and Servicemarks
CATC Trace, FCTracer, SATracer, SASTracer, PETracer, PETracer ML, PETracer EML,
UWBTracer, UWBTracer MPI, BTTracer, Merlin, Merlin II, USBTracer, USB
USB
Mobile HS, Voyager, Advisor T3, UPAS, and BusEngine are trademarks of LeCroy.
Microsoft and Windows are registered trademarks of Microsoft Inc.
All other trademarks are property of their respective companies.
File-based Decoding User ManualChapter 1: Introduction
Chapter 1: Introduction
CATC Scripting Language (CSL) was developed to create scripts that would allow users
to perform file-based decoding with all LeCroy analyzers. CSL is used to edit
CATC
Decode Scripting (CDS) files, which are pre-written decoder scripts supplied by
LeCroy. These script-based decoders can be modified by users or used as-is.
Additionally, users can create brand new CDS files.
This document includes the following analyzer-specific contents:
•Appendix A: PETracer™ Decoder Script Files (for the PETracer product)
•Appendix B: Bluetooth
Decoding scripts for analyzers are located in the /Scripts sub-directory below the
application directory. These scripts are tools to decode and display transactions. Users
can also add entirely new, customized decoders to fit their own specific development
needs. The analyzer application looks in the
sub-directories and automatically loads all of the .dec files that it finds. To prevent a
particular decoder from being loaded, change its extension to something other than .dec
or move it out of the
CSL is based on C language syntax, so anyone with a C programming background
should have no trouble learning CSL. The simple, yet powerful, structure of CSL also
enables less experienced users to easily acquire the basic knowledge needed to start
writing custom scripts.
/Scripts directory.
/Scripts directory and all its
1.1 Features of CATC Scripting Language
•Powerful: Provides a high-level API while simultaneously allowing implementation
of complex algorithms.
•Easy to learn and use: Has a simple but effective syntax.
•Self-contained: Needs no external tools to run scripts.
•Wide range of value types: Provides efficient and easy processing of data.
•Script-based decoding: Used to create built-in script-based decoders for analyz-
ers.
•Custom decoding: May be used to write custom decoders.
•General purpose: Is integrated in a number of LeCroy products.
LeCroy Corporation 1
Chapter 1: IntroductionFile-based Decoding User Manual
2LeCroy Corporation
File-based Decoding User ManualChapter 2: 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
re-declared. Literals, variables and constants can take on any of the five value types,
p
and the types can be reassigned dynamically.
2.1 Literals
Literals are data that remain unchanged when the program is compiled. Literals are a way
of expressing hard-coded data in a script.
Integers
Integer literals represent numeric values with no fractions or decimal points.
Hexadecimal, octal, decimal, and binary notation are supported:
Hexadecimal numbers must be preceded by 0x: 0x2A, 0x54, 0xFFFFFF01
Octal numbers must begin with 0: 0775, 017, 0400
Decimal numbers are written as usual: 24, 1256, 2
Binary numbers are denoted with 0b: 0b01101100, 0b01, 0b100000
Strings
String literals are used to represent text. A string consists of zero or more characters and
can include numbers, letters, spaces, and punctuation. An empty string ("") contains
o characters and evaluates to false in an expression, whereas a non-empty string
n
evaluates to true. Double quotes surround a string, and some standard backslash (
escape sequences are supported.
StringRepresented Text
"Quote: \"This is a string
literal.\""
"256"
"abcd!$%&*"
"June 26, 2001"
"[ 1, 2, 3 ]"
Table 2.1 Examples of String Literals
Quote: "This is a string literal."
256
**Note that this does not represent the
integer 256, but only the characters that
make up the number.
abcd!$%&*
June 26, 2001
[ 1, 2, 3 ]
\)
LeCroy Corporation 3
Chapter 2: ValuesFile-based Decoding User Manual
Escape Sequences
These are the available escape sequences in CSL:
Escape
Character
backslashThis is a backslash: \
le
doub
quote
horizon
tab
ineThis is how
newl
single quote'Single quote'
SequenceExampleOutput
\\"This is a backslash: \\"
\""\"Quotes!\""
tal
\t"Before tab\tAfter tab"
\n"This is how\nto get a newline."
\'"\'Single quote\'"
"Quotes!"
Before tabAfter tab
et a newline.
to g
Table 2.2 Escape Sequences
Lists
A list can hold zero or more pieces of data. A list that contains zero pieces of data is called
an empty list. An empty list evaluates to false when used in an expression, whereas a
non-empty list evaluates to true. List literals are expressed using the square bracket (
delimiters. List elements can be of any type, including lists.
Raw binary values are used primarily for efficient access to packet payloads. A literal
notation is supported using single quotes:
'00112233445566778899AABBCCDDEEFF'
This represents an array of 16 bytes with values starting at 00 and ranging up to 0xFF.
e values can only be hexadecimal digits. Each digit represents a nybble (four bits), and
Th
if there are not an even number of nybbles specified, an implicit zero is added to the first
byte. For example:
'FFF'
is interpreted as
'0FFF'
null
null indicates an absence of valid data. The keyword null represents a literal null value
and evaluates to false when used in expressions.
result = null;
4LeCroy Corporation
File-based Decoding User ManualChapter 2: Values
2.2 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 (
variable names are
x
_NewValue
name_2
A variable is created when it is assigned a value. Variables can be of any value type, and
can change type with re-assignment. Values are assigned using the assignment operator
(
= ). The name of the variable goes on the left side of the operator, and the value goes
on the right:
x = [ 1, 2, 3 ]
New_value = x
name2 = "Smith"
If a variable is referenced before it is assigned a value, it evaluates to null.
There are two types of variables: global and local.
_ ) character, and they cannot begin with a number. Some possible
Global Variables
Global variables are defined outside of the scope of functions. Defining global variables
requires the use of the keyword
all files that it includes).
set Global = 10;
If an assignment in a function has a global as a left-hand value, a variable is not created,
but the global variable is changed. For example:
set Global = 10;
Function()
{
Global = "cat";
Local = 20;
}
creates a local variable called Local, which is only visible within the function Function.
Additionally, it changes the value of
This also changes its value type from an integer to a string.
set. Global variables are visible throughout a file (and
Global to "cat", which is visible to all functions.
LeCroy Corporation 5
Chapter 2: ValuesFile-based Decoding User Manual
Local Variables
Local variables are not declared. Instead, they are created as needed. Local variables
are created either by being in a function's parameter list, or simply by being assigned a
value in a function body.
Function(Parameter)
{
Local = 20;
}
This function creates a local variable Parameter and a local variable Local, which has
an assigned value of 20.
2.3 Constants
A constant is similar to a variable, except that its value cannot be changed. Like variables,
constant names must contain only alphanumeric characters and the underscore (
character, and they cannot begin with a number.
Constants are declared similarly to global variables using the keyword const:
const CONSTANT = 20;
_ )
They can be assigned to any value type, but generates an error if used in the left-hand
side of an assignment statement later on. For example:
const constant_2 = 3;
Function()
{
constant_2 = 5;
}
generates an error.
Declaring a constant with the same name as a global, or a global with the same name as
a constant, also generates an error. Like globals, constants can only be declared in the
file scope.
6LeCroy Corporation
File-based Decoding User ManualChapter 3: 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. Another example is
x > 2
which indicates that x is greater than 2. This is a Boolean expression, so it evaluates to
either true or false. Therefore, if
false.
True is denoted by a non-zero integer (any integer except 0), and false is a zero integer
(0). True and false are also supported for lists (an empty list is false, while all others are
true), and strings (an empty string is false, while all others are true), and
considered false. However, all Boolean operators result in integer values.
x = 3, then x > 2 evaluates to true; if x = 1, it returns
null is
LeCroy Corporation 7
Chapter 3: ExpressionsFile-based Decoding User Manual
3.1 select expression
The select expression selects the value to which it evaluates based on Boolean
expressions. This is the format for a
The expressions are evaluated in order, and the statement that is associated with the first
true expression is executed. That value is what the entire expression evaluates to.
x = 10
Value_of_x = select {
x < 5 : "Less than 5";
x >= 5 : "Greater than or equal to 5";
};
The above expression evaluates to “Greater than or equal to 5” because the first true
expression is
expression because it is not a compound statement and can be used in an expression
context.
x >= 5. Note that a semicolon is required at the end of a select
select expression:
There is also a keyword default, which in effect always evaluates to true. An example
of its use is
Astring = select {
A == 1 : "one";
A == 2 : "two";
A == 3: "three";
A > 3 : "overflow";
default : null;
};
If none of the first four expressions evaluates to true, then default is evaluated,
returning a value of
select expressions can also be used to conditionally execute statements, similar to C
switch statements:
select {
A == 1 : DoSomething();
A == 2 : DoSomethingElse();
default: DoNothing();
};
In this case the appropriate function is called depending on the value of A, but the
evaluated result of the
null for the entire expression.
select expression is ignored.
8LeCroy Corporation
File-based Decoding User ManualChapter 4: 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.
4.1 Operations
Operations can be performed on any combination of value types, but results in a null
value if the operation is not defined. Defined operations are listed in the Operand Types
column of
results in the non-null value. For example, if
then
Tab le 4.2 on page 11. Any binary operation on a null and a non-null value
x = null
3 * x
returns a value of 3.
A binary operation is an operation that contains an operand on each side of the operator,
as in the preceding examples. An operation with only one operand is called a unary
operation, and requires the use of a unary operator. An example of a unary operation is
!1
which uses the logical negation operator. It returns a value of 0.
4.2 Operator Precedence and Associativity
Operator rules of precedence and associativity determine in what order operands are
evaluated in expressions. Expressions with operators of higher precedence are
evaluated first. In the expression
4 + 9 * 5
the * operator has the highest precedence, so the multiplication is performed before the
addition. Therefore, the expression evaluates to 49.
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.
LeCroy Corporation 9
Chapter 4: OperatorsFile-based Decoding User Manual
When operators of equal precedence occur in an expression, the operands are evaluated
according to the associativity of the operators. This means that if an operator's
associativity is left to right, then the operations is done starting from the left side of the
expression. So, the expression
4 + 9 - 6 + 5
would evaluate to 12. However, if the associative
operator is used to group a part or parts
of the expression, those parts are evaluated first. Therefore,
( 4 + 9 ) - ( 6 + 5 )
has a value of 2.
In Table 4.1, Operator Precedence and Associativity, the operators are listed in order of
precedence, from highest to lowest. Operators on
the same line have equal precedence,
and their associativity is shown in the second column.
Operator SymbolAssociativity
++ --
[] ()
~ ! sizeof head tail first next more
Right to left
Left to right
Right to left
last prev
* / %
+ -
<< >>
< > <= >=
== !=
&
Left to right
Left to right
Left to right
Left to right
Left to right
Left to right
^
|
&&
||
= += -= *= /= %= >>= <<= &= ^= |=
Left to right
Left to right
Left to right
Left to right
Right to left
Table 4.1 Operator Precedence and Associativity
10LeCroy Corporation
File-based Decoding User ManualChapter 4: Operators
Operator
SymbolDescriptionOperand Types
Result
TypesExamples
Index Operator
[ ]Index or subscriptRaw BytesIntegerRaw = '001122'
Raw[1] = 0x11
ListAnyList = [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 (
variable is promoted to a list before the assignment
is performed.
Associative Operator
( )AssociativeAnyAny( 2 + 4 ) * 3 = 18
2 + ( 4 * 3 ) = 14
Arithmetic Operators
*MultiplicationInteger-integerInteger3 * 1 = 3
/DivisionInteger-integerInteger3 / 1 = 3
%ModulusInteger-integerInteger3 % 1 = 0
+AdditionInteger-integerInteger2 + 2 = 4
String-str ingStrin g"one " + "two" = "one two"
Raw byte-raw byteRaw'001122' + '334455' = '001122334455'
Chapter 4: OperatorsFile-based Decoding User Manual
16LeCroy Corporation
File-based Decoding User ManualChapter 5: 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.
Most 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. Anything contained inside
the comment delimiters is ignored by the compiler. Thus,
# x = 2;
is not considered part of the program. CSL supports only end-of-line comments of this
type (comments that can be used only at the end of a line or on their own line). It's not
possible to place a comment in the middle of a line using the hash mark.
Writing a multi-line comment requires either beginning each line with the hash mark (and
ending that line with a Return or Enter) or using a comment block.
A comment block begins with "/*" and end with "*/". Everything inside of the comment
block is ignored.
Example of a multi-line comment with comment delimiters on each line:
# otherwise the compiler would try to interpret
# anything outside of the delimiters
# as part of the code.
Example of a multi-line comment block:
/*
The compiler ignores all contents
of the block comment.
*/
The most common use of comments is to explain the purpose of the code immediately
following the comment. For example:
# Add a profile if we got a server channel
if(rfChannel != "Failure")
{
result = SDPAddProfileServiceRecord(rfChannel,
"ObjectPush");
}
LeCroy Corporation 17
Chapter 5: CommentsFile-based Decoding User Manual
18LeCroy Corporation
File-based Decoding User ManualChapter 6: 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.
In addition to the operators, the followin
KeywordUsage
selectselect expression
setDefine a global variable
constDefine a constant
returnreturn statement
whilewhile statement
forfor statement
ifif statement
elseif-else statement
defaultselect expression
nullNull value
inInput context
outOutput context
g are keywords in CSL:
Table 6.1 Keywords
LeCroy Corporation 19
Loading...
+ 57 hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.