2403 Walsh Avenue, Santa Clara, CA 95051-1302 Tel: +1/408.727.6600 Fax: +1/408.727.6622 CATC™ Scripting Language Reference Manual for FireInspector™ Document Revision 1.
CATC SCRIPTING LANGUAGE 1.0 Reference Manual CATC Scripting Language Reference Manual for FireInspector, Document Revision 1.0 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. CATC reserves the right to revise the information presented in this document without notice or penalty.
CATC SCRIPTING LANGUAGE 1.0 FOR FIREINSPECTOR Reference Manual Table of Contents TABLE OF CONTENTS Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CATC SCRIPTING LANGUAGE 1.0 Reference Manual Table of Contents 8 Preprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 9 Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 10 Transaction and Packet Context Fields . . . . . . . . . . . . . . . . . . 29 Transaction Context Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 1394 Transactions . . . . . . . . . . . . . . . . . . . .
CATC SCRIPTING LANGUAGE 1.0 FOR FIREINSPECTOR Reference Manual Table of Contents EndCellBlock() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 GetBitOffset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 PeekNBits(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Pending(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 1 Reference Manual Introduction CHAPTER 1: INTRODUCTION CATC Scripting Language (CSL) was developed to create scripts that allow users to do file-based decoding with CATC analyzers. CSL is used to edit CATC Decode Scripting (CDS) files, which are pre-written decoder scripts supplied by CATC. These script-based decoders can be modified by the users or used as-is. Additionally, users can create brand new CDS files.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 2 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 2 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 2 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 2 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 3 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 3 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 4 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 4 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 4 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 4 Reference Manual Operators Operator Operand Symbol Description Types Result Types Examples Equality Operators 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 5 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 6 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 7 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 7 Reference Manual 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).
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 7 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 7 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 7 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 8 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 9 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 10 Reference Manual Transaction and Packet Context Fields CHAPTER 10: TRANSACTION AND PACKET CONTEXT FIELDS This chapter describes the transaction and packet context fields (symbols) that are defined in FireInspector. These fields define the output context for each built-in transaction or packet type. These output contexts are then used as input to script decoders.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 10 Reference Manual Transaction and Packet Context Fields Target_Node: Integer. The 1394 node ID of the target node. LF: Integer. The LF field of the encapsulation header. datagram_size: Integer. The datagram_size field of the encapsulation header. offset: Integer. The offset field of the encapsulation header. DGL: Integer. The DGL field of the encapsulation header. ether_type: The ether_type of the encapsulation header.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 10 Reference Manual • Transaction and Packet Context Fields Dest_Address IP Protocol Transactions These transactions require the module data InputType = "IP Protocol". Data: Raw bytes. The fully assembled buffer (includes protocol header). DataLength: Integer. Length of Data, in bytes. Payload: Raw bytes. Same as Data, but with the protocol header stripped off. PayloadLength: Integer. Length of Payload buffer, in bytes.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 10 Reference Manual • • Transaction and Packet Context Fields Length Checksum ICMP header fields The following fields are valid for ICMP headers. These are all integer values and come directly from RFC-792. • • • • • • • • • Type Code Checksum Pointer Ident Seq Originate_Timestamp Receive_Timestamp Transmit_Timestamp FCP Transactions: These transactions require the module data InputType = "FCP Transaction".
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 10 Reference Manual Transaction and Packet Context Fields Packet Context Fields A note about using packets as input to a script: When a file is loaded, FireInspector automatically decodes 1394 transactions but does not display them. A packet (or sub-transaction) is only allowed to be a member of one higher level transaction. This means that all of the packets that belong to 1394 transactions will not be handed to a script that takes packets as input.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 10 Reference Manual • Transaction and Packet Context Fields 0x16 -- ping Note: values >= 0x10 are phy packets. raw_data: Raw bytes. Raw unparsed packet header data. Payload: Raw bytes. Data payload of packet. This field will also contain a single quadlet in the case of quadlet format packets. This field will be null if packet contains no data. ack: Integer. Acknowlegement value (without the error-checking bits). This field will be null if one was not received.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 10 Reference Manual Transaction and Packet Context Fields Example The following example is taken from the file IPProtocol.dec, which is included with the FireInspector installation. if ( in.Payload == null ) return Reject(); if ( in.Version != 4 ) return Reject(); ... if ( out.Identification == null ) { out.Identification = in.Identification; } else { if ( out.Identification != in.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 11 Reference Manual Functions CHAPTER 11: 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 11 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 12 Reference Manual Primitives CHAPTER 12: 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 12 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 12 Reference Manual • 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 12 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 12 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 13 Reference Manual Decoder Primitives CHAPTER 13: 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 13 Reference Manual Parameter Decoder Primitives Meaning 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 13 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 13 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 13 Reference Manual Parameter Decoder Primitives Meaning 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 13 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 13 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 13 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 13 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 14 Reference Manual FireInspector-Specific Primitives CHAPTER 14: FIREINSPECTORSPECIFIC PRIMITIVES BitfieldInit() BitfieldInit(, ) Parameter Meaning bitfield_identifier string The name of the bitfield data structure Default Value Comments Used to refer to this bitfield data structure in subsequent calls to other primitives. title string Displays in the title bar of the dialog box. Return value None.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 14 Reference Manual FireInspector-Specific Primitives In the example, “Identifier” is the value of bitfield_identifier and “Label” is the value of bitfield_label. For a complete description of GetNBits, see “GetNBits()” on page 41. Example See “Example for FireInspector-Specific Primitives” on page 60. NextNBits -- Additional parameters NextNBits contains an additional, optional argument in FireInspector to add data to the BitfieldInit data structure: bitfield_label.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 14 Reference Manual FireInspector-Specific Primitives Comments BitfieldDialog brings up a dialog box in which the user can view the fields that were parsed for a particular protocol-dependent data structure. The primitive returns when the user hits the 'OK' button on the dialog box, which causes the box to close.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 14 Reference Manual FireInspector-Specific Primitives Example See “Example for FireInspector-Specific Primitives” on page 60.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 14 Reference Manual FireInspector-Specific Primitives The dialog box displays the data that is referred to by the bitfield identifier “more_stuff”.
CATC SCRIPTING LANGUAGE 1.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 15 Reference Manual Modules CHAPTER 15: 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 15 Reference Manual 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.
CATC SCRIPTING LANGUAGE 1.0 CHAPTER 15 Reference Manual Modules Icon Optional. File name of an icon to display on the toolbar. Must be a 19x19 pixel bitmap file. Example set Icon = "bitmap.
CATC SCRIPTING LANGUAGE 1.