LeCroy Analyzers File Based Decoding Manual
Contents
1. Operator Result Symbol Description Operand Types Types Examples Bitwise Logical Operators Bitwise Integer integer Integer 0b11111110 0b00000001 complement amp Bitwise AND Integer integer Integer 0b11111110 amp 0b01010101 0b01010100 Bitwise exclusive Integer integer Integer 0b11111110 0b01010101 0b10101011 OR Bitwise inclusive Integer integer Integer 0b11111110 0b01010101 0b11111111 OR Shift Operators lt lt Left shift Integer integer Integer 0b11111110 lt lt 3 0b11110000 gt gt Right shift Integer integer Integer 0b11111110 gt gt 1 0b01111111 Assignment Operators Assignment Any Any A l1 BSC S A Addition Integer integer Integer x 1 assignment Xx Fe 2 String string String a one a two one two Raw byte raw byte Raw z 001122 Zz 334455 001122334455 List list List xe Ll 2 x 3 4 1 2 3 4 Integer list List ye l y 2 3 1 2 3 Integer string String a number a 2 number 2 Note integer string concatenation uses decimal conversion String list List s one s two one two Subtraction Integer integer Integer y 3 assignment y L2 Multiplication Integer integer Integer x 3 assignment x 1 3 Division Integer integer Integer s 3 assignment s 1 3 Modulus Integer integer Integer y 3 assignment y 1 0 gt gt Right shift Integer integer Integer b 0b11111110 assignment b gt gt2. 67 Bet Modules eee RARE E URN RA bete ADG RS 67 LeCroy Corporation iii Table of Contents File based Decoding User Manual Module FunctionS Y Y FRY RY I YY 67 Module Data i e nau Se ae e E Ge a da eet 68 B 2 Input ContextData FFF ee 70 How to Contact LeCroy 71 Limited Hardware Warranty 71 What this Warranty Does Not Cover Y ug 72 Coverage During Warranty Period YY sess 72 How to Obtain Warranty Service YY uu 73 General ProvisionS FF RF FR Yu 74 Index 75 Iv LeCroy Corporation File based Decoding User Manual List of Figures LisT OF FIGURES Execution of a for Statement FF FF ug 23 Example Output for AddCell F FF GG ug 52 Example Output for AddDataCell FF ug 54 Example Separator Cell Y GG GG GG Gu 55 Example Output for BeginCellBlock with Red Group Collapsed 58 Example Output for BeginCellBlock with Red Group Expanded and Blue Group Gollapsed ius tue ie re ERE oed m s 58 Example Output for BeginCellBlock with Red Group Expanded and Blue Group Expanded ie see pne E a Ro A e c 58 LeCroy Corporation v List of Tables File based Decoding User Manual LIST OF TABLES Table 2 1 Examples of String Literals FFF eee 3 Table 2 2 Escape SegUenceS
3. FF tee eee 4 Table 4 1 Operator Precedence and Associativity V YV 10 Table 4 2 Operators oue aa decns ea FYD GBDd Face a Sy BD AA GY UNED ON AN Rig 11 Table 6 1 Keywords YY YL EL YL REF RY res 19 LeCroy Corporation File based Decoding User Manual Chapter 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 PE Tracer product 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 Scripts directory 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 Scripts directory CSL is based on C language syntax so anyone with a C programming background sh
4. three Raw byte raw byte Integer 001122 001122 List list Integer 15 2 31 9 IX 2 311 Note eguality operations on values of different types evaluates to false l Not equal Integer integer Integer 2 42 3 String string Integer three four Raw byte raw byte Integer 001122 334455 List list Integer 1 4 25 3T ke 12 411 Note equality operations on values of different types evaluates to false Relational Operators Less than Integer integer Integer 1 2 String string Integer abc def gt Greater than Integer integer Integer 2 gt 1 String string Integer xyz gt abc lt Less than or equal Integer integer Integer 23 27 String string Integer Cat dog gt Greater than or Integer integer Integer 2 325 equal String string Integer sun gt moon Note relational operations on string values are evaluated according to character order in the ASCII table Logical Operators Negation All combinations of types Integer b0 ee p peat uu ig 2 0 19 zT amp amp Logical AND All combinations of types Integer 1 amp 1 1 1 amp amp I 1 1 amp 0 0 1 amp amp cat 1 Logical OR All combinations of types Integer 1 1 1 0 O 0 Ti oc me qup Meat 20 Table 4 2 Operators Continued 12 LeCroy Corporation File based Decoding User Manual Chapter 4 Operators
5. 1 0b01111111 lt lt Left shift Integer integer Integer a 0b11111110 assignment a lt lt 3 0b11111110000 Table 4 2 Operators Continued LeCroy Corporation 13 Chapter 4 Operators File based Decoding User Manual Assignment Operators continued amp Bitwise AND Integer integer Integer a 0b11111110 assignment a amp 0b01010101 0b01010100 s Bitwise exclusive Integer integer Integer e 0b11111110 OR assignment e 0b01010101 0b10101011 Bitwise inclusive Integer integer Integer i 0b11111110 OR assignment i 0b01010101 0b11111111 List Operators sizeof Number of Any Integer sizeof 1 2 31 3 elements sizeof 0011223344 5 sizeof string 6 sizeof 12 1 sizeof 1 2 311 2 Note the last example demonstrates that the sizeof operator returns the shallow count of a complex list head Head List Any head 1 2 31 1 Note the Head of a list is the first item in the list tail Tail List List tail 1 2 31 2 3 Note the Tail of a list includes everything except the Head first Returns the first List Any list 1 2 31 element of the list for item first list and resets the list more list item next list iterator to the beginning of the list ProcessItem item next Returns the next List Any list 1 2 3 element of the list for item first list relative to the more list
6. 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 xX 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 ey 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 Trace SDPAddProfileServiceRecord returned result n LeCroy Corporation 17 Chapter 5 Comments File based Decoding User Manual 18 LeCroy Corporation File based Decoding User Manual Chapter 6 Keywords Chapter 6
7. item next list previous position of the list iterator ProcessItem item Table 4 2 Operators Continued 14 LeCroy Corporation File based Decoding User Manual Chapter 4 Operators more Returns a non zero List Integer list 1 2 3 value if the list for item first list iterator did not more list item next list reach the bounds of the list ProcessItem item last Returns the last List Any Tist s iy 2 23 element of the list for item last list and resets the more list item prev list position of the list iterator to the end ProcessItem item of the list prev Returns the List Any list 1 2 3 previous element in for item last list the list relative to more list item prev list the previous position of the list ProcessItem item iterator Table 4 2 Operators Continued LeCroy Corporation 15 Chapter 4 Operators File based Decoding User Manual 16 LeCroy Corporation File based Decoding User Manual Chapter 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 if and finish at the end of the line The
8. BeginCellBlock BeginCellBlock name string value string description string or null color integer or list additional info any Parameter Meaning Default Value Comments name string Displays in the name field of the cell value string Displays in the value field of the cell description string or Displays in tool tip null color integer or list If not specified Color can be specified as either a packed a default color color value in an integer or as an array of is used RGB values 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 The values are predefined constants and zero or more of them may be used at one time Possible values are BLOCKNAME x _ COLLAPSED _ERROR _ EXPANDED FIXEDWIDTH w _ HIDDEN _ MONOCOLOR _MONOFIELD _SHOWN default _ WARNING Support Supported by all LeCroy analyzers Return value None Comments Begins a cell block and adds a block header cell This is a special cell that can be collapsed and expanded The collapsed expanded state of this cell affects cells in the group according to their COLLAPSED EXPANDED attributes All calls to AddCe11 after a call to BeginCellBlock put the new cells into this group until a call to EndCellBlock is made Cell blocks can be nested 56 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives Exa
9. COURSE OF DEALING COURSE OF PERFORMANCE OR TRADE USAGE SOME JURISDICTIONS MAY NOT ALLOW LIMITATIONS ON HOW LONG AN IMPLIED WARRANTY LASTS SO THE PRECEDING LIMITATION MAY NOT APPLY TO YOU LECROY DOES NOT ACCEPT LIABILITY BEYOND THE REMEDIES SET FORTH IN THIS LIMITED WARRANTY STATEMENT OR FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES INCLUDING WITHOUT LIMITATION ANY LIABILITY FOR THIRD PARTY CLAIMS AGAINST YOU FOR DAMAGES PRODUCTS NOT BEING AVAILABLE FOR USE OR FOR LOST DATA OR SOFTWARE LECROY S LIABILITY TO YOU MAY NOT EXCEED THE AMOUNT YOU PAID FOR THE PRODUCT THAT IS THE SUBJECT OF A CLAIM SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES SO THE PRECEDING EXCLUSION OR LIMITATION MAY NOT APPLY TO YOU The limited warranty on a Product may be transferred for the remaining term if the then current owner transfers ownership of the Product and notifies LeCroy of the transfer You may notify LeCroy of the transfer by writing to Technical Support at LeCroy 3385 Scott Blvd Santa Clara CA 95054 USA or by email at support catc com Please include the transferring owner s name and address the name and address of the new owner the date of transfer and the Product serial number 74 LeCroy Corporation File based Decoding User Manual Index Index C CATC Technical Support 71 E Email CATC Support 71 F Fax number 71 S Servicemarks ii Support CATC 71 T Technical
10. LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives Format Conversion Characters These are the format conversion characters used in CSL Code Type Output Integer Character Integer Signed decimal integer Integer Signed decimal integer Integer Unsigned octal integer Integer Unsigned decimal integer Integer Unsigned hexadecimal integer using abcdef Integer Unsigned hexadecimal integer using ABCDEF String String A conversion specification begins with a percent sign 96 and ends with a conversion character The following optional items can be included in order between the 96 and the conversion character to further control argument formatting Flag characters are used to further specify the formatting There are five flag char acters e A minus sign causes an argument to be left aligned in its field Without the minus sign the default position of the argument is right aligned A plus sign inserts a plus sign before a positive signed integer This only works with the conversion characters d and i A space inserts 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 is ignored A hash mark prepends a 0 to an octal number when used with the conversion character o If is used with x or x it prepends 0x or ox to a hexadecimal number A zero 0 pads the
11. TLP MSGROUTE FROMROOTCOMPLEX TLP MSGROUTE LOCALTERMRECEIVER TLP MSGROUTE GATHERTOROOTCOMPLEX TLP MSGROUTE_RESERVED1TERMRECEIVER TLP MSGROUTE RESERVED2TERMRECEIVER in AddressLo Address 31 00 if MessageRouting is _TLP_MSGROUTE_BYADDRESS in AddressHi Address 63 32 if MessageRouting is _TLP_MSGROUTE_BYADDRESS in DevicelD Device ID if MessageRouting is TLP MSGROUTE BYID in TC TC Traffic Class field of TLP header in Tag Tag field of TLP header in ReguesterlD ReguesterlD field of TLP header in Attr Attr field of TLP header in Length Length field of TLP header in TD TD Transport Digest field of TLP header in EP EP End to end Poisoning field of TLP header Output Data Fields out Decoded Amount of data in bytes that has been decoded LeCroy Corporation File based Decoding User Manual Appendix B Bluetooth The information in this appendix is specific to the Bluetooth analyzer B 1 Modules Modules are collections 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 ProcessData Called repeatedly with input contexts r
12. decimal points Hexadecimal octal decimal and binary notation are supported Hexadecimal numbers must be preceded by 0x 0x2A 0x54 0xFFFFFFOL 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 no characters and evaluates to false in an expression whereas a non empty string evaluates to true Double quotes surround a string and some standard backslash 1 escape sequences are supported String Represented Text Quote This is a string Quote This is a string literal literal 256 256 Note that this does not represent the integer 256 but only the characters that make up the number abcd amp amp abcd amp June 26 2001 June 26 2001 Wd 2y SM 1 2 3 Table 2 1 Examples of String Literals LeCroy Corporation 3 Chapter 2 Values File based Decoding User Manual Escape Seguences These are the available escape seguences in CSL Escape Character Sequence Example Output backslash This is a backslash This is a backslash double AN N Quotes N n Quotes quote horizontal t Before tab tAfter tab Before tab After tab tab newline n This is how nto get a n
13. example if 3 amp amp 3 Trace True causes the program to evaluate whether the expression 3 amp amp 3 is nonzero or True It is so the expression evaluates to True and the Trace statement is executed On the other hand the expression 3 amp amp 0 is not nonzero so it would evaluate to False and the statement wouldn t be executed 7 3 if else Statements The form for an if else statement is if lt expression gt lt statementl gt else lt statement2 gt The following code if 3 3 2 2 Trace Yes else Trace No causes No to be printed because 3 3 2 2 evaluates to False neither 3 3nor2 2 is nonzero LeCroy Corporation 21 Chapter 7 Statements File based Decoding User Manual 7 4 while Statements A while statement is written as while lt expression gt lt statement gt An example of this is Xi A while x lt 5 Trace x y y X op The result of this would be 2r A Ae 22 LeCroy Corporation File based Decoding User Manual Chapter 7 Statements 7 5 or Statements A or statement takes the form for expressionl lt expression2 gt lt expression3 gt statement The first expression initializes or sets the starting value for x It is executed one time before the loop begins The second expression is a conditional expression It determines whether the loop continues If it evaluates true the function keeps executi
14. function Trace causes the function HiThere to be executed HiThere returns the string Hi there as its value This value is passed to the calling environment Trace resulting in this output return Hi there Hi there A return statement also causes a function to stop executing Any statements that come after the return statement are ignored because return transfers control of the program back to the calling environment As a result Trace HiThere HiThere a Hi there return a b Goodbye return b outputs 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 outputs Goodbye 24 LeCroy Corporation File based Decoding User Manual Chapter 7 Statements because the i statement evaluates to false This causes the first return statement to be skipped The function continues executing with the e1se statement thereby returning the value of b to be used as an argument to Trace 7 7 Compound Statements A compound statement or statement block is a group of one or more statements that is treated as a single statement A compound statement is always enclosed in curly braces Each statement within the curly braces is followed by a semicolon however a
15. 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 gt 2 which indicates that x is greater than 2 This is a Boolean expression so it evaluates to either true or false Therefore if x 3 then x gt 2 evaluates to true ifx 1 it returns 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 nu11 is considered false However all Boolean operators result in integer values LeCroy Corporation Chapter 3 Expressions File 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 select expression select lt expressionl gt lt statementl gt lt expression2 gt lt statement2 gt 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 lt 5 Less than 5 x gt 5 Greater than or equal to 5 13 The above expression evaluates to Greater than or equal to 5 because the first true expression is x gt 5 Note that a sem
16. operations are listed in the Operand Types column of Table 4 2 on page 11 Any binary operation on a null and a non null value results in the non null value For example if x null then 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 11 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 49 5 causes the addition to be performed before the multiplication resulting in a value of 65 LeCroy Corporation Chapter 4 Operators File based Decoding User Manual When operators of egual precedence occur in an expression the operands are evaluated according to the associativity of the operators This means tha
17. path information is provided include file inc the application tries to load the file from the current directory If there is no such file in the current directory the application tries to load the file from the Scripts Shared directory Files that are in a directory one level up from the current file can be referenced using AMfile inc andlikewise files one level down can be referenced using the relative pathname directory file inc Last but not least files can also be referred to using a full pathname such as c global_scripts include file inc LeCroy Corporation 27 Chapter 8 Preprocessing File based Decoding User Manual 28 LeCroy Corporation File based Decoding User Manual Chapter 9 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 is invoked on separately A context serves two roles It functions as a symbol table whose values are local to a particular transaction and it functions as an interface to the application Two keywords are used to reference symbols in the context in and out Dot notation is used to specify a symbol within a context out symbol abcd out type in type The output context can be read and written to but the input context can only be read Context symbols follow
18. 0 Master in AmAddr Am address in Cid L2CAP CID value RFCOMM in Data RFCOMM data block in DataLength Length of data block in Slave 1 Slave 0 Master in AmAddr Am address in Dlci RFCOMM dlci value HDLC and PPP in Data HDLC data block in DataLength Length of data block in Protocol PPP protocol value in Slave 1 Slave 0 Master in AmAddr Am address 70 LeCroy Corporation File based Decoding User Manual How to Contact LeCroy How to Contact LeCroy Type of Service Contact Call for technical US and Canada 1 800 909 2282 support Worldwide 1 408 727 6600 Fax your guestions Worldwide 1 408 727 6622 Write a letter LeCroy Protocol Solutions Group Customer Support 3385 Scott Blvd Santa Clara CA 95054 USA Send e mail support CATC com Visit LeCroy s web site http www lecroy com Limited Hardware Warranty So long as you or your authorized representative you or your fully complete and return the registration card provided with the applicable hardware product or peripheral hardware products each a Product within fifteen days of the date of receipt from LeCroy or one of its authorized representatives LeCroy warrants that the Product will be free from defects in materials and workmanship for a period of three years the Warranty Period You may also complete your registration form via the internet by visiting http www lecroy com r
19. 0BB22 _ 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 Normal MonoColor Error Warning ixed Width 20 NWN MonoField aa T Value1 Value Walue4 valueb Figure 1 Example Output for Addce11 52 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives AddDataCell AddDataCell data value raw list or integer gt lt additional_info any gt Default Parameter Meaning Value Comments data_value raw list or Interpreted the same way as GetNBits integer interprets data_source additional_info any Used to create special cells or to modify cell attributes Possible values are _BYTES _ COLLAPSED _ DWORDS _ EXPANDED _ HIDDEN _SHOWN default Support Supported by all LeCroy analyzers Return value None Comments Creates an expandable collapsible cell for viewing raw data such as data payloads Data can be raw bytes an integer or a list If an integer is used it is interpreted as 4 bytes of data Specifying BYTES or DWORDS in an additional info field forces data to be interpreted as bytes or guadlets COLLAPSED EXPANDED HIDDEN and SHOWN are all interpreted the same is in a regular AddCe11 call Examp
20. ID CFGRD 0 TLP TYPE ID CFGRD 1 TLP TYPE ID CFGWR 0 TLP TYPE ID CFGWR 1 in FirstByteEnabled Index of first enabled byte in data block in EnabledByteCount Number of enabled bytes in data block in DevicelD Device ID in Register Configuration space address in TC TC Traffic Class field of TLP header in Tag Tag field of TLP header in ReguesterlD ReguesterlD field of TLP header in Attr Attr field of TLP header in Length Length field of TLP header in TD TD Transport Digest field of TLP header in EP EP End to end Poisoning field of TLP header Output Data Fields out Decoded Amount of data in bytes that has been decoded LeCroy Corporation File based Decoding User Manual io dec Description io dec is an IO data script decoder Input Data Fields in Data Data block to decode in DataLength Length of data block in bytes in PrepareFldsForDlg If not 0 means that script should prepare decoded fields for presenting them in a special dialog in Type Request type TLP TYPE ID IORD TLP TYPE ID IOWR in FirstByteEnabled Index of first enabled byte in data block in EnabledByteCount Number of enabled bytes in data block in Address Address in TC TC Traffic class field of TLP header in Tag Tag field of TLP header in ReguesterlD ReguesterlD field of TLP header in Attr Attr field of TLP header in Length Length field of TLP header in TD TD Transport Digest fie
21. 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 following are keywords in CSL Keyword Usage select select expression set Define a global variable const Define a constant return return statement while while statement for for statement if if statement else if else statement default select expression null Null value in Input context out Output context Table 6 1 Keywords LeCroy Corporation 19 Chapter 6 Keywords File based Decoding User Manual 20 LeCroy Corporation File based Decoding User Manual Chapter 7 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 if else statements while statements for statements return statements and compound statements 7 1 Expression Statements An expression statement describes a value variable or function lt expression gt Here are some examples of the different kinds of expression statements Value x 3 Variable x 3 Function Trace x 3 The variable expression statement is also called an assignment statement because it assigns a value to a variable T 2 if Statements An if statement follows the form if lt expression gt lt statement gt For
22. LeCroy PROTOCOL SOLUTIONS GROUP 3385 SCOTT BLVD SANTA CLARA CA 95054 CATC Protocol Analyzers File Based Decoding User Manual For Software Version 1 2 June 2006 Document Disclaimer File 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 ll USBTracer USB Mobile USB Mobile HS 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 Copyright Copyright 2006 LeCroy All Rights Reserved This document may be printed and reproduced without additional permission but all copies should contain this copyright notice LeCroy Corporation File based Decoding User Manual Table of Contents TABLE OF CONTENTS Chapter1 Introduction 1 1 1 Features of CATC Scripting Language a 1 Chapter2 Values 3 2 1 Eit ralS Ae ud bos ed est bm oe doe Ie Pe Aeg 3 2 2WNaiables kn RR RR RR bo EA bbe ee chad AE T EE 5 2 9 ConstantS ee eu Se tose nis Y dod A
23. Products it repairs LeCroy may use new and or reconditioned parts at its sole discretion made by various manufacturers in performing warranty repairs If LeCroy repairs or replaces a Product the Warranty Period for the Product is not extended If LeCroy evaluates and determines there is no trouble found in any Product returned or that the returned Product is not eligible for warranty coverage LeCroy will inform you of its determination If you thereafter request LeCroy to repair the Product such labor and service shall be performed under the terms and conditions of LeCroy s then current repair policy If you chose not to have the Product repaired by LeCroy you agree to pay LeCroy for the cost to return the Product to you and that LeCroy may require payment in advance of shipment LeCroy Corporation 73 Limited Hardware Warranty File based Decoding User Manual General Provisions THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS YOU MAY HAVE ADDITIONAL RIGHTS THAT VARY BY JURISDICTION LECROY S RESPONSIBILITY FOR DEFECTS IN MATERIALS AND WORKMANSHIP IS LIMITED TO REPAIR AND REPLACEMENT AS SET FORTH IN THIS LIMITED WARRANTY STATEMENT EXCEPT AS EXPRESSLY STATED IN THIS WARRANTY STATEMENT LECROY DISCLAIMS ALL EXPRESS AND IMPLIED WARRANTIES FOR ANY PRODUCT INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF AND CONDITIONS OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AND ANY WARRANTIES THAT MAY ARISE FROM ANY
24. RE Ae Ad a 6 Chapter 3 Expressions 7 3 1 select expression IIYF FY Y Y 8 Chapter4 Operators 9 A 1 Operations sich doas dd Rene Tees erede P deed n 9 4 2 Operator Precedence and Associativity 9 Chapter 5 Comments 17 Chapter 6 Keywords 19 Chapter 7 Statements 21 7 1 Expression Statements YY Y Yg 21 72ifStatements YYY Y FF Y Yg 21 7 3 if else Statements IFF Fu Yg 21 7 4 while Statements Y FY eee 22 T 5ifor Statements 4 223 rara o a TUD WA BA Od 23 7 6 return Statements8 YY YY Yg 24 7 7 Compound Statements YF eee 25 Chapter8 Preprocessing 27 Chapter9 Context 29 Chapter 10 Functions 31 Chapter 11 Primitives 33 11 1 General Primitives Y YF FF YY Y ua 33 11 2 Data Manipulation Primitives YY Yg 40 11 3 List Manipulation Primitives YF YY a 44 11 4 Transaction Decoder Primitives 46 11 5 Display Primitives llle 51 Appendix A PCI Express 61 A Modules eu a A duy e debe YUA Een e UU 61 Module FUNCION uoa cola eser ther ed GANN gs land Ge RD a RS 61 A 2 Decoder Script Files Y FFY Y Y ua 61 eig deca io eL st O A TRA MA DY Ma ds 62 IO dGC iia Yd oun GA DRYW e DU edere e dydd ob Re S 63 MEM COC us doceat bwn pe c Erde Fac it boe BA RG a odd YR 64 Appendix B Bluetooth
25. Support 71 Trademarks ii W Website CATC 71 LeCroy Corporation 75 Index File based Decoding User Manual 76 LeCroy Corporation
26. alues 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 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 Support Supported by all LeCroy analyzers Return value None Comments Adds a display cell to the current output context Cells are displayed in the order that they are added The name and value strings are displayed directly in the cell LeCroy Corporation 51 Chapter 11 Primitives File based Decoding User Manual Example Create a regular cell named Normal with a value Cell and tool tip Normal cell AddCell Normal Valuel Normal cell 8 Use the MONOCOLOR value in the additional info parameter to create a cell with a color value of 0x881122 in both the name and value fields AddCell MonoColor Value2 MonoColor cell 0x881122 _MONOCOLOR Use the MONOFIELD value to create a cell with only a name field AddCell MonoField Value3 MonoField cell 255 200 200 _MONOFIELD Use the _ERROR value to create a cell with a red value field AddCell Error Value4 Error cell 0Oxcc1155 ERROR Use the WARNING value to create a cell with a yellow value field AddCell Warning Value5 Warning cell 0x0
27. ch 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 Format can only handle one value at a time so Format d d 20 30 would not work properly Furthermore types that do not match what is specified in the format string yields unpredictable results 34 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives Format Conversion Characters These are the format conversion characters used in CSL Code Type Output Integer Character Integer Signed decimal integer Integer Signed decimal integer Integer Unsigned octal integer Integer Unsigned decimal integer Integer Unsigned hexadecimal integer using abcdef Integer Unsigned hexadecimal integer using ABCDEF String String A conversion specification begins with a percent sign 96 and ends with a conversion character The following optional items can be included in order between the 96 and the conversion character to further control argument formatting Flag characters are used to further specify the formatting There are five flag char acters e A minus sign causes an argument to be left aligned in its field Without the minus sign the default position of the argument is right aligned A plus sign inserts a plus sign befo
28. e defined in a module which are gueried 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 is valid EXAMPLE set ModuleType Transaction Decoder Note The following applies to transaction decoding When a script is first invoked it is given an input context that corresponds to a packet or transaction that is a candidate for being a part of a larger transaction The output context is initially empty It is the script s job to examine the input context and decide if it qualifies for membership in the type of transaction that the script was designed to decode If it qualifies the appropriate values are decoded and put in the output context symbol table and if the transaction is complete it is done If the transaction is not complete the script indicates this to the application based on its return value and is invoked again with the same output context but a new input context The script then must decide if this new input context is a member of the transaction and keep doing this until the transaction is complete In order to accomplish all this state information should be placed in the output context It should be possible to use the output context of one transaction as an input context to another transaction OutputType Required A string label describing the output of the script Example AVC Transaction EXAMPLE
29. e same as the input format GetNBits also sets up the bit data source and global bit offset used by NextNBits and PeekNBits Note that bits are indexed starting at bit O Example raw FOFO 1111000011110000 binary result GetNBits raw 2 4 Trace result result The output would be 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 OxC LeCroy Corporation 41 Chapter 11 Primitives File based Decoding User Manual NextNBits NextNBits lt bit count integer gt Default Parameter Meaning Value Comments bit_count integer Support Supported by all LeCroy analyzers Return value None Comments Reads bit count bits from the data source specified in the last call to GetNBits starting after the last bit that the previous call to GetNBits or NextNBits returned If called without a previous call to GetNBits the result is undefined Note that bits are indexed starting at bit 0 Example raw FOFO 1111000011110000 binary resultl GetNBits raw 2 4 result2 NextNBits 5 result3 NextNBits 2 Trace resultl resulti result2 result2 result3 result3 This generates this trace output resultl C result2 7 result3 2 In the call to GetNBits starting at bit 2 reads 4 bits 1100 and returns the value OxC In the first call to NextNBi
30. ed 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 This function creates a local variable Parameter and a local variable Local which has an assigned value of 20 Local 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 LeCroy Corporation File based Decoding User Manual Chapter 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
31. egisterscope The Warranty Period commences on the earlier of the date of delivery by LeCroy of a Product to a common carrier for shipment to you or to LeCroy s authorized representative from whom you purchase the Product LeCroy Corporation 71 Limited Hardware Warranty File based Decoding User Manual What this Warranty Does Not Cover Coverage During Warranty Period This warranty does not cover damage due to external causes including accident damage during shipment after delivery to a common carrier by LeCroy abuse misuse problems with electrical power including power surges and outages servicing not authorized by LeCroy usage or operation not in accordance with Product instructions failure to perform reguired preventive maintenance software related problems whether or not provided by LeCroy problems caused by use of accessories parts or components not supplied by LeCroy Products that have been modified or altered by someone other than LeCroy Products with missing or altered service tags or serial numbers and Products for which LeCroy has not received payment in full During the Warranty Period LeCroy or its authorized representatives will repair or replace Products at LeCroy s sole discretion covered under this limited warranty that are returned directly to LeCroy s facility or through LeCroy s authorized representatives 72 LeCroy Corporation File based Decoding User Manual Limited Hardware Warrant
32. epresenting transactions of the specified input types Decides if input transaction is a member of this transaction or if it begins a new transaction This function is called first using incomplete output transactions If the input transaction is not accepted into any of the pending transactions it is called with an empty output transaction to see if it starts a new transaction CollectData Called with each input transaction that was previously accepted by the function ProcessData Generates all output context data that would be reguired for input into a higher level transaction BuildCellList Called with the output context generated by the call to CollectData and no input context This function is responsible for adding display cells based on the data collected by CollectData Note that there is some flexibility in the use of these functions For example if it is easier for a particular protocol to build cells in Co11ectData cells could be generated there and BuildCellList could be left empty Another approach would be to have ProcessData do everything generate output data and build cell lists and then implement CollectData as a pass thru to ProcessData This is less efficient in the decoding phase but may reduce some repetition of code These decisions are dependent on the protocol to be decoded LeCroy Corporation 67 File based Decoding User Manual Module Data There are several standard global variables that should b
33. escription msg dec is a message data script decoder Input Data Fields in Data Data block to decode in DataLength Length of data block in bytes in PrepareFldsForDlg If not 0 means that script should prepare decoded fields for presenting them in a special dialog in Type Request type TLP TYPE ID IORD TLP TYPE ID IOWR in FirstByteEnabled Index of first enabled byte in data block in EnabledByteCount Number of enabled bytes in data block in MessageCode Message code TLP MSGCODE ASSERT INTA TLP MSGCODE ASSERT INTB TLP MSGCODE ASSERT INTC TLP MSGCODE ASSERT INTD TLP MSGCODE DEASSERT INTA _ TLP MSGCODE DEASSERT INTB TLP MSGCODE DEASSERT INTC TLP MSGCODE DEASSERT INTD TLP MSGCODE PM ACTIVESTATENAK TLP MSGCODE PM PME TLP MSGCODE PM TURNOFF TLP MSGCODE PM TOACK TLP MSGCODE ERR COR TLP MSGCODE ERR NONFATAL TLP MSGCODE ERR FATAL TLP MSGCODE UNLOCK TLP MSGCODE SLOTPOWERLIMIT TLP MSGCODE VENDORO TLP MSGCODE VENDOR1 _ TLP MSGCODE HP ATTN IND ON TLP MSGCODE HP ATTN IND BLINK TLP MSGCODE HP ATTN IND OFF LeCroy Corporation 65 File based Decoding User Manual TLP MSGCODE HP POWER IND ON e TLP MSGCODE HP POWER IND BLINK TLP MSGCODE HP POWER IND OFF TLP MSGCODE HP ATTN BTN PRESSED in MessageRouting Message routing TLP MSGROUTE TOROOTCOMPLEX e TLP MSGROUTE BYADDRESS TLP MSGROUTE BYID
34. ewline This is how to get a newline single quote y A Single quote V Single guote Table 2 2 Escape Seguences 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 1 2 3 4 one 2 three 4 5 61111 Raw Bytes Raw binary values are used primarily for efficient access to packet payloads A literal notation is supported using single guotes 00112233445566778899AABBCCDDEEFF This represents an array of 16 bytes with values starting at 00 and ranging up to 0xFF The values can only be hexadecimal digits Each digit represents a nybble four bits and 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 OFFF null null indicates an absence of valid data The keyword nu11 represents a literal null value and evaluates to false when used in expressions result null LeCroy Corporation File based Decoding User Manual Chapter 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 mu
35. field with zeros instead of with spaces Field width specification is a positive integer that defines the field width in spaces of the converted argument If the number of characters in the argument is smaller than the field width then the field is padded with spaces If the argument has more characters than the field width has spaces then the field expands to accommodate the argument LeCroy Corporation 37 Chapter 11 Primitives File based Decoding User Manual Resolve Resolve lt symbol name string gt Default Parameter Meaning Value Comments symbol_name string Support Supported by all LeCroy analyzers 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 Example a Resolve symbol is equivalent to a symbol 38 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives Trace Trace lt argl any gt lt arg2 any gt Default Parameter Meaning Value Comments arg any Number of arguments is variable Return value None Comments The values given to this function are given to the debug console Example list cat dog cow Trace List list n would result in t
36. hapter 11 Primitives File based Decoding User Manual 11 3 List Manipulation Primitives RemoveAt RemoveAt lt list object list index integer gt Default Parameter Meaning Value Comments list_object list index integer Support Supported by all LeCroy analyzers Return value Removed element if the specified index is less than or equal to the list upper bound otherwise null value is returned Comments This function removes an element in a list at a given index Example list 0 1 2 3 list 4 list 5 SetAt list 8 15 OxAA now list 0 1 2 3 4 5 OxAA OxAA 15 removed Item RemoveAt list 6 removed Item RemoveAt list 6 now list 0 1 2 3 4 55 5 removed Item OxAA 44 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives SetAt RemoveAt lt list object list index integer gt Default Parameter Meaning Value Comments list_object list index integer Support Supported by all LeCroy analyzers Return value None Comments This function sets up an element in a list at a given index and fills up the list with new elements Example list 0 1 2 3 list 4 list 5 SetAt list 8 15 OxAA now list 0 1 2 3 4 5 OxAA OxAA 15 last e ON 2 3 I SetAt list 6 15 now list 0 1 2 3 null null 15 LeCroy Corporation 45 Chapter 11 Pr
37. he output List cat dog cow LeCroy Corporation 39 Chapter 11 Primitives File based Decoding User Manual 11 2 Data Manipulation Primitives GetBitOffset GetBitOffset Default Parameter Meaning Value N A Comments Support Supported by all LeCroy analyzers Return value None Comments Returns the current bit offset that is used in NextNBits or PeekNBits Example raw FOFO 1111000011110000 binary resultl GetNBits raw 2 4 result2 PeekNBits 5 result3 NextNBits 2 Trace Offset GetBitOffset The example generates this Trace output Offset D 40 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives GetNBits GetNBits lt bit source list or raw gt lt bit offset integer gt lt bit_ count integer gt Default Parameter Meaning Value Comments bit_source list raw Can be an integer value 4 bytes or a list of or integer integers that are interpreted as bytes bit_offset integer Index of bit to start reading from bit_count integer Number of bits to read Support Supported by all LeCroy analyzers Return value None Comments Reads bit count bits from bit source starting at bit offset Returns null if bit offset bit count exceeds the number of bits in b t source l bit_count is 32 or less the result is returned as an integer Otherwise the result is returned in a list format that is th
38. icolon 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 An example of its use is Astring select A zz 1 one A 2 two A 3 three A gt 3 overflow default null s If none of the first four expressions evaluates to true then default is evaluated returning a value of nu11 for the entire expression select expressions can also be used to conditionally execute statements similar to C switch statements select A 1 DoSomething A DoSomethingElse default DoNothing i In this case the appropriate function is called depending on the value of A but the evaluated result of the select expression is ignored 8 LeCroy Corporation File based Decoding User Manual Chapter 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
39. imitives File based Decoding User Manual 11 4 Transaction Decoder Primitives Abort Abort Default Parameter Meaning Value Comments N A Support Supported by Bluetooth and Firewire analyzers only 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 The input transaction is not consumed by this action and goes on to be considered for other pending transactions Example if IsReset return Abort 46 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives AddEvent AddEvent Group string Value string Default Parameter Meaning Value Comments Group string Name of the group Corresponds to the name of a field that might be encountered while decoding Value string Value associated Corresponds to a field value that might be with the group encountered while parsing Support Supported by Bluetooth and Firewire analyzers only Return value None Comments Events are used for transaction searching and for transaction summary This function is only effective when called during the ProcessData phase of decoding Event groups and values are stored globally for transaction
40. ld of TLP header in EP EP End to end Poisoning field of TLP header Output Data Fields out Decoded Amount of data in bytes that has been decoded set OutputType IO remove __ to use the script LeCroy Corporation 63 File based Decoding User Manual mem dec Description mem dec is a memory data script decoder Input Data Fields in Data Data block to decode in DataLength Length of data block in bytes in PrepareFldsForDlg If not 0 means that script should prepare decoded fields for presenting them in a special dialog in Type Request type TLP TYPE ID MRD32 TLP TYPE ID MRDLK32 TLP TYPE ID MWR32 TLP TYPE ID MRD64 TLP TYPE ID MRDLK64 TLP TYPE ID MWR64 in FirstByteEnabled Index of first enabled byte in data block in EnabledByteCount Number of enabled bytes in data block in AddressLo Address 31 0 in AddressHi Address 63 32 only for TLP TYPE ID MRD64 TLP TYPE ID MRDLK64 TLP TYPE ID MWR64 in TC TC Traffic Class field of TLP header in Tag Tag field of TLP header in ReguesterlD ReguesterlD field of TLP header in Attr Attr field of TLP header in Length Length field of TLP header in TD TD Transport Digest field of TLP header in EP EP End to end Poisoning field of TLP header Output Data Fields out Decoded Amount of data in bytes that has been decoded 64 LeCroy Corporation File based Decoding User Manual msg dec D
41. le 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 AddDataCell 0x11223344 BYTES LeCroy Corporation 53 Chapter 11 Primitives File based Decoding User Manual The output of the example is F Data i Data 01234567 89ABCDEF 11 22 33 44 Data Data 2 guadlets Figure 2 Example Output for AddDataCell 54 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives AddSeparator AddSeparator lt additional info any gt Default Parameter Meaning Value Comments additional_info any Used to create special cells or to modify cell attributes The values are predefined constants Possible values are _ COLLAPSED _ EXPANDED _ HIDDEN _SHOWN default Support Supported by all LeCroy analyzers Return value None Comments Creates a separator cell COLLAPSED EXPANDED HIDDEN and SHOWN are all interpreted the same is in a regular AddCe11 call Example AddCell Stuff Things AddSeparator adds a space between the previous and subsequent cells AddSeparator AddCell More stuff More things The output of the example is gt Stuff Separator cell Figure 3 Example Separator Cell LeCroy Corporation 55 Chapter 11 Primitives File based Decoding User Manual
42. levels and new ones are created as they are encountered Each transaction contains information as to which events were associated with it Example AddEvent DataLength Format d out DataLength LeCroy Corporation 47 Chapter 11 Primitives File based Decoding User Manual Complete Complete Default Parameter Meaning Value Comments Support Supported by Bluetooth and Firewire analyzers only 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 and that the transaction is complete The return value of this function should be passed back to the application from the ProcessData function This function could be used to associate the input context with the output context Example if done return Complete 48 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives Pending Pending Default Parameter Meaning Value Comments Support Supported by Bluetooth and Firewire analyzers only 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 reguires further input to be complete This function could be used to associate input contexts with the
43. mple f Begin the red group For clarity these cells are red BeginCellBlock Red Group null null 0x0000ff MONOFIELD iz This cell is displayed when the red group is in the expanded state AddCell Red is Expanded null 0x0000ff _EXPANDED This cell is displayed when the red group is collapsed AddCell Red is Collapsed null 0x0000ff COLLAPSED This begins the nested blue group Nothing in the blue group is displayed unless the red group is expanded BeginCellBlock Blue Group null null 0xff0000 MONOFIELD _EXPANDED BLOCKNAME BlockName This cell is only displayed when the blue group is visible and expanded AddCell Blue is Expanded null 0xff0000 EXPANDED This cell is also only displayed when the blue group is visible and expanded AddCell Blue Too null 0xff0000 EXPANDED This cell is only displayed when the blue group is visible and collapsed AddCell Blue is Collapsed null 0xff0000 COLLAPSED This ends the blue group EndCellBlock Cells with the SHOWN attribute are always displayed This is the default AddCell Always Shown null 0x0000ff SHOWN This cell is never displayed In a real script this would be driven by a variable AddCell Never Shown null 0x0000ff HIDDEN This ends the red group EndCellBlock LeCroy Corporation 57 Chapter 11 Primitives File based Decoding User Ma
44. ng and proceeds to the statement If it evaluates false the loop ends The third expression is executed after every iteration of the statement 79 False 9 End seres epessere tue Cotton Ls Figure 1 Execution of a for Statement The example for x22 x lt 5 x x 1 Trace x in 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 resultingin 2 lt 5 This evaluates to true so the statement Trace x An 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 Now x 5 is executed again and is again true so the Trace statement is executed causing 3 and a new line to print The third expression increases the value of x to 4 4 lt 5istrue so 4 and a new line are printed by the Trace statement Next the value of x increases to5 5 lt 5 is not true so the loop ends LeCroy Corporation 23 Chapter 7 Statements File based Decoding User Manual 7 6 return Statements Every function returns a value which is usually designated in a return statement A return statement returns the value of an expression to the calling environment It uses the following form return lt expression gt An example of a return statement and its calling environment is Trace HiThere HiThere The call to the primitive
45. nual The output of the example is eds Always Red Gro DECORE TD Figure 4 Example Output for BegincellBlock with Red Group Collapsed ed is Blueis Always Red Gro Up es Blue G roup Collapsed Figure 5 Example Output for BeginCellBlock with Red Group Expanded and Blue Group Collapsed edis Blueis Blue Always Red Group Ex Blue Group Expanded Figure 6 Example Output for BeginCellBlock with Red Group Expanded and Blue Group Expanded 58 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives EndCellBlock EndCellBlock Default Parameter Meaning Value Comments Support Supported by all LeCroy analyzers Return value None Comments Ends a cell block that was started with BeginCellBlock Example SeeBeginCellBlock SeeBeginCellBlock LeCroy Corporation 59 Chapter 11 Primitives File based Decoding User Manual 60 LeCroy Corporation File based Decoding User Manual Appendix A PCI Express A 1 Modu The information in this appendix is specific to the PE Tracer analyzer It is divided into two parts e Modules Decoder Script Files les Modules are a collection of functions and data dedicated to decoding a certain type of transaction Each module consists of one primary file dec and possibly several included files inc Module Function A module function is used as an en
46. ould 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 1 1 Features of CATC Scripting Language e 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 Chapter 1 Introduction File based Decoding User Manual 2 LeCroy Corporation File based Decoding User Manual Chapter 2 Values Chapter 2 Values There are five value types that may be manipulated by a script integers strings lists raw bytes and nu11 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 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
47. output context The return value of this function should be returned to the application in the ProcessData function Example if done return Complete else return Pending LeCroy Corporation 49 Chapter 11 Primitives File based Decoding User Manual Reject Reject Default Parameter Meaning Value Comments Support Supported by Bluetooth and Firewire analyzers only Return value An integer that should be passed back to the application unchanged Comments Called when it is decided that the input context does not meet the criteria for being a part of the current transaction The output context should not be modified before this decision is made The return value of this function should be returned by the ProcessData function Example if UnknownValue return Reject 50 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives 11 5 Display Primitives AddCell AddCell lt name string gt lt value string gt lt description string or null gt lt color integer or list gt additional info any Parameter Meaning Default Value Comments name string Displays in the name field of the cell value string Displays in the value field of the cell description string or Displays in tool tip null color integer or list If not specified Color can be specified as either a packed a default color color value in an integer or as an array of is used RGB v
48. re a positive signed integer This only works with the conversion characters d and i A space inserts 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 is ignored A hash mark prepends a 0 to an octal number when used with the conversion character o If is used with x or x it prepends 0x or ox to a hexadecimal number A zero 0 pads the field with zeros instead of with spaces Field width specification is a positive integer that defines the field width in spaces of the converted argument If the number of characters in the argument is smaller than the field width then the field is padded with spaces If the argument has more characters than the field width has spaces then the field expands to accommodate the argument LeCroy Corporation 35 Chapter 11 Primitives File based Decoding User Manual FormatEx FormatEx format string string arg list list gt Default Parameter Meaning Value Comments format string string arg list list Used as the list of parameters in the function call Support Supported by all LeCroy analyzers Return value Formatted string Comments FormatEx Writes data to a string Example str String i 12 hex i OxAABBCCDD formatted str FormatEx s formatted str String 12 sd Ox 08X str i hex i OxAABBCCDD 36
49. semicolon is not used following the closing curly brace The syntax for a compound statement is first statement second statement last statement An example of a compound statement is Xm 2 X 3 It s also possible to nest compound statements like so Compound statements can be used anywhere that any other kind of statement can be used if 3 amp amp 3 result True Trace result Compound statements are reguired for function declarations and are commonly used in if if else while and for statements LeCroy Corporation 25 Chapter 7 Statements File based Decoding User Manual 26 LeCroy Corporation File based Decoding User Manual Chapter 8 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 inc The quotation marks around the filename are required and by convention the included file has a inc extension The filenames given in the include directive are always treated as being relative to the current file being parsed So if a file is referenced via the preprocessing command in a dec file and no
50. set OutputType BNEP InputType Required A string label describing the input to the script Input and output types should be matched by the application in order to decide which modules to invoke on which contexts EXAMPLE set InputType L2CAP LevelName Optional A string that names this decoder EXAMPLE set LevelName BNEP Transactions LeCroy Corporation File based Decoding User Manual DecoderDesc Optional A string that describes this decoder Displays as a toolbar icon tool tip EXAMPLE set DecoderDesc View Bluetooth Encapsulation Protocol Layer Icon Optional File name of an icon to display on the toolbar Must be a 19x19 pixel bitmap file EXAMPLE set Icon bitmap bmp LeCroy Corporation 69 File based Decoding User Manual B 2 Input Context Data The Merlin application decodes several layers of Bluetooth protocol and provides input context as follows Packet Level in Data Data block packet payload null if no data in packet in DataLength Length of packet payload null if no data in packet in ScoData SCO data block voice null if no SCO data in packet in ScoDataLength Length of SCO data null if no SCO data in packet in Slave 1 Slave 0 Master in AmAddr Am address in Type Type of packet in Flow Packet flow bit in Seqn Packet seqn bit in L CH Packet L CH value L2CAP in Data L2CAP data block in DataLength Length of data block in Slave 1 Slave
51. st 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 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 ID du ui 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 Global Variables Global variables are defined outside of the scope of functions Defining global variables requires the use of the keyword set Global variables are visible throughout a file and 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 Global to cat which is visible to all functions This also changes its value type from an integer to a string LeCroy Corporation 5 Chapter 2 Values File based Decoding User Manual Local Variables Local variables are not declar
52. t checked for appropriate value types or number of arguments when a function is called If a function is called with fewer arguments than were defined the specified arguments are assigned and the remaining arguments are assigned to null If a function is called with more arguments than were defined the extra arguments are ignored For example if the function add is called with just one argument add 1 the parameter x is assigned to 1 and the parameter y is 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 is assigned to 1 y to 2 and 3 is ignored resulting in a return value of 3 LeCroy Corporation 31 Chapter 10 Functions File based Decoding User Manual 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 For instance the function add 1 x y x 221 y 3 return x y reassigns parameter values within the statements So a 10 b 20 add 1 a b has a return value of 5 but the values of a and b is not changed The scope of a function is the file in which it is defined as well as included files with the exception of primitive functions whose scopes are global Calls to undefined functions are legal but always evaluate to null and result in a compiler warning 32 LeCroy Corporation File based Decoding User Manual Chapter 11 Primi
53. t 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 4 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 64 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 Symbol Associativity Right to left O Left to right sizeof head tail first next more Right to left last prev 7 Left to right Left to right lt lt gt gt Left to right lt gt lt gt Left to right mm Left to right amp Left to right As Left to right Left to right amp amp Left to right Left to right E 5 gt gt lt lt amp Right to left Table 4 1 Operator Precedence and Associativity 10 LeCroy Corporation File based Decoding User Manual Chapter 4 Operators Operator Result Symbol Description Operand Types Types Examples Index Operator Ll Index or subscript Raw Bytes Integer Raw 001122 Raw 1 0x11 List Any List 0 1 2 3 4 51 List 2 2 List 4 4 5 List 4 1 5 No
54. te if an indexed Raw value is assigned to any value that is not a byte gt 255 or not an integer the variable is promoted to a list before the assignment is performed Associative Operator 6 Associative Any Any 284 3 18 24 4 3 14 Arithmetic Operators Multiplication Integer integer Integer 3 Dn e3 Division Integer integer Integer LL Modulus Integer integer Integer 3 1 0 Addition Integer integer Integer 2 254 String string String one 4 two one two Raw byte raw byte Raw 001122 334455 001122334455 List list List 1 2 3 4 1 2 3 4 Integer list List Y 2 31 B 25 3 Integer string String number 2 number 2 Note integer string concatenation uses decimal conversion String list List one two one two Subtraction Integer integer Integer 3i mue Increment and Decrement Operators Increment Integer Integer a mr a 2 b 1 b 1 Note that the value of b after execution is 2 Decrement Integer Integer a m2 a 1 B e2 b 2 Note that the value of b after execution is 1 Table 4 2 Operators LeCroy Corporation 11 Chapter 4 Operators File based Decoding User Manual Operator Result Symbol Description Operand Types Types Examples Eguality Operators Equal Integer integer Integer 2 ea 2 String string Integer three
55. the same rules as local variables they are created on demand and uninitialized symbols always evaluate to null LeCroy Corporation 29 Chapter 9 Context File based Decoding User Manual 30 LeCroy Corporation File based Decoding User Manual Chapter 10 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 Value types are not specified for the arguments or return values Named arguments are local to the function body and functions can be called recursively The syntax for a function declaration is name lt parameterl gt lt parameter2 gt The syntax to call a function is lt statements gt name lt parameterl gt lt parameter2 gt So for example a function named add can be declared like this add x y and called this way add 5 6 return X y This would result in a return value of 11 Every function returns a value The return value is usually specified using a return statement but if no return statement is specified the return value is the value of the last statement executed Arguments are no
56. tives 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 returns null 11 1 General Primitives Call Call function name string arg list list Default Parameter Meaning Value Comments function name string arg list list Used as the list of parameters in the function call Support Supported by all LeCroy analyzers Return value Same as that of the function that is called Comments Calls a function whose name matches the function name parameter All scope rules apply normally Spaces in the function name parameter are interpreted as the underscore character since function names cannot contain spaces Example Call Format the number is d 10 is equivalent to Format the number is d 10 LeCroy Corporation 33 Chapter 11 Primitives File based Decoding User Manual Format Format lt format string gt lt value string or integer gt Default Parameter Meaning Value Comments format string value string or integer Support Supported by all LeCroy analyzers Return value None Comments Format is used to control the way that arguments print out The format string may contain conversion specifications that affect the way in whi
57. try point into a decoding module It is called by the application and used each time a transaction needs to be displayed ProcessData PETracer supports only the ProcessData function Itis called with each packet of the appropriate type with input context filled with data from that packet It reports the amount of processed data through the out Decoded variable A 2 Decoder Script Files PETracer includes the four script files in the NScripts directory You can use these files as is or modify them To activate a script file go to the last line in the file for example in io dec the line reads set OutputType IO and remove the underscore For example Set OutputType IO Change to set OutputType IO Following is a list and brief summary of the decoder script files The following sections describe each file in greater detail Decoder Script File Function cfg dec Configuration data script decoder io dec IO data script decoder mem dec Memory data script decoder msg dec Message data script decoder LeCroy Corporation 61 File based Decoding User Manual cfg dec Description cfg dec is a configuration data script decoder Input Data Fields in Data Data block to decode in DataLength Length of data block in bytes in PrepareFldsForDlg If not 0 means that script should prepare decoded fields for presenting them in a special dialog in Type Reguest type TLP TYPE
58. ts starting at bit 6 reads 5 bits 00111 and returns the value OxT In the second call to NextNBits starting at bit 11 6 5 reads 2 bits 10 and returns the value 0x2 42 LeCroy Corporation File based Decoding User Manual Chapter 11 Primitives PeekNBits PeekNBits bit count integer gt Default Parameter Meaning Value Comments bit count integer Support Supported by all LeCroy analyzers 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 If PeekNBits is called without a prior call to GetNBits the result is undefined Note that bits are indexed starting at bit O Example raw FOFO 1111000011110000 binary resultl GetNBits raw 2 4 result2 PeekNBits 5 result3 NextNBits 2 Trace resulti resultl result2 result2 result3 result3 This generates this Trace output resultl C result2 7 result3 O0 In the call to GetNBits starting at bit 2 reads 4 bits 1100 and returns the value OxC In the call to PeekNBits starting at bit 6 reads 5 bits 00111 and returns the value 0x7 In the call to NextNBits starting at bit 6 reads 2 bits 00 and returns the value 0x0 LeCroy Corporation 43 C
59. y How to Obtain Warranty Service To reguest warranty service you must complete and return the registration card or register via the internet within the fifteen day period described above and report your covered warranty claim by contacting LeCroy Technical Support or its authorized representative LeCroy Technical Support can be reached at 800 909 7112 or via email at support catc com You may also refer to LeCroy s website at http www lecroy com for more information on how to contact an authorized representative in your region If warranty service is reguired LeCroy or its authorized representative will issue a Return Material Authorization Number You must ship the Product back to LeCroy or its authorized representative in its original or eguivalent packaging prepay shipping charges and insure the shipment or accept the risk of loss or damage during shipment LeCroy must receive the Product prior to expiration of the Warranty Period for the repair s to be covered LeCroy or its authorized representative will thereafter ship the repaired or replacement Product to you freight prepaid by LeCroy if you are located in the continental United States Shipments made outside the continental United States will be sent freight collect Please remove any peripheral accessories or parts before you ship the Product LeCroy does not accept liability for lost or damaged peripheral accessories data or software LeCroy owns all parts removed from
Download Pdf Manuals
Related Search