From 2bf9fc7130782163db3880f141d530382b6301ff Mon Sep 17 00:00:00 2001 From: Hornos3 Date: Sat, 31 Aug 2024 15:26:03 +0800 Subject: [PATCH 1/2] Add Ghidra doc. The pandoc may have improper parses in some html files that is needed to be optimized soon. --- sources/GhidraDocs/GhidraCodingStandards.md | 608 ++++ sources/GhidraDocs/GhidraFilesystemStorage.md | 204 ++ sources/GhidraDocs/InstallationGuide.md | 640 ++++ sources/GhidraDocs/images/B.gif | Bin 0 -> 553 bytes sources/GhidraDocs/images/D.gif | Bin 0 -> 880 bytes sources/GhidraDocs/images/F.gif | Bin 0 -> 864 bytes sources/GhidraDocs/images/GHIDRA_1.png | Bin 0 -> 189819 bytes sources/GhidraDocs/images/I.gif | Bin 0 -> 868 bytes sources/GhidraDocs/images/L.gif | Bin 0 -> 863 bytes sources/GhidraDocs/images/U.gif | Bin 0 -> 881 bytes sources/GhidraDocs/images/V_slash.png | Bin 0 -> 281 bytes sources/GhidraDocs/images/binaryData.gif | Bin 0 -> 897 bytes sources/GhidraDocs/images/dataTypes.png | Bin 0 -> 596 bytes .../GhidraDocs/images/decompileFunction.gif | Bin 0 -> 111 bytes sources/GhidraDocs/images/disk.png | Bin 0 -> 620 bytes .../GhidraDocs/images/document-properties.png | Bin 0 -> 464 bytes sources/GhidraDocs/images/down.png | Bin 0 -> 192 bytes sources/GhidraDocs/images/function_graph.png | Bin 0 -> 444 bytes sources/GhidraDocs/images/left.png | Bin 0 -> 188 bytes sources/GhidraDocs/images/memory16.gif | Bin 0 -> 931 bytes sources/GhidraDocs/images/notF.gif | Bin 0 -> 882 bytes sources/GhidraDocs/images/notes.gif | Bin 0 -> 866 bytes sources/GhidraDocs/images/play.png | Bin 0 -> 562 bytes sources/GhidraDocs/images/play_again.png | Bin 0 -> 563 bytes sources/GhidraDocs/images/redo.png | Bin 0 -> 187 bytes sources/GhidraDocs/images/registerGroup.png | Bin 0 -> 192 bytes sources/GhidraDocs/images/right.png | Bin 0 -> 190 bytes sources/GhidraDocs/images/sitemap_color.png | Bin 0 -> 406 bytes sources/GhidraDocs/images/table.png | Bin 0 -> 566 bytes sources/GhidraDocs/images/table_go.png | Bin 0 -> 683 bytes sources/GhidraDocs/images/undo.png | Bin 0 -> 185 bytes sources/GhidraDocs/images/up.png | Bin 0 -> 193 bytes sources/GhidraDocs/images/viewmagfit.png | Bin 0 -> 975 bytes .../languages/html/DefaultStyle.css | 92 + .../GhidraDocs/languages/html/Diagram1.png | Bin 0 -> 11652 bytes .../GhidraDocs/languages/html/Diagram2.png | Bin 0 -> 4169 bytes .../GhidraDocs/languages/html/Diagram3.png | Bin 0 -> 7139 bytes .../languages/html/additionalpcode.html | 453 +++ .../languages/html/additionalpcode.md | 436 +++ .../GhidraDocs/languages/html/languages.css | 26 + .../languages/html/pcodedescription.html | 3040 +++++++++++++++++ .../languages/html/pcodedescription.md | 1168 +++++++ .../GhidraDocs/languages/html/pcoderef.html | 369 ++ sources/GhidraDocs/languages/html/pcoderef.md | 155 + .../GhidraDocs/languages/html/pseudo-ops.html | 241 ++ .../GhidraDocs/languages/html/pseudo-ops.md | 102 + .../GhidraDocs/languages/html/reference.html | 530 +++ .../GhidraDocs/languages/html/reference.md | 84 + sources/GhidraDocs/languages/html/sleigh.html | 478 +++ sources/GhidraDocs/languages/html/sleigh.md | 563 +++ .../languages/html/sleigh_constructors.html | 2305 +++++++++++++ .../languages/html/sleigh_constructors.md | 2634 ++++++++++++++ .../languages/html/sleigh_context.html | 364 ++ .../languages/html/sleigh_context.md | 379 ++ .../languages/html/sleigh_definitions.html | 354 ++ .../languages/html/sleigh_definitions.md | 388 +++ .../languages/html/sleigh_layout.html | 122 + .../languages/html/sleigh_layout.md | 167 + .../languages/html/sleigh_preprocessing.html | 214 ++ .../languages/html/sleigh_preprocessing.md | 255 ++ .../GhidraDocs/languages/html/sleigh_ref.html | 607 ++++ .../GhidraDocs/languages/html/sleigh_ref.md | 450 +++ .../languages/html/sleigh_symbols.html | 229 ++ .../languages/html/sleigh_symbols.md | 218 ++ .../languages/html/sleigh_tokens.html | 285 ++ .../languages/html/sleigh_tokens.md | 346 ++ sources/GhidraDocs/languages/manual_index.txt | 54 + sources/GhidraDocs/languages/versioning.html | 237 ++ sources/GhidraDocs/languages/versioning.md | 242 ++ 69 files changed, 19039 insertions(+) create mode 100644 sources/GhidraDocs/GhidraCodingStandards.md create mode 100644 sources/GhidraDocs/GhidraFilesystemStorage.md create mode 100644 sources/GhidraDocs/InstallationGuide.md create mode 100644 sources/GhidraDocs/images/B.gif create mode 100644 sources/GhidraDocs/images/D.gif create mode 100644 sources/GhidraDocs/images/F.gif create mode 100644 sources/GhidraDocs/images/GHIDRA_1.png create mode 100644 sources/GhidraDocs/images/I.gif create mode 100644 sources/GhidraDocs/images/L.gif create mode 100644 sources/GhidraDocs/images/U.gif create mode 100644 sources/GhidraDocs/images/V_slash.png create mode 100644 sources/GhidraDocs/images/binaryData.gif create mode 100644 sources/GhidraDocs/images/dataTypes.png create mode 100644 sources/GhidraDocs/images/decompileFunction.gif create mode 100644 sources/GhidraDocs/images/disk.png create mode 100644 sources/GhidraDocs/images/document-properties.png create mode 100644 sources/GhidraDocs/images/down.png create mode 100644 sources/GhidraDocs/images/function_graph.png create mode 100644 sources/GhidraDocs/images/left.png create mode 100644 sources/GhidraDocs/images/memory16.gif create mode 100644 sources/GhidraDocs/images/notF.gif create mode 100644 sources/GhidraDocs/images/notes.gif create mode 100644 sources/GhidraDocs/images/play.png create mode 100644 sources/GhidraDocs/images/play_again.png create mode 100644 sources/GhidraDocs/images/redo.png create mode 100644 sources/GhidraDocs/images/registerGroup.png create mode 100644 sources/GhidraDocs/images/right.png create mode 100644 sources/GhidraDocs/images/sitemap_color.png create mode 100644 sources/GhidraDocs/images/table.png create mode 100644 sources/GhidraDocs/images/table_go.png create mode 100644 sources/GhidraDocs/images/undo.png create mode 100644 sources/GhidraDocs/images/up.png create mode 100644 sources/GhidraDocs/images/viewmagfit.png create mode 100644 sources/GhidraDocs/languages/html/DefaultStyle.css create mode 100644 sources/GhidraDocs/languages/html/Diagram1.png create mode 100644 sources/GhidraDocs/languages/html/Diagram2.png create mode 100644 sources/GhidraDocs/languages/html/Diagram3.png create mode 100644 sources/GhidraDocs/languages/html/additionalpcode.html create mode 100644 sources/GhidraDocs/languages/html/additionalpcode.md create mode 100644 sources/GhidraDocs/languages/html/languages.css create mode 100644 sources/GhidraDocs/languages/html/pcodedescription.html create mode 100644 sources/GhidraDocs/languages/html/pcodedescription.md create mode 100644 sources/GhidraDocs/languages/html/pcoderef.html create mode 100644 sources/GhidraDocs/languages/html/pcoderef.md create mode 100644 sources/GhidraDocs/languages/html/pseudo-ops.html create mode 100644 sources/GhidraDocs/languages/html/pseudo-ops.md create mode 100644 sources/GhidraDocs/languages/html/reference.html create mode 100644 sources/GhidraDocs/languages/html/reference.md create mode 100644 sources/GhidraDocs/languages/html/sleigh.html create mode 100644 sources/GhidraDocs/languages/html/sleigh.md create mode 100644 sources/GhidraDocs/languages/html/sleigh_constructors.html create mode 100644 sources/GhidraDocs/languages/html/sleigh_constructors.md create mode 100644 sources/GhidraDocs/languages/html/sleigh_context.html create mode 100644 sources/GhidraDocs/languages/html/sleigh_context.md create mode 100644 sources/GhidraDocs/languages/html/sleigh_definitions.html create mode 100644 sources/GhidraDocs/languages/html/sleigh_definitions.md create mode 100644 sources/GhidraDocs/languages/html/sleigh_layout.html create mode 100644 sources/GhidraDocs/languages/html/sleigh_layout.md create mode 100644 sources/GhidraDocs/languages/html/sleigh_preprocessing.html create mode 100644 sources/GhidraDocs/languages/html/sleigh_preprocessing.md create mode 100644 sources/GhidraDocs/languages/html/sleigh_ref.html create mode 100644 sources/GhidraDocs/languages/html/sleigh_ref.md create mode 100644 sources/GhidraDocs/languages/html/sleigh_symbols.html create mode 100644 sources/GhidraDocs/languages/html/sleigh_symbols.md create mode 100644 sources/GhidraDocs/languages/html/sleigh_tokens.html create mode 100644 sources/GhidraDocs/languages/html/sleigh_tokens.md create mode 100644 sources/GhidraDocs/languages/manual_index.txt create mode 100644 sources/GhidraDocs/languages/versioning.html create mode 100644 sources/GhidraDocs/languages/versioning.md diff --git a/sources/GhidraDocs/GhidraCodingStandards.md b/sources/GhidraDocs/GhidraCodingStandards.md new file mode 100644 index 0000000..94425ba --- /dev/null +++ b/sources/GhidraDocs/GhidraCodingStandards.md @@ -0,0 +1,608 @@ +--- +status: collected +title: Ghidra\'s Java Style Guide +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/GhidraCodingStandards.html +--- + +Ghidra\'s Java Style Guide +========================== + +###### Ver 1.1 - 20190307 + +Introduction +------------ + +The purpose of this document is to record the Ghidra team\'s accepted +rules for code formatting, naming conventions, code complexity, and +other best practices. Many of the rules listed in this document are not +universal absolutes and many blur into areas of personal preferences. +The purpose of these types of rules is not to definitely state that one +way is better than another, but that we are consistent throughout the +team. + +Most of these rules came from one or more of the listed references at +the end of this document. Many of these rules were listed in just about +every guide. Where they disagreed, We generally went with the majority. +Some rules seem arbitrary as to the actual value used, but that a value +was needed seemed universal. For example, just about every reference +stated a maximum character line length. We think all were either 80 or +100. So everyone seems to think it is important to have some limit, but +they don\'t agree to the actual number. + +### Most Important Rules of All + +#### Any of the rules or suggestions in this document can be broken, but you must document why breaking the rule makes the code better. + +#### Program for people, not machines. The primary goal of your development efforts should be that your code is easy for other people to understand. + +Naming Conventions +------------------ + +### General Naming Rules + +#### Names for classes, interfaces, methods, parameters, instance variables and long-lived local variables should not contain abbreviations or acronyms except for well known ones (the abbreviation is more commonly used than the full name) like URL and HTML. + +The following exceptions are allowed (The list can be expanded with +majority approval) + +- Utils - can be used as a suffix for the name of a class of static + utility methods (e.g., StringUtils) + +#### If an abbreviation or acronym is used, only the first letter should be capitalized. (Unless it is the beginning of a method or variable name, in which case the first letter is also lower case.) + +For example, use fooUrl, not fooURL. + +### Package Naming + +#### Package names should start with ghidra.\.\. (e.g., ghidra.framework.docking.) + +#### Package names should be all lower case, preferably one word and no abbreviations. + +### Class Naming + +#### Class names should be nouns. + +#### Class names should use upper CamelCase where the first letter of each word is capitalized. + +Examples: Table, FoldingTable, WoodTable + +#### Classes that extend other classes should use the base class name as a base and prepend it with what is more specific about the extended class. + +For example, if the base class is \"Truck\", the subclasses would have +names like \"DumpTruck\", \"DeliveryTruck\", or \"FlyingTruck\". + +#### The design pattern of an interface with one or more implementations should use the following naming conventions: + +- Foo - The interface should be named the fundamental thing. +- AbstractFoo - An abstract implementation intended to be used as the + base of a hierarchy of classes. +- DefaultFoo - A \"default\" implementation that would be appropriate + for the majority of use cases. +- {descriptive}Foo - Other implementations should describe what makes + them unique. + +#### The design pattern for using an [abstract base class]{.underline} without a corresponding interface should use the following naming conventions: + +- Foo - The abstract base class should be named the fundamental thing. + EXCEPTION: if the abstract base class does not represent a + \"fundamental thing\" whose type will be referred to in other code + as parameters, return types, etc., then the class should be named + AbstractFoo. +- {descriptive}Foo - subclasses that provide different flavors of Foo. + +#### Test class names should end with \"Test\" (e.g., FooTest). + +#### Test doubles or stub objects should use the following naming rules: + +- DummyFoo - a stub that returns empty or null values because they are + irrelevant to the test. +- SpyFoo - may provide values to the environment, but also records + statistics. +- MockFoo - provides values to the environment and usually has some + form of expectations. +- FakeFoo - replaces real functionality with a simplified version + (like replacing Database access with in-memory data). + +### Interface Naming + +#### Interface names should be nouns, or adjectives ending with \"able\" such as Runnable or Serializable. + +#### Interface names should use upper CamelCase where the first letter of each word is capitalized. + +### Method Naming + +#### Method names should use lower CamelCase where the first letter of each word is capitalized except for the first word. + +#### Method names should generally be verbs or other descriptions of actions. + +#### Specific naming conventions: + +- Methods that access a class\'s attributes should start with \"get\" + or \"set\". +- Methods that return a boolean should start with \"is\". Sometimes + \"has\", \"can\", or \"should\" are more appropriate. +- Methods that look something up should start with \"find\" + +#### Methods that return a value should be named based on what they return. Void methods should be named based on what they do. + + public Foo buildFoo() { // returns a Foo so method name is based on Foo + ... + } + public int getSize() { // returns a primitive, which is the size, so name is based on "size" + ... + } + public void startServer() { // doesn't return anything so name it based on what it does + ... + } + public boolean installHandler(Handler handler) { // even though it returns a boolean, its not about returning + ... // a boolean, so name it based on what it does + } + + +### Instance Variable Naming + +#### Instance Variable names should use lower CamelCase where the first letter of each word is capitalized except for the first word. + +### Local Variable and Parameter Naming + +#### Local Variable names should use lower CamelCase where the first letter of each word is capitalized except for the first word. + +#### Variable names should be proportional in length to their scope. + +- Names that live throughout large blocks or methods should have very + descriptive names and avoid abbreviations. +- Names that exist in small blocks can use short or abbreviated names. +- Names that exist in tiny blocks can use one letter names (e.g., + lambdas). + +#### Variable names should generally have the same name as their class (e.g., Person person or Button button). + +- If for some reason, this rule doesn\'t seem to fit, then that is a + strong indication that the type is badly named. +- Some variables have a role. These variables can often be named + {role}Type. For example, Button openButton or Point startPoint, + endPoint. + +#### Collections should be named the plural form of the type without the collection type name. For example, use List dogs, not List dogList. + +### Enum Naming + +#### Enum class names should be like any other class (UpperCamelCase). + +#### Enum value names should be all upper case. + + public enum AnalyzerStatus { + ENABLED, DELAYED, DISABLED + } + + +### Loop Counters + +#### Use of i, j, k, etc. is acceptable as generic loop counters, unless a more descriptive name would greatly enhance the readability. + +### Constants (static final fields) + +#### Constants should be all upper case with words separated by \"\_\" (underscore char). + +Examples: MAXIMUM\_VELOCITY, or DEFAULT\_COLOR + +### Generic Types + +#### Generic type names should be named in one of two styles: + +A single Capital Letter, optionally followed by a single number (e.g., +T, X, V, T2) + +- T is used most often for single parameter types. +- R is commonly used for return type. +- K,V is commonly used for key,value types. + +A name in the form used for classes followed by the capital letter T +(e.g., ActionT, RowT, ColumnT). Try to avoid using this full name form +unless it greatly enhances readability. + +### Utility Classes + +#### Utility class names should end in \"Utils\". + +Source File Structure +--------------------- + +### File Order + +#### A Java File should be organized in the following order + +- Header +- Package statement +- Import statements +- Class javadocs +- Class declaration +- Static variables +- Instance variables +- Static factory methods +- Constructors +- Methods +- Private classes + +#### Local variables should be declared when first needed and not at the top of the method and should be initialized as close to the declaration as possible (preferably at the same time). + +#### Overloaded methods should be next to each other. + +#### Modifiers should appear in the following order: + +- access modifier (public/private/protected) +- abstract +- static +- final +- transient +- volatile +- default +- synchronized +- native +- strictfp + +Formatting +---------- + +Most of these are handled by the Eclipse formatter and are here to +document the Ghidra formatting style. The Eclipse formatter can be found +in the ***support/eclipse/*** directory of a Ghidra release, or in the +***eclipse/** *directory of the Ghidra source repository.** + +### Line Length + +#### Java code will have a character limit of 100 characters per line. + +### Indenting + +#### New blocks are indented using a tab character (the tab should be 4 spaces wide). + +#### Line continuation should be indented the same as a new block. + +### Special Formatting + +If special formatting is required to make code readable, you may +surround the statement or code block with the eclipse formatter tags. +For example, + + public String toString() { + //@formatter:off + return "{\n" + + "\tname: " + name + ",\n" + + "\tmodelColumn" + modelIndex + ",\n" + + "\tviewColumn: " + viewIndex + ",\n" + + "\tconstraints: " + + CollectionUtils.collect(applicableConstraints, c -> c.asString()) +"\n" + + "}"; + //@formatter:on + } + + +#### Do not use empty end-of-line comments \"//\" to trick eclipse into not formatting the line. + +### Braces + +#### Braces should always be used where optional. + +#### Braces should follow the Kernighan and Ritchie style for nonempty blocks and block-like structures. + +- No line break before the opening brace. +- Line break after the opening brace. +- Line break before the closing brace. +- Line break after the closing brace. + +#### Empty blocks should look as follows. + + void doNothing() { + // comment as to why we are doing nothing + } + + +### White Space + +#### A single blank line should be used to separate the following sections: + +- Copyright notice +- Package statement +- Import section +- Class declarations +- Methods +- Constructors + +#### A single blank line should be used: + +- Between statements as needed to break code into logical sections. +- Between import statements as needed to break into logical groups. +- Between fields as needed to break into logical groups. +- Between the javadoc description and the javadoc tag section. + +#### A single space should be used: + +- To separate keywords from neighboring opening or closing brackets + and braces. +- Before and after all binary operators +- After a // that starts a comment +- Before a // that starts an end of line comment +- After semicolons separating parts of a \"for\" loop + +### Variable Assignment + +#### Each variable should be declared on its own line. + + don't: + int i,j; + + do: + int i; + int j; + + +Comments +-------- + +### Javadoc + +#### Javadoc blocks are normally of the form + + /** + * Some description with normal + * wrapping. + */ + + +#### Javadoc paragraphs should be separated by a single blank line (Starts with an aligned \*) and each paragraph other than the initial description should start with <p\>. + +#### When referencing other methods, use links (e.g., {\@link \#method(type1, type2, \...} or {\@link Classname\#method(type1, type2, \...}). + +#### Block tags should never appear without a description. + +#### Descriptions in block tags should not end in a period, unless followed by another sentence. + +#### Block tags that are used should appear in the following order: + +- \@param +- \@return +- \@throws +- \@see +- \@deprecated + +#### The Javadoc block should begin with a brief summary fragment. This fragment should be a noun phrase or a verb phrase and not a complete sentence. However, the fragment is capitalized and punctuated as if it were a complete sentence. + + For example, do + + /** + * Sets the warning level for the messaging system. + */ + not + + /** + * This method sets the warning level for the messaging system. + */ + + + +#### Javadoc should be present for every public class and every public or protected method with the following exceptions: + +- Methods that override a super method. + +### Code Comments + +#### Block comments are indented at the same level as the surrounding code. + +#### Block comments should be preceded by a blank line unless it is the first line of the block. + +#### Block comments should be one of the following forms: + + /* + * This is // I like this + * nice. // also. + */ + + +#### Any empty code block should have a comment so that the reader will know it was intentional. Also, the comment should not be something like \"// empty\" or \"don\'t care\", but instead should state why it is empty or why you don\'t care. + +#### Comments should indicate the \'why\' you are doing something, not just \'what\' you are doing. The code tells us what it is doing. Comments should not be pseudo code. + +#### Prefer creating a descriptive method to using a block comment. So if you feel that a block comment is needed to explain the next block of code, then it probably would be better off moved to a method with a name that says what the code does. + +#### Use of comments in code should be minimized by making the code self-documenting by appropriate name choices and an explicit logical structure. + +#### Tricky code should not be commented. Instead, it should be rewritten. + +Complexity +---------- + +### Method Size + +#### Avoid long methods. + +- Methods should perform one clearly defined task. +- Methods should generally fit on one page (approximately 30 lines). + +### Method Complexity + +#### A method should be completely understandable (what, how, why) in about 30 seconds. + +#### Method Complexity should be kept low, according to the following scale: + +- `0-5`: The method is \*probably\* fine +- `6-10`: The method is questionable; seek to simplify +- `11+`: OMG! Unacceptable! + +Calculating Complexity: + +Start with one. + +Add one for each of the following. + +- Returns: Each return other than a simple early guard condition or + the last statement in the method. +- Selection: if, else if, case, default. +- Loops: for, while, do-while, break, and continue. +- Operators: &&, \|\|, ? +- Exceptions: catch, finally, throw. + +#### Methods should avoid deep nesting. + +- 2 or less - good +- 3 or 4 - questionable +- 5 or more - unacceptable + +#### Methods and constructors should avoid large numbers of parameters. + +- 3 or less - good +- 4 or 5 - questionable +- 6 or 7 - bad, should consider redesign +- 8 or more - unacceptable + +#### All blocks of code in a method should be at the same level of abstraction + + // example of mixed levels: + void doDailyChores() { + dust(); + vacuum(); + mopFloor(); + addDirtyClothesToWashingMachine(); + placeDetergentInWashingMachine(); + closeWashingMachineDoor(); + startWashingMachine(); + cleanToilet(); + } + + // fixed + void doDailyChores() { + dust(); + vacuum(); + mopFloor(); + washClothes(); + cleanToilet(); + } + + +#### Methods and constructors should generally avoid multiple parameters of the same type, unless the method\'s purpose is to process multiple instances of the same type (e.g., comparator, math functions). This is especially egregious for boolean parameters. + +#### Tips for lowering complexity + +- Keep the number of nesting levels low +- Keep the number of variables used low +- Keep the lines of code low +- Keep \'span\' low (the number of lines between successive references + to variables) +- Keep \'live time\' low (the number of lines that a variable is in + use) + +Testing +------- + +### Unit testing + +#### A single test case should only test one result. If there are more than 2 or 3 asserts in a single test, consider breaking into multiple tests. + +#### Unit tests should run fast (a single test case (method) should be less than a second) + +Miscellaneous +------------- + +### \@Override + +#### Methods that override a method in a parent class should use the \@Override tag. + +#### Methods that implement an interface method should use the \@Override tag. + +#### Methods that use the \@Override tag do not need a Javadoc comment. + +### Use of Tuple Objects + +#### Use of Pair, Triple, etc. should be avoided. If the multiple values being returned are related, then the method is conceptually returning a higher level object and so should return that. Otherwise, the method should be redesigned. + +### Exception Handling + +#### Exceptions should never have empty code blocks. There should at least be a comment explaining why there is no code for the exception. + +#### If the caught exception is believed to be impossible to happen, the correct action is to throw an AssertException with a message explaining that it should never happen. + +### Final + +#### Instance variables that are immutable should be declared final unless there is a compelling reason not to. + +### Shadowing + +#### Avoid hiding/shadowing methods, variables, and type variables in outer scopes. + +### Access modifiers + +#### Class instance fields should not be public. They should be private whenever possible, but protected and package are acceptable. + +### Java-specific constructs + +#### Use the try-with-resources pattern whenever possible. + +#### Always parameterize types when possible (e.g., JComboBox\ vs. JComboBox). + +#### If an object has an isEmpty() method, use it instead of checking its size == 0. + +### Miscellaneous + +#### Mutating method parameters is discouraged. + +#### Magic numbers should not appear in the code. Other than 0, or 1, the number should be declared as a constant. + +#### Avoid creating a new Utilities class **\*every time you need to share code\***. Try to add to an existing utilities class OR take advantage of code re-use via inheritance. + +### Rules that shouldn\'t need to be stated, but do + +#### Test your feature yourself before submitting for review and make sure the tests pass. + +::: {.info} +Notes: +::: + +##### Complexity + +\'The McCabe measure of complexity isn\'t the only sound measure, but +it\'s the measure most discussed in computing literature and it\'s +especially helpful when you\'re thinking about control flow. Other +measures include the amount of data used, the number of nesting levels +in control constructs, the number of lines of code, the number of lines +between successive references to variables (\"span\"), the number of +lines that a variable is in use (\"live time\"), and the amount of input +and output. Some researchers have developed composite metrics based on +combinations of these simpler ones.\' (McCabe) + +\'Moving part of a routine into another routine doesn\'t reduce the +overall complexity of the program; it just moves the decision points +around. But it reduces the amount of complexity you have to deal with at +any one time. Since the important goal is to minimize the number of +items you have to juggle mentally, reducing the complexity of a given +routine is worthwhile.\' (McCabe) + +\'Excessive indentation, or \"nesting,\" has been pilloried in computing +literature for 25 years and is still one of the chief culprits in +confusing code. Studies by Noam Chomsky and Gerald Weinberg suggest that +few people can understand more than three levels of nested ifs (Yourdon +1986a), and many researchers recommend avoiding nesting to more than +three or four levels (Myers 1976, Marca 1981, and Ledgard and Tauer +1987a). Deep nesting works against what Chapter 5, describes as +Software\'s Primary Technical Imperative: Managing Complexity. That is +reason enough to avoid deep nesting.\' (McCabe) + +\'There is no code so big, twisted, or complex that maintenance can\'t +make it worse.\'\ +     - Gerald Weinberg + +::: {.info} +References: +::: + +- Google Java Style Guide +- OpenJDK Style Guide +- Java Programming Style Guidelines - Geotechnical Software Services +- Code Complete, Steve McConnell +- Java Code Conventions +- Netscapes Software Coding Standards for Java +- C / C++ / Java Coding Standards from NASA +- Coding Standards for Java from AmbySoft +- Clean Code, Robert Martin (Uncle Bob) diff --git a/sources/GhidraDocs/GhidraFilesystemStorage.md b/sources/GhidraDocs/GhidraFilesystemStorage.md new file mode 100644 index 0000000..9ce4e1d --- /dev/null +++ b/sources/GhidraDocs/GhidraFilesystemStorage.md @@ -0,0 +1,204 @@ +--- +status: collected +title: Ghidra Filesystem Storage +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/GhidraFilesystemStorage.html +--- + +Ghidra Filesystem Storage +========================= + +Introduction +------------ + +The purpose of this document is to provide technical details of the file +storage scheme(s) employed by both Ghidra projects and Ghidra Server +repositories. As of this writing Ghidra has employed two different local +filesystem storage schemes: + +- Indexed Filesystem (current) +- Mangled Filesystem (legacy, pre-9.0 PUBLIC release) + +In addition to providing details of each storage scheme, some details +are provided about how project/repository database files are stored +within each filesystem as well as some troubleshooting tips to aid in +any manual interventions which may be required. + +At this point in time all filesystem implementations rely on the use of +a property file for each project defined file (*\*.prp*). For all +database type project files there will be a corresponding subdirectory +(*\~\*.db*) which is used to store all content related to a project file +database (e.g., ProgramDB). The naming and organization of these two +differ significantly between the two filesystem implementations. + +### Name Mangling/Encoding + +Ghidra uses the following name mangling/encoding for both Ghidra Server +project repository subdirectories as well as project folder and file +naming within the legacy Mangled Filesystem. The goal of this encoding +scheme is to preserve case-sensitive naming while allowing storage on a +single-case or case-insensitive native filesystem. This is achieved by +mutating the original name with the following character substitutions: + +- All uppercase letters replaced with an underscore (\'\_\') followed + by the lowercase letter, and +- All underscore (\'\_\') characters are replaced with two underscores + (\"\_\_\") + +For a Ghidra Server repository named \"My\_Project\", the resulting +filesystem storage folder named \"\_my\_\_\_project\" would appear +within the server repositories directory. + +### Ghidra Project Storage + +Ghidra projects employ multiple filesystem storage directories within +the top-level project directory (*\*.rep*): + +- Local project file storage (*idata*) provides the primary storage + area for non-versioned project files and for versioned files + checked-out by the user. +- Versioned project file storage (*versioned*) is present with private + non-shared projects only and provides version control storage + similar to a Ghidra Server repository. +- User data storage (*user*) provides non-versioned storage of + user-specific data associated with a specific project file. + +### Ghidra Server Storage + +The Ghidra Server employs a separate filesystem storage directory for +each project repository using a mangled name (see *Name +Mangling/Encoding* above). While all newly created project repositories +will use the latest Indexed Filesystem storage scheme Ghidra continues +to support the legacy Mangled Filesystem which may be in use by older +Ghidra Server installations. The *svrAdmin* command provides the ability +to migrate an older Mangled Filesystem to the current Index Filesystem +(see *server/serverREADME.html*). + +Indexed Filesystem (current) +---------------------------- + +This filesystem overcomes the project file-path length limitations +inherent to the legacy Managled Filesystem and utilizes an index file to +store project file-paths and the corresponding 8-digit hexadecimal +identifier for each (e.g., *00001234.prp* / *\~00001234.db*). The +following files are used to manage the filesystem content and are +located at the root of the filesystem storage directory. + +- Index File (*\~index.dat*) - current index file** +- Backup Index File (*\~index.bak*) - backup of current index file +- Temporary Index File (*\~index.tmp*) - temporary index file created + during update +- Index Journal File (*\~journal.dat*) - journal or recent changes not + yet reflected by index +- Backup Journal File (*\~journal.bak*) - backup of journal file + created during incremental update +- Index Lock File (*\~index.lock*) - index lock used to coordinate + index access and modification + +**Index Rebuild** - If the index file becomes corrupt it may be easily +rebuilt while the associated project is closed or Ghidra Server stopped +to avoid file access during the repair process. While the filesystem is +not active/in-use all of the index related files mentioned above may be +manually deleted from the root of the appropriate filesystem storage +directory (see Ghidra Project Storage and Ghidra Server Storage above). +Once the filesystem store is started (e.g., project opened or Ghidra +Server started) the missing index will trigger an automatic rebuild of +the index based upon the details provided by each property file +contained within (*\*.prp*). + +**Locating Project File Storage** - Locating individual project files on +disk requires interpretation of the index file (*\~index.dat*) and +traversing the numbered storage folders appropriately. When locating a +project file within the index it is important to know both the full +Ghidra project directory path and project filename. If project filename +are unique you can simply search for the filename within the index, +otherwise you will have to search for project folder path first. Sample +*\~index.dat* file: + + + VERSION=1 + / + 00000003:myFile:a701ee4b1c71321380792951888 + /A + 00000100:anotherFile:a701ee4920f909328022843906 + 00000105:yetAnotherFile:a701ee48743913628104779815 + /A/B + 00001234:myFile:a701ee48019210920546276045 + 00001200:myFile.1:a701ee48491297248400412904 + /A/B/C + 00000004:someFile:a701ee4a23590324427866017 + NEXT-ID:1250 + MD5:d41d8cd98f00b204e9800998ecf8427e + + +Once the project file of interest has been located within the index file +and the corresponding 8-digit hex file number identified, the storage +subfolder name is derived from the 2nd and 3rd digits of the file +number. Example file number \"00001234\" will be contained with the +subfolder \"12\". Within this subfolder the \"00001234.prp\" file should +exist as will all other numbered files which have the same 2nd/3rd +digits. The storage hierarchy for the above index file would have the +following hierarchy: + + ./~index.dat + ./00/ + 00000003.prp + ~00000003.db/ + 00000004.prp + ~00000004.db/ + ./01/ + 00000100.prp + ~00000100.db/ + 00000105.prp + ~00000105.db/ + ./12/ + 00001200.prp + ~00001200.db/ + 00001234.prp <-- /A/B/myFile property file + ~00001234.db/ <-- /A/B/myFile database directory + + +Mangled Filesystem (legacy) +--------------------------- + +This filesystem utilizes mangled naming for all project folders and +files and follows the same hierarchy as the project. For example, a +project file with the path *\"/A\_1/B\_1/myFile\"* would be found stored +as *\"./\_a\_\_1/\_b\_\_1/my\_file.prp\"* and +*\"./\_a\_\_1/\_b\_\_1/\~my\_file.db/\"*. Due to file path-length +limitations of native filesystems the use of this storage scheme is no +longer used by default and has been retained only for backward +compatibility with older projects and repositories. + +Removal of Corrupt Files +------------------------ + +If a project or Ghidra Server repository contains a corrupt file it may +not be possible to remove the file via the Ghidra GUI or API. While a +detailed triage of a corrupt file may be possible by the Ghidra +Development Team, such files may need to be removed after being copied +for triage. For a shared repository this will require stopping the +Ghidra Server and digging into the appropriate named repository +directory. For a local project simply ensure that the project is not in +use. + +For the local project case it will be neccessary to isolate the storage +issue since it could be caused by the local project store +(*\*.rep/idata/*) or versioned repository (Ghidra Server or private +non-shared (*\*.rep/versioned/*). The Ghidra Server case can easily be +identified by creating another temporary shared project to the same +shared repository and check the behavior of the project file in +question. If the same behavior is observed the issue is likely on the +server. If you need assistance identifying the source of the bad +behavior or recommended resolution please submit a Ghidra trouble +ticket. + +As discussed for each filesystem above, the specific *\*.prp* file and +*\~\*.db/* directory should be identified and copied for triage. Keep a +copy will enable triage and may enable restoring the file in the future +if poossible. Once this file and corresponding directory have been +copied they may be removed from the filesystem. For the indexed +filesystem case the index related files can be deleted which will +trigger a rebuild of the index (see Indexed Filesystem above). diff --git a/sources/GhidraDocs/InstallationGuide.md b/sources/GhidraDocs/InstallationGuide.md new file mode 100644 index 0000000..e3c210d --- /dev/null +++ b/sources/GhidraDocs/InstallationGuide.md @@ -0,0 +1,640 @@ +--- +status: collected +title: Ghidra Installation Guide +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/InstallationGuide.html +--- + +Ghidra Installation Guide +========================= + +The installation information provided is effective as of Ghidra 11.2 and +is subject to change with future releases. + +[Platforms Supported](#Platforms) + +[Minimum Requirements](#Requirements) + +[Installing Ghidra](#Install) + +- [Installation Notes](#InstallationNotes) +- [Java Notes](#JavaNotes) + +[Ghidra Installation Directory Layout](#Layout) + +[Building Native Components](#Build) + +[Installing the Debuggers\' Python Dependencies](#DebuggerPython) + +[Running Ghidra](#Run) + +- [GUI Mode](#RunGUI) +- [Ghidra Server](#RunServer) +- [Headless (Batch) Mode](#RunHeadless) +- [Single Jar Mode](#RunJar) + +[Extensions](#Extensions) + +- [Ghidra Extension Notes](#GhidraExtensionNotes) + +[Ghidra Development](#Development) + +[Upgrade Instructions](#Upgrading) + +- [General Upgrade Instructions](#GeneralUpgrade) +- [Server Upgrade Instructions](#ServerUpgrade) + +[Troubleshooting & Help](#Troubleshooting) + +- [Launching Ghidra](#LaunchIssues) +- [Using Ghidra](#GhidraHelp) + +[Known Issues](#KnownIssues) + +- [All Platforms](#CommonIssues) +- [Windows](#WindowsIssues) +- [Linux](#LinuxIssues) +- [macOS (OS X)](#MacOSIssues) + +[]{#Platforms}Platforms Supported +--------------------------------- + +- Windows 10 or later (64-bit) +- Linux (64-bit) +- macOS 10.13 or later + +> **NOTE:** All 32-bit OS installations are now deprecated. Please +> contact the Ghidra team if you have a specific need. + +[]{#Requirements}Minimum Requirements +------------------------------------- + +### Hardware + +- 4 GB RAM +- 1 GB storage (for installed Ghidra binaries) +- Dual monitors strongly suggested + +### Software + +Java 21 64-bit Runtime and Development Kit (JDK) (see [Java +Notes](#JavaNotes)) + +Free long term support (LTS) versions of JDK 21 are provided by: + +- [Adoptium Temurin](https://adoptium.net/temurin/releases) +- [Amazon + Corretto](https://docs.aws.amazon.com/corretto/latest/corretto-21-ug/downloads-list.html) + +Python3 (3.9 to 3.12; for Debugger support) + +- This is available from [Python.org](https://python.org) or most + operating system\'s app stores or software repositories. For Linux + it is recommended that the system\'s package repository be used to + install a suitable version of Python. + +([Back to Top](#top)) + +### + +[]{#Install}Installing Ghidra +----------------------------- + +To install Ghidra, simply extract the Ghidra distribution file to the +desired filesystem destination using any unzip program (built-in OS +utilities, 7-Zip, WinZip, WinRAR, etc) + +### []{#InstallationNotes}Installation Notes + +- Ghidra does not use a traditional installer program. Instead, the + Ghidra distribution file is simply extracted in-place on the + filesystem. This approach has advantages and disadvantages. On the + up side, administrative privilege is not required to install Ghidra + for personal use. Also, because installing Ghidra does not update + any OS configurations such as the registry on Windows, removing + Ghidra is as simple as deleting the Ghidra installation directory. + On the down side, Ghidra will not automatically create a shortcut on + the desktop or appear in application start menus. +- When launching Ghidra for the first time on macOS, the macOS + Gatekeeper feature may attempt to quarantine the pre-built unsigned + Ghidra native components. Two techniques can be used to prevent this + from happening: + - Prior to extracting the Ghidra distribution file, running *xattr + -d com.apple.quarantine ghidra\_\\_\.zip* from + a terminal. + - Prior to first launch, following the instructions in the + [Building Native Components](#Build) section. +- Administrative privilege may be required to extract Ghidra to + certain filesystem destinations (such as C:\\), as well as install + the Ghidra Server as a service. +- Ghidra relies on using directories outside of its installation + directory to manage both temporary and longer-living cache files. + Ghidra attempts to use standard OS directories that are designed for + these purposes in order to avoid several issues, such as storing + large amounts of data to a roaming profile. If it is suspected that + the default location of these directories is causing a problem, they + can be changed by modifying the relevant properties in the + *support/launch.properties* file. + +### []{#JavaNotes}Java Notes + +- Ghidra requires a [supported](#Requirements) version of a Java + Runtime and Development Kit on the PATH to run. However, if there is + a version of Java on the PATH that Ghidra does not support, it will + use that version of Java (if 1.8 or later) to assist in locating a + supported version on your system. If one cannot be automatically + located, the user will be prompted to enter a path to the Java home + directory to use (the Java home directory is the parent directory of + Java\'s *bin* directory). This minimizes the impact Ghidra has on + pre-existing configurations of Java that other software may rely on. +- Depending on your operating system, it may be possible to find and + install a [supported](#Requirements) version of a Java Runtime and + Development Kit through your package manager, without the need to + set the Path environment variables as described below. +- If Ghidra failed to run because *no versions* of Java were on the + PATH, a [supported](#Requirements) JDK should be installed via a + Linux package manager (aptitude, yum, etc), Windows installer + program (\*.exe, \*.msi), macOS Installer package (\*.pkg), or + manually extracted and added to the PATH. The following steps + outline how to manually extract and add a JDK distribution to the + operating system\'s PATH. + - **Windows:** Extract the JDK distribution (.zip file) to your + desired location and add the JDK\'s bin directory to your PATH: + + 1. Extract the JDK: + + 1. Right-click on the zip file and click **Extract + All\...** + 2. Click **Extract** + + 2. Open Environment Variables window: + + 1. Right-click on Windows start button, and click + **System** + 2. Click **Advanced system settings** + 3. Click **Environment variables\...** + + 3. Add the JDK bin directory to the PATH variable: + + 1. Under **System variables**, highlight *Path* and click + **Edit\...** + 2. At the end of the the *Variable value* field, add a + semicolon followed by *\\\bin*, or use the **New** button in the *Edit + environment variable* window to add a new entry to the + *Path*. + 3. Click **OK** + 4. Click **OK** + 5. Click **OK** + + 4. Restart any open Command Prompt windows for changes to take + effect + + - **Linux and macOS (OS X):** Extract the JDK distribution + (.tar.gz file) to your desired location, and add the JDK\'s bin + directory to your PATH: + + 1. Extract the JDK: + + > *tar xvf \* + + 2. Open \~/.bashrc with an editor of your choice. For example: + + > *vi \~/.bashrc* + + 3. At the very end of the file, add the JDK bin directory to + the PATH variable: + + > *export PATH=\/bin:\$PATH* + + 4. Save file + + 5. Restart any open terminal windows for changes to take effect +- In some cases, you may want Ghidra to launch with a specific version + of Java instead of the version that Ghidra automatically locates. To + force Ghidra to launch with a specific version of Java, set the + **JAVA\_HOME\_OVERRIDE** property in the *support/launch.properties* + file. If this property is set to an incompatible version of Java, + Ghidra will revert to automatically locating a compatible version. + Note that *some* Java must still be on the PATH in order for Ghidra + to use the **JAVA\_HOME\_OVERRIDE** property. This limitation will + be addressed in a future version of Ghidra. + +([Back to Top](#top)) + +[]{#Layout}Ghidra Installation Directory Layout +----------------------------------------------- + +When Ghidra is installed, the runnable software gets extracted to a new +directory we will refer to as *\*. Below is a +description of the top-level directories and files that can be found in +*\* once extraction of the distribution file is +complete. + + --------------------- ------------------------------------------------------------ + **Ghidra** Base directory for Ghidra distribution.  Contains files + needed to run Ghidra. + + **Extensions** Optional components that can extend Ghidra\'s functionality + and integrate Ghidra with other tools.\ + See the [Extensions](#Extensions) section for more + information. + + **GPL** Standalone GPL support programs. + + **server** Contains files related to Ghidra Server installation and + administration. + + **support** Contains files useful for debugging Ghidra, running Ghidra + in advanced modes, and controlling how Ghidra launches. + + **docs** Contains documentation for Ghidra, such as release notes, + API files, tutorials, etc. + + **ghidraRun(.bat)** Script used to launch Ghidra. + + **LICENSE.txt** Ghidra license information. + + **licenses** Contains licenses used by Ghidra. + + **bom.json** Software Bill of Materials (SBOM) in CycloneDX JSON format. + --------------------- ------------------------------------------------------------ + +([Back to Top](#top)) + +[]{#Build}Building Native Components +------------------------------------ + +Ghidra requires several native binaries to be present in order to +successfully run. An official public Ghidra release includes native +binaries for the following platforms. + +NOTE: For some non-public Ghidra releases macOS natives may be omitted. + +- Windows 10 or later, x86 64-bit +- Windows 10 or later, ARM 64-bit (using x86 emulation) +- Linux x86 64-bit +- macOS x86 64-bit +- macOS ARM 64-bit + +Ghidra supports running on the following additional platforms with +user-built native binaries: + +- Linux ARM 64-bit +- FreeBSD x86 64-bit (no debugger support) +- FreeBSD ARM 64-bit (no debugger support) + +For supported systems where native binaries have not been supplied, or +those that are supplied fail to run properly, it may be necessary to +build the native Ghidra binaries. In order to build native binaries for +your platform, you will need the following installed on your system: + +A [supported](#Requirements) version of a Java Development Kit + +[Gradle 8.5+](https://gradle.org/releases/) (or supplied Gradle wrapper +with Internet connection) + +Software C/C++ build tools and library packages + +- macOS: *Xcode* or the abbreviated *Command Line Tools for Xcode* + will supply the necessary build tools. Assuming you are connected to + the Internet, *Xcode* (which includes the command tools) may be + installed directly from the App Store while *Command Line Tools for + Xcode* may be installed using the following command: + + xcode-select --install + +- Linux/FreeBSD: the 64-bit versions of the following packages should + installed: + - gcc 8.5 or later + - gcc-c++ / g++ 8.5 or later + - make + +- Windows: [Microsoft Visual + Studio](https://visualstudio.microsoft.com/vs/community/) 2017 or + later, or [Microsoft C++ Build + Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) + with the following components installed: + - MSVC + - Windows SDK + - C++ ATL + +To build the native binaries for your current platform, execute the +following commands: + +> cd /support/gradle/ +> gradle buildNatives +> + +If you are connected to the Internet and do not have Gradle installed, +execute: + +> cd /support/gradle/ +> ./gradlew(.bat) buildNatives +> + +When the commands successfully complete, Ghidra will contain newly built +native binaries in the relevant modules\' *build/os/\/* +subdirectories, which will override any existing pre-built native +binaries in the *os/\/* subdirectories. + +([Back to Top](#top)) + +[]{#DebuggerPython}Installing the Debugger\'s Python Dependencies +----------------------------------------------------------------- + +The Debugger now uses Python to connect to the host platform\'s native +debuggers. This requires Python3 (3.9 to 3.12) and some additional +packages. These packages are included in the distribution, but you may +still install them from PyPI if you prefer: + +- psutil +- protobuf==3.20.3 +- Pybag\>=2.2.10 (for WinDbg support) + +Different native debuggers have varying requirements, so you do not +necessarily have to install all of the above packages. Each connector +will inform you of its specific requirements and where they must be +installed. In some cases, you may need to install packages on the target +system. + +[]{#Run}Running Ghidra +---------------------- + +### []{#RunGUI}GUI Mode + +1. Navigate to *\* + +2. Run *ghidraRun.bat* (Windows) or *ghidraRun* (Linux or macOS) + + If Ghidra failed to launch, see the + [Troubleshooting](#Troubleshooting) section. + +### []{#RunServer}Ghidra Server + +Ghidra can support multiple users working together on a single project. +Individual Ghidra users launch and work on their own local copies of a +particular Ghidra project but check changes into a common repository +containing all commits to that repository. For detailed information on +installing/configuring the Ghidra Server see the +*\*/server/svrREADME.html file. + +### []{#RunHeadless}Headless (Batch) Mode + +Ghidra is traditionally run in GUI mode. However, it is also capable of +running in headless batch mode using the command line. For more +information, see the +*\*/support/analyzeHeadlessREADME.html file. + +### []{#RunJar}Single Jar Mode + +Normally, Ghidra is installed as an entire directory structure that +allows modular inclusion or removal of feature sets and also provides +many files that can be extended or configured. However, there are times +when it would be useful to have all or some subset of Ghidra compressed +into a single jar file at the expense of configuration options. This +makes Ghidra easier to run from the command line for headless operation +or to use as a library of reverse engineering capabilities for another +Java application. + +A single ghidra.jar file can be created using the +*\*/support/buildGhidraJar script. + +([Back to Top](#top)) + +[]{#Extensions}Extensions +------------------------- + +Extensions are optional components that can: + +- Extend Ghidra\'s functionality with experimental or user-contributed + Ghidra plugins or analyzers. +- Integrate other tools with Ghidra, such as Eclipse or IDAPro. + +Ghidra comes with the following extensions available for use (and by +default uninstalled), which can be found in the +*\*/Extensions directory. + +- **Eclipse:** The GhidraDev Eclipse plugin for a pre-existing Eclipse + installation. For information on installing and using the GhidraDev + Eclipse plugin, see + *\*/Extensions/Eclipse/GhidraDev/GhidraDev\_README.html. +- **Ghidra:** Ghidra extensions (formerly known as contribs). See + [Ghidra Extension Notes](#GhidraExtensionNotes) for more + information. +- **IDAPro:** IDAPro plugins/loaders for transferring items with + Ghidra. + +### []{#GhidraExtensionNotes}Ghidra Extension Notes + +- Ghidra extensions are designed to be installed and uninstalled from + the Ghidra front-end GUI: + + 1. Click **File → Install Extensions** + 2. Check boxes to install extensions; uncheck boxes to uninstall + extensions + 3. Restart Ghidra for the changes to take effect + +- Extensions installed from the Ghidra front-end GUI get installed at + *\*/.ghidra/.ghidra-\[version\]/Extensions. + +- It is possible to install Ghidra extensions directly into the Ghidra + installation directory. This may be required if a system + administrator is managing extensions for multiple users that all use + a shared installation of Ghidra. It may also be more convenient to + manage extensions this way if a Ghidra installation is only ever + used headlessly. + + To install an extension in these cases, simply extract the desired + Ghidra extension archive file(s) to the + *\*/Ghidra/Extensions directory. For example, on + Linux or macOS: + + 1. Set current directory to the Ghidra installed-extensions + directory: + 2. Extract desired extension archive file(s) to the current + directory: + 3. The extension(s) will be installed the next time Ghidra is + started. + + To uninstall extensions, simply delete the extracted extension + directories from *\*/Ghidra/Extensions. The + extension(s) will be uninstalled the next time Ghidra is started. + + **NOTE:** It may not be possible to uninstall an extension in this + manner if there is an instance of Ghidra running that holds a file + lock on the extension directory that is trying to be deleted. + +([Back to Top](#top)) + +[]{#Development}Ghidra Development +---------------------------------- + +Users can extend the functionality of Ghidra through the development of +custom Ghidra scripts, plugins, analyzers, etc. + +Ghidra supports development in Eclipse by providing a custom Eclipse +plugin called **GhidraDev**, which can be found in the +*\*/Extensions/Eclipse directory. For more +information on installing and using the GhidraDev Eclipse plugin, see +*\*/Extensions/Eclipse/GhidraDev/GhidraDev\_README.html. + +**NOTE:** Eclipse is not provided with Ghidra. The GhidraDev Eclipse +plugin is designed to be installed in a pre-existing Eclipse +installation. + +Ghidra scripting API javadocs can be found at +*\*/docs/GhidraAPI\_javadoc.zip. + +([Back to Top](#top)) + +[]{#Upgrading}Upgrade Instructions +---------------------------------- + +### []{#GeneralUpgrade}General Upgrade Instructions + +**!!!Important!!! BACKUP YOUR OLD PROJECTS FIRST!! !!!Important!!!** + +- Backup by manually copying the *.rep* directory and *.gpr* file from + any Ghidra project directories to a safe location on your file + system. + +New installations of Ghidra will, by default, use the saved profile from +a user\'s most recent version of Ghidra. This allows any saved tool +configurations to be automatically ported to new projects. However, this +may also prevent new tool options and features from automatically being +configured in some cases. To open new tools containing the latest +configurations, users should, from the Project Manager Window, choose +**Tools → Default Tools\...** + +When you open a program that was created using a previous version of +Ghidra, you will be prompted to upgrade the program before it can be +opened. The upgrade will not overwrite your old file until you save it. +If you save it (to its original file), you will no longer be able to +open it using an older version of Ghidra. You could, however, choose to +perform a "Save As" instead, creating a new file and leaving the old +version unchanged. Be very careful about upgrading shared program files +since everyone accessing the file must also upgrade their Ghidra +installation. + +### []{#ServerUpgrade}Server Upgrade Instructions + +- Please refer to the*\*/server/svrREADME.html file + for details on upgrading your Ghidra Server. + +([Back to Top](#top)) + +[]{#Troubleshooting}Troubleshooting & Help +------------------------------------------ + +### []{#LaunchIssues}Launching Ghidra + +When launching Ghidra with the provided scripts in +*\* and *\*/support, you may +encounter the following error messages: + +- **Problem:** *Java runtime not found.* + - **Solution:** A Java runtime (java/java.exe) is required to be + on the system PATH. Please see the [Requirements](#Requirements) + section for what version of Java must be pre-installed for + Ghidra to launch. +- **Problem:** *Failed to find a supported JDK.* + - **Solution:** The Ghidra launch script uses the Java runtime on + the system PATH to find a supported version of a Java + Development Kit (JDK) that Ghidra needs to complete its launch. + Please see the [Requirements](#Requirements) section for what + version of JDK must be pre-installed for Ghidra to launch. +- **Problem:** *Exited with error. Run in foreground (fg) mode for + more details.* + - **Solution:** Ghidra failed to launch in the background and the + error message describing the cause of the failure is being + suppressed. Rerun Ghidra in the foreground by setting the + LAUNCH\_MODE variable in the launch script you ran to **fg**. + Alternatively, you can use the + *\*/support/ghidraDebug script to run Ghidra + in debug mode, which will also allow you to see the error + message as well as additional debug output. **NOTE:** By + default, running Ghidra in debug mode listens on + 127.0.0.1:18001. + +### []{#GhidraHelp}Using Ghidra + +There are several ways you can get help with using Ghidra: + +- Tutorials and other documentation can be found in + *\*/docs. +- When Ghidra is running, extensive context sensitive help is + available on many topics.  To access Help on a topic, place your + mouse on a window, menu or component and press \.  Help for + that window/menu/component will be displayed. +- When Ghidra is running, indexed help can be found under **Help → + Topics\...** + +([Back to Top](#top)) + +[]{#KnownIssues}Known Issues for current release + +### []{#CommonIssues}All Platforms + +- Displaying the correct processor manual page for an instruction + requires the installation of Adobe Reader 8.0.x or later.  Adobe + broke the goto page in Reader version 7.x.  If a newer version of + Reader is not installed, then the manual for the processor will + display at the top of the manual.  Using an Adobe Reader version + later than 8.0.x works for most platforms, but some platforms and + version of the reader still have issues. +- Some actions may block the GUI update thread if they are long + running. +- Project archives only store private and checked out files within the + archive.  Project archives do not support server-based repositories. +- When using a Ghidra server, all clients and the server must have a + valid Domain Name Server (DNS) defined which has been properly + configured on the network for both forward and reverse lookups. +- Image base may not be changed to an address which falls within an + existing memory block. +- Language versioning and migration does not handle complex changes in + the use of the context register. +- Ghidra will not launch when its path contains a \"!\" character. + This is to avoid issues that Java\'s internal libraries have parsing + these paths (\"!\" is used as a jar-separator by Java). + +### []{#WindowsIssues}Windows + +- Older versions of 7-Zip may not be able to unpack the Ghidra + distribution file if it contains any files with a 0-byte length. + Upgrade to a newer version of 7-Zip to fix this problem. +- Ghidra will fail to launch when its path contains a \"\^\" + character. + +### []{#LinuxIssues}Linux + +- Ghidra may not display correctly when run from a Linux remote + desktop session that uses 32-bit color depth. Setting the remote + desktop application\'s color depth to 24-bit has been known to + improve this issue. +- Some users have reported Ghidra GUI rendering issues on + multi-monitor thin client setups. These problems are attributed to + reported bugs in Java, which will hopefully be fixed in the future. + Disabling the 2nd or 3rd monitor may be necessary to work around the + issue. +- GUI icons may not render correctly in some configurations of Linux. + Setting *VMARGS=-Dsun.java2d.opengl* to **true** in + *\*/support/launch.properties may fix this issue. + +### []{#MacOSIssues}macOS (OS X) + +- Building new Ghidra module extensions on macOS (OS X) using a + network drive (including a network-mapped home directory) throws a + Java exception. This issue is known to the Java/macOS community but + a fix has not yet been released. See + *\*/Extensions/Eclipse/GhidraDev/GhidraDev\_README.html + for more information on building Ghidra module extensions from + Eclipse. + +([Back to Top](#top)) + +\ +\ +\ diff --git a/sources/GhidraDocs/images/B.gif b/sources/GhidraDocs/images/B.gif new file mode 100644 index 0000000000000000000000000000000000000000..49b267ab77a8967611521f6e019cfb8af9f3e2c2 GIT binary patch literal 553 zcmW+zyK0nC7#vYhQm3&L?2g?uiv2D=z4>fB*vu;0Qn!DVuUpc2%fSRjQ_1R9y}^ z<&vAc$lD3p0sO|FE0>lq#I1`XE|@vA?@A>mQ7!y@T<*d$fVU>$U0r)-yP1C-FtcXl1PV6Zz^v}q;m*@h>*`~H+%Wuy^r_!!{f(~_qet8VC7{675v6| zf{PVgRFI#7;4qIl{CGU(SaX_XXaEO4YbNZAe9@u(!*g6l9X zWDUf1C;_JmYRxod7}E17C54y*2FQRIP=JGcX2f*BuuHE)sVLgSxlOc-{D<}ufEG$MaJ~9`v4Q0WZ zg~b+316duhfU3eNU=g@XHVcbr88kA~V+e(+GYgA|4Ezjk3|ql+3RuK+3S*FEh+`-P zC!ZOo9EQ{$`;xtLTLod7qm+Y?U5_0}CD=wmn5Isdh73J=l2T9+^z7!vqC|+#(o}JFwBYt+q+75yWj50y2$kwJ1az=g1aY zNk}A!>@{u^Zo7EM9Rx`sQ-!JSAeF_DMn$;iCY{-PF!Pw<2gAq5JZ(Q&efXk=8h+s{ z(fNwbD=JP=bWp?|d^((RYBq_)so92b>s=GWImP0hMG&a1FMN zyosa%CE(RTW0+;snn6G*DZ~u0Kn^5;0z4Em6J{go9)m8WqUaE77VR9(1Puk@p-wYp zHl{WVhLnAZlt?Y&9AN@q!S&$KkQu4TfRv=*3^NOxBTtYhC=cE|EXJ@QavzBc<-nVV z#Wrjcc>{@ns>3T`5x7V;4~uA9G;=f(2!*;g4~vK`!W@1ASHba0Sj21wYmw(j5-0_) zn3-lAYnp&V$^MzGk}$(b#*t<(U{_KJc2E*#XfkG+I$$6v1w{!96PgjT9(9+2qU=zt zUBtqaX3We`4;l0+({o|}V}T`MB`lnto}QeX93LMa9UTn@gZ=&eG)=d+x8pe8+}sSq zaARY`_x<(tb=P%Ut(N0B%gf74OH0*im4Bx@J9|+S6>h-dxw9&|*oxfvbGZUkaJRTE zenbseXyVesRrzJ->zjqj?Ps4?c6Z;_Dy#RudE>{pa_{EiyRGry{k2=KzyE&uak#bk Up!)OGk3Cn5=Z7EetX#*Vf2#?v#Q*>R literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/GHIDRA_1.png b/sources/GhidraDocs/images/GHIDRA_1.png new file mode 100644 index 0000000000000000000000000000000000000000..659c3f9d9c33db40d31f014375db95e6e2d5444c GIT binary patch literal 189819 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

FpGh+&{h&+QPCjM{<3P0qQG;m{ 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 literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/I.gif b/sources/GhidraDocs/images/I.gif new file mode 100644 index 0000000000000000000000000000000000000000..88b7a0478302ebda3a9ded2857523d53f4975a87 GIT binary patch literal 868 zcmZvbKWG#|9EIPaMXGSvT}WZT2|+Bpt^C6Uw9vT~WDAqC2mzOL3qhD}3t16jA(;zX zELI_bAhOrEO}OonAa@`bP^Jpgcn87qNTVX$bCb^8J(zjS@PpywV;(mi-MRasf(m}& zJn_YfFDfoiaePq59(?#Rb|f>w3^qX#Aq}8B_%1jw?B#50wn8e&rr;86 z14SKa4NAbTg2phN=4BmmMj_t>M3dp!bg>6 z$h=Q&7BUp=~K$=1+ z_~pznXJ6BV>`HddZH);t9OUe2wnMfgm0%NN!VFE$TvLY(C8eMk!@_{3$GlD5VyGya z6ib(}Fr?`-H`HB*9m?!N*#B7In6NP{oSmJWo}QkZoE#q?9~~X-@9$?>w!OWbB+16c zMifQs>+3-fEH5v6p0~KT=(_Iw{QS(!%=Gj${|_t*M5HA`})ptaQ`1yPq5nn literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/L.gif b/sources/GhidraDocs/images/L.gif new file mode 100644 index 0000000000000000000000000000000000000000..71667ab326fb30a287335646df9409dc6dad6188 GIT binary patch literal 863 zcmeH`F=!M)6o$V*iiph?DRN+8kO2h?_X<(t38Lui6*5goCwT3a(_OWoC@5^?kg2Ui zE*5T=0gI%`NlMvrs!L&er8f7wq>NWv`N8Ay;5Fal{ZET0ckaH($oTn&j_SOs^Hz0J zRULJtqfe&`En3YRwY5%49a>F|rlbjROc>#ZxIQ{-HEVQGYrmAY+B4cE6~qA{#~WM^ zwXK>)b*-|LwK8T22_gjW;OKVF)XY>LsN9$JGJ9e-QA7rT++!R)wF@<{9 literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/U.gif b/sources/GhidraDocs/images/U.gif new file mode 100644 index 0000000000000000000000000000000000000000..975f78da36debc219510b60473530bc63aab2074 GIT binary patch literal 881 zcmZvbF=!J}9LB%WBE?F{QZPY;7GAI*Vh#sI(m|wNPLx~PI5_Az$w8O5=;3f!s33TO z0}otEgi_?PcuUD`HIzggI>?*KTTDvlw2O$4&uce(`QW{e_xQu($B*}*wtV}}^8yO^ zjnnvN%RehWJNf=@7QMUuW5}UmKcNcPb=fu<3&zkPQV)>>X~8zYfnqOVD`3N=G+7s1 zfvzE~BC0?N*hNq&CJBRpu1nLT5F~Qe zic~`;eFlndmu8zHCSr{+g%`n*uxuDqWI_g{OPZwM2qO)hB8?D9NE`MzEQZh?QU{R* zX}}(b#Ts-KX$6shEW*xV5jama4vVO1R8v$U2#KOS4vPpiycA9ZOTw^oSj1=qt&ygP zB1j24n;9nT2UIS*CfldBa>5h`33~xsE*mDLU>!MOiYj3eFmUObGzCQt3j?YilNN&p zT}iV}v2q>@L#jR##h^>KO*1|d_CFSw6PClm$;rvl(b2)d!T$b!r_1jXJ`3$*lce3zMr`Pv*%7L>uk$1|7U6f zn85YyHv16;VEQp8r>~e_o8Q(iOk8_<`Pt`tZ*i%1YpVHc@BQSQ_2$d*{N9J+VtH!u s=0dlz@NoP7>z{|;Ki-&G-g=U}=zN-ac~!kSK790Udi~;Dserrx09Ed^>i_@% literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/V_slash.png b/sources/GhidraDocs/images/V_slash.png new file mode 100644 index 0000000000000000000000000000000000000000..c0d71a7021c47306dc2dabb6d09dbed92ec02488 GIT binary patch literal 281 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`jKx9jP7LeL$-D$|*pj^6U4Zmf zhOgfl8^wVv&H|6fVg?3oVGw3ym^DWND9B#o>Fdh=fJIWslI@pEKpId;vcxr_#5q4V zH#M(>!MP|ku_QG`p**uBL&4qCHz2%`4`f)0r;B5V#p$yXck>=l;Bkq6mGeMyljpNk z;j{$itmTUF2Z|=OP0sLp_A}?OK$jBN7rD0cTf|)ir%h3KGI`Ir>fW+Hv%h!<6`Q90dYbKBc^}HEJc*x>_3!CMz{a2h z$_b!6!N3v6z{?=vu|dI+nS)U#;>3o9P7IvE7{DV*mPlteD7bm;KA)Q)c#ZfxM&>^^Kt8@}X5Ie=bVzn=MFZUjYdmCwDp#8yF z?&W;~#$GgC@+%sc?o-nF-4K&3zot+3`G-N|qHL0AClfCI!0+R;~5E9JhUc8y*0 zgRr2Ksyl-nRx9N`FZN5m<_F>B6o5$@06Yoq1O;-yCpRWNt^ zfO6d$BtPv6bd&jqH<+24V6D2ro!J-E-#%dO?iHRsUjs4RyVW3l<|40FJ^-9{2B8H= z3o#MHS(v_gp29?qck7=p$u6QJ#6*Z`{aZRHXRu=drU@d5{)LzrkpwaOwn1V+|z`(|!17rhL z3NSD*n`G>|6DwdP_S&TIse0-1`%7~sEA%8P^Dv90IldO%ELbdh_T2-vJ4$Q@DB{M6?B9ctN}~YB=-OS literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/disk.png b/sources/GhidraDocs/images/disk.png new file mode 100644 index 0000000000000000000000000000000000000000..99d532e8b1750115952f97302a92d713c0486f97 GIT binary patch literal 620 zcmV-y0+aoTP)~H+MJzd|s z^YP1Hc07G_>)Lgir!F1{Qn4GcTg%?koHo<=1qRN{}nPDolOeI^o4N5I>! zU$N=L=sg~ zDx#dOA*B0N~cqPsWI(^rbbkh)DS0_H_UN0C4l_kvWIm2#Kyy6%BCh z(yIUf003&1xdx>t$*eR2ZvXxT0001Z_R$y3Iju92q*wg58};}zm(OaAH=p|y0002M zh5O5#fxp|~jc?yi@+7$`d4Q6Hl%z;WiWG??NXR{Hx%)pMd~SE0000OQI literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/document-properties.png b/sources/GhidraDocs/images/document-properties.png new file mode 100644 index 0000000000000000000000000000000000000000..ab0e8ea377db9a6bb702f0a374b75841bcab0b62 GIT binary patch literal 464 zcmV;>0WbcEP)r z=%QrMoYg6I5Q8zI2z{r+`*EJ{?;HUbkH_CZ5WMl6-uwOj7XYs79-o!#x<`QQC33&t z6GagKA`<)Ovxtz%WH3!LjwJw56yf`R;=-jwgnGT6@Uqv9)oL{Wdc9ukbvhkNrBVtA z@N%8O_kC8Y743E#tu`Ffm|-fd_JdAsoVyL2ui8cJ8&F_^?HqA807Q$$M4`YxFn>} zXs}!^?*lG}b}iF1DVNJBKMP>n_RnB2czxz8+P3}4f9Mb3j-%#nF`Fa+0000&A-ej;gyuG&s$%wkdfKA;H|vEO|L+|vIXqdaF_A89qTKGV%LqLqA&{k|D2>yV7qLmg~*x1@cbjz3zP!z2FhV16<-TNNz zuIz$fLNt0{xWmll%$dUkM1*+|PHJ2ZGvdmC35A3UoF6R(-~DS$BH+@Xy#VYsLyQ>z zxq>v8$ny|FSR~0W2u4ic`k5mcbEIiLksz4Y#KyE{9LLn}_oq&%6$}Oga?Zh83$3-^ zU4V1$eaMkz85m>bTh*c{3ch%tltQ=L4Q7$u>-Ff*JP6K)r(~Ul_41v6uR1rSij#*! zl14&E?hS3Iagod#Oo#p}d7WbijUO{Mqc5?@<$>unxw*22 z?bQuGkPsSMOgEm)qR1=cLLyZOm>T65_V?)|o0p=i_uUiST44Cz-W mqJp!8r`H!$*8T4x&4Leh&Epbde3h>N0000@<_-eJUEzeVCjP{!CMd6l-4+GmSw0uY%c1!IOGXX OKZB>MpUXO@geCw_@BkYSfQDeEO1Dg_KqE_4P)QTxJ`x_{ zHlhNGh6rVyZiSYlQKDL;;t-CHoQI4JT_C9;MoGG)MH-|^Dr}(P!}s9Xumyw$trZq? z@H6mq*hz>Ov{qP5z>mX=!d4(6(3-Fa93*RnMI?O0Jw$CN0uikh7LoIj@u1sC3dFP~ zETYkX@5A$8+Yka;FjIF~u_z6eR2KJaH3^ffx-45P7|f~^3e#v3CMjLI7A=E@N>!oK zgoP?)nQnnrmWH63rZRpI3w6p0T}i7%qe#`+7xq6E*d(k83%k3!wOVa^dwX+pbA5e% zb#>KooW;e(TrM{^HpIadjm>hK{a*>-Sa`-p+@6+wL62SYh_qshc0a zOzH3L|J?b|UO&97;@jCa^T^D}LA!tQTbCaXOumucOzq0k{%coXztElxJ?x!7 xKRngFw2^Y(UwAgKF!AXTcK&W{-2HLxLAN_J@qOqvX1lhQZWy2QUl9u7%s-|%&Cmb< literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/notF.gif b/sources/GhidraDocs/images/notF.gif new file mode 100644 index 0000000000000000000000000000000000000000..9b5fbc0cf8bfb4a158d6ea0a3420d204003f848f GIT binary patch literal 882 zcmZvbF=!J}9LB$33qhn*K`^C4wY(zYU=G2Gq>E55hv+R$aI?1_bnrPH4ku!8y3`wP zENK;y%i=kd+*VVYfJ3J@g*Qk7okKf_2>HBrv&jeVeZ0pX9zTA($K}=K2kWz##c!O( zKU@A;`Ps?$_p<1{&p(G8D)tkqfE|}Dld)h79U}D*Igl1?0~{!J6E*|ZT}qQx!8PbI z(h{N~q<~!jm12@G2`%jAORcM%z#OkL6dHsrlhD6YZ~Pgr3gg{VWU7b zWYTA#=yqtfC}JYk2vc|w90|*YK}9BHK)R$!3XU++&?(Xgk%Y8iPr_md?ICp#S&#_81m18bNEMDWV8c z!p>%f3Ht$+%Z|y`sjV?#ii3pRfK8WmlTxsXF=2`-VG=NK>6$bJ#TXU_R9z-b26eiU zW|d;?JQjvjeI|-Qhi;2zd?xIFEO1QN7#5C?kB^RydcEG^;bFVo-re1e<9KUpD-6S0 zt>$^&#>R%@IF(ApvaFSr6~i!=mX_w`=4NJQ_;=W7eDZxia|342omSS_mgUBusT`2Q zo$NOI5wk%487}1K&99B`Z>LXkc{H~7Yty+~Q!l>k9K5@HwetFXaq%F?7oNVl_HBFh q(Zb@+{PUL|+nbl}TTjZHH?0r%rh7k@Pk!ycxw3xo`t7?5c=!(tNVGHn literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/notes.gif b/sources/GhidraDocs/images/notes.gif new file mode 100644 index 0000000000000000000000000000000000000000..38168ce839605d0604664240446f11f0dfd36f68 GIT binary patch literal 866 zcmc(ey-M6s5XDa*fh+_}iaO5eaLYBT1R`ODmvQ!Oi0*O(2DRLVhHw&{gt6t3A-NG&1s(DcM zun5brYFc!ATBK!KHA{xQEXuO1nlvI{4NZ7Kgw3o18!)D6r_KW>+|#{UA&a?3c!pOC zh6m+H&-7~j(4srav%K04+`=CGzyK5@5lx7IH8kM`5jF!2HegKCPMrr%MpRpgLKbt+ zjA~~Q3=hg#QEfD_kORi!G}huJ=HV9h;0Fev7>SSu3)awt7ev?$G}wSKO*?fSIMtb9 zB??*0y*fhjCvXxbQZghoQX&>|z<8X-TD-&#STc+s7=U6VLK-YsLla&QVKdNR1I9G% z)Oq0aFYy^ZA0J-6kZv?H-aYpjHdh=?2?Ze%_rQh$S ox3-V3H!prn55AA?ua3U#O%7HcH|B2t?!Oo^^BKu&iCH? zJy%qflaQM4(Ce3g^6yfUoY&H7J4|rn2C}~BVnuaSE4VV^oM{8FKaL1Ag-C-#`<`y? z1PKGVGrxkNFUgvDis=lt%sv$i!OG!&BeKS3XWVoe}&y> zj}QINiShUrDqjw|M9zwC?F0q@R#Ycz<|#M=u zFpj#h1zZ`?>z53me7x;H;DVcDV`-Il@ouJ?vT>U5Z(spU_Q%m_q#r?#N1vW?|NUbo zI++%ynx;k0Yq7hRB2rH7VQ@I2JNU}&H+N^hG*SpOMb2v(T5X4jH0TTmaq+=8;K9cy zlwRFR=AknjAkxrkJ3Moc{!f&TaHeC5<6qAC7Z^O`>TW}{+5i9m07*qoM6N<$f>ba1 A#{d8T literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/play_again.png b/sources/GhidraDocs/images/play_again.png new file mode 100644 index 0000000000000000000000000000000000000000..11fad1a750982523a644416eb0f71a8d43c21421 GIT binary patch literal 563 zcmV-30?hr1P)mtOO)WGxIaq-e5;7!PZ;WBs5 z9Om3RqNDwl~*aCQBs2{wc`1bCoxffgdw&~i5#De-I_K$bS2jQKM>+Ww< zzvS{V+amSMJ$?H1$FNDH44|qtnYzla4}bHmUj^1xwK0>xfN&bv1a1QtfEsWxMp*;4 zRkdbZzGlGoAV5_o25<@Z02C*2oE99GjH+5!?H`I$;~R7kKHC5Q002ovPDHLkV1nxY B|JeWl literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/redo.png b/sources/GhidraDocs/images/redo.png new file mode 100644 index 0000000000000000000000000000000000000000..88035efeec2a63f14a19433d0f82255e00ee4afd GIT binary patch literal 187 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!73?$#)eFPFP2=EDU{r~?zkjc=%(9i&)fHaU; zv}jR7Ljy?SKLc1ENPt*CpgCP>15li?B*-tA!Qt7BG$6;))5S5Q;#TijYd!`A9;Sd9 zyAC}uy}M`MgbIepU%x!LYMxf?x0=YX+_1INQ0#_jcbwIMR|^*W+ovLKti`;>#4K+T P&=3YsS3j3^P6~8&^BNXqw$@AekqAsLX(YVXpvB V!;Q%=qJbtcc)I$ztaD0e0ssNkLMH$K literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/right.png b/sources/GhidraDocs/images/right.png new file mode 100644 index 0000000000000000000000000000000000000000..e6d41926bad3d250d62f3f82be954c50506c9590 GIT binary patch literal 190 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!73?$#)eFPFP2=EDU1=0;*+yJH;fV_r=0|yQ? zG&KANivMT$|DVBQ%P$}eWC1||yCM@%oV_H-FBmNFpFzr-*$pUU=IP=XQgJKU!@HTG z%_PN*NxG+y;h4qYX~!7Y()pGcewf3^Y$oxTfvuT$p~O1bs}5!*-i|yB*NZJ`b)!Ry QfhI6`y85}Sb4q9e0A+bS!vFvP literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/sitemap_color.png b/sources/GhidraDocs/images/sitemap_color.png new file mode 100644 index 0000000000000000000000000000000000000000..c64582bcd4f2c8d04451e6ca914ab06df6ac211c GIT binary patch literal 406 zcmV;H0crk;P) zk}*reKp2Lbf0AEO7ypA}amXNqYyp>Y;Fci-g4`}4WOLWH+9@cGQs}0F*iEjOG*W}4 zm%wK(ZQw2m_=MnyjyI)bdn5JojW9_ApWwoHWG)HAlBv>up3c{Bd7V)Nj z@iR8U_45rBpRWSDU5?-*Tkw3&gP5hEC2ui07*qoM6N<$f(bUU AHUIzs literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/table.png b/sources/GhidraDocs/images/table.png new file mode 100644 index 0000000000000000000000000000000000000000..abcd93689a08ec9bdbf0984927e8da06c043c7cd GIT binary patch literal 566 zcmV-60?GY}P)>q?GuNnCdgP^*Bj5V_b?dAq2Ppn9^MBB^YUM zad0N-T{Ujg*A6d~mYV4na=hT4Nz+_}SGTgW|Iir!%$ z;@OGkWI6+j0H}~K4RYR%!7y|zM`O@*K>rL{*&}x3lR**HrMXC1->#slU>X|w!U1xQ zqc&Lm&p%aeyiM6U{&J)Zzehs6~qcg z1!K+DX=Sr^zrF)w?A~pFj1Mhkw|6ytB@m3*Ef1_!0J{5Ay8>LU$tBzlkaYmSjnfHU z4a{=AA%8R1Gc-$c-Bvue80=JFtfI~l^`U1lh3|Xx4yA~A;H@{^>pDl;EYVc{nu?-B zgeC*uF;DGCO|}YDsT!>58jRZ!uO%| z#aWyhLKQ+0j^vh5T5yV`V1?G+DzbUD4Iqkhjw~N8oy?y)Yaaf}M024fA2YfDrYonhIm@?o-n z-UASkj0YZ^uZk1(A&>yELViv$1v$q!d@xCtA0sdOD5KK@e4O~oYDmqN2hLGZe1M<7 z(;Ux_k(M<&2Okq^NFX7}co}ucMuw;Q8J!uUBKA~!+FL%aKO{HM-aTF&THSBNV#E@Y zZlYEZE93y5W*UijF$TuJP_pL<3oD7Y0Fm8(=VV)C#j3wAtu~o@15li?B*-tA!Qt7BG$6;^)5S5Q;#P8k0^bJiY0RE( z3b71HhFly>I~~qwL@)^HGZ?WrykcqKnIK|4gHc4QMe2Zt!xUczBN65o6N)Xj0gYhr MboFyt=akR{0Pznvr~m)} literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/images/up.png b/sources/GhidraDocs/images/up.png new file mode 100644 index 0000000000000000000000000000000000000000..b76e535c48e3f15f23a9376f72fbee71e19832e7 GIT binary patch literal 193 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!73?$#)eFPFP2=EDU1=0;*+yJH;fV_r=0|yQ? zG&KANivMT$|DVBQ%P$}eWC1||yCM@%oV_H-FBmNFpFzr-*$pUU>FMGaQgLhPsg1l0 z3OvjQ*9RGXeeE#;0d&1g<&dsx@tpjRw00M!k1rYC|9;Q#?caBxBmXgYhpY0=W6 zGwe*95(&033 znV6pb{QW~UWoF`24rWfiTB}-ykKaEsY<#(qft8sRtc>k18^hlpe;EG!`@_J-%mUKI z01!a1Fo2ly=YOcGv?iCfga*U?kM|jFy}8Bk=j$JaUrfKis($|a$-u(H!tn3Ue}*sL zzx@M=0R#{{41luf>atqXwq$Q+V&!CFNIa6naP`ww25uH^u+u@d{slrF5nhJBzyC43 z{O}HJDnI}+fi?eONKutho3<`}4HF~le}3&}CKuXkrS{rWV60J{Lg$8R4Q zB)Oy*CYeoQFqbf6VEWC(AjK}l@bKj`hVQ?AyaDM22q3TvzW@BbZ`QHd41fOoVTe(Q zVc`11#qjpsTLuXx35G?^3m8O!E?9kX8$-W!AA_HQ55wh0w}659{SHVkKmaj-lX51I zmB6q$W>)uKyUEL_ba2u=qa+6i#ga&tM>5 z1=0%;K!|8$XYgHeXyGn4Mt0ZkfOZCNWiN(bKo5mb&G4W7EGq-&|KGoU%l x86y81q>hyfnDV~;KXjD=Ab=Pt&CUP;1^|O#NU%BBugCxZ002ovPDHLkV1ite$F2YX literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/languages/html/DefaultStyle.css b/sources/GhidraDocs/languages/html/DefaultStyle.css new file mode 100644 index 0000000..4e712f3 --- /dev/null +++ b/sources/GhidraDocs/languages/html/DefaultStyle.css @@ -0,0 +1,92 @@ +/* ### + * IP: GHIDRA + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/* + WARNING! + Java Help Note: JavaHelp does not accept sizes (like in 'margin-top') in anything but + px (pixel) or with no type marking. + + The blockquote tag is used heavily to control indentation throughout the help docs. Place the + blockquote tag around other elements to create a standard indentation. The default values of + blockquote are: + + blockquote { + display: block; + margin-top: 1em; + margin-bottom: 1em; + margin-left: 40px; + margin-right: 40px; + } + +*/ + + +/* + Add some indentation for lists to show their relation to the preceding text. The value is + chosen based on the left margin of the body and the blockquote. +*/ +ul { margin-left: 50px; } +ol { margin-left: 50px; } +li { font-family:times new roman; font-size:14pt; margin-left: 5px; } + + +h1 { color:#000080; font-family:times new roman; font-size:36pt; font-style:italic; font-weight:bold; text-align:center; } +h2 { margin: 10px; margin-top: 20px; color:#984c4c; font-family:times new roman; font-size:18pt; font-weight:bold; } +h3 { margin-left: 10px; margin-top: 20px; color:#0000ff; font-family:times new roman; font-size:14pt; font-weight:bold; } +h4 { margin-left: 10px; margin-top: 20px; font-family:times new roman; font-size:14pt; font-style:italic; } +h5 { margin-left: 10px; margin-top: 20px; font-family:times new roman; font-size:12pt; font-style:italic; } + + +/* + A class to be used for showing screenshot style images. These images will have padding above + and below the image and will be centered. To apply this to a file path, use this syntax: +

+*/ +div.image { margin-top: 20px; margin-bottom: 40px; text-align: center; } + + + +/* + P tag code. Most of the help files nest P tags inside of blockquote tags (the was the + way it had been done in the beginning). The net effect is that the text is indented. In + modern HTML we would use CSS to do this. We need to support the Ghidra P tags, nested in + blockquote tags, as well as naked P tags. The following two lines accomplish this. Note + that the 'blockquote p' definition will inherit from the first 'p' definition. +*/ +p { margin-left: 40px; font-family:times new roman; font-size:14pt; } +blockquote p { margin-left: 10px; } +p.providedbyplugin { color:#7f7f7f; margin-left: 10px; font-size:14pt; margin-top:100px } +p.relatedtopic { color:#800080; margin-left: 10px; font-size:14pt; } +p.image { margin-top: 100; margin-bottom: 100; } + + +/* + We wish for a tables to have space between it and the preceding element, so that text + is not too close to the top of the table. Also, nest the table a bit so that it is clear + the table relates to the preceding text. +*/ +table { margin-left: 20px; margin-top: 10px; width: 80%;} +td { font-family:times new roman; font-size:14pt; vertical-align: top; } +th { font-family:times new roman; font-size:14pt; font-weight:bold; background-color: #EDF3FE; } + + + +/* + Code-like formatting for things such as file system paths and proper names of classes, + methods, etc. To apply this to a file path, use this syntax: + ... +*/ +code { color: black; font-weight: bold; font-family: courier new, monospace; font-size: 14pt; white-space: nowrap; } +code.path { color: #4682B4; font-weight: bold; font-family: courier new, monospace; font-size: 14pt; white-space: nowrap; } diff --git a/sources/GhidraDocs/languages/html/Diagram1.png b/sources/GhidraDocs/languages/html/Diagram1.png new file mode 100644 index 0000000000000000000000000000000000000000..2ab61badc1b14b13c6a86335a02a12ded488a7cb GIT binary patch literal 11652 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 L9A2Vx^U;3*djl?J literal 0 HcmV?d00001 diff --git a/sources/GhidraDocs/languages/html/Diagram3.png b/sources/GhidraDocs/languages/html/Diagram3.png new file mode 100644 index 0000000000000000000000000000000000000000..157da0302678692bdf3dc4a4d51e4d97df4fad4f GIT binary patch literal 7139 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%0D8g>2*Ksx*@CPCmw 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 + + +Additional P-CODE Operations + + + + + + + + + +
+ + + + + + + +
Additional P-CODE Operations
+Prev   Next +
+
+
+
+

+Additional P-CODE Operations

+

+The following opcodes are not generated as part of the raw translation +of a machine instruction into p-code operations, so none of them can be used +in a processor specification. But, they may be +introduced at a later stage by various analysis algorithms. +

+
+

+MULTIEQUAL

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode to merge from first basic block.
input1Varnode to merge from second basic block.
[...]Varnodes to merge from additional basic blocks.
outputMerged varnode for basic block containing op.
Semantic statement
Cannot be explicitly coded.
+
+

+This operation represents a copy from one or more possible +locations. From the compiler theory concept of Static Single Assignment form, this is +a phi-node. Each input corresponds to a control-flow path +flowing into the basic block containing the MULTIEQUAL. +The operator copies a particular input into the output varnode depending on what path +was last executed. All inputs and outputs must be the same size. +

+
+
+

+INDIRECT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode on which output may depend.
input1(special)Code iop of instruction causing effect.
outputVarnode containing result of effect.
Semantic statement
Cannot be explicitly coded.
+
+

+An INDIRECT operator copies input0 into output, +but the value may be altered in an indirect way +by the operation referred to by input1. The varnode input1 is not part of the +machine state but is really an internal reference to a specific p-code operator that +may be affecting the value of the output varnode. A special address space indicates +input1's use as an internal reference encoding. +An INDIRECT op is a placeholder for possible +indirect effects (such as pointer aliasing or missing code) when data-flow +algorithms do not have enough information to follow the data-flow directly. Like +the MULTIEQUAL, this op is used +for generating Static Single Assignment form. +

+

+A constant varnode (zero) for input0 is used by analysis to indicate that the output +of the INDIRECT is produced solely by the p-code operation +producing the indirect effect, and there is no possibility that the value existing prior +to the operation was used or preserved. +

+
+
+

+PTRADD

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode containing pointer to an array.
input1Varnode containing integer index.
input2(constant)Constant varnode indicating element size.
outputVarnode result containing pointer to indexed array entry.
Semantic statement
Cannot be explicitly coded.
+
+

+This operator serves as a more compact representation of the pointer calculation, +input0 + input1 * input2, but also indicates explicitly that +input0 is a reference to +an array data-type. Input0 is a pointer to the beginning of the array, input1 is an +index into the array, and input2 is a constant indicating the size of +an element in the array. As an +operation, PTRADD produces the +pointer value of the element at the indicated index in the array +and stores it in output. +

+
+
+

+PTRSUB

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode containing pointer to structure.
input1Varnode containing integer offset to a subcomponent.
outputVarnode result containing pointer to the subcomponent.
Semantic statement
Cannot be explicitly coded.
+
+

+A PTRSUB performs the simple pointer calculation, +input0 + input1, but also indicates explicitly that input0 is a +reference to a structured data-type +and one of its subcomponents is being accessed. Input0 is a pointer +to the beginning of the structure, and input1 is a byte offset to the subcomponent. +As an operation, PTRSUB produces a +pointer to the subcomponent and stores it in output. +

+
+
+

+CAST

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode containing value to be copied.
outputVarnode result of copy.
Semantic statement
Cannot be explicitly coded.
+
+

+A CAST performs identically to the COPY +operator but also indicates that there is a forced change in the data-types associated with the varnodes +at this point in the code. The value input0 is strictly copied into output; it is not a conversion cast. +This operator is intended specifically for when the value doesn't change but its +interpretation as a data-type changes at this point. +

+
+
+

+INSERT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode where the value will be inserted.
input1Integer varnode containing the value to insert.
position(constant)Constant indicating the bit position to insert at.
size(constant)Constant indicating the number of bits to insert.
outputVarnode result containing input0 with input1 inserted.
Semantic statement
Cannot be explicitly coded.
+
+

+The values position and size must be constants. +The least significant size bits from input1 are +inserted into input0, overwriting a range of bits of the same size, +but leaving any other bits in input0 unchanged. The least significant bit of the overwritten +range is given by position, where bits in index0 are labeled from least significant +to most significant, starting at 0. The value obtained after this overwriting is returned +as output. +Varnodes input0 and output must be the same size and are intended to be the same varnode. +The value size must be not be bigger than the varnode input1, and +size + position must not be bigger than the varnode input0. +

+

+This operation is never generated as raw p-code, even though it is equivalent +to SLEIGH bitrange syntax such as input0[10,1] = input1. +

+
+
+

+EXTRACT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode to extract a value from.
position(constant)Constant indicating the bit position to extract from.
size(constant)Constant indicating the number of bits to extract.
outputVarnode result containing the extracted value.
Semantic statement
Cannot be explicitly coded.
+
+

+The values position and size must be constants. +The operation extracts size bits from input0 and returns it in output. +The position indicates the least significant bit in the range being extracted, with +the bits in input0 labeled from least to most significant, starting at 0. The varnodes input0 and output +can be different sizes, and the extracted value is zero extended into output. +The value size must not be bigger than the varnode output, and +size + position must not be bigger +than the varnode input0. +

+

+This operation is never generated as raw p-code, even though it is equivalent +to SLEIGH bitrange syntax such as output = input0[10,1]. +

+
+
+
+
+ + + + + + + + + + + +
+Prev   Next +
Pseudo P-CODE Operations Home Syntax Reference
+
+ + diff --git a/sources/GhidraDocs/languages/html/additionalpcode.md b/sources/GhidraDocs/languages/html/additionalpcode.md new file mode 100644 index 0000000..0c1aa84 --- /dev/null +++ b/sources/GhidraDocs/languages/html/additionalpcode.md @@ -0,0 +1,436 @@ +--- +status: collected +title: Additional P-CODE Operations +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/additionalpcode.html +--- + +::: {.navheader} +Additional P-CODE Operations +::: + +[Prev](pseudo-ops.html)  + +  + + [Next](reference.html) + +------------------------------------------------------------------------ + +::: {.sect1} +::: {.titlepage} +
+ +
+ +[]{#additionalpcode}Additional P-CODE Operations {#additional-p-code-operations .title style="clear: both"} +------------------------------------------------ + +
+ +
+::: + +The following opcodes are not generated as part of the raw translation +of a machine instruction into p-code operations, so none of them can be +used in a processor specification. But, they may be introduced at a +later stage by various analysis algorithms. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#cpui_multiequal}MULTIEQUAL {#multiequal .title} + +
+ +
+::: + +::: {.informalexample} +::: {.table} +[]{#multiequal.htmltable} + +[**Parameters**]{.bold} +::: +::: +::: +::: + +[**Description**]{.bold} + +input0 + +Varnode to merge from first basic block. + +input1 + +Varnode to merge from second basic block. + +\[\...\] + +Varnodes to merge from additional basic blocks. + +output + +Merged varnode for basic block containing op. + +[**Semantic statement**]{.bold} + +[*Cannot be explicitly coded.*]{.emphasis} + +This operation represents a copy from one or more possible locations. +From the compiler theory concept of Static Single Assignment form, this +is a [**phi-node**]{.bold}. Each input corresponds to a control-flow +path flowing into the basic block containing the +[**MULTIEQUAL**]{.bold}. The operator copies a particular input into the +output varnode depending on what path was last executed. All inputs and +outputs must be the same size. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#cpui_indirect}INDIRECT {#indirect .title} + +
+ +
+::: + +::: {.informalexample} +::: {.table} +[]{#indirect.htmltable} + +[**Parameters**]{.bold} +::: +::: +::: + +[**Description**]{.bold} + +input0 + +Varnode on which output may depend. + +input1 + +([**special**]{.bold}) + +Code iop of instruction causing effect. + +output + +Varnode containing result of effect. + +[**Semantic statement**]{.bold} + +[*Cannot be explicitly coded.*]{.emphasis} + +An [**INDIRECT**]{.bold} operator copies input0 into output, but the +value may be altered in an indirect way by the operation referred to by +input1. The varnode input1 is not part of the machine state but is +really an internal reference to a specific p-code operator that may be +affecting the value of the output varnode. A special address space +indicates input1\'s use as an internal reference encoding. An +[**INDIRECT**]{.bold} op is a placeholder for possible indirect effects +(such as pointer aliasing or missing code) when data-flow algorithms do +not have enough information to follow the data-flow directly. Like the +[**MULTIEQUAL**]{.bold}, this op is used for generating Static Single +Assignment form. + +A constant varnode (zero) for input0 is used by analysis to indicate +that the output of the [**INDIRECT**]{.bold} is produced solely by the +p-code operation producing the indirect effect, and there is no +possibility that the value existing prior to the operation was used or +preserved. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#cpui_ptradd}PTRADD {#ptradd .title} + +
+ +
+::: + +::: {.informalexample} +::: {.table} +[]{#ptradd.htmltable} + +[**Parameters**]{.bold} +::: +::: +::: + +[**Description**]{.bold} + +input0 + +Varnode containing pointer to an array. + +input1 + +Varnode containing integer index. + +input2 + +([**constant**]{.bold}) + +Constant varnode indicating element size. + +output + +Varnode result containing pointer to indexed array entry. + +[**Semantic statement**]{.bold} + +[*Cannot be explicitly coded.*]{.emphasis} + +This operator serves as a more compact representation of the pointer +calculation, input0 + input1 \* input2, but also indicates explicitly +that input0 is a reference to an array data-type. Input0 is a pointer to +the beginning of the array, input1 is an index into the array, and +input2 is a constant indicating the size of an element in the array. As +an operation, [**PTRADD**]{.bold} produces the pointer value of the +element at the indicated index in the array and stores it in output. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#cpui_ptrsub}PTRSUB {#ptrsub .title} + +
+ +
+::: + +::: {.informalexample} +::: {.table} +[]{#ptrsub.htmltable} + +[**Parameters**]{.bold} +::: +::: +::: + +[**Description**]{.bold} + +input0 + +Varnode containing pointer to structure. + +input1 + +Varnode containing integer offset to a subcomponent. + +output + +Varnode result containing pointer to the subcomponent. + +[**Semantic statement**]{.bold} + +[*Cannot be explicitly coded.*]{.emphasis} + +A [**PTRSUB**]{.bold} performs the simple pointer calculation, input0 + +input1, but also indicates explicitly that input0 is a reference to a +structured data-type and one of its subcomponents is being accessed. +Input0 is a pointer to the beginning of the structure, and input1 is a +byte offset to the subcomponent. As an operation, [**PTRSUB**]{.bold} +produces a pointer to the subcomponent and stores it in output. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#cpui_cast}CAST {#cast .title} + +
+ +
+::: + +::: {.informalexample} +::: {.table} +[]{#cast.htmltable} + +[**Parameters**]{.bold} +::: +::: +::: + +[**Description**]{.bold} + +input0 + +Varnode containing value to be copied. + +output + +Varnode result of copy. + +[**Semantic statement**]{.bold} + +[*Cannot be explicitly coded.*]{.emphasis} + +A [**CAST**]{.bold} performs identically to the [**COPY**]{.bold} +operator but also indicates that there is a forced change in the +data-types associated with the varnodes at this point in the code. The +value input0 is strictly copied into output; it is not a conversion +cast. This operator is intended specifically for when the value doesn\'t +change but its interpretation as a data-type changes at this point. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#cpui_insert}INSERT {#insert .title} + +
+ +
+::: + +::: {.informalexample} +::: {.table} +[]{#insert.htmltable} + +[**Parameters**]{.bold} +::: +::: +::: + +[**Description**]{.bold} + +input0 + +Varnode where the value will be inserted. + +input1 + +Integer varnode containing the value to insert. + +position + +([**constant**]{.bold}) + +Constant indicating the bit position to insert at. + +size + +([**constant**]{.bold}) + +Constant indicating the number of bits to insert. + +output + +Varnode result containing input0 with input1 inserted. + +[**Semantic statement**]{.bold} + +[*Cannot be explicitly coded.*]{.emphasis} + +The values [*position*]{.emphasis} and [*size*]{.emphasis} must be +constants. The least significant [*size*]{.emphasis} bits from input1 +are inserted into input0, overwriting a range of bits of the same size, +but leaving any other bits in input0 unchanged. The least significant +bit of the overwritten range is given by [*position*]{.emphasis}, where +bits in index0 are labeled from least significant to most significant, +starting at 0. The value obtained after this overwriting is returned as +output. Varnodes input0 and output must be the same size and are +intended to be the same varnode. The value [*size*]{.emphasis} must be +not be bigger than the varnode input1, and [*size*]{.emphasis} + +[*position*]{.emphasis} must not be bigger than the varnode input0. + +This operation is never generated as raw p-code, even though it is +equivalent to SLEIGH [**bitrange**]{.bold} syntax such as input0\[10,1\] += input1. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#cpui_extract}EXTRACT {#extract .title} + +
+ +
+::: + +::: {.informalexample} +::: {.table} +[]{#extract.htmltable} + +[**Parameters**]{.bold} +::: +::: +::: + +[**Description**]{.bold} + +input0 + +Varnode to extract a value from. + +position + +([**constant**]{.bold}) + +Constant indicating the bit position to extract from. + +size + +([**constant**]{.bold}) + +Constant indicating the number of bits to extract. + +output + +Varnode result containing the extracted value. + +[**Semantic statement**]{.bold} + +[*Cannot be explicitly coded.*]{.emphasis} + +The values [*position*]{.emphasis} and [*size*]{.emphasis} must be +constants. The operation extracts [*size*]{.emphasis} bits from input0 +and returns it in output. The [*position*]{.emphasis} indicates the +least significant bit in the range being extracted, with the bits in +input0 labeled from least to most significant, starting at 0. The +varnodes input0 and output can be different sizes, and the extracted +value is zero extended into output. The value [*size*]{.emphasis} must +not be bigger than the varnode output, and [*size*]{.emphasis} + +[*position*]{.emphasis} must not be bigger than the varnode input0. + +This operation is never generated as raw p-code, even though it is +equivalent to SLEIGH [**bitrange**]{.bold} syntax such as output = +input0\[10,1\]. + +::: {.navfooter} + +------------------------------------------------------------------------ + + --------------------------- ----------------------- ------------------------- + [Prev](pseudo-ops.html)     [Next](reference.html) + Pseudo P-CODE Operations  [Home](pcoderef.html)  Syntax Reference + --------------------------- ----------------------- ------------------------- +::: diff --git a/sources/GhidraDocs/languages/html/languages.css b/sources/GhidraDocs/languages/html/languages.css new file mode 100644 index 0000000..d0a955c --- /dev/null +++ b/sources/GhidraDocs/languages/html/languages.css @@ -0,0 +1,26 @@ +/* ### + * IP: GHIDRA + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/* + This file contains non-Ghidra style sheet markup. This file will be loaded in addition to + FrontPage.css. +*/ + +h5 { margin-left: 10px; } +div.informalexample { margin-left: 50px; } +div.example-contents { margin-left: 50px; } +span.term { font-family:times new roman; font-size:14pt; font-weight:bold; } +span.code { font-weight: bold; font-family: courier new; font-size: 14pt; color:#000000; } + diff --git a/sources/GhidraDocs/languages/html/pcodedescription.html b/sources/GhidraDocs/languages/html/pcodedescription.html new file mode 100644 index 0000000..067fc2b --- /dev/null +++ b/sources/GhidraDocs/languages/html/pcodedescription.html @@ -0,0 +1,3040 @@ + + + +P-Code Operation Reference + + + + + + + + + +
+ + + + + + + +
P-Code Operation Reference
+Prev   Next +
+
+
+
+

+P-Code Operation Reference

+

+For each possible p-code operation, we give a brief description and +provide a table that lists the inputs that must be present and their +meaning. We also list the basic syntax for denoting the operation when +describing semantics in a processor specification file. +

+
+

+COPY

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Source varnode.
outputDestination varnode.
Semantic statement
output = input0;
+
+

+Copy a sequence of contiguous bytes from anywhere to anywhere. Size of +input0 and output must be the same. +

+
+
+

+LOAD

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0(special)Constant ID of space to load from.
input1Varnode containing pointer offset to data.
outputDestination varnode.
Semantic statement
output = *input1;
output = *[input0]input1;
+
+

+This instruction loads data from a dynamic location into the output +variable by dereferencing a pointer. The “pointer” comes in two +pieces. One piece, input1, is a normal variable containing the offset +of the object being pointed at. The other piece, input0, is a constant +indicating the space into which the offset applies. The data in input1 +is interpreted as an unsigned offset and should have the same size as +the space referred to by the ID, i.e. a 4-byte address space requires +a 4-byte offset. The space ID is not manually entered by a user but is +automatically generated by the p-code compiler. The amount of data +loaded by this instruction is determined by the size of the output +variable. It is easy to confuse the address space of the output and +input1 variables and the Address Space represented by the ID, which +could all be different. Unlike many programming models, there are +multiple spaces that a “pointer” can refer to, and so an extra ID is +required. +

+

+It is possible for the addressable unit of an address +space to be bigger than a single byte. If +the wordsize attribute of the space +given by the ID is bigger than one, the offset into the space obtained +from input1 must be multiplied by this value in order to obtain the +correct byte offset into the space. +

+
+
+

+STORE

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0(special)Constant ID of space to store into.
input1Varnode containing pointer offset of destination.
input2Varnode containing data to be stored.
Semantic statement
*input1 = input2;
*[input0]input1 = input2;
+
+

+This instruction is the complement +of LOAD. The data in the variable +input2 is stored at a dynamic location by dereferencing a pointer. As +with LOAD, the “pointer” comes in two +pieces: a space ID part, and an offset variable. The size of input1 +must match the address space specified by the ID, and the amount of +data stored is determined by the size of input2. +

+

+Its possible for the addressable unit of an address +space to be bigger than a single byte. If +the wordsize attribute of the space +given by the ID is bigger than one, the offset into the space obtained +from input1 must be multiplied by this value in order to obtain the +correct byte offset into the space. +

+
+
+

+BRANCH

+
+ ++++ + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0(special)Location of next instruction to execute.
Semantic statement
goto input0;
+
+

+This is an absolute jump instruction. The varnode parameter input0 encodes +the destination address (address space and offset) of the jump. The varnode is not +treated as a variable for this instruction and does not store the destination. Its address space and +offset are the destination. The size of input0 is irrelevant. +

+

+Confusion about the meaning of this instruction can result because of +the translation from machine instructions to p-code. The destination of the jump is +a machine address and refers to +the machine instruction at that address. When +attempting to determine which p-code instruction is executed next, the +rule is: execute the first p-code instruction resulting from the +translation of the machine instruction(s) at that address. The +resulting p-code instruction may not be attached directly to the +indicated address due to NOP instructions and delay slots. +

+

+If input0 is constant, i.e. its address space +is the constant +address space, then it encodes a p-code relative branch. +In this case, the offset of input0 is considered a relative offset into +the indexed list of p-code operations corresponding to the translation +of the current machine instruction. This allows branching within the +operations forming a single instruction. For example, if +the BRANCH occurs as the pcode +operation with index 5 for the instruction, it can branch to operation +with index 8 by specifying a constant destination “address” of +3. Negative constants can be used for backward branches. +

+
+
+

+CBRANCH

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0(special)Location of next instruction to execute.
input1Boolean varnode indicating whether branch is taken.
Semantic statement
if (input1) goto input0;
+
+

+This is a conditional branch instruction where the dynamic condition +for taking the branch is determined by the 1 byte variable input1. If +this variable is non-zero, the condition is +considered true and the branch is taken. As in +the BRANCH instruction the parameter +input0 is not treated as a variable but as an address and is +interpreted in the same way. Furthermore, a constant space address is +also interpreted as a relative address so that +a CBRANCH can do p-code +relative branching. See the discussion for the +BRANCH operation. +

+
+
+

+BRANCHIND

+
+ ++++ + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode containing offset of next instruction.
Semantic statement
goto [input0];
+
+

+This is an indirect branching instruction. The address to branch to is +determined dynamically (at runtime) by examining the contents of the +variable input0. As this instruction is currently defined, the +variable input0 only contains the offset of the +destination, and the address space is taken from the address +associated with the branching instruction +itself. So execution can only branch within the same address +space via this instruction. The size of the variable input0 +must match the size of offsets for the current address space. P-code +relative branching is not possible with BRANCHIND. +

+
+
+

+CALL

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0(special)Location of next instruction to execute.
[input1]First parameter to call (never present in raw p-code)
...Additional parameters to call (never present in raw p-code)
Semantic statement
call [input0];
+
+

+This instruction is semantically equivalent to +the BRANCH instruction. +Beware: This instruction does not +behave like a typical function call. In particular, there is no +internal stack in p-code for saving the return address. Use of this +instruction instead of BRANCH is +intended to provide a hint to algorithms that try to follow code flow. +It indicates that the original machine instruction, of which this +p-code instruction is only a part, is intended to be a function +call. The p-code instruction does not implement the full semantics of +the call itself; it only implements the final branch. +

+

+In the raw p-code translation process, this operation can only take +input0, but in follow-on analysis, it can take arbitrary additional inputs. +These represent (possibly partial) recovery of the parameters being +passed to the logical call represented by this +operation. These additional parameters have no effect on the original +semantics of the raw p-code but naturally hold the varnode values flowing +into the call. +

+
+
+

+CALLIND

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode containing offset of next instruction.
[input1]First parameter to call (never present in raw p-code)
...Additional parameters to call (never present in raw p-code)
Semantic statement
call [input0];
+
+

+This instruction is semantically equivalent to +the BRANCHIND instruction. It does +not perform a function call in the usual sense of the term. It merely +indicates that the original machine instruction is intended to be an +indirect call. See the discussion for +the CALL instruction. +

+

As with the CALL instruction, +this operation may take additional inputs when not in raw form, representing +the parameters being passed to the logical call. +

+
+
+

+RETURN

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode containing offset of next instruction.
[input1]Value returned from call (never present in raw p-code)
Semantic statement
return [input0];
+
+

+This instruction is semantically equivalent to +the BRANCHIND instruction. It does +not perform a return from subroutine in the usual sense of the +term. It merely indicates that the original machine instruction is +intended to be a return from subroutine. See the discussion for +the CALL instruction. +

+

+Similarly to CALL and CALLIND, +this operation may take an additional input when not in raw form. If input1 is +present it represents the value being returned by this operation. +This is used by analysis algorithms to hold the value logically flowing back to the parent +subroutine. +

+
+
+

+PIECE

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode containing most significant data to merge.
input1Varnode containing least significant data to merge.
outputVarnode to contain resulting concatenation.
Semantic statement
Cannot (currently) be explicitly coded
+
+

+This is a concatenation operator that understands the endianness of the +data. The size of input0 and input1 must add up to the size of +output. The data from the inputs is concatenated in such a way that, +if the inputs and output are considered integers, the first input +makes up the most significant part of the output. +

+
+
+

+SUBPIECE

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode containing source data to truncate.
input1(constant)Constant indicating how many bytes to truncate.
outputVarnode to contain result of truncation.
Semantic statement
output = input0(input1);
+
+

+This is a truncation operator that understands the endianness of the +data. Input1 indicates the number of least significant bytes of input0 +to be thrown away. Output is then filled with any remaining bytes of +input0 up to the size of output. If the size of +output is smaller than the size of input0 minus the constant input1, +then the additional most significant bytes of input0 will also be +truncated. +

+
+
+

+POPCOUNT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Input varnode to count.
outputResulting integer varnode containing count.
Semantic statement
output = popcount(input0);
+
+

+This is a bit count (population count) operator. Within the binary representation of the value +contained in the input varnode, the number of 1 bits are counted and then returned in the +output varnode. A value of 0 returns 0, a 4-byte varnode containing the value 232-1 +(all bits set) returns 32, for instance. The input and output varnodes can have any size. The resulting +count is zero extended into the output varnode. +

+
+
+

+LZCOUNT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Input varnode to count.
outputResulting integer varnode containing count.
Semantic statement
output = lzcount(input0);
+
+

+This operator counts the number of zeros starting at the most significant bit. +For instance, for a 4-byte varnode, a value of 0 returns 32, a value of 1 +returns 31, and the value 231 returns 0. +The resulting count is zero extended into the output varnode. +

+
+
+

+INT_EQUAL

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode to compare.
input1Second varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 == input1;
+
+

+This is the integer equality operator. Output is +assigned true, if input0 equals input1. It works +for signed, unsigned, or any contiguous data where the match must be +down to the bit. Both inputs must be the same size, and the output +must have a size of 1. +

+
+
+

+INT_NOTEQUAL

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode to compare.
input1Second varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 != input1;
+
+

+This is the integer inequality operator. Output is +assigned true, if input0 does not equal +input1. It works for signed, unsigned, or any contiguous data where +the match must be down to the bit. Both inputs must be the same size, +and the output must have a size of 1. +

+
+
+

+INT_LESS

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First unsigned varnode to compare.
input1Second unsigned varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 < input1;
+
+

+This is an unsigned integer comparison operator. If the unsigned +integer input0 is strictly less than the unsigned integer input1, +output is set to true. Both inputs must be the +same size, and the output must have a size of 1. +

+
+
+

+INT_SLESS

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First signed varnode to compare.
input1Second signed varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 s< input1;
+
+

+This is a signed integer comparison operator. If the signed integer +input0 is strictly less than the signed integer input1, output is set +to true. Both inputs must be the same size, and +the output must have a size of 1. +

+
+
+

+INT_LESSEQUAL

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First unsigned varnode to compare.
input1Second unsigned varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 <= input1;
+
+

+This is an unsigned integer comparison operator. If the unsigned +integer input0 is less than or equal to the unsigned integer input1, +output is set to true. Both inputs must be the +same size, and the output must have a size of 1. +

+
+
+

+INT_SLESSEQUAL

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First signed varnode to compare.
input1Second signed varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 s<= input1;
+
+

+This is a signed integer comparison operator. If the signed integer +input0 is less than or equal to the signed integer input1, output is +set to true. Both inputs must be the same size, +and the output must have a size of 1. +

+
+
+

+INT_ZEXT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode to zero-extend.
outputVarnode containing zero-extended result.
Semantic statement
output = zext(input0);
+
+

+Zero-extend the data in input0 and store the result in output. Copy +all the data from input0 into the least significant positions of +output. Fill out any remaining space in the most significant bytes of +output with zero. The size of output must be strictly bigger than the +size of input. +

+
+
+

+INT_SEXT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode to sign-extend.
outputVarnode containing sign-extended result.
Semantic statement
output = sext(input0);
+
+

+Sign-extend the data in input0 and store the result in output. Copy +all the data from input0 into the least significant positions of +output. Fill out any remaining space in the most significant bytes of +output with either zero or all ones (0xff) depending on the most +significant bit of input0. The size of output must be strictly bigger +than the size of input0. +

+
+
+

+INT_ADD

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode to add.
input1Second varnode to add.
outputVarnode containing result of integer addition.
Semantic statement
output = input0 + input1;
+
+

+This is standard integer addition. It works for either unsigned or +signed interpretations of the integer encoding (twos complement). Size +of both inputs and output must be the same. The addition is of course +performed modulo this size. Overflow and carry conditions are +calculated by other +operations. See INT_CARRY +and INT_SCARRY. +

+
+
+

+INT_SUB

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode input.
input1Varnode to subtract from first.
outputVarnode containing result of integer subtraction.
Semantic statement
output = input0 - input1;
+
+

+This is standard integer subtraction. It works for either unsigned or +signed interpretations of the integer encoding (twos complement). Size +of both inputs and output must be the same. The subtraction is of +course performed modulo this size. Overflow and borrow conditions are +calculated by other +operations. See INT_SBORROW +and INT_LESS. +

+
+
+

+INT_CARRY

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode to add.
input1Second varnode to add.
outputBoolean result containing carry condition.
Semantic statement
output = carry(input0,input1);
+
+

+This operation checks for unsigned addition overflow or carry +conditions. If the result of adding input0 and input1 as unsigned +integers overflows the size of the varnodes, output is +assigned true. Both inputs must be the same size, +and output must be size 1. +

+
+
+

+INT_SCARRY

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode to add.
input1Second varnode to add.
outputBoolean result containing signed overflow condition.
Semantic statement
output = scarry(input0,input1);
+
+

+This operation checks for signed addition overflow or carry +conditions. If the result of adding input0 and input1 as signed +integers overflows the size of the varnodes, output is +assigned true. Both inputs must be the same size, +and output must be size 1. +

+
+
+

+INT_SBORROW

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode input.
input1Varnode to subtract from first.
outputBoolean result containing signed overflow condition.
Semantic statement
output = sborrow(input0,input1);
+
+

+This operation checks for signed subtraction overflow or borrow +conditions. If the result of subtracting input1 from input0 as signed +integers overflows the size of the varnodes, output is +assigned true. Both inputs must be the same size, +and output must be size 1. Note that the equivalent unsigned +subtraction overflow condition +is INT_LESS. +

+
+
+

+INT_2COMP

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First to negate.
outputVarnode result containing twos complement.
Semantic statement
output = -input0;
+
+

+This is the twos complement or arithmetic negation operation. Treating input0 as a signed +integer, the result is the same integer value but with the opposite sign. This is equivalent +to doing a bitwise negation of input0 and then adding one. Both input0 and output must +be the same size. +

+
+
+

+INT_NEGATE

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode to negate.
outputVarnode result containing bitwise negation.
Semantic statement
output = ~input0;
+
+

+This is the bitwise negation operation. Output is the result of taking +every bit of input0 and flipping it. Both input0 and output must be +the same size. +

+
+
+

+INT_XOR

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First input to exclusive-or.
input1Second input to exclusive-or.
outputVarnode result containing exclusive-or of inputs.
Semantic statement
output = input0 ^ input1;
+
+

+This operation performs a logical Exclusive-Or on the bits of input0 +and input1. Both inputs and output must be the same size. +

+
+
+

+INT_AND

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First input to logical-and.
input1Second input to logical-and.
outputVarnode result containing logical-and of inputs.
Semantic statement
output = input0 & input1;
+
+

+This operation performs a Logical-And on the bits of input0 and input1. Both inputs and +output must be the same size. +

+
+
+

+INT_OR

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First input to logical-or.
input1Second input to logical-or.
outputVarnode result containing logical-or of inputs.
Semantic statement
output = input0 | input1;
+
+

+This operation performs a Logical-Or on the bits of input0 and input1. Both inputs and +output must be the same size. +

+
+
+

+INT_LEFT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode input being shifted.
input1Varnode indicating number of bits to shift.
outputVarnode containing shifted result.
Semantic statement
output = input0 << input1;
+
+

+This operation performs a left shift on input0. The value given by +input1, interpreted as an unsigned integer, indicates the number of +bits to shift. The vacated (least significant) bits are filled with +zero. If input1 is zero, no shift is performed and input0 is copied +into output. If input1 is larger than the number of bits in output, +the result is zero. Both input0 and output must be the same +size. Input1 can be any size. +

+
+
+

+INT_RIGHT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode input being shifted.
input1Varnode indicating number of bits to shift.
outputVarnode containing shifted result.
Semantic statement
output = input0 >> input1;
+
+

+This operation performs an unsigned (logical) right shift on +input0. The value given by input1, interpreted as an unsigned integer, +indicates the number of bits to shift. The vacated (most significant) +bits are filled with zero. If input1 is zero, no shift is performed +and input0 is copied into output. If input1 is larger than the number +of bits in output, the result is zero. Both input0 and output must be +the same size. Input1 can be any size. +

+
+
+

+INT_SRIGHT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode input being shifted.
input1Varnode indicating number of bits to shift.
outputVarnode containing shifted result.
Semantic statement
output = input0 s>> input1;
+
+

+This operation performs a signed (arithmetic) right shift on +input0. The value given by input1, interpreted as an unsigned integer, +indicates the number of bits to shift. The vacated bits are filled +with the original value of the most significant (sign) bit of input0. +If input1 is zero, no shift is performed and input0 is copied into +output. If input1 is larger than the number of bits in output, the +result is zero or all 1-bits (-1), depending on the original sign of +input0. Both input0 and output must be the same size. Input1 can be +any size. +

+
+
+

+INT_MULT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode to be multiplied.
input1Second varnode to be multiplied.
outputVarnode containing result of multiplication.
Semantic statement
output = input0 * input1;
+
+

+This is an integer multiplication operation. The result of multiplying +input0 and input1, viewed as integers, is stored in output. Both +inputs and output must be the same size. The multiplication is +performed modulo the size, and the result is true for either a signed +or unsigned interpretation of the inputs and output. To get extended +precision results, the inputs must first by zero-extended or +sign-extended to the desired size. +

+
+
+

+INT_DIV

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode input.
input1Second varnode input (divisor).
outputVarnode containing result of division.
Semantic statement
output = input0 / input1;
+
+

+This is an unsigned integer division operation. Divide input0 by +input1, truncating the result to the nearest integer, and store the +result in output. Both inputs and output must be the same size. There +is no handling of division by zero. To simulate a processor’s handling +of a division-by-zero trap, other operations must be used before +the INT_DIV. +

+
+
+

+INT_REM

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode input.
input1Second varnode input (divisor).
outputVarnode containing remainder of division.
Semantic statement
output = input0 % input1;
+
+

+This is an unsigned integer remainder operation. The remainder of +performing the unsigned integer division of input0 and input1 is put +in output. Both inputs and output must be the same size. If q = +input0/input1, using the INT_DIV +operation defined above, then output satisfies the equation q*input1 + +output = input0, using the INT_MULT +and INT_ADD operations. +

+
+
+

+INT_SDIV

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode input.
input1Second varnode input (divisor).
outputVarnode containing result of signed division.
Semantic statement
output = input0 s/ input1;
+
+

+This is a signed integer division operation. The resulting integer is +the one closest to the rational value input0/input1 but which is still +smaller in absolute value. Both inputs and output must be the same +size. There is no handling of division by zero. To simulate a +processor’s handling of a division-by-zero trap, other operations must +be used before the INT_SDIV. +

+
+
+

+INT_SREM

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First varnode input.
input1Second varnode input (divisor).
outputVarnode containing remainder of signed division.
Semantic statement
output = input0 s% input1;
+
+

+This is a signed integer remainder operation. The remainder of +performing the signed integer division of input0 and input1 is put in +output. Both inputs and output must be the same size. If q = input0 s/ +input1, using the INT_SDIV operation +defined above, then output satisfies the equation q*input1 + output = +input0, using the INT_MULT +and INT_ADD operations. +

+
+
+

+BOOL_NEGATE

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Boolean varnode to negate.
outputBoolean varnode containing result of negation.
Semantic statement
output = !input0;
+
+

+This is a logical negate operator, where we assume input0 and output +are boolean values. It puts the logical complement of input0, treated +as a single bit, into output. Both input0 and output are size +1. Boolean values are implemented with a full byte, but are still +considered to only support a value of true +or false. +

+
+
+

+BOOL_XOR

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First boolean input to exclusive-or.
input1Second boolean input to exclusive-or.
outputBoolean varnode containing result of exclusive-or.
Semantic statement
output = input0 ^^ input1;
+
+

+This is an Exclusive-Or operator, where we assume the inputs and +output are boolean values. It puts the exclusive-or of input0 and +input1, treated as single bits, into output. Both inputs and output +are size 1. Boolean values are implemented with a full byte, but are +still considered to only support a value of true +or false. +

+
+
+

+BOOL_AND

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First boolean input to logical-and.
input1Second boolean input to logical-and.
outputBoolean varnode containing result of logical-and.
Semantic statement
output = input0 && input1;
+
+

+This is a Logical-And operator, where we assume the inputs and output +are boolean values. It puts the logical-and of input0 and input1, +treated as single bits, into output. Both inputs and output are size +1. Boolean values are implemented with a full byte, but are still +considered to only support a value of true +or false. +

+
+
+

+BOOL_OR

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First boolean input to logical-or.
input1Second boolean input to logical-or.
outputBoolean varnode containing result of logical-or.
Semantic statement
output = input0 || input1;
+
+

+This is a Logical-Or operator, where we assume the inputs and output +are boolean values. It puts the logical-or of input0 and input1, +treated as single bits, into output. Both inputs and output are size +1. Boolean values are implemented with a full byte, but are still +considered to only support a value of true +or false. +

+
+
+

+FLOAT_EQUAL

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First floating-point input to compare.
input1Second floating-point input to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 f== input1;
+
+

+This is a floating-point equality operator. Output is +assigned true, if input0 and input1 are +considered equal as floating-point values. Both inputs must be the +same size, and output is size 1. If either input +is NaN, output is set +to false. +

+
+
+

+FLOAT_NOTEQUAL

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First floating-point input to compare.
input1Second floating-point input to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 f!= input1;
+
+

+This is a floating-point inequality operator. Output is +assigned true, if input0 and input1 are not +considered equal as floating-point values. Both inputs must be the +same size, and output is size 1. If either input +is NaN, output is set +to false. +

+
+
+

+FLOAT_LESS

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First floating-point input to compare.
input1Second floating-point input to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 f< input1;
+
+

+This is a comparison operator, where both inputs are considered +floating-point values. Output is assigned true, +if input0 is less than input1. Both inputs must be the same size, and +output is size 1. If either input +is NaN, output is set +to false. +

+
+
+

+FLOAT_LESSEQUAL

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First floating-point input to compare.
input1Second floating-point input to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 f<= input1;
+
+

+This is a comparison operator, where both inputs are considered +floating-point values. Output is assigned true, +if input0 is less than or equal to input1. Both inputs must be the +same size, and output is size 1. If either input +is NaN, output is set +to false. +

+
+
+

+FLOAT_ADD

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First floating-point input to add.
input1Second floating-point input to add.
outputVarnode containing result of addition.
Semantic statement
output = input0 f+ input1;
+
+

+This is a floating-point addition operator. The result of adding +input0 and input1 as floating-point values is stored in output. Both +inputs and output must be the same size. If either input +is NaN, output is set +to NaN. If any overflow condition +occurs, output is set to NaN. +

+
+
+

+FLOAT_SUB

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First floating-point input.
input1Floating-point varnode to subtract from first.
outputVarnode containing result of subtraction.
Semantic statement
output = input0 f- input1;
+
+

+This is a floating-point subtraction operator. The result of +subtracting input1 from input0 as floating-point values is stored in +output. Both inputs and output must be the same size. If either input +is NaN, output is set +to NaN. If any overflow condition +occurs, output is set to NaN. +

+
+
+

+FLOAT_MULT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First floating-point input to multiply.
input1Second floating-point input to multiply.
outputVarnode containing result of multiplication.
Semantic statement
output = input0 f* input1;
+
+

+This is a floating-point multiplication operator. The result of +multiplying input0 to input1 as floating-point values is stored in +output. Both inputs and output must be the same size. If either input +is NaN, output is set +to NaN. If any overflow condition +occurs, output is set to NaN. +

+
+
+

+FLOAT_DIV

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0First floating-point input.
input1Second floating-point input (divisor).
outputVarnode containing result of division.
Semantic statement
output = input0 f/ input1;
+
+

+This is a floating-point division operator. The result of dividing +input1 into input0 as floating-point values is stored in output. Both +inputs and output must be the same size. If either input +is NaN, output is set +to NaN. If any overflow condition +occurs, output is set to NaN. +

+
+
+

+FLOAT_NEG

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Floating-point varnode to negate.
outputVarnode containing result of negation.
Semantic statement
output = f- input0;
+
+

+This is a floating-point negation operator. The floating-point value +in input0 is stored in output with the opposite sign. Both input and +output must be the same size. If input +is NaN, output is set +to NaN. +

+
+
+

+FLOAT_ABS

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Floating-point input.
outputVarnode result containing absolute-value.
Semantic statement
output = abs(input0);
+
+

+This is a floating-point absolute-value operator. The absolute value +of input0 is stored in output. Both input0 and output must be the same +size. If input0 is NaN, output is set +to NaN. +

+
+
+

+FLOAT_SQRT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Floating-point input.
outputVarnode result containing square root.
Semantic statement
output = sqrt(input0);
+
+

+This is a floating-point square-root operator. The square root of +input0 is stored in output. Both input0 and output must be the same +size. If input0 is NaN, output is set +to NaN. +

+
+
+

+FLOAT_CEIL

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Floating-point input.
outputVarnode result containing result of truncation.
Semantic statement
output = ceil(input0);
+
+

+This operation rounds input0, as a signed floating-point value, towards positive infinity. +For instance, the value 1.2 rounds to 2.0; -1.2 rounds to -1.0. +The integral value obtained by rounding input0 up is stored in output, as a floating-point +value. Both input0 and output must be the same size. If input0 +is NaN, output is set +to NaN. +

+
+
+

+FLOAT_FLOOR

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Floating-point input.
outputVarnode result containing result of truncation.
Semantic statement
output = floor(input0);
+
+

+This operation rounds input0, as a floating-point value, towards negative infinity. +For instance, the value 1.2 rounds to 1.0 and -1.2 rounds to -2.0. +The integral value obtained by rounding input0 down is stored in output, as a floating-point +value. FLOAT_FLOOR does not produce +a twos complement integer output (See the TRUNC operator). +Both input0 and output must be the same size. If input0 +is NaN, output is set +to NaN. +

+
+
+

+FLOAT_ROUND

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Floating-point input.
outputVarnode result containing result of truncation.
Semantic statement
output = round(input0);
+
+

+This is a floating-point rounding operator. The integral value closest to the +floating-point value in input0 is stored in output, as a floating-point value. +For example, 1.2 rounds to 1.0 and 1.9 rounds to 2.0. +FLOAT_ROUND does not +produce a twos complement integer output (See the TRUNC operator). +Both input0 and output must be the same size. If +input0 is NaN, output is set +to NaN. +

+
+
+

+FLOAT_NAN

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Floating-point input.
outputBoolean varnode containing result of NaN test.
Semantic statement
output = nan(input0);
+
+

+This operator returns true in output if input0 is +interpreted as NaN. Output must be +size 1, and input0 can be any size. +

+
+
+

+INT2FLOAT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Signed integer input.
outputResult containing floating-point conversion.
Semantic statement
output = int2float(input0);
+
+

+This is an integer to floating-point conversion operator. Input0 +viewed as a signed integer is converted to floating-point format and +stored in output. Input0 and output do not need to be the same +size. The conversion to floating-point may involve a loss of +precision. +

+
+
+

+FLOAT2FLOAT

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Floating-point input varnode.
outputResult varnode containing conversion.
Semantic statement
output = float2float(input0);
+
+

+This is a floating-point precision conversion operator. The +floating-point value in input0 is converted to a floating-point value +of a different size and stored in output. If output is smaller than +input0, then the operation will lose precision. Input0 and output +should be different sizes. If input0 +is NaN, then output is set +to NaN. +

+
+
+

+TRUNC

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Floating-point input varnode.
outputResulting integer varnode containing conversion.
Semantic statement
output = trunc(input0);
+
+

+This is a floating-point to integer conversion operator. The +floating-point value in input0 is converted to a signed integer and +stored in output using the default twos complement encoding. +The fractional part of input0 is dropped in the conversion by rounding towards zero. +Input0 and output can be different sizes. +

+
+
+
+
+ + + + + + + + + + + +
+Prev   Next +
P-Code Reference Manual Home Pseudo P-CODE Operations
+
+ + diff --git a/sources/GhidraDocs/languages/html/pcodedescription.md b/sources/GhidraDocs/languages/html/pcodedescription.md new file mode 100644 index 0000000..65c538d --- /dev/null +++ b/sources/GhidraDocs/languages/html/pcodedescription.md @@ -0,0 +1,1168 @@ +--- +status: collected +title: P-Code Operation Reference +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/pcodedescription.html +--- + +# P-Code Operation Reference + +For each possible p-code operation, we give a brief description and +provide a table that lists the inputs that must be present and their +meaning. We also list the basic syntax for denoting the operation when +describing semantics in a processor specification file. + +### COPY + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Source varnode.| +|output|Destination varnode.| + +**Semantic statement** + +`output = input0;` + +Copy a sequence of contiguous bytes from anywhere to anywhere. Size of +input0 and output must be the same. + +### LOAD + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Constant ID of space to load from.| +|input1|Varnode containing pointer offset to data.| +|output|Destination varnode.| + +**Semantic statement** + +`output = *input1;` + +`output = *[input0]input1;` + +This instruction loads data from a dynamic location into the output +variable by dereferencing a pointer. The "pointer" comes in two pieces. +One piece, input1, is a normal variable containing the offset of the +object being pointed at. The other piece, input0, is a constant +indicating the space into which the offset applies. The data in input1 +is interpreted as an unsigned offset and should have the same size as +the space referred to by the ID, i.e. a 4-byte address space requires a +4-byte offset. The space ID is not manually entered by a user but is +automatically generated by the p-code compiler. The amount of data +loaded by this instruction is determined by the size of the output +variable. It is easy to confuse the address space of the output and +input1 variables and the Address Space represented by the ID, which +could all be different. Unlike many programming models, there are +multiple spaces that a "pointer" can refer to, and so an extra ID is +required. + +It is possible for the addressable unit of an address space to be bigger +than a single byte. If the **wordsize** attribute of the space +given by the ID is bigger than one, the offset into the space obtained +from input1 must be multiplied by this value in order to obtain the +correct byte offset into the space. + +### STORE + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Constant ID of space to store into.| +|input1|Varnode containing pointer offset of destination.| +|output|Varnode containing data to be stored.| + +**Semantic statement** + +`*input1 = input2;` + +`*[input0]input1 = input2; ` + +This instruction is the complement of **LOAD**. The data in the +variable input2 is stored at a dynamic location by dereferencing a +pointer. As with **LOAD**, the "pointer" comes in two pieces: a +space ID part, and an offset variable. The size of input1 must match the +address space specified by the ID, and the amount of data stored is +determined by the size of input2. + +Its possible for the addressable unit of an address space to be bigger +than a single byte. If the **wordsize** attribute of the space +given by the ID is bigger than one, the offset into the space obtained +from input1 must be multiplied by this value in order to obtain the +correct byte offset into the space. + +### BRANCH + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Location of next instruction to execute.| + +**Semantic statement** + +`goto input0;` + +This is an absolute jump instruction. The varnode parameter input0 +encodes the destination address (address space and offset) of the jump. +The varnode is not treated as a variable for this instruction and does +not store the destination. Its address space and offset +*are* the destination. The size of input0 is irrelevant. + +Confusion about the meaning of this instruction can result because of +the translation from machine instructions to p-code. The destination of +the jump is a *machine* address and refers to the +*machine* instruction at that address. When attempting to +determine which p-code instruction is executed next, the rule is: +execute the first p-code instruction resulting from the translation of +the machine instruction(s) at that address. The resulting p-code +instruction may not be attached directly to the indicated address due to +NOP instructions and delay slots. + +If input0 is constant, i.e. its address space is the +**constant** address space, then it encodes a *p-code relative +branch*. In this case, the offset of input0 is considered a +relative offset into the indexed list of p-code operations corresponding +to the translation of the current machine instruction. This allows +branching within the operations forming a single instruction. For +example, if the **BRANCH** occurs as the pcode operation with +index 5 for the instruction, it can branch to operation with index 8 by +specifying a constant destination "address" of 3. Negative constants can +be used for backward branches. + +### CBRANCH + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Location of next instruction to execute.| +|input1|Boolean varnode indicating whether branch is taken.| + +**Semantic statement** + +`if (input1) goto input0;` + +This is a conditional branch instruction where the dynamic condition for +taking the branch is determined by the 1 byte variable input1. If this +variable is non-zero, the condition is considered *true* +and the branch is taken. As in the **BRANCH** instruction the +parameter input0 is not treated as a variable but as an address and is +interpreted in the same way. Furthermore, a constant space address is +also interpreted as a relative address so that a **CBRANCH** +can do *p-code relative branching*. See the discussion for +the **BRANCH** operation. + +### BRANCHIND + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Varnode containing offset of next instruction.| + +**Semantic statement** + +`goto [input0];` + +This is an indirect branching instruction. The address to branch to is +determined dynamically (at runtime) by examining the contents of the +variable input0. As this instruction is currently defined, the variable +input0 only contains the *offset* of the destination, and +the address space is taken from the address associated with the +branching instruction itself. So *execution can only branch within the +same address space* via this instruction. The size of the +variable input0 must match the size of offsets for the current address +space. P-code relative branching is not possible with +**BRANCHIND**. + +### CALL + +|**Parameters**|**Description**| +|:-:|:-| +|input0(**special**)|Location of next instruction to execute.| +|[input1]|First parameter to call (never present in raw p-code)| +|...|Additional parameters to call (never present in raw p-code)| + +**Semantic statement** + +`call [input0];` + +This instruction is semantically equivalent to the **BRANCH** +instruction. **Beware:** This instruction does not behave like +a typical function call. In particular, there is no internal stack in +p-code for saving the return address. Use of this instruction instead of +**BRANCH** is intended to provide a hint to algorithms that try +to follow code flow. It indicates that the original machine instruction, +of which this p-code instruction is only a part, is intended to be a +function call. The p-code instruction does not implement the full +semantics of the call itself; it only implements the final branch. + +In the raw p-code translation process, this operation can only take +input0, but in follow-on analysis, it can take arbitrary additional +inputs. These represent (possibly partial) recovery of the parameters +being passed to the logical *call* represented by this +operation. These additional parameters have no effect on the original +semantics of the raw p-code but naturally hold the varnode values +flowing into the call. + +### CALLIND + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Varnode containing offset of next instruction.| +|[input1]|First parameter to call (never present in raw p-code)| +|...|Additional parameters to call (never present in raw p-code)| + +**Semantic statement** + +`call [input0];` + +This instruction is semantically equivalent to the +**BRANCHIND** instruction. It does not perform a function call +in the usual sense of the term. It merely indicates that the original +machine instruction is intended to be an indirect call. See the +discussion for the **CALL** instruction. + +As with the **CALL** instruction, this operation may take +additional inputs when not in raw form, representing the parameters +being passed to the logical call. + +### RETURN + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Varnode containing offset of next instruction.| +|[input1]|Value returned from call (never present in raw p-code)| + +**Semantic statement** + +`return [input0];` + +This instruction is semantically equivalent to the +**BRANCHIND** instruction. It does not perform a return from +subroutine in the usual sense of the term. It merely indicates that the +original machine instruction is intended to be a return from subroutine. +See the discussion for the **CALL** instruction. + +Similarly to **CALL** and **CALLIND**, this operation +may take an additional input when not in raw form. If input1 is present +it represents the value being *returned* by this operation. +This is used by analysis algorithms to hold the value logically flowing +back to the parent subroutine. + +### PIECE + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Varnode containing most significant data to merge.| +|input1|Varnode containing least significant data to merge.| +|output|Varnode to contain resulting concatenation.| + +**Semantic statement** + +*Cannot (currently) be explicitly coded* + +This is a concatenation operator that understands the endianness of the +data. The size of input0 and input1 must add up to the size of output. +The data from the inputs is concatenated in such a way that, if the +inputs and output are considered integers, the first input makes up the +most significant part of the output. + +### SUBPIECE + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Varnode containing source data to truncate.| +|input1(**constant**)|Constant indicating how many bytes to truncate.| +|output|Varnode to contain result of truncation.| + +**Semantic statement** + +`output = input0(input1);` + +This is a truncation operator that understands the endianness of the +data. Input1 indicates the number of least significant bytes of input0 +to be thrown away. Output is then filled with any remaining bytes of +input0 *up to the size of output*. If the size of output is +smaller than the size of input0 minus the constant input1, then the +additional most significant bytes of input0 will also be truncated. + +### POPCOUNT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Input varnode to count.| +|output|Resulting integer varnode containing count.| + +**Semantic statement** + +`output = popcount(input0);` + +This is a bit count (population count) operator. Within the binary +representation of the value contained in the input varnode, the number +of 1 bits are counted and then returned in the output varnode. A value +of 0 returns 0, a 4-byte varnode containing the value 2^32^-1 (all bits +set) returns 32, for instance. The input and output varnodes can have +any size. The resulting count is zero extended into the output varnode. + +### LZCOUNT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Input varnode to count.| +|output|Resulting integer varnode containing count.| + +**Semantic statement** + +`output = lzcount(input0);` + +This operator counts the number of zeros starting at the most +significant bit. For instance, for a 4-byte varnode, a value of 0 +returns 32, a value of 1 returns 31, and the value 2^31^ returns 0. The +resulting count is zero extended into the output varnode. + +### INT_EQUAL + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode to compare.| +|input1|Second varnode to compare.| +|output|Boolean varnode containing result of comparison.| + +**Semantic statement** + +`output = input0 == input1;` + +This is the integer equality operator. Output is assigned +*true*, if input0 equals input1. It works for signed, +unsigned, or any contiguous data where the match must be down to the +bit. Both inputs must be the same size, and the output must have a size +of 1. + +### INT_NOTEQUAL + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode to compare.| +|input1|Second varnode to compare.| +|output|Boolean varnode containing result of comparison.| + +**Semantic statement** + +`output = input0 != input1;` + +This is the integer inequality operator. Output is assigned +*true*, if input0 does not equal input1. It works for +signed, unsigned, or any contiguous data where the match must be down to +the bit. Both inputs must be the same size, and the output must have a +size of 1. + +### INT_LESS + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode to compare.| +|input1|Second varnode to compare.| +|output|Boolean varnode containing result of comparison.| + +**Semantic statement** + +`output = input0 < input1;` + +This is an unsigned integer comparison operator. If the unsigned integer +input0 is strictly less than the unsigned integer input1, output is set +to *true*. Both inputs must be the same size, and the +output must have a size of 1. + +### INT_SLESS + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode to compare.| +|input1|Second varnode to compare.| +|output|Boolean varnode containing result of comparison.| + +**Semantic statement** + +`output = input0 s< input1;` + +This is a signed integer comparison operator. If the signed integer +input0 is strictly less than the signed integer input1, output is set to +*true*. Both inputs must be the same size, and the output +must have a size of 1. + +### INT_LESSEQUAL + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode to compare.| +|input1|Second varnode to compare.| +|output|Boolean varnode containing result of comparison.| + +**Semantic statement** + +`output = input0 <= input1;` + +This is an unsigned integer comparison operator. If the unsigned integer +input0 is less than or equal to the unsigned integer input1, output is +set to *true*. Both inputs must be the same size, and the +output must have a size of 1. + +### INT_SLESSEQUAL + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode to compare.| +|input1|Second varnode to compare.| +|output|Boolean varnode containing result of comparison.| + +**Semantic statement** + +`output = input0 s<= input1;` + +This is a signed integer comparison operator. If the signed integer +input0 is less than or equal to the signed integer input1, output is set +to *true*. Both inputs must be the same size, and the +output must have a size of 1. + +### INT_ZEXT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Varnode to zero-extend.| +|output|Varnode containing zero-extended result.| + +**Semantic statement** + +`output = zext(input0);` + +Zero-extend the data in input0 and store the result in output. Copy all +the data from input0 into the least significant positions of output. +Fill out any remaining space in the most significant bytes of output +with zero. The size of output must be strictly bigger than the size of +input. + +### INT_SEXT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Varnode to sign-extend.| +|output|Varnode containing sign-extended result.| + +**Semantic statement** + +`output = sext(input0);` + +Sign-extend the data in input0 and store the result in output. Copy all +the data from input0 into the least significant positions of output. +Fill out any remaining space in the most significant bytes of output +with either zero or all ones (0xff) depending on the most significant +bit of input0. The size of output must be strictly bigger than the size +of input0. + +### INT_ADD + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode to add.| +|input1|Second varnode to add.| +|output|Varnode containing result of integer addition.| + +**Semantic statement** + +`output = input0 + input1;` + +This is standard integer addition. It works for either unsigned or +signed interpretations of the integer encoding (twos complement). Size +of both inputs and output must be the same. The addition is of course +performed modulo this size. Overflow and carry conditions are calculated +by other operations. See **INT_CARRY** and +**INT_SCARRY**. + +### INT_SUB + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode input.| +|input1|Varnode to subtract from first.| +|output|Varnode containing result of integer subtraction.| + +**Semantic statement** + +`output = input0 - input1;` + +This is standard integer subtraction. It works for either unsigned or +signed interpretations of the integer encoding (twos complement). Size +of both inputs and output must be the same. The subtraction is of course +performed modulo this size. Overflow and borrow conditions are +calculated by other operations. See **INT_SBORROW** and +**INT_LESS**. + +### INT_CARRY + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode to add.| +|input1|Second varnode to add.| +|output|Boolean result containing carry condition.| + +**Semantic statement** + +`output = carry(input0,input1);` + +This operation checks for unsigned addition overflow or carry +conditions. If the result of adding input0 and input1 as unsigned +integers overflows the size of the varnodes, output is assigned +*true*. Both inputs must be the same size, and output must +be size 1. + +### INT_SCARRY + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode to add.| +|input1|Second varnode to add.| +|output|Boolean result containing signed overflow condition.| + +**Semantic statement** + +`output = scarry(input0,input1);` + +This operation checks for signed addition overflow or carry conditions. +If the result of adding input0 and input1 as signed integers overflows +the size of the varnodes, output is assigned *true*. Both +inputs must be the same size, and output must be size 1. + +### INT_SBORROW + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode input.| +|input1|Varnode to subtract from first.| +|output|Boolean result containing signed overflow condition.| + +**Semantic statement** + +`output = sborrow(input0,input1);` + +This operation checks for signed subtraction overflow or borrow +conditions. If the result of subtracting input1 from input0 as signed +integers overflows the size of the varnodes, output is assigned +*true*. Both inputs must be the same size, and output must +be size 1. Note that the equivalent unsigned subtraction overflow +condition is **INT_LESS**. + +### INT_2COMP + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First to negate.| +|output|Varnode result containing twos complement.| + +**Semantic statement** + +`output = -input0;` + +This is the twos complement or arithmetic negation operation. Treating +input0 as a signed integer, the result is the same integer value but +with the opposite sign. This is equivalent to doing a bitwise negation +of input0 and then adding one. Both input0 and output must be the same +size. + +### INT_NEGATE + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Varnode to negate.| +|output|Varnode result containing bitwise negation.| + +**Semantic statement** + +`output = ~input0;` + +This is the bitwise negation operation. Output is the result of taking +every bit of input0 and flipping it. Both input0 and output must be the +same size. + +### INT_XOR + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First input to exclusive-or.| +|input1|Second input to exclusive-or.| +|output|Varnode result containing exclusive-or of inputs.| + +**Semantic statement** + +`output = input0 ^ input1;` + +This operation performs a logical Exclusive-Or on the bits of input0 and +input1. Both inputs and output must be the same size. + +### INT_AND + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First input to logical-and.| +|input1|Second input to logical-and.| +|output|Varnode result containing logical-and of inputs.| + +**Semantic statement** + +`output = input0 & input1;` + +This operation performs a Logical-And on the bits of input0 and input1. +Both inputs and output must be the same size. + +### INT_OR + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First input to logical-or.| +|input1|Second input to logical-or.| +|output|Varnode result containing logical-or of inputs.| + +**Semantic statement** + +`output = input0 | input1;` + +This operation performs a Logical-Or on the bits of input0 and input1. +Both inputs and output must be the same size. + +### INT_LEFT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Varnode input being shifted.| +|input1|Varnode indicating number of bits to shift.| +|output|Varnode containing shifted result.| + +**Semantic statement** + +`output = input0 << input1;` + +This operation performs a left shift on input0. The value given by +input1, interpreted as an unsigned integer, indicates the number of bits +to shift. The vacated (least significant) bits are filled with zero. If +input1 is zero, no shift is performed and input0 is copied into output. +If input1 is larger than the number of bits in output, the result is +zero. Both input0 and output must be the same size. Input1 can be any +size. + +### INT_RIGHT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Varnode input being shifted.| +|input1|Varnode indicating number of bits to shift.| +|output|Varnode containing shifted result.| + +**Semantic statement** + +`output = input0 >> input1;` + +This operation performs an unsigned (logical) right shift on input0. The +value given by input1, interpreted as an unsigned integer, indicates the +number of bits to shift. The vacated (most significant) bits are filled +with zero. If input1 is zero, no shift is performed and input0 is copied +into output. If input1 is larger than the number of bits in output, the +result is zero. Both input0 and output must be the same size. Input1 can +be any size. + +### INT_SRIGHT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Varnode input being shifted.| +|input1|Varnode indicating number of bits to shift.| +|output|Varnode containing shifted result.| + +**Semantic statement** + +`output = input0 s>> input1;` + +This operation performs a signed (arithmetic) right shift on input0. The +value given by input1, interpreted as an unsigned integer, indicates the +number of bits to shift. The vacated bits are filled with the original +value of the most significant (sign) bit of input0. If input1 is zero, +no shift is performed and input0 is copied into output. If input1 is +larger than the number of bits in output, the result is zero or all +1-bits (-1), depending on the original sign of input0. Both input0 and +output must be the same size. Input1 can be any size. + +### INT_MULT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode to be multiplied.| +|input1|Second varnode to be multiplied.| +|output|Varnode containing result of multiplication.| + +**Semantic statement** + +`output = input0 * input1;` + +This is an integer multiplication operation. The result of multiplying +input0 and input1, viewed as integers, is stored in output. Both inputs +and output must be the same size. The multiplication is performed modulo +the size, and the result is true for either a signed or unsigned +interpretation of the inputs and output. To get extended precision +results, the inputs must first by zero-extended or sign-extended to the +desired size. + +### INT_DIV + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode input.| +|input1|Second varnode input (divisor).| +|output|Varnode containing result of division.| + +**Semantic statement** + +`output = input0 / input1;` + +This is an unsigned integer division operation. Divide input0 by input1, +truncating the result to the nearest integer, and store the result in +output. Both inputs and output must be the same size. There is no +handling of division by zero. To simulate a processor's handling of a +division-by-zero trap, other operations must be used before the +**INT_DIV**. + +### INT_REM + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode input.| +|input1|Second varnode input (divisor).| +|output|Varnode containing remainder of division.| + +**Semantic statement** + +`output = input0 % input1;` + +This is an unsigned integer remainder operation. The remainder of +performing the unsigned integer division of input0 and input1 is put in +output. Both inputs and output must be the same size. If q = +input0/input1, using the **INT_DIV** operation defined above, +then output satisfies the equation q*input1 + output = input0, using +the **INT_MULT** and **INT_ADD** operations. + +### INT_SDIV + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode input.| +|input1|Second varnode input (divisor).| +|output|Varnode containing result of signed division.| + +**Semantic statement** + +`output = input0 s/ input1;` + +This is a signed integer division operation. The resulting integer is +the one closest to the rational value input0/input1 but which is still +smaller in absolute value. Both inputs and output must be the same size. +There is no handling of division by zero. To simulate a processor's +handling of a division-by-zero trap, other operations must be used +before the **INT_SDIV**. + +### INT_SREM + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First varnode input.| +|input1|Second varnode input (divisor).| +|output|Varnode containing remainder of signed division.| + +**Semantic statement** + +`output = input0 s% input1;` + +This is a signed integer remainder operation. The remainder of +performing the signed integer division of input0 and input1 is put in +output. Both inputs and output must be the same size. If q = input0 s/ +input1, using the **INT_SDIV** operation defined above, then +output satisfies the equation q*input1 + output = input0, using the +**INT_MULT** and **INT_ADD** operations. + +### BOOL_NEGATE + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Boolean varnode to negate.| +|output|Boolean varnode containing result of negation.| + +**Semantic statement** + +`output = !input0;` + +This is a logical negate operator, where we assume input0 and output are +boolean values. It puts the logical complement of input0, treated as a +single bit, into output. Both input0 and output are size 1. Boolean +values are implemented with a full byte, but are still considered to +only support a value of *true* or *false*. + +### BOOL_XOR + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First boolean input to exclusive-or.| +|input1|Second boolean input to exclusive-or.| +|output|Boolean varnode containing result of exclusive-or.| + +**Semantic statement** + +`output = input0 ^^ input1;` + +This is an Exclusive-Or operator, where we assume the inputs and output +are boolean values. It puts the exclusive-or of input0 and input1, +treated as single bits, into output. Both inputs and output are size 1. +Boolean values are implemented with a full byte, but are still +considered to only support a value of *true* or +*false*. + +### BOOL_AND + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First boolean input to logical-and.| +|input1|Second boolean input to logical-and.| +|output|Boolean varnode containing result of logical-and.| + +**Semantic statement** + +`output = input0 && input1;` + +This is a Logical-And operator, where we assume the inputs and output +are boolean values. It puts the logical-and of input0 and input1, +treated as single bits, into output. Both inputs and output are size 1. +Boolean values are implemented with a full byte, but are still +considered to only support a value of *true* or +*false*. + +### BOOL_OR + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First boolean input to logical-or.| +|input1|Second boolean input to logical-or.| +|output|Boolean varnode containing result of logical-or.| + +**Semantic statement** + +`output = input0 || input1;` + +This is a Logical-Or operator, where we assume the inputs and output are +boolean values. It puts the logical-or of input0 and input1, treated as +single bits, into output. Both inputs and output are size 1. Boolean +values are implemented with a full byte, but are still considered to +only support a value of *true* or *false*. + +### FLOAT_EQUAL + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First floating-point input to compare.| +|input1|Second floating-point input to compare.| +|output|Boolean varnode containing result of comparison.| + +**Semantic statement** + +`output = input0 f== input1;` + +This is a floating-point equality operator. Output is assigned +*true*, if input0 and input1 are considered equal as +floating-point values. Both inputs must be the same size, and output is +size 1. If either input is **NaN**, output is set to +*false*. + +### FLOAT_NOTEQUAL + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First floating-point input to compare.| +|input1|Second floating-point input to compare.| +|output|Boolean varnode containing result of comparison.| + +**Semantic statement** + +`output = input0 f!= input1;` + +This is a floating-point inequality operator. Output is assigned +*true*, if input0 and input1 are not considered equal as +floating-point values. Both inputs must be the same size, and output is +size 1. If either input is **NaN**, output is set to +*false*. + +### FLOAT_LESS + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First floating-point input to compare.| +|input1|Second floating-point input to compare.| +|output|Boolean varnode containing result of comparison.| + +**Semantic statement** + +`output = input0 f< input1;` + +This is a comparison operator, where both inputs are considered +floating-point values. Output is assigned *true*, if input0 +is less than input1. Both inputs must be the same size, and output is +size 1. If either input is **NaN**, output is set to +*false*. + +### FLOAT_LESSEQUAL + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First floating-point input to compare.| +|input1|Second floating-point input to compare.| +|output|Boolean varnode containing result of comparison.| + +**Semantic statement** + +`output = input0 f<= input1;` + +This is a comparison operator, where both inputs are considered +floating-point values. Output is assigned *true*, if input0 +is less than or equal to input1. Both inputs must be the same size, and +output is size 1. If either input is **NaN**, output is set to +*false*. + +### FLOAT_ADD + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First floating-point input to add.| +|input1|Second floating-point input to add.| +|output|Varnode containing result of addition.| + +**Semantic statement** + +`output = input0 f+ input1;` + +This is a floating-point addition operator. The result of adding input0 +and input1 as floating-point values is stored in output. Both inputs and +output must be the same size. If either input is **NaN**, +output is set to **NaN**. If any overflow condition occurs, +output is set to **NaN**. + +### FLOAT_SUB + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First floating-point input.| +|input1|Floating-point varnode to subtract from first.| +|output|Varnode containing result of subtraction.| + +**Semantic statement** + +`output = input0 f- input1;` + +This is a floating-point subtraction operator. The result of subtracting +input1 from input0 as floating-point values is stored in output. Both +inputs and output must be the same size. If either input is +**NaN**, output is set to **NaN**. If any overflow +condition occurs, output is set to **NaN**. + +### FLOAT_MULT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First floating-point input to multiply.| +|input1|Second floating-point input to multiply.| +|output|Varnode containing result of multiplication.| + +**Semantic statement** + +`output = input0 f* input1;` + +This is a floating-point multiplication operator. The result of +multiplying input0 to input1 as floating-point values is stored in +output. Both inputs and output must be the same size. If either input is +**NaN**, output is set to **NaN**. If any overflow +condition occurs, output is set to **NaN**. + +### FLOAT_DIV + +|**Parameters**|**Description**| +|:-:|:-| +|input0|First floating-point input.| +|input1|Second floating-point input (divisor).| +|output|Varnode containing result of division.| + +**Semantic statement** + +`output = input0 f/ input1;` + +This is a floating-point division operator. The result of dividing +input1 into input0 as floating-point values is stored in output. Both +inputs and output must be the same size. If either input is +**NaN**, output is set to **NaN**. If any overflow +condition occurs, output is set to **NaN**. + +### FLOAT_NEG + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Floating-point varnode to negate.| +|output|Varnode containing result of negation.| + +**Semantic statement** + +`output = f- input0;` + +This is a floating-point negation operator. The floating-point value in +input0 is stored in output with the opposite sign. Both input and output +must be the same size. If input is **NaN**, output is set to +**NaN**. + +### FLOAT_ABS + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Floating-point input.| +|output|Varnode result containing absolute-value.| + +**Semantic statement** + +`output = abs(input0);` + +This is a floating-point absolute-value operator. The absolute value of +input0 is stored in output. Both input0 and output must be the same +size. If input0 is **NaN**, output is set to **NaN**. + +### FLOAT_SQRT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Floating-point input.| +|output|Varnode result containing square root.| + +**Semantic statement** + +`output = sqrt(input0);` + +This is a floating-point square-root operator. The square root of input0 +is stored in output. Both input0 and output must be the same size. If +input0 is **NaN**, output is set to **NaN**. + +### FLOAT_CEIL + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Floating-point input.| +|output|Varnode result containing result of truncation.| + +**Semantic statement** + +`output = ceil(input0);` + +This operation rounds input0, as a signed floating-point value, towards +*positive infinity*. For instance, the value 1.2 rounds to +2.0; -1.2 rounds to -1.0. The integral value obtained by rounding input0 +up is stored in output, as a floating-point value. Both input0 and +output must be the same size. If input0 is **NaN**, output is +set to **NaN**. + +### FLOAT_FLOOR + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Floating-point input.| +|output|Varnode result containing result of truncation.| + +**Semantic statement** + +`output = floor(input0);` + +This operation rounds input0, as a floating-point value, towards +*negative infinity*. For instance, the value 1.2 rounds to +1.0 and -1.2 rounds to -2.0. The integral value obtained by rounding +input0 down is stored in output, as a floating-point value. +**FLOAT_FLOOR** does *not* produce a twos +complement integer output (See the **TRUNC** operator). Both +input0 and output must be the same size. If input0 is **NaN**, +output is set to **NaN**. + +### FLOAT_ROUND + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Floating-point input.| +|output|Varnode result containing result of truncation.| + +**Semantic statement** + +`output = round(input0);` + +This is a floating-point rounding operator. The integral value closest +to the floating-point value in input0 is stored in output, as a +floating-point value. For example, 1.2 rounds to 1.0 and 1.9 rounds to +2.0. **FLOAT_ROUND** does *not* produce a twos +complement integer output (See the **TRUNC** operator). Both +input0 and output must be the same size. If input0 is **NaN**, +output is set to **NaN**. + +### FLOAT_NAN + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Floating-point input.| +|output|Boolean varnode containing result of NaN test.| + +**Semantic statement** + +`output = nan(input0);` + +This operator returns *true* in output if input0 is +interpreted as **NaN**. Output must be size 1, and input0 can +be any size. + +### INT2FLOAT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Signed integer input.| +|output|Result containing floating-point conversion.| + +**Semantic statement** + +`output = int2float(input0);` + +This is an integer to floating-point conversion operator. Input0 viewed +as a signed integer is converted to floating-point format and stored in +output. Input0 and output do not need to be the same size. The +conversion to floating-point may involve a loss of precision. + +### FLOAT2FLOAT + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Floating-point input varnode.| +|output|Result varnode containing conversion.| + +**Semantic statement** + +`output = float2float(input0);` + +This is a floating-point precision conversion operator. The +floating-point value in input0 is converted to a floating-point value of +a different size and stored in output. If output is smaller than input0, +then the operation will lose precision. Input0 and output should be +different sizes. If input0 is **NaN**, then output is set to +**NaN**. + +### TRUNC + +|**Parameters**|**Description**| +|:-:|:-| +|input0|Floating-point input varnode.| +|output|Resulting integer varnode containing conversion.| + +**Semantic statement** + +`output = trunc(input0);` + +This is a floating-point to integer conversion operator. The +floating-point value in input0 is converted to a signed integer and +stored in output using the default twos complement encoding. The +fractional part of input0 is dropped in the conversion by rounding +*towards zero*. Input0 and output can be different sizes. \ No newline at end of file diff --git a/sources/GhidraDocs/languages/html/pcoderef.html b/sources/GhidraDocs/languages/html/pcoderef.html new file mode 100644 index 0000000..5347599 --- /dev/null +++ b/sources/GhidraDocs/languages/html/pcoderef.html @@ -0,0 +1,369 @@ + + + +P-Code Reference Manual + + + + + + + +
+ + + + + + + +
P-Code Reference Manual
   Next +
+
+
+
+
+
+

+P-Code Reference Manual

+

Last updated March 2, 2023

+
+
+
+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
COPYINT_ADDBOOL_OR
LOADINT_SUBFLOAT_EQUAL
STOREINT_CARRYFLOAT_NOTEQUAL
BRANCHINT_SCARRYFLOAT_LESS
CBRANCHINT_SBORROWFLOAT_LESSEQUAL
BRANCHINDINT_2COMPFLOAT_ADD
CALLINT_NEGATEFLOAT_SUB
CALLINDINT_XORFLOAT_MULT
USERDEFINEDINT_ANDFLOAT_DIV
RETURNINT_ORFLOAT_NEG
PIECEINT_LEFTFLOAT_ABS
SUBPIECEINT_RIGHTFLOAT_SQRT
POPCOUNTINT_SRIGHTFLOAT_CEIL
LZCOUNTINT_MULTFLOAT_FLOOR
INT_EQUALINT_DIVFLOAT_ROUND
INT_NOTEQUALINT_REMFLOAT_NAN
INT_LESSINT_SDIVINT2FLOAT
INT_SLESSINT_SREMFLOAT2FLOAT
INT_LESSEQUALBOOL_NEGATETRUNC
INT_SLESSEQUALBOOL_XORCPOOLREF
INT_ZEXTBOOL_ANDNEW
INT_SEXT
+
+
+

+A Brief Introduction to P-Code

+

+P-code is a register transfer language designed +for reverse engineering applications. The language is general enough +to model the behavior of many different processors. By modeling in +this way, the analysis of different processors is put into a common +framework, facilitating the development of retargetable analysis +algorithms and applications. +

+

+Fundamentally, p-code works by translating individual processor instructions +into a sequence of p-code operations that take +parts of the processor state as input and output variables +(varnodes). The set of unique p-code operations +(distinguished by opcode) comprise a fairly tight set +of the arithmetic and logical actions performed by general purpose processors. +The direct translation of instructions into these operations is referred +to as raw p-code. Raw p-code can be used to directly emulate +instruction execution and generally follows the same control-flow, +although it may add some of its own internal control-flow. The subset of +opcodes that can occur in raw p-code is described in +the section called “P-Code Operation Reference” and in the section called “Pseudo P-CODE Operations”, making up +the bulk of this document. +

+

+P-code is designed specifically to facilitate the +construction of data-flow graphs for follow-on analysis of +disassembled instructions. Varnodes and +p-code operators can be thought of explicitly as nodes in these graphs. +Generation of raw p-code is a necessary first step in graph construction, +but additional steps are required, which introduces some new +opcodes. Two of these, +MULTIEQUAL and INDIRECT, +are specific to the graph construction process, but other opcodes can be introduced during +subsequent analysis and transformation of a graph and help hold recovered data-type relationships. +All of the new opcodes are described in the section called “Additional P-CODE Operations”, none of which can occur +in the original raw p-code translation. Finally, a few of the p-code operators, +CALL, +CALLIND, and RETURN, +may have their input and output varnodes changed during analysis so that they no +longer match their raw p-code form. +

+

+The core concepts of p-code are: +

+
+

+Address Space

+

+The address space for p-code is a generalization +of RAM. It is defined simply as an indexed sequence of bytes that can +be read and written by the p-code operations. For a specific byte, the unique index +that labels it is the byte's address. An address space has a +name to identify it, a size that indicates the number of distinct +indices into the space, and an endianness +associated with it that indicates how integers and other multi-byte +values are encoded into the space. A typical processor +will have a ram space, to model +memory accessible via its main data bus, and +a register space for modeling the +processor's general purpose registers. Any data that a processor +manipulates must be in some address space. The specification for a +processor is free to define as many address spaces as it needs. There +is always a special address space, called +a constant address space, which is +used to encode any constant values needed for p-code operations. Systems generating +p-code also generally use a dedicated temporary +space, which can be viewed as a bottomless source of temporary registers. These +are used to hold intermediate values when modeling instruction behavior. + +

+

+P-code specifications allow the addressable unit of an address +space to be bigger than just a byte. Each address space has +a wordsize attribute that can be set +to indicate the number of bytes in a unit. A wordsize which is bigger +than one makes little difference to the representation of p-code. All +the offsets into an address space are still represented internally as +a byte offset. The only exceptions are +the LOAD and +STORE p-code +operations. These operations read a pointer offset that must be scaled properly to get the +right byte offset when dereferencing the pointer. The wordsize attribute has no effect on +any of the other p-code operations. +

+
+
+

+Varnode

+

+A varnode is a generalization of +either a register or a memory location. It is represented by the formal triple: +an address space, an offset into the space, and a size. Intuitively, a +varnode is a contiguous sequence of bytes in some address space that +can be treated as a single value. All manipulation of data by p-code +operations occurs on varnodes. +

+

+Varnodes by themselves are just a contiguous chunk of bytes, +identified by their address and size, and they have no type. The +p-code operations however can force one of three type interpretations +on the varnodes: integer, boolean, and floating-point. +

+
    +
  • + Operations that manipulate integers always interpret a varnode as a + twos-complement encoding using the endianness associated with the + address space containing the varnode. +
    • +
  • + A varnode being used as a boolean value is assumed to be a single byte + that can only take the value 0, for false, and 1, + for true. +
    • +
  • + Floating-point operations use the encoding expected by the processor being modeled, + which varies depending on the size of the varnode. + For most processors, these encodings are described by the IEEE 754 standard, but + other encodings are possible in principle. +
    • +
+

+

+

+If a varnode is specified as an offset into +the constant address space, that +offset is interpreted as a constant, or immediate value, in any p-code +operation that uses that varnode. The size of the varnode, in this +case, can be treated as the size or precision available for the encoding +of the constant. As with other varnodes, constants only have a type forced +on them by the p-code operations that use them. +

+
+
+

+P-code Operation

+

+A p-code operation is the analog of a +machine instruction. All p-code operations have the same basic format +internally. They all take one or more varnodes as input and optionally +produce a single output varnode. The action of the operation is determined by +its opcode. +For almost all p-code operations, only the output varnode can have its +value modified; there are no indirect effects of the operation. +The only possible exceptions are pseudo operations, +see the section called “Pseudo P-CODE Operations”, which are sometimes necessary when there +is incomplete knowledge of an instruction's behavior. +

+

+All p-code operations are associated with the address of the original +processor instruction they were translated from. For a single instruction, +a 1-up counter, starting at zero, is used to enumerate the +multiple p-code operations involved in its translation. The address and +counter as a pair are referred to as the p-code op's +unique sequence number. Control-flow of +p-code operations generally follows sequence number order. When execution +of all p-code for one instruction is completed, if the +instruction has fall-through semantics, p-code +control-flow picks up with the first p-code operation in sequence corresponding to +the instruction at the fall-through address. Similarly, if a p-code operation +results in a control-flow branch, the first p-code operation in sequence executes +at the destination address. +

+

+The list of possible +opcodes are similar to many RISC based instruction sets. The effect of +each opcode is described in detail in the following sections, +and a reference table is given +in the section called “Syntax Reference”. In general, the size or +precision of a particular p-code operation is determined by the size +of the varnode inputs or output, not by the opcode. +

+
+
+
+
+
+ + + + + + + + + + + +
   Next +
   P-Code Operation Reference
+
+ + diff --git a/sources/GhidraDocs/languages/html/pcoderef.md b/sources/GhidraDocs/languages/html/pcoderef.md new file mode 100644 index 0000000..d1d7274 --- /dev/null +++ b/sources/GhidraDocs/languages/html/pcoderef.md @@ -0,0 +1,155 @@ +--- +status: collected +title: A Brief Introduction to P-Code +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/pcoderef.html +--- + +# A Brief Introduction to P-Code + +P-code is a *register transfer language* designed for +reverse engineering applications. The language is general enough to +model the behavior of many different processors. By modeling in this +way, the analysis of different processors is put into a common +framework, facilitating the development of retargetable analysis +algorithms and applications. + +Fundamentally, p-code works by translating individual processor +instructions into a sequence of **p-code operations** that take +parts of the processor state as input and output variables +(**varnodes**). The set of unique p-code operations +(distinguished by **opcode**) comprise a fairly tight set of +the arithmetic and logical actions performed by general purpose +processors. The direct translation of instructions into these operations +is referred to as **raw p-code**. Raw p-code can be used to +directly emulate instruction execution and generally follows the same +control-flow, although it may add some of its own internal control-flow. +The subset of opcodes that can occur in raw p-code is described in [the +section called "P-Code Operation +Reference"](pcodedescription.md "P-Code Operation Reference") +and in [the section called "Pseudo P-CODE +Operations"](pseudo-ops.md "Pseudo P-CODE Operations"), making +up the bulk of this document. + +P-code is designed specifically to facilitate the construction of +*data-flow* graphs for follow-on analysis of disassembled +instructions. Varnodes and p-code operators can be thought of explicitly +as nodes in these graphs. Generation of raw p-code is a necessary first +step in graph construction, but additional steps are required, which +introduces some new opcodes. Two of these, **MULTIEQUAL** and +**INDIRECT**, are specific to the graph construction process, +but other opcodes can be introduced during subsequent analysis and +transformation of a graph and help hold recovered data-type +relationships. All of the new opcodes are described in [the section +called "Additional P-CODE +Operations"](additionalpcode.md "Additional P-CODE Operations"), +none of which can occur in the original raw p-code translation. Finally, +a few of the p-code operators, **CALL**, **CALLIND**, +and **RETURN**, may have their input and output varnodes +changed during analysis so that they no longer match their *raw +p-code* form. + +The core concepts of p-code are: + +### Address Space + +The **address space** for p-code is a generalization of RAM. It +is defined simply as an indexed sequence of bytes that can be read and +written by the p-code operations. For a specific byte, the unique index +that labels it is the byte\'s **address**. An address space has +a name to identify it, a size that indicates the number of distinct +indices into the space, and an **endianness** associated with +it that indicates how integers and other multi-byte values are encoded +into the space. A typical processor will have a **ram** space, +to model memory accessible via its main data bus, and a +**register** space for modeling the processor\'s general +purpose registers. Any data that a processor manipulates must be in some +address space. The specification for a processor is free to define as +many address spaces as it needs. There is always a special address +space, called a **constant** address space, which is used to +encode any constant values needed for p-code operations. Systems +generating p-code also generally use a dedicated **temporary** +space, which can be viewed as a bottomless source of temporary +registers. These are used to hold intermediate values when modeling +instruction behavior. + +P-code specifications allow the addressable unit of an address space to +be bigger than just a byte. Each address space has a +**wordsize** attribute that can be set to indicate the number +of bytes in a unit. A wordsize which is bigger than one makes little +difference to the representation of p-code. All the offsets into an +address space are still represented internally as a byte offset. The +only exceptions are the **LOAD** and **STORE** p-code +operations. These operations read a pointer offset that must be scaled +properly to get the right byte offset when dereferencing the pointer. +The wordsize attribute has no effect on any of the other p-code +operations. + +### Varnode + +A **varnode** is a generalization of either a register or a +memory location. It is represented by the formal triple: an address +space, an offset into the space, and a size. Intuitively, a varnode is a +contiguous sequence of bytes in some address space that can be treated +as a single value. All manipulation of data by p-code operations occurs +on varnodes. + +Varnodes by themselves are just a contiguous chunk of bytes, identified +by their address and size, and they have no type. The p-code operations +however can force one of three *type* interpretations on +the varnodes: integer, boolean, and floating-point. + +- Operations that manipulate integers always interpret a varnode as a + twos-complement encoding using the endianness associated with the + address space containing the varnode. +- A varnode being used as a boolean value is assumed to be a single + byte that can only take the value 0, for *false*, and + 1, for *true*. +- Floating-point operations use the encoding expected by the processor + being modeled, which varies depending on the size of the varnode. + For most processors, these encodings are described by the IEEE 754 + standard, but other encodings are possible in principle. + +If a varnode is specified as an offset into the **constant** +address space, that offset is interpreted as a constant, or immediate +value, in any p-code operation that uses that varnode. The size of the +varnode, in this case, can be treated as the size or precision available +for the encoding of the constant. As with other varnodes, constants only +have a type forced on them by the p-code operations that use them. + +### P-code Operation + +A **p-code operation** is the analog of a machine instruction. +All p-code operations have the same basic format internally. They all +take one or more varnodes as input and optionally produce a single +output varnode. The action of the operation is determined by its +**opcode**. For almost all p-code operations, only the output +varnode can have its value modified; there are no indirect effects of +the operation. The only possible exceptions are *pseudo* +operations, see [the section called "Pseudo P-CODE +Operations"](pseudo-ops.md "Pseudo P-CODE Operations"), which +are sometimes necessary when there is incomplete knowledge of an +instruction\'s behavior. + +All p-code operations are associated with the address of the original +processor instruction they were translated from. For a single +instruction, a 1-up counter, starting at zero, is used to enumerate the +multiple p-code operations involved in its translation. The address and +counter as a pair are referred to as the p-code op\'s unique **sequence +number**. Control-flow of p-code operations generally follows +sequence number order. When execution of all p-code for one instruction +is completed, if the instruction has *fall-through* +semantics, p-code control-flow picks up with the first p-code operation +in sequence corresponding to the instruction at the fall-through +address. Similarly, if a p-code operation results in a control-flow +branch, the first p-code operation in sequence executes at the +destination address. + +The list of possible opcodes are similar to many RISC based instruction +sets. The effect of each opcode is described in detail in the following +sections, and a reference table is given in [the section called "Syntax +Reference"](reference.md "Syntax Reference"). In general, the +size or precision of a particular p-code operation is determined by the +size of the varnode inputs or output, not by the opcode. \ No newline at end of file diff --git a/sources/GhidraDocs/languages/html/pseudo-ops.html b/sources/GhidraDocs/languages/html/pseudo-ops.html new file mode 100644 index 0000000..bbcc9f6 --- /dev/null +++ b/sources/GhidraDocs/languages/html/pseudo-ops.html @@ -0,0 +1,241 @@ + + + +Pseudo P-CODE Operations + + + + + + + + + +
+ + + + + + + +
Pseudo P-CODE Operations
+Prev   Next +
+
+
+
+

+Pseudo P-CODE Operations

+

+Practical analysis systems need to be able to describe operations, whose exact effect on a machine's +memory state is not fully modeled. P-code allows for this by defining a small set of +pseudo operators. Such an operator is generally treated as a placeholder +for some, possibly large, sequence of changes to the machine state. In terms of analysis, +either the operator is just carried through as a black-box or it serves as a plug-in point for operator +substitution or other specially tailored transformation. Pseudo operators may violate the requirement +placed on other p-code operations that all effects must be explicit. +

+
+

+USERDEFINED

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0(special)Constant ID of user-defined op to perform.
input1First parameter of user-defined op.
...Additional parameters of user-defined op.
[output]Optional output of user-defined op.
Semantic statement
userop(input1, ... );
output = userop(input1,...);
+
+

+This is a placeholder for (a family of) user-definable p-code +instructions. It allows p-code instructions to be defined with +semantic actions that are not fully specified. Machine instructions +that are too complicated or too esoteric to fully implement can use +one or more USERDEFINED instructions +as placeholders for their semantics. +

+

+The first input parameter input0 is a constant ID assigned by the specification +to a particular semantic action. Depending on how the specification +defines the action associated with the ID, +the USERDEFINED instruction can take +an arbitrary number of input parameters and optionally have an output +parameter. Exact details are processor and specification dependent. +Ideally, the output parameter is determined by the input +parameters, and no variable is affected except the output +parameter. But this is no longer a strict requirement, side-effects are possible. +Analysis should generally treat these instructions as a “black-box” which +still have normal data-flow and can be manipulated symbolically. +

+
+
+

+CPOOLREF

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode containing pointer offset to object.
input1(special)Constant ID indicating type of value to return.
...Additional parameters describing value to return.
outputVarnode to contain requested size, offset, or address.
Semantic statement
output = cpool(input0,intput1);
+
+

+This operator returns specific run-time dependent values from the +constant pool. This is a concept for object-oriented +instruction sets and other managed code environments, where some details about +how instructions behave can be deferred +until run-time and are not directly encoded in the instruction. +The CPOOLREF operator acts a query to the system to +recover this type of information. The first parameter is a +pointer to a specific object, and subsequent parameters are IDs or other special constants +describing exactly what value is requested, relative to the object. The canonical example +is requesting a method address given just an ID describing the method and a specific object, but +CPOOLREF can be used as a placeholder for recovering +any important value the system knows about. Details about this instruction, in terms +of emulation and analysis, are necessarily architecture dependent. +

+
+
+

+NEW

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParametersDescription
input0Varnode containing class reference
[input1]If present, varnode containing count of objects to allocate.
outputVarnode to contain pointer to allocated memory.
Semantic statement
output = new(input0);
+
+

+This operator allocates memory for an object described by the first parameter and +returns a pointer to that memory. +This is used to model object-oriented instruction sets where object allocation is an atomic operation. +Exact details about how memory is affected by a NEW operation is generally +not modeled in these cases, so the operator serves as a placeholder to allow analysis to proceed. +

+
+
+
+
+ + + + + + + + + + + +
+Prev   Next +
P-Code Operation Reference Home Additional P-CODE Operations
+
+ + diff --git a/sources/GhidraDocs/languages/html/pseudo-ops.md b/sources/GhidraDocs/languages/html/pseudo-ops.md new file mode 100644 index 0000000..5107c79 --- /dev/null +++ b/sources/GhidraDocs/languages/html/pseudo-ops.md @@ -0,0 +1,102 @@ +--- +status: collected +title: Pseudo P-CODE Operations +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/pseudo-ops.html +--- + +# Pseudo P-CODE Operations + +Practical analysis systems need to be able to describe operations, whose +exact effect on a machine\'s memory state is not fully modeled. P-code +allows for this by defining a small set of *pseudo*{.emphasis} +operators. Such an operator is generally treated as a placeholder for +some, possibly large, sequence of changes to the machine state. In terms +of analysis, either the operator is just carried through as a black-box +or it serves as a plug-in point for operator substitution or other +specially tailored transformation. Pseudo operators may violate the +requirement placed on other p-code operations that all effects must be +explicit. + +### USERDEFINED + +|Parameters|Description| +|:-:|-:| +|input0(**special**)|Constant ID of user-defined op to perform.| +|input1|First parameter of user-defined op.| +|...|Additional parameters of user-defined op.| +|[output]|Optional output of user-defined op.| + +**Semantic statement** + +`userop(input1, ... );` + +`output = userop(input1,...);` + +This is a placeholder for (a family of) user-definable p-code +instructions. It allows p-code instructions to be defined with semantic +actions that are not fully specified. Machine instructions that are too +complicated or too esoteric to fully implement can use one or more +**USERDEFINED** instructions as placeholders for their +semantics. + +The first input parameter input0 is a constant ID assigned by the +specification to a particular semantic action. Depending on how the +specification defines the action associated with the ID, the +**USERDEFINED** instruction can take an arbitrary number of +input parameters and optionally have an output parameter. Exact details +are processor and specification dependent. Ideally, the output parameter +is determined by the input parameters, and no variable is affected +except the output parameter. But this is no longer a strict requirement, +side-effects are possible. Analysis should generally treat these +instructions as a "black-box" which still have normal data-flow and can +be manipulated symbolically. + +### CPOOLREF + +|Parameters|Description| +|:-:|-:| +|input0|Varnode containing pointer offset to object.| +|input1(**special**)|Constant ID indicating type of value to return.| +|...|Additional parameters describing value to return.| +|output|Varnode to contain requested size, offset, or address.| + +**Semantic statement** + +`output = cpool(input0,intput1);` + +This operator returns specific run-time dependent values from the +*constant pool*{.emphasis}. This is a concept for object-oriented +instruction sets and other managed code environments, where some details +about how instructions behave can be deferred until run-time and are not +directly encoded in the instruction. The **CPOOLREF** operator +acts a query to the system to recover this type of information. The +first parameter is a pointer to a specific object, and subsequent +parameters are IDs or other special constants describing exactly what +value is requested, relative to the object. The canonical example is +requesting a method address given just an ID describing the method and a +specific object, but **CPOOLREF** can be used as a placeholder +for recovering any important value the system knows about. Details about +this instruction, in terms of emulation and analysis, are necessarily +architecture dependent. + +### NEW + +|Parameters|Description| +|:-:|-:| +|input0|Varnode containing class reference| +|[input1]|If present, varnode containing count of objects to allocate.| +|output|Varnode to contain pointer to allocated memory.| + +**Semantic statement** + +`output = new(input0);` + +This operator allocates memory for an object described by the first +parameter and returns a pointer to that memory. This is used to model +object-oriented instruction sets where object allocation is an atomic +operation. Exact details about how memory is affected by a +**NEW** operation is generally not modeled in these cases, so +the operator serves as a placeholder to allow analysis to proceed. \ No newline at end of file diff --git a/sources/GhidraDocs/languages/html/reference.html b/sources/GhidraDocs/languages/html/reference.html new file mode 100644 index 0000000..0212d3e --- /dev/null +++ b/sources/GhidraDocs/languages/html/reference.html @@ -0,0 +1,530 @@ + + + +Syntax Reference + + + + + + + + +
+ + + + + + + +
Syntax Reference
+Prev   
+
+
+
+

+Syntax Reference

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameSyntaxDescription
COPYv0 = v1;Copy v1 into v0.
LOAD +
+ + + + + + + + + + + + + +
* v1
*[spc]v1
*:2 v1
*[spc]:2 v1
+
+ 		Dereference v1 as pointer into default space. Optionally specify a space + to load from and size of data in bytes.
STORE +
+ + + + + + + + + + + + + +
*v0 = v1;
*[spc]v0 = v1;
*:4 v0 = v1;
*[spc]:4 v0 = v1;
+
+ 		Store in v1 in default space using v0 as pointer. Optionally specify space to store in + and size of data in bytes.
BRANCHgoto v0;Branch execution to address of v0.
CBRANCHif (v0) goto v1;Branch execution to address of v1 if v0 equals 1 (true).
BRANCHINDgoto [v0];Branch execution to value in v0 viewed as an offset into the current space.
CALLcall v0;Branch execution to address of v0. Hint that the branch is a subroutine call.
CALLINDcall [v0];Branch execution to value in v0 viewed as an offset into the current space. + Hint that the branch is a subroutine call.
RETURNreturn [v0];Branch execution to value in v0 viewed as an offset into the current space. + Hint that the branch is a subroutine return.
PIECE<na>Concatenate two varnodes into a single varnode.
SUBPIECEv0:2The least signficant n bytes of v0.
SUBPIECEv0(2)All but the least significant n bytes of v0.
POPCOUNTpopcount(v0)Count 1 bits in v0.
LZCOUNTlzcount(v0)Counts the number of leading zero bits in v0.
INT_EQUALv0 == v1True if v0 equals v1.
INT_NOTEQUALv0 != v1True if v0 does not equal v1.
INT_LESS +
+ + + + + + + +
v0 < v1
v1 > v0
+
+ 		True if v0 is less than v1 as an unsigned integer.
INT_SLESS +
+ + + + + + + +
v0 s< v1
v1 s> v0
+
+ 		True if v0 is less than v1 as a signed integer.
INT_LESSEQUAL +
+ + + + + + + +
v0 <= v1
v1 >= v0
+
+ 		True if v0 is less than or equal to v1 as an unsigned integer.
INT_SLESSEQUAL +
+ + + + + + + +
v0 s<= v1
v1 s>= v0
+
+ 		True if v0 is less than or equal to v1 as a signed integer.
INT_ZEXTzext(v0)Zero extension of v0.
INT_SEXTsext(v0)Sign extension of v0.
INT_ADDv0 + v1Addition of v0 and v1 as integers.
INT_SUBv0 - v1Subtraction of v1 from v0 as integers.
INT_CARRYcarry(v0,v1)True if adding v0 and v1 would produce an unsigned carry.
INT_SCARRYscarry(v0,v1)True if adding v0 and v1 would produce an signed carry.
INT_SBORROWsborrow(v0,v1)True if subtracting v1 from v0 would produce a signed borrow.
INT_2COMP-v0Twos complement of v0.
INT_NEGATE~v0Bitwise negation of v0.
INT_XORv0 ^ v1Bitwise Exclusive Or of v0 with v1.
INT_ANDv0 & v1Bitwise Logical And of v0 with v1.
INT_ORv0 | v1Bitwise Logical Or of v0 with v1.
INT_LEFTv0 << v1Left shift of v0 by v1 bits.
INT_RIGHTv0 >> v1Unsigned (logical) right shift of v0 by v1 bits.
INT_SRIGHTv0 s>> v1Signed (arithmetic) right shift of v0 by v1 bits.
INT_MULTv0 * v1Integer multiplication of v0 and v1.
INT_DIVv0 / v1Unsigned division of v0 by v1.
INT_REMv0 % v1Unsigned remainder of v0 modulo v1.
INT_SDIVv0 s/ v1Signed division of v0 by v1.
INT_SREMv0 s% v1Signed remainder of v0 modulo v1.
BOOL_NEGATE!v0Negation of boolean value v0.
BOOL_XORv0 ^^ v1Exclusive-Or of booleans v0 and v1.
BOOL_ANDv0 && v1Logical-And of booleans v0 and v1.
BOOL_ORv0 || v1Logical-Or of booleans v0 and v1.
FLOAT_EQUALv0 f== v1True if v0 equals v1 viewed as floating-point numbers.
FLOAT_NOTEQUALv0 f!= v1True if v0 does not equal v1 viewed as floating-point numbers.
FLOAT_LESS +
+ + + + + + + +
v0 f< v1
v1 f> v0
+
+ 		True if v0 is less than v1 viewed as floating-point numbers.
FLOAT_LESSEQUAL +
+ + + + + + + +
v0 f<= v1
v1 f>= v0
+
+ 		True if v0 is less than or equal to v1 viewed as floating-point numbers.
FLOAT_ADDv0 f+ v1Addition of v0 and v1 as floating-point numbers.
FLOAT_SUBv0 f- v1Subtraction of v1 from v0 as floating-point numbers.
FLOAT_MULTv0 f* v1Multiplication of v0 and v1 as floating-point numbers.
FLOAT_DIVv0 f/ v1Division of v0 by v1 as floating-point numbers.
FLOAT_NEGf- v0Additive inverse of v0 as a floating-point number.
FLOAT_ABSabs(v0)Absolute value of v0 as a floating-point number.
FLOAT_SQRTsqrt(v0)Square root of v0 as a floating-point number.
FLOAT_CEILceil(v0)Nearest integral floating-point value greater than v0, viewed as a floating-point number.
FLOAT_FLOORfloor(v0)Nearest integral floating-point value less than v0, viewed as a floating-point number.
FLOAT_ROUNDround(v0)Nearest integral floating-point to v0, viewed as a floating-point number.
FLOAT_NANnan(v0)True if v0 is not a valid floating-point number (NaN).
INT2FLOATint2float(v0)Floating-point representation of v0 viewed as an integer.
FLOAT2FLOATfloat2float(v0)Copy of floating-point number v0 with more or less precision.
TRUNCtrunc(v0)Signed integer obtained by truncating v0 viewed as a floating-point number.
CPOOLREFcpool(v0,...)Obtain constant pool value.
NEW +
+ + + + + + + +
newobject(v0)
newobject(v0,v1)
+
+ 		Allocate an object or an array of objects.
MULTIEQUAL<na>Compiler phi-node: values merging from multiple control-flow paths.
INDIRECT<na>Indirect effect from input varnode to output varnode.
CAST<na>Copy from input to output. A hint that the underlying datatype has changed.
PTRADD<na>Construct a pointer to an element from a pointer to the start of an array and an index.
PTRSUB<na>Construct a pointer to a field from a pointer to a structure and an offset.
INSERT<na>Insert a value as a bit-range into a varnode
EXTRACT<na>Extract a bit-range from a varnode
+
+
+
+
+ + + + + + + + + + + +
+Prev   
Additional P-CODE Operations Home 
+
+ + diff --git a/sources/GhidraDocs/languages/html/reference.md b/sources/GhidraDocs/languages/html/reference.md new file mode 100644 index 0000000..6fd2b2c --- /dev/null +++ b/sources/GhidraDocs/languages/html/reference.md @@ -0,0 +1,84 @@ +--- +status: collected +title: Syntax Reference +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/reference.html +--- + +# Syntax Reference + +Name|Syntax|Description +:-|:-|:- +COPY|`v0 = v1;`|Copy v1 into v0. +LOAD|`*v1`
`*[spc]v1`
`*:2 v1`
`*[spc]:2 v1`|Dereference v1 as pointer into default space. Optionally specify a space to load from and size of data in bytes. +STORE|`*v0 = v1`
`*[spc]v0 = v1`
`*;4 v0 = v1`
`*[spc]:4 v0 = v1`|Store in v1 in default space using v0 as pointer. Optionally specify space to store in and size of data in bytes. +BRANCH|`goto v0`|Branch execution to address of v0. +CBRANCH|`if (v0) goto v1;`|Branch execution to address of v1 if v0 equals 1 (true). +BRANCHIND|`goto [v0];`|Branch execution to value in v0 viewed as an offset into the current space. +CALL|`call v0;`|Branch execution to address of v0. Hint that the branch is a subroutine call. +CALLIND|`call [v0];`|Branch execution to value in v0 viewed as an offset into the current space. Hint that the branch is a subroutine call. +RETURN|`return [v0];`|Branch execution to value in v0 viewed as an offset into the current space. Hint that the branch is a subroutine return. +PIECE|``|Concatenate two varnodes into a single varnode. +SUBPIECE|`v0:2`|The least signficant n bytes of v0. +SUBPIECE|`v0(2)`|All but the least significant n bytes of v0. +POPCOUNT|`popcount(v0)`|Count 1 bits in v0. +LZCOUNT|`lzcount(v0)`|Counts the number of leading zero bits in v0. +INT_EQUAL|`v0 == v1`|True if v0 equals v1. +INT_NOTEQUAL|`v0 != v1`|True if v0 does not equal v1. +INT_LESS|`v0 < v1`
`v1 > v0`|True if v0 is less than v1 as an unsigned integer. +INT_SLESS|`v0 s< v1`
`v1 s> v0`|True if v0 is less than v1 as a signed integer. +INT_LESSEQUAL|`v0 <= v1`
`v1 >= v0`|True if v0 is less than or equal to v1 as an unsigned integer. +INT_SLESSEQUAL|`v0 s<= v1`
`v1 s>= v0`|True if v0 is less than or equal to v1 as a signed integer. +INT_ZEXT|`zext(v0)`|Zero extension of v0. +INT_SEXT|`sext(v0)`|Sign extension of v0. +INT_ADD|`v0 + v1`|Addition of v0 and v1 as integers. +INT_SUB|`v0 - v1`|Subtraction of v1 from v0 as integers. +INT_CARRY|`carry(v0,v1)`|True if adding v0 and v1 would produce an unsigned carry. +INT_SCARRY|`scarry(v0,v1)`|True if adding v0 and v1 would produce an signed carry. +INT_SBORROW|`sborrow(v0,v1)`|True if subtracting v1 from v0 would produce a signed borrow. +INT_2COMP|`~v0`|Twos complement of v0. +INT_NEGATE|`~v0`|Bitwise negation of v0. +INT_XOR|`v0 ^ v1`|Bitwise Exclusive Or of v0 with v1. +INT_AND|`v0 & v1`|Bitwise Logical And of v0 with v1. +INT_OR|`v0 | v1`|Bitwise Logical Or of v0 with v1. +INT_LEFT|`v0 << v1`|Left shift of v0 by v1 bits. +INT_RIGHT|`v0 >> v1`|Unsigned (logical) right shift of v0 by v1 bits. +INT_SRIGHT|`v0 s>> v1`|Signed (arithmetic) right shift of v0 by v1 bits. +INT_MULT|`v0 * v1`|Integer multiplication of v0 and v1. +INT_DIV|`v0 / v1`|Unsigned division of v0 by v1. +INT_REM|`v0 % v1`|Unsigned remainder of v0 modulo v1. +INT_SDIV|`v0 s/ v1`|Signed division of v0 by v1. +INT_SREM|`v0 s% v1`|Signed remainder of v0 modulo v1. +BOOL_NEGATE|`!v0`|Negation of boolean value v0. +BOOL_XOR|`v0 ^^ v1`|Exclusive-Or of booleans v0 and v1. +BOOL_AND|`v0 && v1`|Logical-And of booleans v0 and v1. +BOOL_OR|`v0 || v1`|Logical-Or of booleans v0 and v1. +FLOAT_EQUAL|`v0 f== v1`|True if v0 equals v1 viewed as floating-point numbers. +FLOAT_NOTEQUAL|`v0 f!= v1`|True if v0 does not equal v1 viewed as floating-point numbers. +FLOAT_LESS|`v0 f< v1`
`v1 f> v0`|True if v0 is less than v1 viewed as floating-point numbers. +FLOAT_LESSEQUAL|`v0 f<= v1`
`v1 f>= v0`|True if v0 is less than or equal to v1 viewed as floating-point numbers. +FLOAT_ADD|`v0 f+ v1`|Addition of v0 and v1 as floating-point numbers. +FLOAT_SUB|`v0 f- v1`|Subtraction of v1 from v0 as floating-point numbers. +FLOAT_MULT|`v0 f* v1`|Multiplication of v0 and v1 as floating-point numbers. +FLOAT_DIV|`v0 f/ v1`| Division of v0 by v1 as floating-point numbers. +FLOAT_NEG|`f- v0`|Additive inverse of v0 as a floating-point number. +FLOAT_ABS|`abs(v0)`|Absolute value of v0 as a floating-point number. +FLOAT_SQRT|`sqrt(v0)`|Square root of v0 as a floating-point number. +FLOAT_CEIL|`ceil(v0)`|Nearest integral floating-point value greater than v0, viewed as a floating-point number. +FLOAT_FLOOR|`floor(v0)`|Nearest integral floating-point value less than v0, viewed as a floating-point number. +FLOAT_ROUND|`round(v0)`|Nearest integral floating-point to v0, viewed as a floating-point number. +FLOAT_NAN|`nan(v0)`|True if v0 is not a valid floating-point number (NaN). +INT2FLOAT|`int2float(v0)`|Floating-point representation of v0 viewed as an integer. +FLOAT2FLOAT|`float2float(v0)`|Copy of floating-point number v0 with more or less precision. +TRUNC|`trunc(v0)`|Signed integer obtained by truncating v0 viewed as a floating-point number. +CPOOLREF|`cpool(v0,...)`|Obtain constant pool value. +NEW|`newobject(v0)`
`newobject(v0,v1)`|Allocate an object or an array of objects. +MULTIEQUAL|``|Compiler phi-node: values merging from multiple control-flow paths. +INDIRECT|``|Indirect effect from input varnode to output varnode. +CAST|``|Copy from input to output. A hint that the underlying datatype has changed. +PTRADD|``|Construct a pointer to an element from a pointer to the start of an array and an index. +PTRSUB|``|Construct a pointer to a field from a pointer to a structure and an offset. +INSERT|``|Insert a value as a bit-range into a varnode +EXTRACT|``|Extract a bit-range from a varnode \ No newline at end of file diff --git a/sources/GhidraDocs/languages/html/sleigh.html b/sources/GhidraDocs/languages/html/sleigh.html new file mode 100644 index 0000000..4ab92f7 --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh.html @@ -0,0 +1,478 @@ + + + +SLEIGH + + + + + + + +
+ + + + + + + +
SLEIGH
   Next +
+
+
+
+
+
+

+SLEIGH

+

A Language for Rapid Processor Specification

+

Last updated October 31, 2023

+

Originally published December 16, 2005

+
+
+
+
+

Table of Contents

+
+
1. Introduction to P-Code
+
+
1.1. Address Spaces
+
1.2. Varnodes
+
1.3. Operations
+
+
2. Basic Specification Layout
+
+
2.1. Comments
+
2.2. Identifiers
+
2.3. Strings
+
2.4. Integers
+
2.5. White Space
+
+
3. Preprocessing
+
+
3.1. Including Files
+
3.2. Preprocessor Macros
+
3.3. Conditional Compilation
+
+
4. Basic Definitions
+
+
4.1. Endianness Definition
+
4.2. Alignment Definition
+
4.3. Space Definitions
+
4.4. Naming Registers
+
4.5. Bit Range Registers
+
4.6. User-Defined Operations
+
+
5. Introduction to Symbols
+
+
5.1. Notes on Namespaces
+
5.2. Predefined Symbols
+
+
6. Tokens and Fields
+
+
6.1. Defining Tokens and Fields
+
6.2. Fields as Family Symbols
+
6.3. Attaching Alternate Meanings to Fields
+
6.4. Context Variables
+
+
7. Constructors
+
+
7.1. The Five Sections of a Constructor
+
7.2. The Table Header
+
7.3. The Display Section
+
7.4. The Bit Pattern Section
+
7.5. Disassembly Actions Section
+
7.6. The With Block
+
7.7. The Semantic Section
+
7.8. Tables
+
7.9. P-code Macros
+
7.10. Build Directives
+
7.11. Delay Slot Directives
+
+
8. Using Context
+
+
8.1. Basic Use of Context Variables
+
8.2. Local Context Change
+
8.3. Global Context Change
+
+
9. P-code Tables
+
+
+
+

+History

+

+ This document describes the syntax for the SLEIGH processor + specification language, which was developed for the GHIDRA + project. The language that is now called SLEIGH has undergone + several redesign iterations, but it can still trace its heritage + from the language SLED, from whom its name is derived. SLED, the + “Specification Language for Encoding and Decoding”, was defined by + Norman Ramsey and Mary F. Fernández in [3] + as a concise way to define the + translation, in both directions, between machine instructions and + their corresponding assembly statements. This facilitated the + development of architecture independent disassemblers and + assemblers, such as the New Jersey Machine-code Toolkit. +

+

+ The direct predecessor of SLEIGH was an implementation of SLED for + GHIDRA, which concentrated on its reverse-engineering + capabilities. The main addition of SLEIGH is the ability to provide + semantic descriptions of instructions for data-flow and decompilation + analysis. This piece of SLEIGH borrowed ideas from the Semantic Syntax Language (SSL), + a specification language developed in [2] for the + University of Queensland Binary Translator (UQBT) project by + Cristina Cifuentes, Mike Van Emmerik and Norman Ramsey. +

+

+ Dr. Cristina Cifuentes' work, in general, was an important starting point for the GHIDRA decompiler. + Its design follows the basic structure layed out in her 1994 thesis "Reverse Compilation Techniques": +

+
    +
  • + Disassembly of machine instructions and translation to an intermediate representation (IR). +
    • +
  • + Transformation toward a high-level representation via +
      +
    • + Data-flow analysis, including dead code analysis and copy propagation. +
      • +
    • + Control-flow analysis, using graph reducibility to achieve a structured representation. +
      • +
    +
    • +
  • + Back-end code generation from the transformed representation. +
    • +
+

+ In keeping with her philosophy of decompilation, SLEIGH is GHIDRA's implementation of the first step. + It efficiently couples disassembly of machine instructions with the initial translation into an IR. +

+
+

References

+
+

[1] Cristina Cifuentes. Reverse Compilation Techniques. 1994. Ph.D. Dissertation. Queensland University of Technology. Brisbane City, QLD, Australia.

+
+
+

[2] Cristina Cifuentes and Mike Van Emmerik. “UQBT: Adaptable Binary Translation at Low Cost”. Computer. (Mar. 2000). pp. 60-66.

+
+
+

[3] Norman Ramsey and Mary F. Fernández. “Specifying Representations of Machine Instructions”. ACM Trans. Programming Languages and Systems. (May 1997). pp. 492-524.

+
+
+
+
+

+Overview

+

+SLEIGH is a language for describing the instruction sets of general +purpose microprocessors, in order to facilitate the reverse +engineering of software written for them. SLEIGH was designed for the +GHIDRA reverse engineering platform and is used to describe +microprocessors with enough detail to facilitate two major components +of GHIDRA, the disassembly and decompilation engines. For disassembly, +SLEIGH allows a concise description of the translation from the bit +encoding of machine instructions to human-readable assembly language +statements. Moreover, it does this with enough detail to allow the +disassembly engine to break apart the statement into the mnemonic, +operands, sub-operands, and associated syntax. For decompilation, +SLEIGH describes the translation from machine instructions into +p-code. P-code is a Register Transfer Language +(RTL), distinct from SLEIGH, designed to specify +the semantics of machine instructions. By +semantics, we mean the detailed description of +how an instruction actually manipulates data, in registers and in +RAM. This provides the foundation for the data-flow analysis performed +by the decompiler. +

+

+A SLEIGH specification typically describes a single microprocessor and +is contained in a single file. The term processor +will always refer to this target of the specification. +

+

+Italics are used when defining terms and for named entities. Bold is used for SLEIGH keywords. +

+
+
+

+1. Introduction to P-Code

+

+Although p-code is a distinct language from SLEIGH, because a major +purpose of SLEIGH is to specify the translation from machine code to +p-code, this document serves as a primer for p-code. The key concepts +and terminology are presented in this section, and more detail is +given in Section 7.7, “The Semantic Section”. There is also a complete set +of tables which list syntax and descriptions for p-code operations in +the Appendix. +

+

+The design criteria for p-code was to have a language that looks much +like modern assembly instruction sets but capable of modeling any +general purpose processor. Code for different processors can be +translated in a straightforward manner into p-code, and then a single +suite of analysis software can be used to do data-flow analysis and +decompilation. In this way, the analysis software +becomes retargetable, and it isn’t necessary to +redesign it for each new processor being analyzed. It is only +necessary to specify the translation of the processor’s instruction +set into p-code. +

+

+So the key properties of p-code are +

+
    +
  • + The language is machine independent. +
    • +
  • + The language is designed to model general purpose processors. +
    • +
  • + Instructions operate on user defined registers and address spaces. +
    • +
  • + All data is manipulated explicitly. Instructions have no indirect effects. +
    • +
  • + Individual p-code operations mirror typical processor tasks and concepts. +
    • +
+

+

+

+SLEIGH is the language which specifies the translation from a machine +instruction to p-code. It specifies both this translation and how to +display the instruction as an assembly statement. +

+

+A model for a particular processor is built out of three concepts: +the address space, +the varnode, and +the operation. These are generalizations of the +computing concepts of RAM, registers, and machine instructions +respectively. +

+
+

+1.1. Address Spaces

+

+An address space for p-code is a generalization of +the indexed memory (RAM) that a typical processor has access to, and +it is defined simply as an indexed sequence of +memory words that can be read and written by +p-code. In almost all cases, a word of the space +is a byte (8 bits), and we will usually use the +term byte instead +of word. However, see the discussion of +the wordsize attribute of address +spaces below. +

+

+The defining characteristics of a space are its name and its size. The +size of a space indicates the number of distinct indices into the +space and is usually given as the number of bytes required to encode +an arbitrary index into the space. A space of size 4 requires a 32 bit +integer to specify all indices and contains +232 bytes. The index of a byte is usually +referred to as the offset, and the offset +together with the name of the space is called +the address of the byte. +

+

+Any manipulation of data that p-code operations perform happens in +some address space. This includes the modeling of data stored in RAM +but also includes the modeling of processor registers. Registers must +be modeled as contiguous sequences of bytes at a specific offset (see +the definition of varnodes below), typically in their own distinct +address space. In order to facilitate the modeling of many different +processors, a SLEIGH specification provides complete control over what +address spaces are defined and where registers are located within +them. +

+

+Typically, a processor can be modeled with only two spaces, +a ram address space that represents the main +memory accessible to the processor via its data-bus, and +a register address space that is used to +implement the processor’s registers. However, the specification +designer can define as many address spaces as needed. +

+

+There is one address space that is automatically defined for a SLEIGH +specification. This space is used to allocate temporary storage when +the SLEIGH compiler breaks down the expressions describing processor +semantics into individual p-code operations. It is called +the unique space. There is also a special address +space, called the const space, used as a +placeholder for constant operands of p-code instructions. For the most +part, a SLEIGH specification doesn’t need to be aware of this space, +but it can be used in certain situations to force values to be +interpreted as constants. +

+
+
+

+1.2. Varnodes

+

+A varnode is the unit of data manipulated by +p-code. It is simply a contiguous sequence of bytes in some address +space. The two defining characteristics of a varnode are +

+
    +
  • + The address of the first byte. +
    • +
  • + The number of bytes (size). +
    • +
+

+With the possible exception of constants treated as varnodes, there is +never any distinction made between one varnode and another. They can +have any size, they can overlap, and any number of them can be +defined. +

+

+Varnodes by themselves are typeless. An individual p-code operation +forces an interpretation on each varnode that it uses, as either an +integer, a floating-point number, or a boolean value. In the case of +an integer, the varnode is interpreted as having a big endian or +little endian encoding, depending on the specification (see +Section 4.1, “Endianness Definition”). Certain instructions +also distinguish between signed and unsigned interpretations. For a +signed integer, the varnode is considered to have a standard twos +complement encoding. For a boolean interpretation, the varnode must be +a single byte in size. In this special case, the zero encoding of the +byte is considered a false value and an encoding +of 1 is a true value. +

+

+These interpretations only apply to the varnode for a particular +operation. A different operation can interpret the same varnode in a +different way. Any consistent meaning assigned to a particular varnode +must be provided and enforced by the specification designer. +

+
+
+

+1.3. Operations

+

+P-code is intended to emulate a target processor by substituting a +sequence of p-code operations for each machine instruction. Thus every +p-code operation is naturally associated with the address of a +specific machine instruction, but there is usually more than one +p-code operation associated with a single machine instruction. Except +in the case of branching, p-code operations have fall-through control +flow, both within and across machine instructions. For a single +machine instruction, the associated p-code operations execute from +first to last. And if there is no branching, execution picks up with +the first operation corresponding to the next machine instruction. +

+

+Every p-code operation can take one or more varnodes as input and can +optionally have one varnode as output. The operation can only make a +change to this output varnode, which is always indicated +explicitly. Because of this rule, all manipulation of data is +explicit. The operations have no indirect effects. In general, there +is absolutely no restriction on what varnodes can be used as inputs +and outputs to p-code operations. The only exceptions to this are that +constants cannot be used as output varnodes and certain operations +impose restrictions on the size of their varnode operands. +

+

+The actual operations should be familiar to anyone who has studied +general purpose processor instruction sets. They break up into groups. +

+
+
+

Table 1. P-code Operations

+
+++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Operation CategoryList of Operations
Data MovingCOPY, LOAD, STORE
ArithmeticINT_ADD, INT_SUB, INT_CARRY, INT_SCARRY, INT_SBORROW, + INT_2COMP, INT_MULT, INT_DIV, INT_SDIV, INT_REM, INT_SREM
LogicalINT_NEGATE, INT_XOR, INT_AND, INT_OR, INT_LEFT, INT_RIGHT, INT_SRIGHT, + POPCOUNT, LZCOUNT
Integer ComparisonINT_EQUAL, INT_NOTEQUAL, INT_SLESS, INT_SLESSEQUAL, INT_LESS, INT_LESSEQUAL
BooleanBOOL_NEGATE, BOOL_XOR, BOOL_AND, BOOL_OR
Floating PointFLOAT_ADD, FLOAT_SUB, FLOAT_MULT, FLOAT_DIV, FLOAT_NEG, + FLOAT_ABS, FLOAT_SQRT, FLOAT_NAN
Floating Point CompareFLOAT_EQUAL, FLOAT_NOTEQUAL, FLOAT_LESS, FLOAT_LESSEQUAL
Floating Point ConversionINT2FLOAT, FLOAT2FLOAT, TRUNC, CEIL, FLOOR, ROUND
BranchingBRANCH, CBRANCH, BRANCHIND, CALL, CALLIND, RETURN
Extension/TruncationINT_ZEXT, INT_SEXT, PIECE, SUBPIECE
Managed CodeCPOOLREF, NEW
+
+
+
+

+We postpone a full discussion of the individual operations until Section 7.7, “The Semantic Section”. +

+
+
+
+
+
+ + + + + + + + + + + +
   Next +
   2. Basic Specification Layout
+
+ + diff --git a/sources/GhidraDocs/languages/html/sleigh.md b/sources/GhidraDocs/languages/html/sleigh.md new file mode 100644 index 0000000..6578a22 --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh.md @@ -0,0 +1,563 @@ +--- +status: collected +title: SLEIGH +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh.html +--- + +::: {.navheader} +SLEIGH +::: + +  + +  + + [Next](sleigh_layout.html) + +------------------------------------------------------------------------ + +::: {.article} +::: {.titlepage} +
+ +
+ +
+ +
+ +### *A Language for Rapid Processor Specification* {#a-language-for-rapid-processor-specification .subtitle} + +
+ +
+ +Last updated October 31, 2023 + +
+ +
+ +Originally published December 16, 2005 + +
+ +
+ +------------------------------------------------------------------------ +::: + +::: {.toc} +**Table of Contents** + +[[1. Introduction to P-Code](sleigh.html#sleigh_introduction)]{.sect1} + +[[1.1. Address Spaces](sleigh.html#sleigh_address_spaces)]{.sect2} + +[[1.2. Varnodes](sleigh.html#sleigh_varnodes)]{.sect2} + +[[1.3. Operations](sleigh.html#sleigh_operations)]{.sect2} + +[[2. Basic Specification Layout](sleigh_layout.html)]{.sect1} + +[[2.1. Comments](sleigh_layout.html#sleigh_comments)]{.sect2} + +[[2.2. Identifiers](sleigh_layout.html#sleigh_identifiers)]{.sect2} + +[[2.3. Strings](sleigh_layout.html#sleigh_strings)]{.sect2} + +[[2.4. Integers](sleigh_layout.html#sleigh_integers)]{.sect2} + +[[2.5. White Space](sleigh_layout.html#sleigh_white_space)]{.sect2} + +[[3. Preprocessing](sleigh_preprocessing.html)]{.sect1} + +[[3.1. Including +Files](sleigh_preprocessing.html#sleigh_including_files)]{.sect2} + +[[3.2. Preprocessor +Macros](sleigh_preprocessing.html#sleigh_preprocessor_macros)]{.sect2} + +[[3.3. Conditional +Compilation](sleigh_preprocessing.html#sleigh_conditional_compilation)]{.sect2} + +[[4. Basic Definitions](sleigh_definitions.html)]{.sect1} + +[[4.1. Endianness +Definition](sleigh_definitions.html#sleigh_endianness_definition)]{.sect2} + +[[4.2. Alignment +Definition](sleigh_definitions.html#sleigh_alignment_definition)]{.sect2} + +[[4.3. Space +Definitions](sleigh_definitions.html#sleigh_space_definitions)]{.sect2} + +[[4.4. Naming +Registers](sleigh_definitions.html#sleigh_naming_registers)]{.sect2} + +[[4.5. Bit Range +Registers](sleigh_definitions.html#sleigh_bitrange_registers)]{.sect2} + +[[4.6. User-Defined +Operations](sleigh_definitions.html#sleigh_userdefined_operations)]{.sect2} + +[[5. Introduction to Symbols](sleigh_symbols.html)]{.sect1} + +[[5.1. Notes on +Namespaces](sleigh_symbols.html#sleigh_notes_namespaces)]{.sect2} + +[[5.2. Predefined +Symbols](sleigh_symbols.html#sleigh_predefined_symbols)]{.sect2} + +[[6. Tokens and Fields](sleigh_tokens.html)]{.sect1} + +[[6.1. Defining Tokens and +Fields](sleigh_tokens.html#sleigh_defining_tokens)]{.sect2} + +[[6.2. Fields as Family +Symbols](sleigh_tokens.html#sleigh_fields_family)]{.sect2} + +[[6.3. Attaching Alternate Meanings to +Fields](sleigh_tokens.html#sleigh_alternate_meanings)]{.sect2} + +[[6.4. Context +Variables](sleigh_tokens.html#sleigh_context_variables)]{.sect2} + +[[7. Constructors](sleigh_constructors.html)]{.sect1} + +[[7.1. The Five Sections of a +Constructor](sleigh_constructors.html#sleigh_sections_constructor)]{.sect2} + +[[7.2. The Table +Header](sleigh_constructors.html#sleigh_table_header)]{.sect2} + +[[7.3. The Display +Section](sleigh_constructors.html#sleigh_display_section)]{.sect2} + +[[7.4. The Bit Pattern +Section](sleigh_constructors.html#sleigh_bit_pattern)]{.sect2} + +[[7.5. Disassembly Actions +Section](sleigh_constructors.html#sleigh_disassembly_actions)]{.sect2} + +[[7.6. The With +Block](sleigh_constructors.html#sleigh_with_block)]{.sect2} + +[[7.7. The Semantic +Section](sleigh_constructors.html#sleigh_semantic_section)]{.sect2} + +[[7.8. Tables](sleigh_constructors.html#sleigh_tables)]{.sect2} + +[[7.9. P-code Macros](sleigh_constructors.html#sleigh_macros)]{.sect2} + +[[7.10. Build +Directives](sleigh_constructors.html#sleigh_build_directives)]{.sect2} + +[[7.11. Delay Slot +Directives](sleigh_constructors.html#sleigh_delayslot_directives)]{.sect2} + +[[8. Using Context](sleigh_context.html)]{.sect1} + +[[8.1. Basic Use of Context +Variables](sleigh_context.html#sleigh_context_basic)]{.sect2} + +[[8.2. Local Context +Change](sleigh_context.html#sleigh_local_change)]{.sect2} + +[[8.3. Global Context +Change](sleigh_context.html#sleigh_global_change)]{.sect2} + +[[9. P-code Tables](sleigh_ref.html)]{.sect1} +::: + +::: {.simplesect} +::: {.titlepage} +
+ +
+ +[]{#sleigh_history}History {#history .title style="clear: both"} +-------------------------- + +
+ +
+::: + +This document describes the syntax for the SLEIGH processor +specification language, which was developed for the GHIDRA project. The +language that is now called SLEIGH has undergone several redesign +iterations, but it can still trace its heritage from the language SLED, +from whom its name is derived. SLED, the "Specification Language for +Encoding and Decoding", was defined by Norman Ramsey and Mary F. +Fernández in [\[3\]](sleigh.html#Ramsey97){.xref} as a concise way to +define the translation, in both directions, between machine instructions +and their corresponding assembly statements. This facilitated the +development of architecture independent disassemblers and assemblers, +such as the New Jersey Machine-code Toolkit. + +The direct predecessor of SLEIGH was an implementation of SLED for +GHIDRA, which concentrated on its reverse-engineering capabilities. The +main addition of SLEIGH is the ability to provide semantic descriptions +of instructions for data-flow and decompilation analysis. This piece of +SLEIGH borrowed ideas from the Semantic Syntax Language (SSL), a +specification language developed in +[\[2\]](sleigh.html#Cifuentes00){.xref} for the University of Queensland +Binary Translator (UQBT) project by Cristina Cifuentes, Mike Van Emmerik +and Norman Ramsey. + +Dr. Cristina Cifuentes\' work, in general, was an important starting +point for the GHIDRA decompiler. Its design follows the basic structure +layed out in her 1994 thesis \"Reverse Compilation Techniques\": + +::: {.informalexample} +::: {.itemizedlist} +- Disassembly of machine instructions and translation to an + intermediate representation (IR). +- Transformation toward a high-level representation via + ::: {.itemizedlist} + - Data-flow analysis, including dead code analysis and copy + propagation. + - Control-flow analysis, using graph reducibility to achieve a + structured representation. + ::: +- Back-end code generation from the transformed representation. +::: +::: + +In keeping with her philosophy of decompilation, SLEIGH is GHIDRA\'s +implementation of the first step. It efficiently couples disassembly of +machine instructions with the initial translation into an IR. + +::: {.bibliolist} +**References** + +::: {.biblioentry} +[]{#Cifuentes94} + +\[1\] [[Cristina]{.firstname} [Cifuentes]{.surname}. +]{.authorgroup}[*Reverse Compilation Techniques*. ]{.title}[1994. +]{.pubdate}[[Ph.D. Dissertation. Queensland University of Technology. +]{.publishername}[[Brisbane City]{.city}, [QLD]{.state}, +[Australia]{.country}. ]{.address}]{.publisher} +::: + +::: {.biblioentry} +[]{#Cifuentes00} + +\[2\] [[[Cristina]{.firstname} [Cifuentes]{.surname} and +[Mike]{.firstname} [Van Emmerik]{.surname}. ]{.authorgroup}"UQBT: +Adaptable Binary Translation at Low Cost". ]{.biblioset}[*Computer*. +[(Mar. 2000). ]{.date}[pp. 60-66. ]{.pagenums}]{.biblioset} +::: + +::: {.biblioentry} +[]{#Ramsey97} + +\[3\] [[[Norman]{.firstname} [Ramsey]{.surname} and [Mary +F.]{.firstname} [Fernández]{.surname}. ]{.authorgroup}"Specifying +Representations of Machine Instructions". ]{.biblioset}[*ACM Trans. +Programming Languages and Systems*. [(May 1997). ]{.date}[pp. 492-524. +]{.pagenums}]{.biblioset} +::: +::: +::: + +::: {.simplesect} +::: {.titlepage} +
+ +
+ +[]{#sleigh_overview}Overview {#overview .title style="clear: both"} +---------------------------- + +
+ +
+::: + +SLEIGH is a language for describing the instruction sets of general +purpose microprocessors, in order to facilitate the reverse engineering +of software written for them. SLEIGH was designed for the GHIDRA reverse +engineering platform and is used to describe microprocessors with enough +detail to facilitate two major components of GHIDRA, the disassembly and +decompilation engines. For disassembly, SLEIGH allows a concise +description of the translation from the bit encoding of machine +instructions to human-readable assembly language statements. Moreover, +it does this with enough detail to allow the disassembly engine to break +apart the statement into the mnemonic, operands, sub-operands, and +associated syntax. For decompilation, SLEIGH describes the translation +from machine instructions into [*p-code*]{.emphasis}. P-code is a +Register Transfer Language (RTL), distinct from SLEIGH, designed to +specify the [*semantics*]{.emphasis} of machine instructions. By +[*semantics*]{.emphasis}, we mean the detailed description of how an +instruction actually manipulates data, in registers and in RAM. This +provides the foundation for the data-flow analysis performed by the +decompiler. + +A SLEIGH specification typically describes a single microprocessor and +is contained in a single file. The term [*processor*]{.emphasis} will +always refer to this target of the specification. + +Italics are used when defining terms and for named entities. Bold is +used for SLEIGH keywords. +::: + +::: {.sect1} +::: {.titlepage} +
+ +
+ +[]{#sleigh_introduction}1. Introduction to P-Code {#introduction-to-p-code .title style="clear: both"} +------------------------------------------------- + +
+ +
+::: + +Although p-code is a distinct language from SLEIGH, because a major +purpose of SLEIGH is to specify the translation from machine code to +p-code, this document serves as a primer for p-code. The key concepts +and terminology are presented in this section, and more detail is given +in [Section 7.7, "The Semantic +Section"](sleigh_constructors.html#sleigh_semantic_section "7.7. The Semantic Section"){.xref}. +There is also a complete set of tables which list syntax and +descriptions for p-code operations in the Appendix. + +The design criteria for p-code was to have a language that looks much +like modern assembly instruction sets but capable of modeling any +general purpose processor. Code for different processors can be +translated in a straightforward manner into p-code, and then a single +suite of analysis software can be used to do data-flow analysis and +decompilation. In this way, the analysis software becomes +[*retargetable*]{.emphasis}, and it isn't necessary to redesign it for +each new processor being analyzed. It is only necessary to specify the +translation of the processor's instruction set into p-code. + +So the key properties of p-code are + +::: {.informalexample} +::: {.itemizedlist} +- The language is machine independent. +- The language is designed to model general purpose processors. +- Instructions operate on user defined registers and address spaces. +- All data is manipulated explicitly. Instructions have no indirect + effects. +- Individual p-code operations mirror typical processor tasks and + concepts. +::: +::: + +SLEIGH is the language which specifies the translation from a machine +instruction to p-code. It specifies both this translation and how to +display the instruction as an assembly statement. + +A model for a particular processor is built out of three concepts: the +[*address space*]{.emphasis}, the [*varnode*]{.emphasis}, and the +[*operation*]{.emphasis}. These are generalizations of the computing +concepts of RAM, registers, and machine instructions respectively. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_address_spaces}1.1. Address Spaces {#address-spaces .title} + +
+ +
+::: + +An [*address*]{.emphasis} space for p-code is a generalization of the +indexed memory (RAM) that a typical processor has access to, and it is +defined simply as an indexed sequence of memory [*words*]{.emphasis} +that can be read and written by p-code. In almost all cases, a +[*word*]{.emphasis} of the space is a [*byte*]{.emphasis} (8 bits), and +we will usually use the term [*byte*]{.emphasis} instead of +[*word*]{.emphasis}. However, see the discussion of the +[**wordsize**]{.bold} attribute of address spaces below. + +The defining characteristics of a space are its name and its size. The +size of a space indicates the number of distinct indices into the space +and is usually given as the number of bytes required to encode an +arbitrary index into the space. A space of size 4 requires a 32 bit +integer to specify all indices and contains 2^32^ bytes. The index of a +byte is usually referred to as the [*offset*]{.emphasis}, and the offset +together with the name of the space is called the [*address*]{.emphasis} +of the byte. + +Any manipulation of data that p-code operations perform happens in some +address space. This includes the modeling of data stored in RAM but also +includes the modeling of processor registers. Registers must be modeled +as contiguous sequences of bytes at a specific offset (see the +definition of varnodes below), typically in their own distinct address +space. In order to facilitate the modeling of many different processors, +a SLEIGH specification provides complete control over what address +spaces are defined and where registers are located within them. + +Typically, a processor can be modeled with only two spaces, a +[*ram*]{.emphasis} address space that represents the main memory +accessible to the processor via its data-bus, and a +[*register*]{.emphasis} address space that is used to implement the +processor's registers. However, the specification designer can define as +many address spaces as needed. + +There is one address space that is automatically defined for a SLEIGH +specification. This space is used to allocate temporary storage when the +SLEIGH compiler breaks down the expressions describing processor +semantics into individual p-code operations. It is called the +[*unique*]{.emphasis} space. There is also a special address space, +called the [*const*]{.emphasis} space, used as a placeholder for +constant operands of p-code instructions. For the most part, a SLEIGH +specification doesn't need to be aware of this space, but it can be used +in certain situations to force values to be interpreted as constants. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_varnodes}1.2. Varnodes {#varnodes .title} + +
+ +
+::: + +A [*varnode*]{.emphasis} is the unit of data manipulated by p-code. It +is simply a contiguous sequence of bytes in some address space. The two +defining characteristics of a varnode are + +::: {.informalexample} +::: {.itemizedlist} +- The address of the first byte. +- The number of bytes (size). +::: +::: + +With the possible exception of constants treated as varnodes, there is +never any distinction made between one varnode and another. They can +have any size, they can overlap, and any number of them can be defined. + +Varnodes by themselves are typeless. An individual p-code operation +forces an interpretation on each varnode that it uses, as either an +integer, a floating-point number, or a boolean value. In the case of an +integer, the varnode is interpreted as having a big endian or little +endian encoding, depending on the specification (see [Section 4.1, +"Endianness +Definition"](sleigh_definitions.html#sleigh_endianness_definition "4.1. Endianness Definition"){.xref}). +Certain instructions also distinguish between signed and unsigned +interpretations. For a signed integer, the varnode is considered to have +a standard twos complement encoding. For a boolean interpretation, the +varnode must be a single byte in size. In this special case, the zero +encoding of the byte is considered a [*false*]{.emphasis} value and an +encoding of 1 is a [*true*]{.emphasis} value. + +These interpretations only apply to the varnode for a particular +operation. A different operation can interpret the same varnode in a +different way. Any consistent meaning assigned to a particular varnode +must be provided and enforced by the specification designer. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_operations}1.3. Operations {#operations .title} + +
+ +
+::: + +P-code is intended to emulate a target processor by substituting a +sequence of p-code operations for each machine instruction. Thus every +p-code operation is naturally associated with the address of a specific +machine instruction, but there is usually more than one p-code operation +associated with a single machine instruction. Except in the case of +branching, p-code operations have fall-through control flow, both within +and across machine instructions. For a single machine instruction, the +associated p-code operations execute from first to last. And if there is +no branching, execution picks up with the first operation corresponding +to the next machine instruction. + +Every p-code operation can take one or more varnodes as input and can +optionally have one varnode as output. The operation can only make a +change to this [*output varnode*]{.emphasis}, which is always indicated +explicitly. Because of this rule, all manipulation of data is explicit. +The operations have no indirect effects. In general, there is absolutely +no restriction on what varnodes can be used as inputs and outputs to +p-code operations. The only exceptions to this are that constants cannot +be used as output varnodes and certain operations impose restrictions on +the [*size*]{.emphasis} of their varnode operands. + +The actual operations should be familiar to anyone who has studied +general purpose processor instruction sets. They break up into groups. + +::: {.informalexample} +::: {.table} +[]{#ops.htmltable} + +**Table 1. P-code Operations** + +::: {.table-contents} + --------------------------------------------------------------------------------------------------------------------------------------------------------- + [**Operation [**List of Operations**]{.bold} + Category**]{.bold} + ---------------------------- ---------------------------------------------------------------------------------------------------------------------------- + Data Moving `COPY, LOAD, STORE`{.code} + + Arithmetic `INT_ADD, INT_SUB, INT_CARRY, INT_SCARRY, INT_SBORROW, INT_2COMP, INT_MULT, INT_DIV, INT_SDIV, INT_REM, INT_SREM`{.code} + + Logical `INT_NEGATE, INT_XOR, INT_AND, INT_OR, INT_LEFT, INT_RIGHT, INT_SRIGHT, POPCOUNT, LZCOUNT`{.code} + + Integer Comparison `INT_EQUAL, INT_NOTEQUAL, INT_SLESS, INT_SLESSEQUAL, INT_LESS, INT_LESSEQUAL`{.code} + + Boolean `BOOL_NEGATE, BOOL_XOR, BOOL_AND, BOOL_OR`{.code} + + Floating Point `FLOAT_ADD, FLOAT_SUB, FLOAT_MULT, FLOAT_DIV, FLOAT_NEG, FLOAT_ABS, FLOAT_SQRT, FLOAT_NAN`{.code} + + Floating Point Compare `FLOAT_EQUAL, FLOAT_NOTEQUAL, FLOAT_LESS, FLOAT_LESSEQUAL`{.code} + + Floating Point Conversion `INT2FLOAT, FLOAT2FLOAT, TRUNC, CEIL, FLOOR, ROUND`{.code} + + Branching `BRANCH, CBRANCH, BRANCHIND, CALL, CALLIND, RETURN`{.code} + + Extension/Truncation `INT_ZEXT, INT_SEXT, PIECE, SUBPIECE`{.code} + + Managed Code `CPOOLREF, NEW`{.code} + --------------------------------------------------------------------------------------------------------------------------------------------------------- +::: +::: + +\ +::: + +We postpone a full discussion of the individual operations until +[Section 7.7, "The Semantic +Section"](sleigh_constructors.html#sleigh_semantic_section "7.7. The Semantic Section"){.xref}. +::: +::: +::: + +::: {.navfooter} + +------------------------------------------------------------------------ + + --- --- -------------------------------- +      [Next](sleigh_layout.html) +      2. Basic Specification Layout + --- --- -------------------------------- +::: diff --git a/sources/GhidraDocs/languages/html/sleigh_constructors.html b/sources/GhidraDocs/languages/html/sleigh_constructors.html new file mode 100644 index 0000000..3b4dde0 --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_constructors.html @@ -0,0 +1,2305 @@ + + + +7. Constructors + + + + + + + + + +
+ + + + + + + +
7. Constructors
+Prev   Next +
+
+
+
+

+7. Constructors

+

+Fields are the basic building block for family symbols. The mechanisms +for building up from fields to the +root instruction symbol are +the constructor and table. +

+

+A constructor is the unit of syntax for building +new symbols. In essence a constructor describes how to build a new +family symbol, by describing, in turn, how to build a new display +meaning, how to build a new semantic meaning, and how encodings map to +these new meanings. A table is a set of one or +more constructors and is the final step in creating a new family +symbol identifier associated with the pieces defined by +constructors. The name of the table is this new identifier, and it is +this identifier which can be used in the syntax for subsequent +constructors. +

+

+The difference between a constructor and table is slightly confusing +at first. In short, the syntactical elements described in this +chapter, for combining existing symbols into new symbols, are all used +to describe a single constructor. Specifications for multiple +constructors are combined to describe a single table. Since many +tables are built with only one constructor, it is natural and correct +to think of a constructor as a kind of table in and of itself. But it +is only the table that has an actual family symbol identifier +associated with it. Most of this chapter is devoted to describing how +to define a single constructor. The issues involved in combining +multiple constructors into a single table are addressed in Section 7.8, “Tables”. +

+
+

+7.1. The Five Sections of a Constructor

+

+A single complex statement in the specification file describes a +constructor. This statement is always made up of five distinct +sections that are listed below in the order in which the must occur. +

+
    +
  1. + Table Header +
    2. +
  2. + Display Section +
    3. +
  3. + Bit Pattern Sections +
    4. +
  4. + Disassembly Actions Section +
    5. +
  5. + Semantics Actions Section +
    6. +
+

+The full set of rules for correctly writing each section is long and +involved, but for any given constructor in a real specification file, +the syntax typically fits on a single line. We describe each section +in turn. +

+
+
+

+7.2. The Table Header

+

+Every constructor must be part of a table, which is the element with +an actual family symbol identifier associated with it. So each +constructor starts with the identifier of the table it belongs to +followed by a colon ‘:’. +

+
+mode1:           ...
+
+

+

+

+The above line starts the definition of a constructor that is part of +the table identified as mode1. If the identifier +has not appeared before, a new table is created. If other constructors +have used the identifier, the new constructor becomes an additional +part of that same table. A constructor in the +root instruction table is defined by omitting the +identifier. +

+
+:                ...
+
+

+

+

+The identifier instruction is actually reserved +for the root table, but should not be used in the table header as the +SLEIGH parser uses the blank identifier to help distinguish assembly +mnemonics from operands (see Section 7.3.1, “Mnemonic”). +

+
+
+

+7.3. The Display Section

+

+The display section consists of all characters +after the table header ‘:’ up to the SLEIGH +keyword is. The section’s primary +purpose is to assign disassembly display meaning to the +constructor. The section’s secondary purpose is to define local +identifiers for the pieces out of which the constructor is being +built. Characters in the display section are treated as literals with +the following exceptions. +

+
    +
  • + Legal identifiers are not treated literally unless +
      +
    1. + The identifier is surrounded by double quotes. +
      2. +
    2. + The identifier is considered a mnemonic (see below). +
      3. +
    +
    • +
  • + The character ‘^’ has special meaning. +
    • +
  • + White space is trimmed from the beginning and end of the section. +
    • +
  • + Other sequences of white space characters are condensed into a single space. +
    • +
+

+

+

+In particular, all punctuation except ‘^’ loses its special +meaning. Those identifiers that are not treated as literals are +considered to be new, initially undefined, family symbols. We refer to +these new symbols as the operands of the constructor. And for root +constructors, these operands frequently correspond to the natural +assembly operands. Thinking of it as a family symbol, the +constructor’s display meaning becomes the string of literals itself, +with each identifier replaced with the display meaning of the symbol +corresponding to that identifier. +

+
+mode1: ( op1 ),op2 is          ...
+
+

+

+

+In the above example, a constructor for +table mode1 is being built out of two pieces, +symbol op1 and +symbol op2. The characters ‘(‘, ’)’, and ‘,’ +become literal parts of the disassembly display for symbol +mode1. After the display strings for op1 +and op2 are found, they are inserted into the +string of literals, forming the constructor’s display string. The +white space characters surrounding the op1 +identifier are preserved as part of this string. +

+

+The identifiers op1 and op2 +are local to the constructor and can mask global symbols with the same +names. The symbols will (must) be defined in the following sections, +but only their identifiers are established in the display section. +

+
+

+7.3.1. Mnemonic

+

+If the constructor is part of the root instruction table, the first +string of characters in the display section that does not contain +white space is treated as the literal mnemonic of +the instruction and is not considered a local symbol identifier even +if it is legal. +

+
+:and (var1) is                 ...
+
+

+

+

+In the above example, the string “var1” is treated as a symbol +identifier, but the string “and” is considered to be the mnemonic of +the instruction. +

+

+There is nothing that special about the mnemonic. As far as the +display meaning of the constructor is concerned, it is just a sequence +of literal characters. Although the current parser does not concern +itself with this, the mnemonic of any assembly language instruction in +general is used to guarantee the uniqueness of the assembly +representation. It is conceivable that a forward engineering engine +built on SLEIGH would place additional requirements on the mnemonic to +assure uniqueness, but for reverse engineering applications there is +no such requirement. +

+
+
+

+7.3.2. The '^' character

+

+The ‘^’ character in the display section is used to separate +identifiers from other characters where there shouldn’t be white space +in the disassembly display. This can be used in any manner but is +usually used to attach display characters from a local symbol to the +literal characters of the mnemonic. +

+
+:bra^cc op1,op2 is             ...
+
+

+

+

+In the above example, “bra” is treated as literal characters in the +resulting display string followed immediately, with no intervening +spaces, by the display string of the local +symbol cc. Thus the whole constructor actually +has three operands, denoted by the three +identifiers cc, op1, +and op2. +

+

+If the ‘^’ is used as the first (non-whitespace) character in the +display section of a base constructor, this inhibits the first +identifier in the display from being considered the mnemonic, as +described in Section 7.3.1, “Mnemonic”. This allows +specification of less common situations, where the first part of the +mnemonic, rather than perhaps a later part, needs to be considered as +an operand. An initial ‘^’ character can also facilitate certain +recursive constructions. +

+
+
+
+

+7.4. The Bit Pattern Section

+

+Syntactically, this section comes between the +keyword is and the delimiter for the +following section, either an ‘{‘ or an ‘[‘. The bit pattern +section describes a +constructor’s pattern, the subset of possible +instruction encodings that the designer wants +to match the constructor being defined. +

+
+

+7.4.1. Constraints

+

+The patterns required for processor specifications can almost always +be described as a mask and value pair. Given a specific instruction +encoding, we can decide if the encoding matches our pattern by looking +at just the bits specified by the mask and seeing +if they match a specific value. The fields, as +defined in Section 6.1, “Defining Tokens and Fields”, typically give us +our masks. So to construct a pattern, we can simply require that the +field take on a specific value, as in the example below. +

+
+:halt is opcode=0x15 {         ...
+
+

+Assuming the symbol opcode was defined as a field, this says that a +root constructor with mnemonic “halt” matches any instruction where +the bits defining this field have the value 0x15. The equation +“opcode=0x15” is called a constraint. +

+

+The standard bit encoding of the integer is used when restricting the +value of a field. This encoding is used even if +an attach statement has assigned a +different meaning to the field. The alternate meaning does not apply +within the pattern. This can be slightly confusing, particularly in +the case of an attach values +statement, which provides an alternate integer interpretation of the +field. +

+
+
+

+7.4.2. The '&' and '|' Operators

+

+More complicated patterns are built out of logical operators. The +meaning of these are fairly straightforward. We can force two or more +constraints to be true at the same time, a logical +and ‘&’, or we can require that either one constraint or +another must be true, a logical or ‘|’. By using these with +constraints and parentheses for grouping, arbitrarily complicated +patterns can be constructed. +

+
+:nop is (opcode=0 & mode=0) | (opcode=15) { ...
+
+

+

+

+Of the two operators, the logical and is much +more common. The SLEIGH compiler typically can group together several +constraints that are combined with this operator into a single +efficient mask/value check, so this operator is to be preferred if at +all possible. The logical or operator usually +requires two or more mask/value style checks to correctly implement. +

+
+
+

+7.4.3. Defining Operands and Invoking Subtables

+

+The principle way of defining a constructor operand, left undefined +from the display section, is done in the bit pattern section. If an +operand’s identifier is used by itself, not as part of a constraint, +then the operand takes on both the display and semantic definition of +the global symbol with the same identifier. The syntax is slightly +confusing at first. The identifier must appear in the pattern as if it +were a term in a sequence of constraints but without the operator and +right-hand side of the constraint. +

+
+define token instr(32)
+    opcode = (0,5)
+    r1 = (6,10)
+    r2 = (11,15);
+attach variables [ r1 r2 ] [ reg0 reg1 reg2 reg3 ];
+
+:add r1,r2 is opcode=7 & r1 & r2 { ...
+
+

+

+

+This is a typical example. The add instruction +must have the bits in the opcode field set +specifically. But it also uses two fields in the instruction which +specify registers. The r1 +and r2 identifiers are defined to be local +because they appear in the display section, but their use in the +pattern section of the definition links the local symbols with the +global register symbols defined as fields with attached registers. The +constructor is essentially saying that it is building the +full add instruction encoding out of the register +fields r1 and r2 but is not +specifying their value. +

+

+The syntax makes a little more sense keeping in mind this principle: +

+
  • + The pattern must somehow specify all the bits and symbols + being used by the constructor, even if the bits are not restricted + to specific values. +
+

+The linkage from local symbol to global symbol will happen for any +global identifier which represents a family symbol, including table +symbols. This is in fact the principle mechanism for recursively +building new symbols from old symbols. For those familiar with grammar +parsers, a SLEIGH specification is in part a grammar +specification. The terminal symbols, or tokens, are the bits of an +instruction, and the constructors and tables are the non-terminating +symbols. These all build up to the root instruction table, the +grammar’s start symbol. So this link from local to global is simply a +statement of the grouping of old symbols into the new constructor. +

+
+
+

+7.4.4. Variable Length Instructions

+

+There are some additional complexities to designing a specification +for a processor with variable length instructions. Some initial +portion of an instruction must always be parsed. But depending on the +fields in this first portion, additional portions of varying lengths +may need to be read. The key to incorporating this behavior into a +SLEIGH specification is the token. Recall that all fields are built on +top of a token which is defined to be a specific number of bytes. If a +processor has fixed length instructions, the specification needs to +define only a single token representing the entire instruction, and +all fields are built on top of this one token. For processors with +variable length instructions however, more than one token needs to be +defined. Each token has different fields defined upon it, and the +SLEIGH compiler can distinguish which tokens are involved in a +particular constructor by examining the fields it uses. The tokens +that are actually used by any matching constructors determine the +final length of the instruction. SLEIGH has two operators that are +specific to variable length instruction sets and that give the +designer control over how tokens fit together. +

+
+
+7.4.4.1. The ';' Operator
+

+The most important operator for patterns defining variable length +instructions is the concatenation operator ‘;’. When building a +constructor with fields from two or more tokens, the pattern must +explicitly define the order of the tokens. In terms of the logic of +the pattern expressions themselves, the ‘;’ operator has the same +meaning as the ‘&’ operator. The combined expression matches only if +both subexpressions are true. However, it also requires that the +subexpressions involve multiple tokens and explicitly indicates an +order for them. +

+
+define token base(8)
+    op=(0,3)
+    mode=(4,4)
+    reg=(5,7);
+define token immtoken(16)
+    imm16 = (0,15);
+
+:inc reg       is op=2 & reg        { ...
+:add reg,imm16 is op=3 & reg; imm16 { ...
+
+

+

+

+In the above example, we see the definitions of two different +tokens, base +and immtoken. For the first +instruction, inc, the constructor uses +fields op and reg, both +defined on base. Thus, the pattern applies +constraints to just a single byte, the size of base, in the +corresponding encoding. The second +instruction, add, uses +fields op and reg, but it +also uses field imm16 contained +in immtoken. The ‘;’ operator indicates that +token base (via its fields) comes first in the +encoding, followed by immtoken. The constraints +on base will therefore correspond to constraints +on the first byte of the encoding, and the constraints +on immtoken will apply to the second and third +bytes. The length of the final encoding for add +will be 3 bytes, the sum of the lengths of the two tokens. +

+

+If two pattern expressions are combined with the ‘&’ or ‘|’ operator, +where the concatenation operator ‘;’ is also being used, the designer +must make sure that the tokens underlying each expression are the same +and come in the same order. In the example add +instruction for instance, the ‘&’ operator combines the “op=3” and +“reg” expressions. Both of these expressions involve only the +token base, so the matching requirement is +satisfied. The ‘&’ and ‘|’ operators can combine expressions built out +of more than one token, but the tokens must come in the same +order. Also these operators have higher precedence than the ‘;’ +operator, so parentheses may be necessary to get the intended meaning. +

+
+
+
+7.4.4.2. The '...' Operator
+

+The ellipsis operator ‘...’ is used to satisfy the token matching +requirements of the ‘&’ and ‘|’ operators (described in the previous +section), when the operands are of different lengths. The ellipsis is +a unary operator applied to a pattern expression that extends its +token length before it is combined with another expression. Depending +on what side of the expression the ellipsis is applied, the +expression's tokens are either right or left justified within the +extension. +

+
+addrmode: reg is reg & mode=0    {     ...
+addrmode: #imm16 is mode=1; imm16    {  ...
+
+:xor “A”,addrmode is op=4 ... & addrmode {	...
+
+

+

+

+Extending the example from the previous section, we add a +subtable addrmode, representing an operand that +can be encoded either as a register, if mode is +set to zero, or as an immediate value, if +the mode bit is one. If the immediate value mode +is selected, the operand is built by reading an additional two bytes +directly from the instruction encoding. So +the addrmode table can represent a 1 byte or a 3 +byte encoding depending on the mode. In the +following xor +instruction, addrmode is used as an operand. The +particular instruction is selected by encoding a 4 in +the op field, so it requires a constraint on that +field in the pattern expression. Since the instruction uses +the addrmode operand, it must combine the +constraint on op with the pattern +for addrmode. But op +involves only the token base, +while addrmode may also +involve immtoken. The ellipsis operator resolves +the conflict by extending the op constraint to be +whatever the length of addrmode turns out to be. +

+

+Since the op constraint occurs to the left of the +ellipsis, it is considered left justified, and the matching +requirement for ‘&’ will insist that base is the +first token in all forms of addrmode. This allows +the xor instruction's constraint +on op and the addrmode +constraint on mode to be combined into +constraints on a single byte in the final encoding. +

+
+
+
+

+7.4.5. Invisible Operands

+

+It is not necessary for a global symbol, which is needed by a +constructor, to appear in the display section of the definition. If +the global identifier is used in the pattern section as it would be +for a normal operand definition but the identifier was not used in the +display section, then the constructor defines an invisible +operand. Such an operand behaves and is parsed exactly like +any other operand but there is absolutely no visible indication of the +operand in the final display of the assembly instruction. The one +common type of instruction that uses this is the relative branch (see +Section 7.5.1, “Relative Branches”) but it is otherwise needed +only in more esoteric instructions. It is useful in situations where +you need to break up the parsing of an instruction along lines that +don’t quite match the assembly. +

+
+
+

+7.4.6. Empty Patterns

+

+Occasionally there is a need for an empty pattern when building +tables. An empty pattern matches everything. There is a predefined +symbol epsilon which has been traditionally used +to indicate an empty pattern. +

+
+
+

+7.4.7. Advanced Constraints

+

+A constraint does not have to be of the form “field = constant”, +although this is almost always what is needed. In certain situations, +it may be more convenient to use a different kind of +constraint. Special care should be taken when designing these +constraints because they can substantially deviate from the mask/value +model used to implement most constraints. These more general +constraints are implemented by splitting it up into smaller states +which can be modeled as a mask/value pair. This is all done +automatically, and the designer may inadvertently create huge numbers +of parsing states for a single constraint. +

+

+A constraint can actually be built out of arbitrary +expressions. These pattern expressions are more +commonly used in disassembly actions and are defined in +Section 7.5.2, “General Actions and Pattern Expressions”, but they can also be used in +constraints. So in general, a constraint is any equation where the +left-hand side is a single family symbol, the right-hand side is an +arbitrary pattern expression, and the constraint operator is one of +the following: +

+
+
+

Table 3. Constraint Operators

+
+++ + + + + + + + + + + + + + + + + + + + + + +
Operator NameSyntax
Integer equality=
Integer inequality!=
Integer less-than<
Integer greater-than>
+
+
+
+

+For a particular instruction encoding, each variable evaluates to a +specific integer depending on the encoding. A constraint is satisfied +if, when all the variables are evaluated, the equation is true. +

+
+:xor r1,r2 is opcode=0xcd & r1 & r2 { r1 = r1 ^ r2; }
+:clr r1    is opcode=0xcd & r1 & r1=r2 { r1 = 0; }
+
+

+

+

+The above example illustrates a situation that does come up +occasionally. A processor uses an exclusive-or instruction to clear a +register by setting both operands of the instruction to the same +register. The first line in the example illustrates such an +instruction. However, processor documentation stipulates, and analysts +prefer, that, in this case, the disassembler should print a +pseudo-instruction clr. The distinguishing +feature of clr from xor is +that the two fields, specifying the two register inputs +to xor, are equal. The easiest way to specify +this special case is with the general constraint, +“r1 = r2”, as in the second +line of the example. The SLEIGH compiler will implement this by +enumerating all the cases where r1 +equals r2, creating as many states as there are +registers. But the specification itself, at least, remains compact. +

+
+
+
+

+7.5. Disassembly Actions Section

+

+After the bit pattern section, there can optionally be a section for +doing dynamic calculations, which must be between square brackets. For +certain kinds of instructions, there is a need to calculate values +that depend on the specific bits of the instruction, but which cannot +be obtained as an integer interpretation of a field or by building +with an attach values statement. So +SLEIGH provides a mechanism to build values of arbitrary +complexity. This section is not intended to emulate the execution of +the processor (this is the job of the semantic section) but is +intended to produce only those values that are needed at disassembly +time, usually for part of the disassembly display. +

+
+

+7.5.1. Relative Branches

+

+The canonical example of an action at disassembly time is a branch +relocation. A jump instruction encodes the address of where it jumps +to as a relative offset to the instruction’s address, for +instance. But when we display the assembly, we want to show the +absolute address of the jump destination. The correct way to specify +this is to reserve an identifier in the display section which +represents the absolute address, but then, instead of defining it in +the pattern section, we define it in the disassembly action section as +a function of the current address and the relative offset. +

+
+jmpdest: reloc is simm8 [ reloc=inst_next + simm8*4; ] { ...
+
+

+

+

+The identifier reloc is reserved in the display +section for this constructor, but the identifier is not defined in the +pattern section. Instead, an invisible +operand simm8 is defined which is attached to a +global field definition. The reloc identifier is +defined in the action section as the integer obtained by adding a +multiple of simm8 +to inst_next, a symbol predefined to be equal to +the address of the following instruction (see +Section 5.2, “Predefined Symbols”). Now reloc +is a specific symbol with both semantic and display meaning equal to +the desired absolute address. This address is calculated separately, +at disassembly time, for every instruction that this constructor +matches. +

+
+
+

+7.5.2. General Actions and Pattern Expressions

+

+In general, the disassembly actions are encoded as a sequence of +assignments separated by semicolons. The left-hand side of each +statement must be a single operand identifier, and the right-hand side +must be a pattern expression. A pattern +expression is made up of both integer constants and family +symbols that have retained their semantic meaning as integers, and it +is built up out of the following typical operators: +

+
+
+

Table 4. Pattern Expression Operators

+
+++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Operator NameSyntax
Integer addition+
Integer subtraction-
Integer multiplication*
Integer division/
Left-shift<<
Arithmetic right-shift>>
Bitwise and +
+ + + + + + + +
$and
& (within square brackets)
+
+
Bitwise or +
+ + + + + + + +
$or
| (within square brackets)
+
+
Bitwise xor +
+ + + + + + + +
$xor
^
+
+
Bitwise negation~
+
+
+
+

+For the sake of these expressions, integers are considered signed +values of arbitrary precision. Expressions can also make use of +parentheses. A family symbol can be used in an expression, only if it +can be resolved to a particular specific symbol. This generally means +that a global family symbol, such as a field, must be attached to a +local identifier before it can be used. +

+

+The left-hand side of an assignment statement can be a context +variable (see Section 6.4, “Context Variables”). An +assignment to such a variable changes the context in which the current +instruction is being disassembled and can potentially have a drastic +effect on how the rest of the instruction is disassembled. An +assignment of this form is considered local to the instruction and +will not affect how other instructions are parsed. The context +variable is reset to its original value before parsing other +instructions. The disassembly action may also contain one or +more globalset directives, which +cause changes to context variables to become more permanent. This +directive is distinct from the operators in a pattern expression and +must be invoked as a separate statement. See +Section 8, “Using Context”, for a discussion of how to +effectively use context variables and +Section 8.3, “Global Context Change”, for details of +the globalset directive. +

+

+Note that there are two syntax forms for the logical operators in a +pattern expression. When an expression is used as part of a +constraint, the “$and” and “$or” forms of the operators must be used +in order to distinguish the bitwise operators from the special pattern +combining operators, ‘&’ and ‘|’ (as described in +Section 7.4.2, “The '&' and '|' Operators”). However inside the square braces +of the disassembly action section, ‘&’ and ‘|’ are interpreted as +the usual logical operators. +

+
+
+
+

+7.6. The With Block

+

+To avoid tedious repetition and to ease the maintenance of specifications +already having many, many constructors and tables, the with +block is provided. It is a syntactic construct that allows a +designer to apply a table header, bit pattern constraints, and/or disassembly +actions to a group of constructors. The block starts at the +with directive and ends with a closing brace. +All constructors within the block are affected: +

+
+with op1 : mode=1 [ mode=2; ] {
+  :reg   is reg & ind=0 [ mode=1; ] { ... }
+  :[reg] is reg & ind=1             { ... }
+}
+
+

+In the example, both constructors are added to the table identified by +op1. Both require the context field +mode to be equal to 1. The listed constraints take the +form described in Section 7.4, “The Bit Pattern Section”, and they are joined to +those given in the constructor statement as if prepended using ‘&’. Similarly, +the actions take the form described in Section 7.5, “Disassembly Actions Section” +and are prepended to the actions given in the constructor statement. Prepending +the actions allows the statement to override actions in the with block. Both +technically occur, but only the last one has a noticeable effect. The above +example could have been equivalently specified: +

+
+op1:reg   is mode=1 & reg & ind=0 [ mode=2; mode=1; ] { ... }
+op1:[ref] is mode=1 & reg & ind=1 [ mode=2; ]         { ... }
+
+

+

+

+The three parts (table header, bit pattern section, and disassembly actions +section) of the with block are all optional. Any of them may be omitted, +though omitting all of them is rather pointless. With blocks may also be nested. +The innermost with block having a table header specifies the default header of +the constructors it contains. The constraints and actions are combined outermost +to innermost, left to right. + +Note that when a with block has a table header specifying a table that does not +yet exist, the table is created immediately. Inside a with block that has a +table header, a nested with block may specify the instruction +table by name, as in "with instruction : {...}". +Inside such a block, the rule regarding mnemonic literals is restored (see +Section 7.3.1, “Mnemonic”). +

+
+
+

+7.7. The Semantic Section

+

+The final section of a constructor definition is the semantic +section. This is a description of how the processor would manipulate +data if it actually executed an instruction that matched the +constructor. From the perspective of a single constructor, the basic +idea is that all the operands for the constructor have been defined in +the bit pattern or disassembly action sections as either specific or +family symbols. In context, all the family symbols map to specific +symbols, and the semantic section uses these and possibly other global +specific symbols in statements that describe the action of the +constructor. All specific symbols have a varnode associated with them, +so within the semantic section, symbols are manipulated as if they +were varnodes. +

+

+The semantic section for one constructor is surrounded by curly braces +‘{‘ and ‘}’ and consists of zero or more statements separated by +semicolons ‘;’. Most statements are built up out of C-like syntax, +where the variables are the symbols visible to the constructor. There +is a direct correspondence between each type of operator used in the +statements and a p-code operation. The SLEIGH compiler generates +p-code operations and varnodes corresponding to the SLEIGH operators +and symbols by collapsing the syntax trees represented by the +statements and creating temporary storage within +the unique space when it needs to. +

+
+:add r1,r2 is opcode=0x26 & r1 & r2 { r1 = r1 + r2; }
+
+

+

+

+The above example generates exactly one integer addition +operation, INT_ADD, where the input varnodes +are r1 and r2 and the output +varnode is r1. +

+
+

+7.7.1. Expressions

+

+Expressions are built out of symbols and the binary and unary +operators listed in Table 5, “Semantic Expression Operators and Syntax” in the +Appendix. All expressions evaluate to an integer, floating point, or +boolean value, depending on the final operation of the expression. The +value is then used depending on the kind of statement. Most of the +operators require that their input and output varnodes all be the same +size (see Section 7.7.3, “Varnode Sizes”). The operators all +have a precedence, which is used by the SLEIGH compiler to determine +the ordering of the final p-code operations. Parentheses can be used +within expressions to affect this order. +

+
+
+7.7.1.1. Arithmetic, Logical and Boolean Operators
+

+For the most part these operators should be familiar to software +developers. The only real differences arise from the fact that +varnodes are typeless. So for instance, there has to be separate +operators to distinguish between dividing unsigned numbers ‘/’, +dividing signed numbers ‘s/’, and dividing floating point numbers +‘f/’. +

+

+Carry, borrow, and overflow calculations are implemented with separate +operations, rather than having indirect effects with the arithmetic +operations. Thus +the INT_CARRY, INT_SCARRY, +and INT_SBORROW operations may be unfamiliar to +some people in this form (see the descriptions in the Appendix). +

+
+
+
+7.7.1.2. The '*' Operator
+

+The dereference operator, which generates LOAD +operations (and STORE operations), has slightly +unfamiliar syntax. The ‘*’ operator, as is usual in many programming +languages, indicates that the affected variable is a pointer and that +the expression is dereferencing the data being +pointed to. Unlike most languages, in SLEIGH, it is not immediately +clear what address space the variable is pointing into because there +may be multiple address spaces defined. In the absence of any other +information, SLEIGH assumes that the variable points into +the default space, as labeled in the definition +of one of the address spaces with +the default attribute. If that is not +the space desired, the default can be overridden by putting the +identifier for the space in square brackets immediately after the ‘*’. +

+

+It is also frequently not clear what the size of the dereferenced data +is because the pointer variable is typeless. The SLEIGH compiler can +frequently deduce what the size must be by looking at the operation in +the context of the entire statement (see +Section 7.7.3, “Varnode Sizes”). But in some situations, this +may not be possible, so there is a way to specify the size +explicitly. The operator can be followed by a colon ‘:’ and an integer +indicating the number of bytes being dereferenced. This can be used +with or without the address space override. We give an example of each +kind of override in the example below. +

+
+:load  r1,[r2] is opcode=0x99 & r1 & r2 { r1 = * r2; }
+:load2 r1,[r2] is opcode=0x9a & r1 & r2 { r1 = *[other] r2; }
+:load3 r1,[r2] is opcode=0x9b & r1 & r2 { r1 = *:2 r2; }
+:load4 r1,[r2] is opcode=0x9c & r1 & r2 { r1 = *[other]:2 r2; }
+
+

+Keep in mind that the address represented by the pointer is not a byte +address if the wordsize attribute is +set to something other than one. +

+
+
+
+7.7.1.3. Extension
+

+Most processors have instructions that extend small values into big +values, and many instructions do these minor data manipulations +implicitly. In keeping with the p-code philosophy, these operations +must be specified explicitly with the INT_ZEXT +and INT_SEXT operators in the semantic +section. The INT_ZEXT, does a +so-called zero extension. The low-order bits are +copied from the input, and any remaining high-order bits in the result +are set to zero. The INT_SEXT, does +a signed extension. The low-order bits are copied +from the input, but any remaining high-order bits in the result are +set to the value of the high-order bit of the +input. The INT_ZEXT operation is invoked with +the zext operator, and +the INT_SEXT operation is invoked with +the sext operator. +

+
+
+
+7.7.1.4. Truncation
+

+There are two forms of syntax indicating a truncation of the input +varnode. In one the varnode is followed by a colon ‘:’ and an integer +indicating the number of bytes to copy into the output, starting with +the least significant byte. In the second form, the varnode is +followed by an integer, surrounded by parentheses, indicating the +number of least significant bytes to truncate from the input. This +second form doesn’t directly specify the size of the output, which +must be inferred from context. +

+
+:split r1,lo,hi is opcode=0x81 & r1 & lo & hi {
+    lo = r1:4;
+    hi = r1(4);
+}
+
+

+This is an example using both forms of truncation to split a large +value r1 into two smaller +pieces, lo +and hi. Assuming r1 is an 8 +byte value, lo receives the least significant +half and hi receives the most significant half. +

+
+
+
+7.7.1.5. Bit Range Operator
+

+A specific subrange of bits within a varnode can be explicitly +referenced. Depending on the range, this may amount to just a +variation on the truncation syntax described earlier. But for this +operator, the size and boundaries of the range do not have to be +restricted to byte alignment. +

+
+:bit3 r1,r2 is op=0x7e & r1 & r2 { r1 = zext(r2[3,1]); }
+
+

+

+

+A varnode, r2 in this example, is immediately +followed by square brackets ‘[’ and ‘]’ indicating a bit range, and +within the brackets, there are two parameters separated by a +comma. The first parameter is an integer indicating the least +significant bit of the resulting bit range. The bits of the varnode +are labeled in order of significance, with the least significant bit +of the varnode being 0. The second parameter is an integer indicating +the number of bits in the range. In the example, a single bit is +extracted from r2, and its value is extended to +fill r1. Thus r1 takes +either the value 0 or 1, depending on bit 3 +of r2. +

+

+There are some caveats associated with using this operator. Bit range +extraction is really a pseudo operator, as real p-code can only work +with memory down to byte resolution. The bit range operator will +generate some combination +of INT_RIGHT, INT_AND, +and SUBPIECE to simulate the extraction of +smaller or unaligned pieces. The “r2[3,1]” from the example generates +the following p-code, for instance. +

+
+u1 = INT_RIGHT r2,#3
+u2 = SUBPIECE u1,0
+u3 = INT_AND u2,#0x1
+
+

+

+

+The result of any bit range operator still has a size in bytes. This +size is always the minimum number of bytes needed to contain the +resulting bit range, and if there are any extra bits in the result +these are automatically set to zero. +

+

+This operator can also be used on the left-hand side of assignments +with similar behavior and caveats (see Section 7.7.2.8, “Bit Range Assignments”). +

+
+
+
+7.7.1.6. Address-of Operator
+

+There is an address-of operator for generating +the address offset of a selected varnode as an integer value for use +in expressions. Use of this operator is a little subtle because it +does not generate a p-code operation that +calculates the desired value. The address is only calculated at +disassembly time and not during execution. The operator can only be +used if the symbol referenced has a static address. +

+
+

Warning

+

The current SLEIGH compiler cannot distinguish when +the symbol has an address that can always be resolved during +disassembly. So improper use may not be flagged as an error, and the +specification may produce unexpected results. +

+
+

+There ‘&’ operator in front of a symbol invokes this function. The +ampersand can also be followed by a colon ‘:’ and an integer +explicitly indicating the size of the resulting constant as a varnode. +

+
+:copyr r1 is op=0x3b & r1 { tmp:4 = &r1 + 4; r1 = *[register]tmp;}
+
+

+

+

+The above is a contrived example of using the address-of operator to +copy from a register that is not explicitly indicated by the +instruction. This example constructs the address of the register +following r1 within +the register space, and then +loads r1 with data from that address. The net +effect of all this is that the register +following r1 is copied +into r1, even though it is not mentioned directly +in the instruction. Notice that the address-of operator only produces +the offset portion of the address, and to copy the desired value, the +‘*’ operator must have a register space override. +

+
+
+
+7.7.1.7. Managed Code Operations
+

+SLEIGH provides basic support for instructions where encoding and context +don't provide a complete description of the semantics. This is the case +typically for managed code instruction sets where generation +of the semantic details of an instruction may be deferred until run-time. Support for +these operators is architecture dependent, otherwise they just act as black-box +functions. +

+

+The constant pool operator, cpool, +returns sizes, offsets, addresses, and other structural constants. It behaves like a +query to the architecture about these constants. The first +parameter is generally an object reference, and additional parameters +are constants describing the particular query. The operator returns the requested value. +In the following example, an object reference +regParamC and the encoded constant METHOD_INDEX +are sent as part of a query to obtain the final destination address of an object method. +

+
+:invoke_direct METHOD_INDEX,regParamC
+               is inst0=0x70 ; N_PARAMS=1 & METHOD_INDEX & regParamC
+{
+	iv0 = regParamC;
+	destination:4 = cpool( regParamC, METHOD_INDEX, $(CPOOL_METHOD));
+	call [ destination ];
+}
+
+

+

+

+If object memory allocation is an atomic feature of the instruction set, the specification +designer can use the newobject functional operator to +implement it in SLEIGH. It takes one +or two parameters. The first parameter is a class reference or other value +describing the object to be allocated, and the second parameter is an optional count of the number +of objects to allocate. It returns a pointer to the allocated object. +

+
+
+
+7.7.1.8. User-Defined Operations
+

+Any identifier that has been defined as a new p-code operation, using +the define pcodeop statement, can be +invoked as an operator using functional syntax. The SLEIGH compiler +assumes that the operator can take an arbitrary number of inputs, and +if used in an expression, the compiler assumes the operation returns +an output. Using this syntax of course generates the particular p-code +operation reserved for the identifier. +

+
+define pcodeop arctan;
+  ...
+:atan r1,r2 is opcode=0xa3 & r1 & r2 { r1 = arctan(r2); }
+
+

+

+
+
+
+

+7.7.2. Statements

+

+We describe the types of semantic statements that are allowed in SLEIGH. +

+
+
+7.7.2.1. Assignment Statements and Temporary Variables
+

+Of course SLEIGH allows assignment statements with the ‘=’ operator, +where the right-hand side is an arbitrary expression and the left-hand +side is the varnode being assigned. The assigned varnode can be any +specific symbol in the scope of the constructor, either a global +symbol or a local operand. +

+

+In SLEIGH, the keyword local +is used to allocate temporary variables. If an assignment +statement is prepended with local, +and the identifier on the left-hand side of an assignment does not match +any symbol in the scope of the constructor, a named temporary varnode is +created in the unique address space to hold the +result of the expression. The new symbol becomes part of the local +scope of the constructor, and can be referred to in the following +semantic statements. The size of the new varnode is calculated by +examining the statement in context (see +Section 7.7.3, “Varnode Sizes”). It is also possible to +explicitly indicate the size by using the colon ‘:’ operator followed +by an integer size in bytes. The following examples demonstrate the +temporary variable tmp being defined using both +forms. +

+
+:swap r1,r2 is opcode=0x41 & r1 & r2 {
+    local tmp = r1;
+    r1 = r2;
+    r2 = tmp;
+}
+:store r1,imm is opcode=0x42 & r1 & imm {
+    local tmp:4 = imm+0x20;
+    *r1 = tmp;
+}
+
+

+

+

+The local keyword can also be used +to declare a named temporary varnode, without an assignment statement. +This is useful for temporaries that are immediately passed into a macro. +

+
+:pushflags r1 is opcode=0x43 & r1 {
+    local tmp:4;
+    packflags(tmp);
+    * r1 = tmp;
+    r1 = r1 - 4;
+}
+
+

+

+
+

Warning

+

Currently, the SLEIGH compiler does not need the +local keyword to create a temporary +variable. For any assignment statement, if the left-hand side has a new +identifier, a new temporary symbol will be created using this identifier. +Unfortunately, this can cause SLEIGH to blindly accept assignment statements +where the left-hand side identifier is a misspelling of an existing symbol. +Use of the local keyword is preferred +and may be enforced in future compiler versions. +

+
+
+
+
+7.7.2.2. Storage Statements
+

+SLEIGH supports fairly standard storage statement +syntax to complement the load operator. The left-hand side of an +assignment statement uses the ‘*’ operator to indicate a dynamic +storage location, followed by an arbitrary expression to calculate the +location. This syntax of course generates the +p-code STORE operator as the final step of the +statement. +

+
+:sta [r1],r2 is opcode=0x20 & r1 & r2 { *r1 = r2; }
+:stx [r1],r2 is opcode=0x21 & r1 & r2 { *[other] r1 = r2; }
+:sti [r1],imm is opcode=0x22 & r1 & imm { *:4 r1 = imm; }
+
+

+

+

+The same size and address space considerations that apply to the ‘*’ +operator when it is used as a load operator also apply when it is used +as a store operator, see +Section 7.7.1.2, “The '*' Operator”. Unless explicit modifiers are +given, the default address space is assumed as the storage +destination, and the size of the data being stored is calculated from +context. Keep in mind that the address represented by the pointer is +not a byte address if the wordsize +attribute is set to something other than one. +

+
+
+
+7.7.2.3. Exports
+

+The semantic section doesn’t just specify how to generate p-code for a +constructor. Except for those constructors in the root table, this +section also associates a semantic meaning to the table symbol the +constructor is part of, allowing the table to be used as an operand in +other tables. The mechanism for making this association is +the export statement. This must be the last +statement in the section and consists of +the export keyword followed by the +specific symbol to be associated with the constructor. In general, the +constructor will have a sequence of assignment statements building a +final value, and then the varnode containing the value will be +exported. However, anything can be exported. +

+
+mode: reg++ is addrmode=0x2 & reg { tmp=reg; reg=reg+1; export tmp; }
+
+

+

+

+This is an example of a post-increment addressing mode that would be +used to build more complicated instructions. The constructor +increments a register reg but stores a copy of its +original value in tmp. The +varnode tmp is then exported, associating it with +the table symbol mode. When this constructor is +matched, as part of a more complicated instruction, the +symbol mode will represent the original semantic +value of reg but with the standard post-increment +side-effect. +

+

+The table symbol associated with the constructor becomes +a reference to the varnode being exported, not a +copy of the value. If the table symbol is written to, as the left-hand +side of an assignment statement, in some other constructor, the +exported varnode is affected. A constant can be exported if its size +as a varnode is given explicitly with the ‘:’ operator. +

+

+It is not legal to put a full expression in +an export statement, any expression +must appear in an earlier statement. However, a single ‘&’ +operator is allowed as part of the statement and it behaves as it +would in a normal expression (see +Section 7.7.1.6, “Address-of Operator”). It causes the address of the +varnode being modified to be exported as an integer constant. +

+
+
+
+7.7.2.4. Dynamic References
+

+The only other operator allowed as part of +an export statement, is the ‘*’ +operator. The semantic meaning of this operator is the same as if it +were used in an expression (see +Section 7.7.1.2, “The '*' Operator”), but it is worth examining the +effects of this form of export in detail. Bearing in mind that +an export statement exports +a reference, using the ‘*’ operator in the +statement exports a dynamic reference. The +varnode being modified by the ‘*’ is interpreted as a pointer to +another varnode. It is this varnode being pointed to which is +exported, even though the address may be dynamic and cannot be +determined at disassembly time. This is not the same as dereferencing +the pointer into a temporary variable that is then exported. The +dynamic reference can be both read +and written. Internally, the SLEIGH compiler +keeps track of the pointer and inserts a LOAD +or STORE operation when the symbol associated +with the dynamic reference is referred to in other constructors. +

+
+mode: reg[off] is addr=1 & reg & off {
+    ea = reg + off;
+    export *:4 ea;
+}
+dest: reloc    is abs [ reloc = abs * 4; ] {
+    export *[ram]:4 reloc;
+}
+
+

+

+

+In the first example, the effective address of an operand is +calculated from a register reg and a field of the +instruction off. The constructor does not export +the resulting pointer ea, it exports the location +being pointed to by ea. Notice the size of this +location (4) is given explicitly with the ‘:’ modifier. The ‘*’ +operator can also be used on constant pointers. In the second example, +the constant operand reloc is used as the offset +portion of an address into the ram address +space. The constant reloc is calculated at +disassembly time from the instruction +field abs. This is a very common construction for +jump destinations (see Section 7.5.1, “Relative Branches”) but +can be used in general. This particular combination of a disassembly +time action and a dynamic export is a very general way to construct a +family of varnodes. +

+

+Dynamic references are a key construction for effectively separating +addressing mode implementations from instruction semantics at higher +levels. +

+
+
+
+7.7.2.5. Branching Statements
+

+This section discusses statements that generate p-code branching +operations. These are listed in Table 7, “Branching Statements”, in the Appendix. +

+

+There are six forms covering the gamut of typical assembly language +branches, but in terms of actual semantics there are really only +three. With p-code, +

+
    +
  • +CALL is semantically equivalent to BRANCH, +
    • +
  • +CALLIND is semantically equivalent to BRANCHIND, and +
    • +
  • +RETURN is semantically equivalent to BRANCHIND. +
    • +
+

+The reason for this is that calls and returns imply the presence of +some sort of a stack. Typically an assembly language call instruction +does several separate actions, manipulating a stack pointer, storing a +return value, and so on. When translating the call instruction into +p-code, these actions must be implemented with explicit +operations. The final step of the instruction, the actual jump to the +destination of the call is now just a branch, stripped of its implied +meaning. The CALL, CALLIND, +and RETURN operations, are kept as distinct from +their BRANCH counterparts in order to provide +analysis software a hint as to the higher level meaning of the branch. +

+

+There are actually two fundamentally different ways of indicating a +destination for these branch operations. By far the most common way to +specify a destination is to give the address of a +machine instruction. It bears repeating here that there is typically +more than one p-code operation per machine instruction. So specifying +a destination address really means that the +destination is the first p-code operation for the (translated) machine +instruction at that address. For most cases, this is the only kind of +branching needed. The rarer case of p-code +relative branching is discussed in the following section +(Section 7.7.2.6, “P-code Relative Branching”), but for the remainder of +this section, we assume the destination is ultimately given as an +address. +

+

+There are two ways to specify a branching operation’s destination +address; directly and indirectly. Where a direct address is needed, as +for the BRANCH, CBRANCH, +and CALL instructions, The specification can give +the integer offset of the jump destination within the address space of +the current instruction. Optionally, the offset can be followed by the +name of another address space in square brackets, if the destination +is in another address space. +

+
+:reset is opcode=0x0 { goto 0x1000; }
+:modeshift is opcode=0x1 { goto 0x0[codespace]; }
+
+

+

+

+Of course, most branching instructions encode the destination of the +jump within the instruction somehow. So the jump destination is almost +always represented by an operand symbol and its associated +varnode. For a direct branch, the destination is given by the address +space and the offset defining the varnode. In this case, the varnode +itself is really just an annotation of the jump destination and not +used as a variable. The best way to define varnodes which annotate +jump destinations in this way is with a dynamic export. +

+
+dest: rel is simm8 [ rel = inst_next + simm8*4; ] {
+    export *[ram]:4 rel;
+}
+
+

+

+

+In this example, the operand rel is defined with +a disassembly action in terms of the address of the following +instruction, inst_next, and a field specifying a +relative relocation, simm8. The resulting +exported varnode has rel as its offset +and ram as its address space, by virtue of the +dynamic form of the export. The symbol associated with this +varnode, dest, can now be used in branch +operations. +

+
+:jmp dest is opcode=3 & dest {
+    goto dest;
+}
+:call dest is opcode=4 & dest {
+    *:4 sp = inst_next;
+    sp=sp-4;
+    call dest;
+}
+
+

+

+

+The above examples illustrate the direct forms of +the goto +and call operators, which generate +the p- code BRANCH and CALL +operations respectively. Both these operations take a single +annotation varnode as input, indicating the destination address of the +jump. Notice the explicit manipulation of a stack +pointer sp, for the call +instruction. The CBRANCH operation takes two +inputs, a boolean value indicating whether or not the branch should be +taken, and a destination annotation. +

+
+:bcc dest is opcode=5 & dest { if (carryflag==0) goto dest; }
+
+

+

+

+As in the above example, the CBRANCH operation +takes two inputs, a boolean value indicating whether or operation is +invoked with the if goto operation +takes two inputs, a boolean value indicating whether or syntax. The +condition of the if operation takes +two inputs, a boolean value indicating whether or can be any semantic +expression that results in a boolean value. The destination must be an +annotation varnode. +

+

+The +operators BRANCHIND, CALLIND, +and RETURN all have the same semantic meaning and +all use the same syntax to specify an indirect address. +

+
+:b [reg] is opcode=6 & reg {
+    goto [reg];
+}
+:call (reg) is opcode=7 & reg {
+    *:4 sp = inst_next;
+    sp=sp-4;
+    call [reg];
+}
+:ret is opcode=8 {
+    sp=sp+4;
+    tmp:4 = * sp;
+    return [tmp];
+}
+
+

+

+

+Square brackets surround the varnode containing the +address. Currently, any indirect address must be in the address space +containing the branch instruction. The offset of the destination +address is taken dynamically from the varnode. The size of the varnode +must match the size of the destination space. +

+
+
+
+7.7.2.6. P-code Relative Branching
+

+In some cases, the semantics of an instruction may require +branching within the semantics of a single +instruction, so specifying a destination address is too coarse. In +this case, SLEIGH is capable of p-code relative +branching. Individual p-code operations can be identified by +a label, and this label can be used as the +destination specifier, after the goto +keyword. A label, within the semantic section, is +any identifier surrounded by the ‘<’ and ‘>’ characters. If this +construction occurs at the beginning of a statement, we say the label +is defined, and that identifier is now associated +with the first p-code operation corresponding to the following +statement. Any label must be defined exactly once in this way. When +the construction is used as a destination, immediately after +a goto +or call, this is referred to as a +label reference. Of course the p-code destination meant by a label +reference is the operation at the point where the label was +defined. Multiple references to the same label are allowed. +

+
+:sum r1,r2,r3 is opcode=7 & r1 & r2 & r3 {
+     tmp:4 = 0;
+     r1 = 0;
+   <loopstart>
+     r1 = r1 + *r2;
+     r2 = r2 + 4;
+     tmp = tmp + 1;
+     if (tmp < r3) goto <loopstart>;
+}
+
+

+

+

+In the example above, the string “loopstart” is the label identifier +which appears twice; once at the point where the label is defined at +the top of the loop, after the initialization, and once as a reference +where the conditional branch is made for the loop. +

+

+References to labels can refer to p-code that occurs either before or +after the branching statement. But label references can only be used +in a branching statement, they cannot be used as a varnode in other +expressions. The label identifiers are local symbols and can only be +referred to within the semantic section of the constructor that +defines them. Branching into the middle of some completely different +instruction is not possible. +

+

+Internally, branches to labels are encoded as a relative index. Each +p-code operation is assigned an index corresponding to the operation’s +position within the entire translation of the instruction. Then the +branch can be expressed as a relative offset between the branch +operation’s index and the destination operation’s index. The SLEIGH +compiler encodes this offset as a constant varnode that is used as +input to +the BRANCH, CBRANCH, +or CALL operation. +

+
+
+
+7.7.2.7. Skip Instruction Branching
+

+Many processors have a conditional-skip-instruction which must branch over the next instruction +based upon some condition. The inst_next2 symbol has been provided for +this purpose. +

+
+:skip.eq is opcode=10 {
+    if (zeroflag!=0) goto inst_next2;
+}
+
+

+

+

+In the example above, the branch address will be determined by adding the parsed-length of the next +instruction to the value of inst_next causing a branch over the next +instruction when the condition is satisfied. +

+
+
+
+7.7.2.8. Bit Range Assignments
+

+The bit range operator can appear on the left-hand side of an +assignment. But as with the ‘*’ operator, its meaning is slightly +different when used on this side. The bit range is specified in square +brackets, as before, by giving the integer specifying the least +significant bit of the range, followed by the number of bits in the +range. In contrast with its use on the right however (see +Section 7.7.1.5, “Bit Range Operator”), the indicated bit range +is filled rather than extracted. Bits obtained from evaluating the +expression on the right are extracted and spliced into the result at +the indicated bit offset. +

+
+:bitset3 r1 is op=0x7d & r1 { r1[3,1] = 1; }
+
+

+In this example, bit 3 of varnode r1 is set to 1, +leaving all other bits unaffected. +

+

+As in the right-hand case, the desired insertion is achieved by +piecing together some combination of the p-code +operations INT_LEFT, INT_ZEXT, INT_AND, +and INT_OR. +

+

+In terms of the rest of the assignment expression, the bit range +operator is again assumed to have a size equal to the minimum number +of bytes needed to hold the bit range. In particular, in order to +satisfy size restrictions (see +Section 7.7.3, “Varnode Sizes”), the right-hand side must +match this size. Furthermore, it is assumed that any extra bits in the +right-hand side expression are already set to zero. +

+
+
+
+

+7.7.3. Varnode Sizes

+

+All statements within the semantic section must be specified up to the +point where the sizes of all varnodes are unambiguously +determined. Most specific symbols, like registers, must have their +size defined by definition, but there are two sources of size +ambiguity. +

+
    +
  • + Constants +
    • +
  • + Temporary Variables +
    • +
+

+

+

+The SLEIGH compiler does not make assumptions about the size of a +constant variable based on the constant value itself. This is true of +values occurring explicitly in the specification and of values that +are calculated dynamically in a disassembly action. As described in +Section 7.7.2.1, “Assignment Statements and Temporary Variables”, temporary variables do not +need to have their size given explicitly. +

+

+The SLEIGH compiler can usually fill in the required size by examining +these situations in the context of the entire semantic section. Most +p-code operations have size restrictions on their inputs and outputs, +which when put together can uniquely determine the unspecified +sizes. Referring to Table 5, “Semantic Expression Operators and Syntax” in the +Appendix, all arithmetic and logical operations, both integer and +floating point, must have inputs and outputs all of the same size. The +only exceptions are as follows. The overflow +operators, INT_CARRY, INT_SCARRY, INT_SBORROW, +and FLOAT_NAN have a boolean output. The shift +operators, INT_LEFT, INT_RIGHT, +and INT_SRIGHT, currently place no restrictions +on the shift amount operand. All the comparison +operators, both integer and floating point, insist that their inputs +are all the same size, and the output must be a boolean variable, with +a size of 1 byte. +

+

+The operators without a size constraint are the load and store +operators, the extension and truncation operators, and the conversion +operators. As discussed in Section 7.7.1.2, “The '*' Operator”, the +‘*’ operator cannot get size information for the dynamic (pointed-to) +object from the pointer itself. The other operators by definition +involve a change of size from input to output. +

+

+If the SLEIGH compiler cannot discover the sizes of constants and +temporaries, it will report an error stating that it could not resolve +variable sizes for that constructor. This can usually be fixed rapidly +by appending the size ‘:’ modifier to either the ‘*’ operator, the +temporary variable definition, or to an explicit integer. Here are +three examples of statements that generate a size resolution error, +each followed by a variation which corrects the error. +

+
+:sta [r1],imm is opcode=0x3a & r1 & imm {
+    *r1 = imm;                                      #Error
+}
+:sta [r1],imm is opcode=0x3a & r1 & imm {
+    *:4 r1 = imm;                                   #Correct
+}
+:inc [r1]     is opcode=0x3b & r1       {
+    tmp = *r1 + 1; *r1 = tmp;                       # Error
+}
+:inc [r1]     is opcode=0x3b & r1       {
+    tmp:4 = *r1 + 1; *r1 = tmp;                     # Correct
+}
+:clr [r1]     is opcode=0x3c & r1       {
+    * r1 = 0;                                       # Error
+}
+:clr [r1]     is opcode=0x3c & r1       {
+    * r1 = 0:4;                                     # Correct
+}
+
+

+

+
+
+

+7.7.4. Unimplemented Semantics

+

+The semantic section must be present for every constructor in the +specification. But the designer can leave the semantics explicitly +unimplemented if the keyword unimpl +is put in the constructor definition in place of the curly +braces. This serves as a placeholder if a specification is still in +development or if the designer does not intend to model data flow for +portions of the instruction set. Any instruction involving a +constructor that is unimplemented in this way will still be +disassembled properly, but the basic data flow routines will report an +error when analyzing the instruction. Analysis routines then can +choose whether or not to intentionally ignore the error, effectively +treating the unimplemented portion of the instruction as if it does +nothing. +

+
+:cache r1 is opcode=0x45 & r1  unimpl
+:nop      is opcode=0x0        { }
+
+

+

+
+
+
+

+7.8. Tables

+

+A single constructor does not form a new specific +symbol. The table that the constructor is +associated with via its table header is the actual symbol that can be +reused to build up more complicated elements. With all the basic +building blocks now in place, we outline the final elements for +building symbols that represent larger and larger portions of the +disassembly and p- code translation process. +

+

+The best analogy here is with grammar specifications and Regular +Language parsers. Those who have +used yacc, bison, or +otherwise looked at BNF grammars should find the concepts here +familiar. +

+

+With SLEIGH, there are in some sense two separate grammars being +parsed at the same time. A display grammar and a semantic grammar. To +the extent that the two grammars breakdown in the same way, SLEIGH can +exploit the similarity to produce an extremely concise description. +

+
+

+7.8.1. Matching

+

+If a table contains exactly one constructor, the meaning of the table +as a specific symbol is straightforward. The display meaning of the +symbol comes from the display section of the +constructor, and the symbol’s semantic meaning comes from the +constructor’s semantic section. +

+
+mode1: (r1) is addrmode=1 & r1 { export r1; }
+
+

+

+

+The table symbol in this example +is mode1. Assuming this is the only constructor, +the display meaning of the symbol are the literal characters ‘(‘, and +‘)’ concatenated with the display meaning of r1, +presumably a register name that has been attached. The semantic +meaning of mode1, because of the export +statement, becomes whatever register is matched by +the r1. +

+
+mode1: (r1) is addrmode=1 & r1 { export r1; }
+mode1: [r2] is addrmode=2 & r2 { export r2; }
+
+

+

+

+If there are two or more constructors defined for the same table, +the bit pattern section is used to select between +the constructors in context. In the above example, +the mode1 table is now defined with two +constructors and the distinguishing feature of their bit patterns is +that in one the addrmode field must be 1 and in +the other it must be 2. In the context of a particular instruction, +the matching constructor can be determined uniquely based on this +field, and the mode1 symbol takes on the display +and semantic characteristics of the matching constructor. +

+

+The bit patterns for constructors under a single table must be built +so that a constructor can be uniquely determined in context. The above +example shows the easiest way to accomplish this. The two sets of +instruction encodings, which match one or the other of the +two addrmode constraints, are disjoint. In +general, if each constructor has a set of instruction encodings +associated with it, and if the sets for any two constructors are +disjoint, then no two constructors can match at the same time. +

+

+It is possible for two sets to intersect, if one of the two sets +properly contains the other. In this situation, the constructor +corresponding to the smaller (contained) set is considered +a special case of the other constructor. If an +instruction encoding matches the special case, that constructor is +used to define the symbol, even though the other constructor will also +match. If the special case does not match but the other more general +constructor does, then the general constructor is used to define the +symbol. +

+
+zA: r1  is addrmode=3 & r1   { export r1; }
+zA: “0” is addrmode=3 & r1=0 { export 0:4; } # Special case
+
+

+

+

+In this example, the symbol zA takes on the same +display and semantic meaning as r1, except in the +special case when the field r1 equals 0. In this +case, zA takes on the display and semantic +meaning of the constant zero. Notice that the first constructor has +only the one constraint on addrmode, which is +also a constraint for the second constructor. So any instruction that +matches the second must also match the first. +

+

+The same exact rules apply when there are more than two +constructors. Any two sets defined by the bit patterns must be either +disjoint or one contained in the other. It is entirely possible to +have one general case with many special cases, or a special case of a +special case, and so on. +

+

+If the patterns for two constructors intersect, but one pattern does +not properly contain the other, this is generally an error in the +specification. Depending on the flags given to the SLEIGH compiler, it +may be more or less lenient with this kind of situation however. In +the case where an intersection is not flagged as an error, +the first constructor that matches, in the order +that the constructors appear in the specification, is used. +

+

+If two constructors intersect, but there is a third constructor whose +pattern is exactly equal to the intersection, then the third pattern +is said to resolve the conflict produced by the +first two constructors. An instruction in the intersection will match +the third constructor, as a specialization, and the remaining pieces +in the patterns of the first two constructors are disjoint. A resolved +conflict like this is not flagged as an error even with the strictest +checking. Other types of intersections, in combination with lenient +checking, can be used for various tricks in the specification but +should generally be avoided. +

+
+
+

+7.8.2. Specific Symbol Trees

+

+When the SLEIGH parser analyzes an instruction, it starts with the +root symbol instruction, and decides which of the +constructors defined under it match. This particular constructor is +likely to be defined in terms of one or more other family symbols. The +parsing process recurses at this point. Each of the unresolved family +symbols is analyzed in the same way to find the matching specific +symbol. The matching is accomplished either with a table lookup, as +with a field with attached registers, or with the matching algorithm +described in Section 7.8.1, “Matching”. By the end of the +parsing process, we have a tree of specific symbols representing the +parsed instruction. We present a small but complete SLEIGH +specification to illustrate this hierarchy. +

+

+

+
+define endian=big;
+define space ram type=ram_space size=4 default;
+define space register type=register_space size=4;
+define register offset=0 size=4 [ r0 r1 r2 r3 r4 r5 r6 r7 ];
+
+define token instr(16)
+  op=(10,15) mode=(6,9) reg1=(3,5) reg2=(0,2) imm=(0,2)
+;
+attach variables [ reg1 reg2 ] [ r0 r1 r2 r3 r4 r5 r6 r7 ];
+
+op2: reg2 is mode=0 & reg2   { export reg2; }
+op2: imm is mode=1 & imm     { export *[const]:4 imm; }
+op2: [reg2] is mode=2 & reg2 { tmp = *:4 reg2; export tmp;}
+
+:and reg1,op2 is op=0x10 & reg1 & op2 { reg1 = reg1 & op2; }
+:xor reg1,op2 is op=0x11 & reg1 & op2 { reg1 = reg1 ^ op2; }
+:or  reg1,op2 is op=0x12 & reg1 & op2 { reg1 = reg1 | op2; }
+
+

+

+

+This processor has 16 bit instructions. The high order 6 bits are the +main opcode field, selecting between logical +operations, and, or, +and xor. The logical operations each take two +operands, reg1 and op2. The +operand reg1 selects between the 8 registers of +the processor, r0 +through r7. The operand op2 +is a table built out of more complicated addressing modes, determined +by the field mode. The addressing mode can either +be direct, in which op2 is really just the +register selected by reg2, it can be immediate, +in which case the same bits are interpreted as a constant +value imm, or it can be an indirect mode, where +the register reg2 is interpreted as a pointer to +the actual operand. In any case, the two operands are combined by the +logical operation and the result is stored back +in reg1. +

+

+The parsing proceeds from the root symbol down. Once a particular +matching constructor is found, any disassembly action associated with +that constructor is executed. After that, each operand of the +constructor is resolved in turn. +

+
+
Two Encodings and the Resulting Specific Symbol Trees
+

Figure 1. Two Encodings and the Resulting Specific Symbol Trees

+
+

+In Figure 1, “Two Encodings and the Resulting Specific Symbol Trees”, we can see the break down +of two typical instructions in the example instruction set. For each +instruction, we see the how the encodings split into the relevant +fields and the resulting tree of specific symbols. Each node in the +trees are labeled with the base family symbol, the portion of the bit +pattern that matches, and then the resulting specific symbol or +constructor. Notice that the use of the overlapping +fields, reg2 and imm, is +determined by the matching constructor for +the op2 table. SLEIGH generates the disassembly +and p-code for these encodings by walking the trees. +

+
+
+7.8.2.1. Disassembly Trees
+

+If the nodes of each tree are replaced with the display information of +the corresponding specific symbol, we see how the disassembly +statement is built. +

+
+
Two Disassembly Trees
+

Figure 2. Two Disassembly Trees

+
+

+Figure 2, “Two Disassembly Trees”, shows the resulting +disassembly trees corresponding to the specific symbol trees in +Figure 1, “Two Encodings and the Resulting Specific Symbol Trees”. The display information comes +from constructor display sections, the names of attached registers, or +the integer interpretation of fields. The identifiers in a constructor +display section serves as placeholders for the subtrees below them. By +walking the tree, SLEIGH obtains the final illustrated assembly +statements corresponding to the original instruction encodings. +

+
+
+
+7.8.2.2. P-code Trees
+

+A similar procedure produces the resulting p-code translation of the +instruction. If each node in the specific symbol tree is replaced with +the corresponding p-code, we see how the final translation is built. +

+
+
Two P-code Trees
+

Figure 3. Two P-code Trees

+
+

+Figure 3, “Two P-code Trees” lists the final p-code +translation for our example instructions and shows the trees from +which the translation is derived. Symbol names within the p-code for a +particular node, as with the disassembly tree, are placeholders for +the subtree below them. The final translation is put together by +concatenating the p-code from each node, traversing the nodes in a +depth-first order. Thus the p-code of a child tends to come before the +p-code of the parent node (but see +Section 7.9, “P-code Macros”). Placeholders are filled in with the +appropriate varnode, as determined by the export statement of the root +of the corresponding subtree. +

+
+
+
+
+

+7.9. P-code Macros

+

+SLEIGH supports a macro facility for encapsulating semantic +actions. The syntax, in effect, allows the designer to define p-code +subroutines which can be invoked as part of a constructor’s semantic +action. The subroutine is expanded automatically at compile time. +

+

+A macro definition is started with +the macro keyword, which can occur +anywhere in the file before its first use. This is followed by the +global identifier for the new macro and a parameter list, comma +separated and in parentheses. The body of the definition comes next, +surrounded by curly braces. The body is a sequence of semantic +statements with the same syntax as a constructor’s semantic +section. The identifiers in the macro’s parameter list are local in +scope. The macro can refer to these and any global specific symbol. +

+
+macro resultflags(op) {
+  zeroflag = (op == 0);
+  signflag = (op1 s< 0);
+}
+
+:add r1,r2 is opcode=0xba & r1 & r2 { r1 = r1 + r2; resultflags(r1); }
+
+

+

+

+The macro is invoked in the semantic section of a constructor by using +the identifier with a functional syntax, listing the varnodes which +are to be passed into the macro. In the example above, the +macro resultflags calculates the value of two +global flags by comparing its parameter to zero. +The add constructor invokes the macro so that +the r1 is used in the comparisons. Parameters are +passed by reference, so the value of varnodes +passed into the macro can be changed. Currently, there is no syntax +for returning a value from the macro, except by writing to a parameter +or global symbol. +

+

+Almost any statement that can be used in a constructor can also be +used in a macro. This includes assignment statements, branching +statements, delayslot directives, and +calls to other macros. A build +directive however should not be used in a macro. +

+
+
+

+7.10. Build Directives

+

+Because the nodes of a specific symbol tree are traversed in a +depth-first order, the p-code for a child node in general comes before +the p-code of the parent. Furthermore, without special intervention, +the specification designer has no control over the order in which the +children of a particular node are +traversed. The build directive is +used to affect these issues in the rare cases where it is +necessary. The build directive occurs +as another form of statement in the semantic section of a +constructor. The keyword build is +followed by one of the constructor’s operand identifiers. Then, +instead of filling in the operand’s associated p-code based on an +arbitrary traversal of the symbol tree, the directive specifies that +the operand’s p-code must occur at that point in the p-code for the +parent constructor. +

+

+This directive is useful in situations where an instruction supports +prefixes or addressing modes with side-effects that must occur in a +particular order. Suppose for example that many instructions support a +condition bit in their encoding. If the bit is set, then the +instruction is executed only if a status flag is set. Otherwise, the +instruction always executes. This situation can be implemented by +treating the instruction variations as distinct constructors. However, +if many instructions support the same variation, it is probably more +efficient to treat the condition bit which distinguishes the variants +as a special operand. +

+
+cc: “c” is condition=1 { if (flag==1) goto inst_next; }
+cc:     is condition=0 { }
+
+:and^cc  r1,r2 is opcode=0x67 & cc & r1 & r2 {
+    build cc;
+    r1 = r1 & r2;
+}
+
+

+

+

+In this example, the conditional variant is distinguished by a ‘c’ +appended to the assembly mnemonic. The cc operand +performs the conditional side-effect, checking a flag in one case, or +doing nothing in the other. The two forms of the instruction can now +be implemented with a single constructor. To make sure that the flag +is checked first, before the action of the instruction, +the cc operand is forced to evaluate first with +a build directive, followed by the +normal action of the instruction. +

+
+
+

+7.11. Delay Slot Directives

+

+For processors with a pipe-lined architecture, multiple instructions +are typically executing simultaneously. This can lead to processor +conventions where certain pairs of instructions do not seem to execute +sequentially. The standard examples are branching instructions that +execute the instruction in the delay +slot. Despite the fact that execution of the branch +instruction does not fall through, the following instruction is +executed anyway. Such semantics can be implemented in SLEIGH with +the delayslot directive. +

+

+This directive appears as a standalone statement in the semantic +section of a constructor. When p- code is generated for a matching +instruction, at the point where the directive occurs, p-code for the +following instruction(s) will be generated and inserted. The directive +takes a single integer argument, indicating the minimum number of +bytes in the delay slot. Additional machine instructions will be +parsed and p-code generated, until at least that many bytes have been +disassembled. Typically the value of 1 is used to indicate that there +is exactly one more instruction in the delay slot. +

+
+:beq r1,r2,dest is op=0xbc & r1 & r2 & dest { flag=(r1==r2);
+                                              delayslot(1);
+                                              if flag goto dest; }
+
+

+

+

+This is an example of a conditional branching instruction with a delay +slot. The p-code for the following instruction is inserted before the +final CBRANCH. Notice that +the delayslot directive can appear +anywhere in the semantic section. In this example, the condition +governing the branch is evaluated before the directive because the +following instruction could conceivably affect the registers checked +by the condition. +

+

+Because the delayslot directive +combines two or more instructions into one, the meaning of the +symbols inst_next and inst_next2 +become ambiguous. It is not +clear anymore what exactly the “next instruction” is. SLEIGH uses the +following conventions for interpreting +an inst_next symbol. If it is used in the +semantic section, the symbol refers to the address of the instruction +after any instructions in the delay slot. However, if it is used in a +disassembly action, the inst_next symbol refers +to the address of the instruction immediately after the first +instruction, even if there is a delay slot. The use of the +inst_next2 symbol may be inappropriate in conjunction +with delayslot use. While its use of the +next instruction address is identified by inst_next, +the length of the next instruction ignores any delay slots it may have +when computing the value of inst_next2. +

+
+
+
+
+ + + + + + + + + + + +
+Prev   Next +
6. Tokens and Fields Home 8. Using Context
+
+ + diff --git a/sources/GhidraDocs/languages/html/sleigh_constructors.md b/sources/GhidraDocs/languages/html/sleigh_constructors.md new file mode 100644 index 0000000..0c02ad2 --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_constructors.md @@ -0,0 +1,2634 @@ +--- +status: collected +title: 7. Constructors +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_constructors.html +--- + +::: {.navheader} +7. Constructors +::: + +[Prev](sleigh_tokens.html)  + +  + + [Next](sleigh_context.html) + +------------------------------------------------------------------------ + +::: {.sect1} +::: {.titlepage} +
+ +
+ +[]{#sleigh_constructors}7. Constructors {#constructors .title style="clear: both"} +--------------------------------------- + +
+ +
+::: + +Fields are the basic building block for family symbols. The mechanisms +for building up from fields to the root [*instruction*]{.emphasis} +symbol are the [*constructor*]{.emphasis} and [*table*]{.emphasis}. + +A [*constructor*]{.emphasis} is the unit of syntax for building new +symbols. In essence a constructor describes how to build a new family +symbol, by describing, in turn, how to build a new display meaning, how +to build a new semantic meaning, and how encodings map to these new +meanings. A [*table*]{.emphasis} is a set of one or more constructors +and is the final step in creating a new family symbol identifier +associated with the pieces defined by constructors. The name of the +table is this new identifier, and it is this identifier which can be +used in the syntax for subsequent constructors. + +The difference between a constructor and table is slightly confusing at +first. In short, the syntactical elements described in this chapter, for +combining existing symbols into new symbols, are all used to describe a +single constructor. Specifications for multiple constructors are +combined to describe a single table. Since many tables are built with +only one constructor, it is natural and correct to think of a +constructor as a kind of table in and of itself. But it is only the +table that has an actual family symbol identifier associated with it. +Most of this chapter is devoted to describing how to define a single +constructor. The issues involved in combining multiple constructors into +a single table are addressed in [Section 7.8, +"Tables"](sleigh_constructors.html#sleigh_tables "7.8. Tables"){.xref}. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_sections_constructor}7.1. The Five Sections of a Constructor {#the-five-sections-of-a-constructor .title} + +
+ +
+::: + +A single complex statement in the specification file describes a +constructor. This statement is always made up of five distinct sections +that are listed below in the order in which the must occur. + +::: {.informalexample} +::: {.orderedlist} +1. Table Header +2. Display Section +3. Bit Pattern Sections +4. Disassembly Actions Section +5. Semantics Actions Section +::: +::: + +The full set of rules for correctly writing each section is long and +involved, but for any given constructor in a real specification file, +the syntax typically fits on a single line. We describe each section in +turn. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_table_header}7.2. The Table Header {#the-table-header .title} + +
+ +
+::: + +Every constructor must be part of a table, which is the element with an +actual family symbol identifier associated with it. So each constructor +starts with the identifier of the table it belongs to followed by a +colon ':'. + +::: {.informalexample} +``` +mode1: ... +``` +::: + +The above line starts the definition of a constructor that is part of +the table identified as [*mode1*]{.emphasis}. If the identifier has not +appeared before, a new table is created. If other constructors have used +the identifier, the new constructor becomes an additional part of that +same table. A constructor in the root [*instruction*]{.emphasis} table +is defined by omitting the identifier. + +::: {.informalexample} +``` +: ... +``` +::: + +The identifier [*instruction*]{.emphasis} is actually reserved for the +root table, but should not be used in the table header as the SLEIGH +parser uses the blank identifier to help distinguish assembly mnemonics +from operands (see [Section 7.3.1, +"Mnemonic"](sleigh_constructors.html#sleigh_mnemonic "7.3.1. Mnemonic"){.xref}). +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_display_section}7.3. The Display Section {#the-display-section .title} + +
+ +
+::: + +The [*display section*]{.emphasis} consists of all characters after the +table header ':' up to the SLEIGH keyword [**is**]{.bold}. The section's +primary purpose is to assign disassembly display meaning to the +constructor. The section's secondary purpose is to define local +identifiers for the pieces out of which the constructor is being built. +Characters in the display section are treated as literals with the +following exceptions. + +::: {.informalexample} +::: {.itemizedlist} +- Legal identifiers are not treated literally unless + ::: {.orderedlist} + a. The identifier is surrounded by double quotes. + b. The identifier is considered a mnemonic (see below). + ::: +- The character '\^' has special meaning. +- White space is trimmed from the beginning and end of the section. +- Other sequences of white space characters are condensed into a + single space. +::: +::: + +In particular, all punctuation except '\^' loses its special meaning. +Those identifiers that are not treated as literals are considered to be +new, initially undefined, family symbols. We refer to these new symbols +as the [*operands*]{.emphasis} of the constructor. And for root +constructors, these operands frequently correspond to the natural +assembly operands. Thinking of it as a family symbol, the constructor's +display meaning becomes the string of literals itself, with each +identifier replaced with the display meaning of the symbol corresponding +to that identifier. + +::: {.informalexample} +``` +mode1: ( op1 ),op2 is ... +``` +::: + +In the above example, a constructor for table [*mode1*]{.emphasis} is +being built out of two pieces, symbol [*op1*]{.emphasis} and symbol +[*op2*]{.emphasis}. The characters '(', ')', and ',' become literal +parts of the disassembly display for symbol mode1. After the display +strings for [*op1*]{.emphasis} and [*op2*]{.emphasis} are found, they +are inserted into the string of literals, forming the constructor's +display string. The white space characters surrounding the +[*op1*]{.emphasis} identifier are preserved as part of this string. + +The identifiers [*op1*]{.emphasis} and [*op2*]{.emphasis} are local to +the constructor and can mask global symbols with the same names. The +symbols will (must) be defined in the following sections, but only their +identifiers are established in the display section. + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_mnemonic}7.3.1. Mnemonic {#mnemonic .title} + +
+ +
+::: + +If the constructor is part of the root instruction table, the first +string of characters in the display section that does not contain white +space is treated as the [*literal mnemonic*]{.emphasis} of the +instruction and is not considered a local symbol identifier even if it +is legal. + +::: {.informalexample} +``` +:and (var1) is ... +``` +::: + +In the above example, the string "var1" is treated as a symbol +identifier, but the string "and" is considered to be the mnemonic of the +instruction. + +There is nothing that special about the mnemonic. As far as the display +meaning of the constructor is concerned, it is just a sequence of +literal characters. Although the current parser does not concern itself +with this, the mnemonic of any assembly language instruction in general +is used to guarantee the uniqueness of the assembly representation. It +is conceivable that a forward engineering engine built on SLEIGH would +place additional requirements on the mnemonic to assure uniqueness, but +for reverse engineering applications there is no such requirement. +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_caret}7.3.2. The \'\^\' character {#the-character .title} + +
+ +
+::: + +The '\^' character in the display section is used to separate +identifiers from other characters where there shouldn't be white space +in the disassembly display. This can be used in any manner but is +usually used to attach display characters from a local symbol to the +literal characters of the mnemonic. + +::: {.informalexample} +``` +:bra^cc op1,op2 is ... +``` +::: + +In the above example, "bra" is treated as literal characters in the +resulting display string followed immediately, with no intervening +spaces, by the display string of the local symbol [*cc*]{.emphasis}. +Thus the whole constructor actually has three operands, denoted by the +three identifiers [*cc*]{.emphasis}, [*op1*]{.emphasis}, and +[*op2*]{.emphasis}. + +If the '\^' is used as the first (non-whitespace) character in the +display section of a base constructor, this inhibits the first +identifier in the display from being considered the mnemonic, as +described in [Section 7.3.1, +"Mnemonic"](sleigh_constructors.html#sleigh_mnemonic "7.3.1. Mnemonic"){.xref}. +This allows specification of less common situations, where the first +part of the mnemonic, rather than perhaps a later part, needs to be +considered as an operand. An initial '\^' character can also facilitate +certain recursive constructions. +::: +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_bit_pattern}7.4. The Bit Pattern Section {#the-bit-pattern-section .title} + +
+ +
+::: + +Syntactically, this section comes between the keyword [**is**]{.bold} +and the delimiter for the following section, either an '{' or an '\['. +The [*bit pattern section*]{.emphasis} describes a constructor's +[*pattern*]{.emphasis}, the subset of possible instruction encodings +that the designer wants to [*match*]{.emphasis} the constructor being +defined. + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_constraints}7.4.1. Constraints {#constraints .title} + +
+ +
+::: + +The patterns required for processor specifications can almost always be +described as a mask and value pair. Given a specific instruction +encoding, we can decide if the encoding matches our pattern by looking +at just the bits specified by the [*mask*]{.emphasis} and seeing if they +match a specific [*value*]{.emphasis}. The fields, as defined in +[Section 6.1, "Defining Tokens and +Fields"](sleigh_tokens.html#sleigh_defining_tokens "6.1. Defining Tokens and Fields"){.xref}, +typically give us our masks. So to construct a pattern, we can simply +require that the field take on a specific value, as in the example +below. + +::: {.informalexample} +``` +:halt is opcode=0x15 { ... +``` +::: + +Assuming the symbol [*opcode*]{.emphasis} was defined as a field, this +says that a root constructor with mnemonic "halt" matches any +instruction where the bits defining this field have the value 0x15. The +equation "opcode=0x15" is called a [*constraint*]{.emphasis}. + +The standard bit encoding of the integer is used when restricting the +value of a field. This encoding is used even if an [**attach**]{.bold} +statement has assigned a different meaning to the field. The alternate +meaning does not apply within the pattern. This can be slightly +confusing, particularly in the case of an [**attach values**]{.bold} +statement, which provides an alternate integer interpretation of the +field. +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_ampandor}7.4.2. The \'&\' and \'\|\' Operators {#the-and-operators .title} + +
+ +
+::: + +More complicated patterns are built out of logical operators. The +meaning of these are fairly straightforward. We can force two or more +constraints to be true at the same time, a [*logical and*]{.emphasis} +'&', or we can require that either one constraint or another must be +true, a [*logical or*]{.emphasis} '\|'. By using these with constraints +and parentheses for grouping, arbitrarily complicated patterns can be +constructed. + +::: {.informalexample} +``` +:nop is (opcode=0 & mode=0) | (opcode=15) { ... +``` +::: + +Of the two operators, the [*logical and*]{.emphasis} is much more +common. The SLEIGH compiler typically can group together several +constraints that are combined with this operator into a single efficient +mask/value check, so this operator is to be preferred if at all +possible. The [*logical or*]{.emphasis} operator usually requires two or +more mask/value style checks to correctly implement. +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_defining_operands}7.4.3. Defining Operands and Invoking Subtables {#defining-operands-and-invoking-subtables .title} + +
+ +
+::: + +The principle way of defining a constructor operand, left undefined from +the display section, is done in the bit pattern section. If an operand's +identifier is used by itself, not as part of a constraint, then the +operand takes on both the display and semantic definition of the global +symbol with the same identifier. The syntax is slightly confusing at +first. The identifier must appear in the pattern as if it were a term in +a sequence of constraints but without the operator and right-hand side +of the constraint. + +::: {.informalexample} +``` +define token instr(32) + opcode = (0,5) + r1 = (6,10) + r2 = (11,15); +attach variables [ r1 r2 ] [ reg0 reg1 reg2 reg3 ]; + +:add r1,r2 is opcode=7 & r1 & r2 { ... +``` +::: + +This is a typical example. The [*add*]{.emphasis} instruction must have +the bits in the [*opcode*]{.emphasis} field set specifically. But it +also uses two fields in the instruction which specify registers. The +[*r1*]{.emphasis} and [*r2*]{.emphasis} identifiers are defined to be +local because they appear in the display section, but their use in the +pattern section of the definition links the local symbols with the +global register symbols defined as fields with attached registers. The +constructor is essentially saying that it is building the full +[*add*]{.emphasis} instruction encoding out of the register fields +[*r1*]{.emphasis} and [*r2*]{.emphasis} but is not specifying their +value. + +The syntax makes a little more sense keeping in mind this principle: + +::: {.informalexample} +::: {.itemizedlist} +- The pattern must somehow specify all the bits and symbols being used + by the constructor, even if the bits are not restricted to specific + values. +::: +::: + +The linkage from local symbol to global symbol will happen for any +global identifier which represents a family symbol, including table +symbols. This is in fact the principle mechanism for recursively +building new symbols from old symbols. For those familiar with grammar +parsers, a SLEIGH specification is in part a grammar specification. The +terminal symbols, or tokens, are the bits of an instruction, and the +constructors and tables are the non-terminating symbols. These all build +up to the root instruction table, the grammar's start symbol. So this +link from local to global is simply a statement of the grouping of old +symbols into the new constructor. +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_variable_length}7.4.4. Variable Length Instructions {#variable-length-instructions .title} + +
+ +
+::: + +There are some additional complexities to designing a specification for +a processor with variable length instructions. Some initial portion of +an instruction must always be parsed. But depending on the fields in +this first portion, additional portions of varying lengths may need to +be read. The key to incorporating this behavior into a SLEIGH +specification is the token. Recall that all fields are built on top of a +token which is defined to be a specific number of bytes. If a processor +has fixed length instructions, the specification needs to define only a +single token representing the entire instruction, and all fields are +built on top of this one token. For processors with variable length +instructions however, more than one token needs to be defined. Each +token has different fields defined upon it, and the SLEIGH compiler can +distinguish which tokens are involved in a particular constructor by +examining the fields it uses. The tokens that are actually used by any +matching constructors determine the final length of the instruction. +SLEIGH has two operators that are specific to variable length +instruction sets and that give the designer control over how tokens fit +together. + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_semicolon}7.4.4.1. The \';\' Operator {#the-operator .title} + +
+ +
+::: + +The most important operator for patterns defining variable length +instructions is the concatenation operator ';'. When building a +constructor with fields from two or more tokens, the pattern must +explicitly define the order of the tokens. In terms of the logic of the +pattern expressions themselves, the ';' operator has the same meaning as +the '&' operator. The combined expression matches only if both +subexpressions are true. However, it also requires that the +subexpressions involve multiple tokens and explicitly indicates an order +for them. + +::: {.informalexample} +``` +define token base(8) + op=(0,3) + mode=(4,4) + reg=(5,7); +define token immtoken(16) + imm16 = (0,15); + +:inc reg is op=2 & reg { ... +:add reg,imm16 is op=3 & reg; imm16 { ... +``` +::: + +In the above example, we see the definitions of two different tokens, +[*base*]{.emphasis} and [*immtoken*]{.emphasis}. For the first +instruction, [*inc*]{.emphasis}, the constructor uses fields +[*op*]{.emphasis} and [*reg*]{.emphasis}, both defined on +[*base*]{.emphasis}. Thus, the pattern applies constraints to just a +single byte, the size of base, in the corresponding encoding. The second +instruction, [*add*]{.emphasis}, uses fields [*op*]{.emphasis} and +[*reg*]{.emphasis}, but it also uses field [*imm16*]{.emphasis} +contained in [*immtoken*]{.emphasis}. The ';' operator indicates that +token [*base*]{.emphasis} (via its fields) comes first in the encoding, +followed by [*immtoken*]{.emphasis}. The constraints on +[*base*]{.emphasis} will therefore correspond to constraints on the +first byte of the encoding, and the constraints on +[*immtoken*]{.emphasis} will apply to the second and third bytes. The +length of the final encoding for [*add*]{.emphasis} will be 3 bytes, the +sum of the lengths of the two tokens. + +If two pattern expressions are combined with the '&' or '\|' operator, +where the concatenation operator ';' is also being used, the designer +must make sure that the tokens underlying each expression are the same +and come in the same order. In the example [*add*]{.emphasis} +instruction for instance, the '&' operator combines the "op=3" and "reg" +expressions. Both of these expressions involve only the token +[*base*]{.emphasis}, so the matching requirement is satisfied. The '&' +and '\|' operators can combine expressions built out of more than one +token, but the tokens must come in the same order. Also these operators +have higher precedence than the ';' operator, so parentheses may be +necessary to get the intended meaning. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_ellipsis}7.4.4.2. The \'\...\' Operator {#the-...-operator .title} + +
+ +
+::: + +The ellipsis operator '\...' is used to satisfy the token matching +requirements of the '&' and '\|' operators (described in the previous +section), when the operands are of different lengths. The ellipsis is a +unary operator applied to a pattern expression that extends its token +length before it is combined with another expression. Depending on what +side of the expression the ellipsis is applied, the expression\'s tokens +are either right or left justified within the extension. + +::: {.informalexample} +``` +addrmode: reg is reg & mode=0 { ... +addrmode: #imm16 is mode=1; imm16 { ... + +:xor “A”,addrmode is op=4 ... & addrmode { ... +``` +::: + +Extending the example from the previous section, we add a subtable +[*addrmode*]{.emphasis}, representing an operand that can be encoded +either as a register, if [*mode*]{.emphasis} is set to zero, or as an +immediate value, if the [*mode*]{.emphasis} bit is one. If the immediate +value mode is selected, the operand is built by reading an additional +two bytes directly from the instruction encoding. So the +[*addrmode*]{.emphasis} table can represent a 1 byte or a 3 byte +encoding depending on the mode. In the following [*xor*]{.emphasis} +instruction, [*addrmode*]{.emphasis} is used as an operand. The +particular instruction is selected by encoding a 4 in the +[*op*]{.emphasis} field, so it requires a constraint on that field in +the pattern expression. Since the instruction uses the +[*addrmode*]{.emphasis} operand, it must combine the constraint on +[*op*]{.emphasis} with the pattern for [*addrmode*]{.emphasis}. But +[*op*]{.emphasis} involves only the token [*base*]{.emphasis}, while +[*addrmode*]{.emphasis} may also involve [*immtoken*]{.emphasis}. The +ellipsis operator resolves the conflict by extending the +[*op*]{.emphasis} constraint to be whatever the length of +[*addrmode*]{.emphasis} turns out to be. + +Since the [*op*]{.emphasis} constraint occurs to the left of the +ellipsis, it is considered left justified, and the matching requirement +for '&' will insist that [*base*]{.emphasis} is the first token in all +forms of [*addrmode*]{.emphasis}. This allows the [*xor*]{.emphasis} +instruction\'s constraint on [*op*]{.emphasis} and the +[*addrmode*]{.emphasis} constraint on [*mode*]{.emphasis} to be combined +into constraints on a single byte in the final encoding. +::: +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_invisible_operands}7.4.5. Invisible Operands {#invisible-operands .title} + +
+ +
+::: + +It is not necessary for a global symbol, which is needed by a +constructor, to appear in the display section of the definition. If the +global identifier is used in the pattern section as it would be for a +normal operand definition but the identifier was not used in the display +section, then the constructor defines an [*invisible +operand*]{.emphasis}. Such an operand behaves and is parsed exactly like +any other operand but there is absolutely no visible indication of the +operand in the final display of the assembly instruction. The one common +type of instruction that uses this is the relative branch (see +[Section 7.5.1, "Relative +Branches"](sleigh_constructors.html#sleigh_relative_branches "7.5.1. Relative Branches"){.xref}) +but it is otherwise needed only in more esoteric instructions. It is +useful in situations where you need to break up the parsing of an +instruction along lines that don't quite match the assembly. +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_empty_patterns}7.4.6. Empty Patterns {#empty-patterns .title} + +
+ +
+::: + +Occasionally there is a need for an empty pattern when building tables. +An empty pattern matches everything. There is a predefined symbol +[*epsilon*]{.emphasis} which has been traditionally used to indicate an +empty pattern. +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_advanced_constraints}7.4.7. Advanced Constraints {#advanced-constraints .title} + +
+ +
+::: + +A constraint does not have to be of the form "field = constant", +although this is almost always what is needed. In certain situations, it +may be more convenient to use a different kind of constraint. Special +care should be taken when designing these constraints because they can +substantially deviate from the mask/value model used to implement most +constraints. These more general constraints are implemented by splitting +it up into smaller states which can be modeled as a mask/value pair. +This is all done automatically, and the designer may inadvertently +create huge numbers of parsing states for a single constraint. + +A constraint can actually be built out of arbitrary expressions. These +[*pattern expressions*]{.emphasis} are more commonly used in disassembly +actions and are defined in [Section 7.5.2, "General Actions and Pattern +Expressions"](sleigh_constructors.html#sleigh_general_actions "7.5.2. General Actions and Pattern Expressions"){.xref}, +but they can also be used in constraints. So in general, a constraint is +any equation where the left-hand side is a single family symbol, the +right-hand side is an arbitrary pattern expression, and the constraint +operator is one of the following: + +::: {.informalexample} +::: {.table} +[]{#constraints.htmltable} + +**Table 3. Constraint Operators** + +::: {.table-contents} + ----------------------------------------------------------------------- + [**Operator Name**]{.bold} [**Syntax**]{.bold} + ----------------------------------- ----------------------------------- + Integer equality = + + Integer inequality != + + Integer less-than \< + + Integer greater-than \> + ----------------------------------------------------------------------- +::: +::: + +\ +::: + +For a particular instruction encoding, each variable evaluates to a +specific integer depending on the encoding. A constraint is +[*satisfied*]{.emphasis} if, when all the variables are evaluated, the +equation is true. + +::: {.informalexample} +``` +:xor r1,r2 is opcode=0xcd & r1 & r2 { r1 = r1 ^ r2; } +:clr r1 is opcode=0xcd & r1 & r1=r2 { r1 = 0; } +``` +::: + +The above example illustrates a situation that does come up +occasionally. A processor uses an exclusive-or instruction to clear a +register by setting both operands of the instruction to the same +register. The first line in the example illustrates such an instruction. +However, processor documentation stipulates, and analysts prefer, that, +in this case, the disassembler should print a pseudo-instruction +[*clr*]{.emphasis}. The distinguishing feature of [*clr*]{.emphasis} +from [*xor*]{.emphasis} is that the two fields, specifying the two +register inputs to [*xor*]{.emphasis}, are equal. The easiest way to +specify this special case is with the general constraint, +"[*r1*]{.emphasis} = [*r2*]{.emphasis}", as in the second line of the +example. The SLEIGH compiler will implement this by enumerating all the +cases where [*r1*]{.emphasis} equals [*r2*]{.emphasis}, creating as many +states as there are registers. But the specification itself, at least, +remains compact. +::: +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_disassembly_actions}7.5. Disassembly Actions Section {#disassembly-actions-section .title} + +
+ +
+::: + +After the bit pattern section, there can optionally be a section for +doing dynamic calculations, which must be between square brackets. For +certain kinds of instructions, there is a need to calculate values that +depend on the specific bits of the instruction, but which cannot be +obtained as an integer interpretation of a field or by building with an +[**attach values**]{.bold} statement. So SLEIGH provides a mechanism to +build values of arbitrary complexity. This section is not intended to +emulate the execution of the processor (this is the job of the semantic +section) but is intended to produce only those values that are needed at +disassembly time, usually for part of the disassembly display. + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_relative_branches}7.5.1. Relative Branches {#relative-branches .title} + +
+ +
+::: + +The canonical example of an action at disassembly time is a branch +relocation. A jump instruction encodes the address of where it jumps to +as a relative offset to the instruction's address, for instance. But +when we display the assembly, we want to show the absolute address of +the jump destination. The correct way to specify this is to reserve an +identifier in the display section which represents the absolute address, +but then, instead of defining it in the pattern section, we define it in +the disassembly action section as a function of the current address and +the relative offset. + +::: {.informalexample} +``` +jmpdest: reloc is simm8 [ reloc=inst_next + simm8*4; ] { ... +``` +::: + +The identifier [*reloc*]{.emphasis} is reserved in the display section +for this constructor, but the identifier is not defined in the pattern +section. Instead, an invisible operand [*simm8*]{.emphasis} is defined +which is attached to a global field definition. The [*reloc*]{.emphasis} +identifier is defined in the action section as the integer obtained by +adding a multiple of [*simm8*]{.emphasis} to [*inst\_next*]{.emphasis}, +a symbol predefined to be equal to the address of the following +instruction (see [Section 5.2, "Predefined +Symbols"](sleigh_symbols.html#sleigh_predefined_symbols "5.2. Predefined Symbols"){.xref}). +Now [*reloc*]{.emphasis} is a specific symbol with both semantic and +display meaning equal to the desired absolute address. This address is +calculated separately, at disassembly time, for every instruction that +this constructor matches. +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_general_actions}7.5.2. General Actions and Pattern Expressions {#general-actions-and-pattern-expressions .title} + +
+ +
+::: + +In general, the disassembly actions are encoded as a sequence of +assignments separated by semicolons. The left-hand side of each +statement must be a single operand identifier, and the right-hand side +must be a [*pattern expression*]{.emphasis}. A [*pattern +expression*]{.emphasis} is made up of both integer constants and family +symbols that have retained their semantic meaning as integers, and it is +built up out of the following typical operators: + +::: {.informalexample} +::: {.table} +[]{#patexp.htmltable} + +**Table 4. Pattern Expression Operators** + +::: {.table-contents} ++-----------------------------------+-----------------------------------+ +| [**Operator Name**]{.bold} | [**Syntax**]{.bold} | ++===================================+===================================+ +| Integer addition | \+ | ++-----------------------------------+-----------------------------------+ +| Integer subtraction | \- | ++-----------------------------------+-----------------------------------+ +| Integer multiplication | \* | ++-----------------------------------+-----------------------------------+ +| Integer division | / | ++-----------------------------------+-----------------------------------+ +| Left-shift | \<\< | ++-----------------------------------+-----------------------------------+ +| Arithmetic right-shift | \>\> | ++-----------------------------------+-----------------------------------+ +| Bitwise and | ::: {.informaltable} | +| | []{#bitwiseand.htmltable} | +| | | +| | ---------------------------- | +| | \$and | +| | & (within square brackets) | +| | ---------------------------- | +| | ::: | ++-----------------------------------+-----------------------------------+ +| Bitwise or | ::: {.informaltable} | +| | []{#bitwiseor.htmltable} | +| | | +| | ----------------------------- | +| | \$or | +| | \| (within square brackets) | +| | ----------------------------- | +| | ::: | ++-----------------------------------+-----------------------------------+ +| Bitwise xor | ::: {.informaltable} | +| | []{#bitwisexor.htmltable} | +| | | +| | ------- | +| | \$xor | +| | \^ | +| | ------- | +| | ::: | ++-----------------------------------+-----------------------------------+ +| Bitwise negation | \~ | ++-----------------------------------+-----------------------------------+ +::: +::: + +\ +::: + +For the sake of these expressions, integers are considered signed values +of arbitrary precision. Expressions can also make use of parentheses. A +family symbol can be used in an expression, only if it can be resolved +to a particular specific symbol. This generally means that a global +family symbol, such as a field, must be attached to a local identifier +before it can be used. + +The left-hand side of an assignment statement can be a context variable +(see [Section 6.4, "Context +Variables"](sleigh_tokens.html#sleigh_context_variables "6.4. Context Variables"){.xref}). +An assignment to such a variable changes the context in which the +current instruction is being disassembled and can potentially have a +drastic effect on how the rest of the instruction is disassembled. An +assignment of this form is considered local to the instruction and will +not affect how other instructions are parsed. The context variable is +reset to its original value before parsing other instructions. The +disassembly action may also contain one or more [**globalset**]{.bold} +directives, which cause changes to context variables to become more +permanent. This directive is distinct from the operators in a pattern +expression and must be invoked as a separate statement. See [Section 8, +"Using Context"](sleigh_context.html "8. Using Context"){.xref}, for a +discussion of how to effectively use context variables and [Section 8.3, +"Global Context +Change"](sleigh_context.html#sleigh_global_change "8.3. Global Context Change"){.xref}, +for details of the [**globalset**]{.bold} directive. + +Note that there are two syntax forms for the logical operators in a +pattern expression. When an expression is used as part of a constraint, +the "\$and" and "\$or" forms of the operators must be used in order to +distinguish the bitwise operators from the special pattern combining +operators, '&' and '\|' (as described in [Section 7.4.2, "The \'&\' and +\'\|\' +Operators"](sleigh_constructors.html#sleigh_ampandor "7.4.2. The '&' and '|' Operators"){.xref}). +However inside the square braces of the disassembly action section, '&' +and '\|' are interpreted as the usual logical operators. +::: +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_with_block}7.6. The With Block {#the-with-block .title} + +
+ +
+::: + +To avoid tedious repetition and to ease the maintenance of +specifications already having many, many constructors and tables, the +[*with block*]{.emphasis} is provided. It is a syntactic construct that +allows a designer to apply a table header, bit pattern constraints, +and/or disassembly actions to a group of constructors. The block starts +at the [**with**]{.bold} directive and ends with a closing brace. All +constructors within the block are affected: + +::: {.informalexample} +``` +with op1 : mode=1 [ mode=2; ] { + :reg is reg & ind=0 [ mode=1; ] { ... } + :[reg] is reg & ind=1 { ... } +} +``` +::: + +In the example, both constructors are added to the table identified by +[*op1*]{.emphasis}. Both require the context field [*mode*]{.emphasis} +to be equal to 1. The listed constraints take the form described in +[Section 7.4, "The Bit Pattern +Section"](sleigh_constructors.html#sleigh_bit_pattern "7.4. The Bit Pattern Section"){.xref}, +and they are joined to those given in the constructor statement as if +prepended using '&'. Similarly, the actions take the form described in +[Section 7.5, "Disassembly Actions +Section"](sleigh_constructors.html#sleigh_disassembly_actions "7.5. Disassembly Actions Section"){.xref} +and are prepended to the actions given in the constructor statement. +Prepending the actions allows the statement to override actions in the +with block. Both technically occur, but only the last one has a +noticeable effect. The above example could have been equivalently +specified: + +::: {.informalexample} +``` +op1:reg is mode=1 & reg & ind=0 [ mode=2; mode=1; ] { ... } +op1:[ref] is mode=1 & reg & ind=1 [ mode=2; ] { ... } +``` +::: + +The three parts (table header, bit pattern section, and disassembly +actions section) of the with block are all optional. Any of them may be +omitted, though omitting all of them is rather pointless. With blocks +may also be nested. The innermost with block having a table header +specifies the default header of the constructors it contains. The +constraints and actions are combined outermost to innermost, left to +right. Note that when a with block has a table header specifying a table +that does not yet exist, the table is created immediately. Inside a with +block that has a table header, a nested with block may specify the +[*instruction*]{.emphasis} table by name, as in \"with instruction : +{[\...]{.weak}}\". Inside such a block, the rule regarding mnemonic +literals is restored (see [Section 7.3.1, +"Mnemonic"](sleigh_constructors.html#sleigh_mnemonic "7.3.1. Mnemonic"){.xref}). +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_semantic_section}7.7. The Semantic Section {#the-semantic-section .title} + +
+ +
+::: + +The final section of a constructor definition is the [*semantic +section*]{.emphasis}. This is a description of how the processor would +manipulate data if it actually executed an instruction that matched the +constructor. From the perspective of a single constructor, the basic +idea is that all the operands for the constructor have been defined in +the bit pattern or disassembly action sections as either specific or +family symbols. In context, all the family symbols map to specific +symbols, and the semantic section uses these and possibly other global +specific symbols in statements that describe the action of the +constructor. All specific symbols have a varnode associated with them, +so within the semantic section, symbols are manipulated as if they were +varnodes. + +The semantic section for one constructor is surrounded by curly braces +'{' and '}' and consists of zero or more statements separated by +semicolons ';'. Most statements are built up out of C-like syntax, where +the variables are the symbols visible to the constructor. There is a +direct correspondence between each type of operator used in the +statements and a p-code operation. The SLEIGH compiler generates p-code +operations and varnodes corresponding to the SLEIGH operators and +symbols by collapsing the syntax trees represented by the statements and +creating temporary storage within the [*unique*]{.emphasis} space when +it needs to. + +::: {.informalexample} +``` +:add r1,r2 is opcode=0x26 & r1 & r2 { r1 = r1 + r2; } +``` +::: + +The above example generates exactly one integer addition operation, +[*INT\_ADD*]{.emphasis}, where the input varnodes are [*r1*]{.emphasis} +and [*r2*]{.emphasis} and the output varnode is [*r1*]{.emphasis}. + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_expressions}7.7.1. Expressions {#expressions .title} + +
+ +
+::: + +Expressions are built out of symbols and the binary and unary operators +listed in [Table 5, "Semantic Expression Operators and +Syntax"](sleigh_ref.html#syntaxref.htmltable "Table 5. Semantic Expression Operators and Syntax"){.xref} +in the Appendix. All expressions evaluate to an integer, floating point, +or boolean value, depending on the final operation of the expression. +The value is then used depending on the kind of statement. Most of the +operators require that their input and output varnodes all be the same +size (see [Section 7.7.3, "Varnode +Sizes"](sleigh_constructors.html#sleigh_varnode_sizes "7.7.3. Varnode Sizes"){.xref}). +The operators all have a precedence, which is used by the SLEIGH +compiler to determine the ordering of the final p-code operations. +Parentheses can be used within expressions to affect this order. + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_arithmetic_logical}7.7.1.1. Arithmetic, Logical and Boolean Operators {#arithmetic-logical-and-boolean-operators .title} + +
+ +
+::: + +For the most part these operators should be familiar to software +developers. The only real differences arise from the fact that varnodes +are typeless. So for instance, there has to be separate operators to +distinguish between dividing unsigned numbers '/', dividing signed +numbers 's/', and dividing floating point numbers 'f/'. + +Carry, borrow, and overflow calculations are implemented with separate +operations, rather than having indirect effects with the arithmetic +operations. Thus the [*INT\_CARRY*]{.emphasis}, +[*INT\_SCARRY*]{.emphasis}, and [*INT\_SBORROW*]{.emphasis} operations +may be unfamiliar to some people in this form (see the descriptions in +the Appendix). +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_star_operator}7.7.1.2. The \'\*\' Operator {#the-operator-1 .title} + +
+ +
+::: + +The dereference operator, which generates [*LOAD*]{.emphasis} operations +(and [*STORE*]{.emphasis} operations), has slightly unfamiliar syntax. +The '\*' operator, as is usual in many programming languages, indicates +that the affected variable is a pointer and that the expression is +[*dereferencing*]{.emphasis} the data being pointed to. Unlike most +languages, in SLEIGH, it is not immediately clear what address space the +variable is pointing into because there may be multiple address spaces +defined. In the absence of any other information, SLEIGH assumes that +the variable points into the [*default*]{.emphasis} space, as labeled in +the definition of one of the address spaces with the +[**default**]{.bold} attribute. If that is not the space desired, the +default can be overridden by putting the identifier for the space in +square brackets immediately after the '\*'. + +It is also frequently not clear what the size of the dereferenced data +is because the pointer variable is typeless. The SLEIGH compiler can +frequently deduce what the size must be by looking at the operation in +the context of the entire statement (see [Section 7.7.3, "Varnode +Sizes"](sleigh_constructors.html#sleigh_varnode_sizes "7.7.3. Varnode Sizes"){.xref}). +But in some situations, this may not be possible, so there is a way to +specify the size explicitly. The operator can be followed by a colon ':' +and an integer indicating the number of bytes being dereferenced. This +can be used with or without the address space override. We give an +example of each kind of override in the example below. + +::: {.informalexample} +``` +:load r1,[r2] is opcode=0x99 & r1 & r2 { r1 = * r2; } +:load2 r1,[r2] is opcode=0x9a & r1 & r2 { r1 = *[other] r2; } +:load3 r1,[r2] is opcode=0x9b & r1 & r2 { r1 = *:2 r2; } +:load4 r1,[r2] is opcode=0x9c & r1 & r2 { r1 = *[other]:2 r2; } +``` +::: + +Keep in mind that the address represented by the pointer is not a byte +address if the [**wordsize**]{.bold} attribute is set to something other +than one. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_extension}7.7.1.3. Extension {#extension .title} + +
+ +
+::: + +Most processors have instructions that extend small values into big +values, and many instructions do these minor data manipulations +implicitly. In keeping with the p-code philosophy, these operations must +be specified explicitly with the [*INT\_ZEXT*]{.emphasis} and +[*INT\_SEXT*]{.emphasis} operators in the semantic section. The +[*INT\_ZEXT*]{.emphasis}, does a so-called [*zero +extension*]{.emphasis}. The low-order bits are copied from the input, +and any remaining high-order bits in the result are set to zero. The +[*INT\_SEXT*]{.emphasis}, does a [*signed extension*]{.emphasis}. The +low-order bits are copied from the input, but any remaining high-order +bits in the result are set to the value of the high-order bit of the +input. The [*INT\_ZEXT*]{.emphasis} operation is invoked with the +[**zext**]{.bold} operator, and the [*INT\_SEXT*]{.emphasis} operation +is invoked with the [**sext**]{.bold} operator. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_truncation}7.7.1.4. Truncation {#truncation .title} + +
+ +
+::: + +There are two forms of syntax indicating a truncation of the input +varnode. In one the varnode is followed by a colon ':' and an integer +indicating the number of bytes to copy into the output, starting with +the least significant byte. In the second form, the varnode is followed +by an integer, surrounded by parentheses, indicating the number of least +significant bytes to truncate from the input. This second form doesn't +directly specify the size of the output, which must be inferred from +context. + +::: {.informalexample} +``` +:split r1,lo,hi is opcode=0x81 & r1 & lo & hi { + lo = r1:4; + hi = r1(4); +} +``` +::: + +This is an example using both forms of truncation to split a large value +[*r1*]{.emphasis} into two smaller pieces, [*lo*]{.emphasis} and +[*hi*]{.emphasis}. Assuming [*r1*]{.emphasis} is an 8 byte value, +[*lo*]{.emphasis} receives the least significant half and +[*hi*]{.emphasis} receives the most significant half. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_bitrange_operator}7.7.1.5. Bit Range Operator {#bit-range-operator .title} + +
+ +
+::: + +A specific subrange of bits within a varnode can be explicitly +referenced. Depending on the range, this may amount to just a variation +on the truncation syntax described earlier. But for this operator, the +size and boundaries of the range do not have to be restricted to byte +alignment. + +::: {.informalexample} +``` +:bit3 r1,r2 is op=0x7e & r1 & r2 { r1 = zext(r2[3,1]); } +``` +::: + +A varnode, [*r2*]{.emphasis} in this example, is immediately followed by +square brackets '\[' and '\]' indicating a bit range, and within the +brackets, there are two parameters separated by a comma. The first +parameter is an integer indicating the least significant bit of the +resulting bit range. The bits of the varnode are labeled in order of +significance, with the least significant bit of the varnode being 0. The +second parameter is an integer indicating the number of bits in the +range. In the example, a single bit is extracted from [*r2*]{.emphasis}, +and its value is extended to fill [*r1*]{.emphasis}. Thus +[*r1*]{.emphasis} takes either the value 0 or 1, depending on bit 3 of +[*r2*]{.emphasis}. + +There are some caveats associated with using this operator. Bit range +extraction is really a pseudo operator, as real p-code can only work +with memory down to byte resolution. The bit range operator will +generate some combination of [*INT\_RIGHT*]{.emphasis}, +[*INT\_AND*]{.emphasis}, and [*SUBPIECE*]{.emphasis} to simulate the +extraction of smaller or unaligned pieces. The "r2\[3,1\]" from the +example generates the following p-code, for instance. + +::: {.informalexample} +``` +u1 = INT_RIGHT r2,#3 +u2 = SUBPIECE u1,0 +u3 = INT_AND u2,#0x1 +``` +::: + +The result of any bit range operator still has a size in bytes. This +size is always the minimum number of bytes needed to contain the +resulting bit range, and if there are any extra bits in the result these +are automatically set to zero. + +This operator can also be used on the left-hand side of assignments with +similar behavior and caveats (see [Section 7.7.2.8, "Bit Range +Assignments"](sleigh_constructors.html#sleigh_bitrange_assign "7.7.2.8. Bit Range Assignments"){.xref}). +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_addressof}7.7.1.6. Address-of Operator {#address-of-operator .title} + +
+ +
+::: + +There is an [*address-of*]{.emphasis} operator for generating the +address offset of a selected varnode as an integer value for use in +expressions. Use of this operator is a little subtle because it does +[*not*]{.emphasis} generate a p-code operation that calculates the +desired value. The address is only calculated at disassembly time and +not during execution. The operator can only be used if the symbol +referenced has a static address. + +::: {.warning style="margin-left: 0.5in; margin-right: 0.5in;"} +### Warning {#warning .title} + +The current SLEIGH compiler cannot distinguish when the symbol has an +address that can always be resolved during disassembly. So improper use +may not be flagged as an error, and the specification may produce +unexpected results. +::: + +There '&' operator in front of a symbol invokes this function. The +ampersand can also be followed by a colon ':' and an integer explicitly +indicating the size of the resulting constant as a varnode. + +::: {.informalexample} +``` +:copyr r1 is op=0x3b & r1 { tmp:4 = &r1 + 4; r1 = *[register]tmp;} +``` +::: + +The above is a contrived example of using the address-of operator to +copy from a register that is not explicitly indicated by the +instruction. This example constructs the address of the register +following [*r1*]{.emphasis} within the [*register*]{.emphasis} space, +and then loads [*r1*]{.emphasis} with data from that address. The net +effect of all this is that the register following [*r1*]{.emphasis} is +copied into [*r1*]{.emphasis}, even though it is not mentioned directly +in the instruction. Notice that the address-of operator only produces +the offset portion of the address, and to copy the desired value, the +'\*' operator must have a [*register*]{.emphasis} space override. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_managed_code}7.7.1.7. Managed Code Operations {#managed-code-operations .title} + +
+ +
+::: + +SLEIGH provides basic support for instructions where encoding and +context don\'t provide a complete description of the semantics. This is +the case typically for [*managed code*]{.emphasis} instruction sets +where generation of the semantic details of an instruction may be +deferred until run-time. Support for these operators is architecture +dependent, otherwise they just act as black-box functions. + +The constant pool operator, [**cpool**]{.bold}, returns sizes, offsets, +addresses, and other structural constants. It behaves like a +[*query*]{.emphasis} to the architecture about these constants. The +first parameter is generally an [*object reference*]{.emphasis}, and +additional parameters are constants describing the particular query. The +operator returns the requested value. In the following example, an +object reference [*regParamC*]{.emphasis} and the encoded constant +[*METHOD\_INDEX*]{.emphasis} are sent as part of a query to obtain the +final destination address of an object method. + +::: {.informalexample} +``` +:invoke_direct METHOD_INDEX,regParamC + is inst0=0x70 ; N_PARAMS=1 & METHOD_INDEX & regParamC +{ + iv0 = regParamC; + destination:4 = cpool( regParamC, METHOD_INDEX, $(CPOOL_METHOD)); + call [ destination ]; +} +``` +::: + +If object memory allocation is an atomic feature of the instruction set, +the specification designer can use the [**newobject**]{.bold} functional +operator to implement it in SLEIGH. It takes one or two parameters. The +first parameter is a [*class reference*]{.emphasis} or other value +describing the object to be allocated, and the second parameter is an +optional count of the number of objects to allocate. It returns a +pointer to the allocated object. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_userdef_op}7.7.1.8. User-Defined Operations {#user-defined-operations .title} + +
+ +
+::: + +Any identifier that has been defined as a new p-code operation, using +the [**define pcodeop**]{.bold} statement, can be invoked as an operator +using functional syntax. The SLEIGH compiler assumes that the operator +can take an arbitrary number of inputs, and if used in an expression, +the compiler assumes the operation returns an output. Using this syntax +of course generates the particular p-code operation reserved for the +identifier. + +::: {.informalexample} +``` +define pcodeop arctan; + ... +:atan r1,r2 is opcode=0xa3 & r1 & r2 { r1 = arctan(r2); } +``` +::: +::: +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_statements}7.7.2. Statements {#statements .title} + +
+ +
+::: + +We describe the types of semantic statements that are allowed in SLEIGH. + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_assign_statements}7.7.2.1. Assignment Statements and Temporary Variables {#assignment-statements-and-temporary-variables .title} + +
+ +
+::: + +Of course SLEIGH allows assignment statements with the '=' operator, +where the right-hand side is an arbitrary expression and the left-hand +side is the varnode being assigned. The assigned varnode can be any +specific symbol in the scope of the constructor, either a global symbol +or a local operand. + +In SLEIGH, the keyword [**local**]{.bold} is used to allocate temporary +variables. If an assignment statement is prepended with +[**local**]{.bold}, and the identifier on the left-hand side of an +assignment does not match any symbol in the scope of the constructor, a +named temporary varnode is created in the [*unique*]{.emphasis} address +space to hold the result of the expression. The new symbol becomes part +of the local scope of the constructor, and can be referred to in the +following semantic statements. The size of the new varnode is calculated +by examining the statement in context (see [Section 7.7.3, "Varnode +Sizes"](sleigh_constructors.html#sleigh_varnode_sizes "7.7.3. Varnode Sizes"){.xref}). +It is also possible to explicitly indicate the size by using the colon +':' operator followed by an integer size in bytes. The following +examples demonstrate the temporary variable [*tmp*]{.emphasis} being +defined using both forms. + +::: {.informalexample} +``` +:swap r1,r2 is opcode=0x41 & r1 & r2 { + local tmp = r1; + r1 = r2; + r2 = tmp; +} +:store r1,imm is opcode=0x42 & r1 & imm { + local tmp:4 = imm+0x20; + *r1 = tmp; +} +``` +::: + +The [**local**]{.bold} keyword can also be used to declare a named +temporary varnode, without an assignment statement. This is useful for +temporaries that are immediately passed into a macro. + +::: {.informalexample} +``` +:pushflags r1 is opcode=0x43 & r1 { + local tmp:4; + packflags(tmp); + * r1 = tmp; + r1 = r1 - 4; +} +``` +::: + +::: {.warning style="margin-left: 0.5in; margin-right: 0.5in;"} +### Warning {#warning-1 .title} + +Currently, the SLEIGH compiler does not need the [**local**]{.bold} +keyword to create a temporary variable. For any assignment statement, if +the left-hand side has a new identifier, a new temporary symbol will be +created using this identifier. Unfortunately, this can cause SLEIGH to +blindly accept assignment statements where the left-hand side identifier +is a misspelling of an existing symbol. Use of the [**local**]{.bold} +keyword is preferred and may be enforced in future compiler versions. +::: +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_storage_statements}7.7.2.2. Storage Statements {#storage-statements .title} + +
+ +
+::: + +SLEIGH supports fairly standard [*storage statement*]{.emphasis} syntax +to complement the load operator. The left-hand side of an assignment +statement uses the '\*' operator to indicate a dynamic storage location, +followed by an arbitrary expression to calculate the location. This +syntax of course generates the p-code [*STORE*]{.emphasis} operator as +the final step of the statement. + +::: {.informalexample} +``` +:sta [r1],r2 is opcode=0x20 & r1 & r2 { *r1 = r2; } +:stx [r1],r2 is opcode=0x21 & r1 & r2 { *[other] r1 = r2; } +:sti [r1],imm is opcode=0x22 & r1 & imm { *:4 r1 = imm; } +``` +::: + +The same size and address space considerations that apply to the '\*' +operator when it is used as a load operator also apply when it is used +as a store operator, see [Section 7.7.1.2, "The \'\*\' +Operator"](sleigh_constructors.html#sleigh_star_operator "7.7.1.2. The '*' Operator"){.xref}. +Unless explicit modifiers are given, the default address space is +assumed as the storage destination, and the size of the data being +stored is calculated from context. Keep in mind that the address +represented by the pointer is not a byte address if the +[**wordsize**]{.bold} attribute is set to something other than one. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_exports}7.7.2.3. Exports {#exports .title} + +
+ +
+::: + +The semantic section doesn't just specify how to generate p-code for a +constructor. Except for those constructors in the root table, this +section also associates a semantic meaning to the table symbol the +constructor is part of, allowing the table to be used as an operand in +other tables. The mechanism for making this association is the +[*export*]{.emphasis} statement. This must be the last statement in the +section and consists of the [**export**]{.bold} keyword followed by the +specific symbol to be associated with the constructor. In general, the +constructor will have a sequence of assignment statements building a +final value, and then the varnode containing the value will be exported. +However, anything can be exported. + +::: {.informalexample} +``` +mode: reg++ is addrmode=0x2 & reg { tmp=reg; reg=reg+1; export tmp; } +``` +::: + +This is an example of a post-increment addressing mode that would be +used to build more complicated instructions. The constructor increments +a register [*reg*]{.emphasis} but stores a copy of its original value in +[*tmp*]{.emphasis}. The varnode [*tmp*]{.emphasis} is then exported, +associating it with the table symbol [*mode*]{.emphasis}. When this +constructor is matched, as part of a more complicated instruction, the +symbol [*mode*]{.emphasis} will represent the original semantic value of +[*reg*]{.emphasis} but with the standard post-increment side-effect. + +The table symbol associated with the constructor becomes a +[*reference*]{.emphasis} to the varnode being exported, not a copy of +the value. If the table symbol is written to, as the left-hand side of +an assignment statement, in some other constructor, the exported varnode +is affected. A constant can be exported if its size as a varnode is +given explicitly with the ':' operator. + +It is not legal to put a full expression in an [**export**]{.bold} +statement, any expression must appear in an earlier statement. However, +a single '&' operator is allowed as part of the statement and it behaves +as it would in a normal expression (see [Section 7.7.1.6, "Address-of +Operator"](sleigh_constructors.html#sleigh_addressof "7.7.1.6. Address-of Operator"){.xref}). +It causes the address of the varnode being modified to be exported as an +integer constant. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_dynamic_references}7.7.2.4. Dynamic References {#dynamic-references .title} + +
+ +
+::: + +The only other operator allowed as part of an [**export**]{.bold} +statement, is the '\*' operator. The semantic meaning of this operator +is the same as if it were used in an expression (see [Section 7.7.1.2, +"The \'\*\' +Operator"](sleigh_constructors.html#sleigh_star_operator "7.7.1.2. The '*' Operator"){.xref}), +but it is worth examining the effects of this form of export in detail. +Bearing in mind that an [**export**]{.bold} statement exports a +[*reference*]{.emphasis}, using the '\*' operator in the statement +exports a [*dynamic reference*]{.emphasis}. The varnode being modified +by the '\*' is interpreted as a pointer to another varnode. It is this +varnode being pointed to which is exported, even though the address may +be dynamic and cannot be determined at disassembly time. This is not the +same as dereferencing the pointer into a temporary variable that is then +exported. The dynamic reference can be both read and +[*written*]{.emphasis}. Internally, the SLEIGH compiler keeps track of +the pointer and inserts a [*LOAD*]{.emphasis} or [*STORE*]{.emphasis} +operation when the symbol associated with the dynamic reference is +referred to in other constructors. + +::: {.informalexample} +``` +mode: reg[off] is addr=1 & reg & off { + ea = reg + off; + export *:4 ea; +} +dest: reloc is abs [ reloc = abs * 4; ] { + export *[ram]:4 reloc; +} +``` +::: + +In the first example, the effective address of an operand is calculated +from a register [*reg*]{.emphasis} and a field of the instruction +[*off*]{.emphasis}. The constructor does not export the resulting +pointer [*ea*]{.emphasis}, it exports the location being pointed to by +[*ea*]{.emphasis}. Notice the size of this location (4) is given +explicitly with the ':' modifier. The '\*' operator can also be used on +constant pointers. In the second example, the constant operand +[*reloc*]{.emphasis} is used as the offset portion of an address into +the [*ram*]{.emphasis} address space. The constant [*reloc*]{.emphasis} +is calculated at disassembly time from the instruction field +[*abs*]{.emphasis}. This is a very common construction for jump +destinations (see [Section 7.5.1, "Relative +Branches"](sleigh_constructors.html#sleigh_relative_branches "7.5.1. Relative Branches"){.xref}) +but can be used in general. This particular combination of a disassembly +time action and a dynamic export is a very general way to construct a +family of varnodes. + +Dynamic references are a key construction for effectively separating +addressing mode implementations from instruction semantics at higher +levels. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_branching_statements}7.7.2.5. Branching Statements {#branching-statements .title} + +
+ +
+::: + +This section discusses statements that generate p-code branching +operations. These are listed in [Table 7, "Branching +Statements"](sleigh_ref.html#branchref.htmltable "Table 7. Branching Statements"){.xref}, +in the Appendix. + +There are six forms covering the gamut of typical assembly language +branches, but in terms of actual semantics there are really only three. +With p-code, + +::: {.informalexample} +::: {.itemizedlist} +- [*CALL*]{.emphasis} is semantically equivalent to + [*BRANCH*]{.emphasis}, +- [*CALLIND*]{.emphasis} is semantically equivalent to + [*BRANCHIND*]{.emphasis}, and +- [*RETURN*]{.emphasis} is semantically equivalent to + [*BRANCHIND*]{.emphasis}. +::: +::: + +The reason for this is that calls and returns imply the presence of some +sort of a stack. Typically an assembly language call instruction does +several separate actions, manipulating a stack pointer, storing a return +value, and so on. When translating the call instruction into p-code, +these actions must be implemented with explicit operations. The final +step of the instruction, the actual jump to the destination of the call +is now just a branch, stripped of its implied meaning. The +[*CALL*]{.emphasis}, [*CALLIND*]{.emphasis}, and [*RETURN*]{.emphasis} +operations, are kept as distinct from their [*BRANCH*]{.emphasis} +counterparts in order to provide analysis software a hint as to the +higher level meaning of the branch. + +There are actually two fundamentally different ways of indicating a +destination for these branch operations. By far the most common way to +specify a destination is to give the [*address*]{.emphasis} of a machine +instruction. It bears repeating here that there is typically more than +one p-code operation per machine instruction. So specifying a +[*destination address*]{.emphasis} really means that the destination is +the first p-code operation for the (translated) machine instruction at +that address. For most cases, this is the only kind of branching needed. +The rarer case of [*p-code relative*]{.emphasis} branching is discussed +in the following section ([Section 7.7.2.6, "P-code Relative +Branching"](sleigh_constructors.html#sleigh_pcode_relative "7.7.2.6. P-code Relative Branching"){.xref}), +but for the remainder of this section, we assume the destination is +ultimately given as an address. + +There are two ways to specify a branching operation's destination +address; directly and indirectly. Where a direct address is needed, as +for the [*BRANCH*]{.emphasis}, [*CBRANCH*]{.emphasis}, and +[*CALL*]{.emphasis} instructions, The specification can give the integer +offset of the jump destination within the address space of the current +instruction. Optionally, the offset can be followed by the name of +another address space in square brackets, if the destination is in +another address space. + +::: {.informalexample} +``` +:reset is opcode=0x0 { goto 0x1000; } +:modeshift is opcode=0x1 { goto 0x0[codespace]; } +``` +::: + +Of course, most branching instructions encode the destination of the +jump within the instruction somehow. So the jump destination is almost +always represented by an operand symbol and its associated varnode. For +a direct branch, the destination is given by the address space and the +offset defining the varnode. In this case, the varnode itself is really +just an annotation of the jump destination and not used as a variable. +The best way to define varnodes which annotate jump destinations in this +way is with a dynamic export. + +::: {.informalexample} +``` +dest: rel is simm8 [ rel = inst_next + simm8*4; ] { + export *[ram]:4 rel; +} +``` +::: + +In this example, the operand [*rel*]{.emphasis} is defined with a +disassembly action in terms of the address of the following instruction, +[*inst\_next*]{.emphasis}, and a field specifying a relative relocation, +[*simm8*]{.emphasis}. The resulting exported varnode has +[*rel*]{.emphasis} as its offset and [*ram*]{.emphasis} as its address +space, by virtue of the dynamic form of the export. The symbol +associated with this varnode, [*dest*]{.emphasis}, can now be used in +branch operations. + +::: {.informalexample} +``` +:jmp dest is opcode=3 & dest { + goto dest; +} +:call dest is opcode=4 & dest { + *:4 sp = inst_next; + sp=sp-4; + call dest; +} +``` +::: + +The above examples illustrate the direct forms of the [**goto**]{.bold} +and [**call**]{.bold} operators, which generate the p- code +[*BRANCH*]{.emphasis} and [*CALL*]{.emphasis} operations respectively. +Both these operations take a single annotation varnode as input, +indicating the destination address of the jump. Notice the explicit +manipulation of a stack pointer [*sp*]{.emphasis}, for the call +instruction. The [*CBRANCH*]{.emphasis} operation takes two inputs, a +boolean value indicating whether or not the branch should be taken, and +a destination annotation. + +::: {.informalexample} +``` +:bcc dest is opcode=5 & dest { if (carryflag==0) goto dest; } +``` +::: + +As in the above example, the [*CBRANCH*]{.emphasis} operation takes two +inputs, a boolean value indicating whether or operation is invoked with +the [**if goto**]{.bold} operation takes two inputs, a boolean value +indicating whether or syntax. The condition of the [**if**]{.bold} +operation takes two inputs, a boolean value indicating whether or can be +any semantic expression that results in a boolean value. The destination +must be an annotation varnode. + +The operators [*BRANCHIND*]{.emphasis}, [*CALLIND*]{.emphasis}, and +[*RETURN*]{.emphasis} all have the same semantic meaning and all use the +same syntax to specify an indirect address. + +::: {.informalexample} +``` +:b [reg] is opcode=6 & reg { + goto [reg]; +} +:call (reg) is opcode=7 & reg { + *:4 sp = inst_next; + sp=sp-4; + call [reg]; +} +:ret is opcode=8 { + sp=sp+4; + tmp:4 = * sp; + return [tmp]; +} +``` +::: + +Square brackets surround the varnode containing the address. Currently, +any indirect address must be in the address space containing the branch +instruction. The offset of the destination address is taken dynamically +from the varnode. The size of the varnode must match the size of the +destination space. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_pcode_relative}7.7.2.6. P-code Relative Branching {#p-code-relative-branching .title} + +
+ +
+::: + +In some cases, the semantics of an instruction may require branching +[*within*]{.emphasis} the semantics of a single instruction, so +specifying a destination address is too coarse. In this case, SLEIGH is +capable of [*p-code relative*]{.emphasis} branching. Individual p-code +operations can be identified by a [*label*]{.emphasis}, and this label +can be used as the destination specifier, after the [**goto**]{.bold} +keyword. A [*label*]{.emphasis}, within the semantic section, is any +identifier surrounded by the '\<' and '\>' characters. If this +construction occurs at the beginning of a statement, we say the label is +[*defined*]{.emphasis}, and that identifier is now associated with the +first p-code operation corresponding to the following statement. Any +label must be defined exactly once in this way. When the construction is +used as a destination, immediately after a [**goto**]{.bold} or +[**call**]{.bold}, this is referred to as a label reference. Of course +the p-code destination meant by a label reference is the operation at +the point where the label was defined. Multiple references to the same +label are allowed. + +::: {.informalexample} +``` +:sum r1,r2,r3 is opcode=7 & r1 & r2 & r3 { + tmp:4 = 0; + r1 = 0; + + r1 = r1 + *r2; + r2 = r2 + 4; + tmp = tmp + 1; + if (tmp < r3) goto ; +} +``` +::: + +In the example above, the string "loopstart" is the label identifier +which appears twice; once at the point where the label is defined at the +top of the loop, after the initialization, and once as a reference where +the conditional branch is made for the loop. + +References to labels can refer to p-code that occurs either before or +after the branching statement. But label references can only be used in +a branching statement, they cannot be used as a varnode in other +expressions. The label identifiers are local symbols and can only be +referred to within the semantic section of the constructor that defines +them. Branching into the middle of some completely different instruction +is not possible. + +Internally, branches to labels are encoded as a relative index. Each +p-code operation is assigned an index corresponding to the operation's +position within the entire translation of the instruction. Then the +branch can be expressed as a relative offset between the branch +operation's index and the destination operation's index. The SLEIGH +compiler encodes this offset as a constant varnode that is used as input +to the [*BRANCH*]{.emphasis}, [*CBRANCH*]{.emphasis}, or +[*CALL*]{.emphasis} operation. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_skip_instruction_branching}7.7.2.7. Skip Instruction Branching {#skip-instruction-branching .title} + +
+ +
+::: + +Many processors have a conditional-skip-instruction which must branch +over the next instruction based upon some condition. The +[*inst\_next2*]{.emphasis} symbol has been provided for this purpose. + +::: {.informalexample} +``` +:skip.eq is opcode=10 { + if (zeroflag!=0) goto inst_next2; +} +``` +::: + +In the example above, the branch address will be determined by adding +the parsed-length of the next instruction to the value of +[*inst\_next*]{.emphasis} causing a branch over the next instruction +when the condition is satisfied. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_bitrange_assign}7.7.2.8. Bit Range Assignments {#bit-range-assignments .title} + +
+ +
+::: + +The bit range operator can appear on the left-hand side of an +assignment. But as with the '\*' operator, its meaning is slightly +different when used on this side. The bit range is specified in square +brackets, as before, by giving the integer specifying the least +significant bit of the range, followed by the number of bits in the +range. In contrast with its use on the right however (see +[Section 7.7.1.5, "Bit Range +Operator"](sleigh_constructors.html#sleigh_bitrange_operator "7.7.1.5. Bit Range Operator"){.xref}), +the indicated bit range is filled rather than extracted. Bits obtained +from evaluating the expression on the right are extracted and spliced +into the result at the indicated bit offset. + +::: {.informalexample} +``` +:bitset3 r1 is op=0x7d & r1 { r1[3,1] = 1; } +``` +::: + +In this example, bit 3 of varnode [*r1*]{.emphasis} is set to 1, leaving +all other bits unaffected. + +As in the right-hand case, the desired insertion is achieved by piecing +together some combination of the p-code operations +[*INT\_LEFT*]{.emphasis}, [*INT\_ZEXT*]{.emphasis}, +[*INT\_AND*]{.emphasis}, and [*INT\_OR*]{.emphasis}. + +In terms of the rest of the assignment expression, the bit range +operator is again assumed to have a size equal to the minimum number of +bytes needed to hold the bit range. In particular, in order to satisfy +size restrictions (see [Section 7.7.3, "Varnode +Sizes"](sleigh_constructors.html#sleigh_varnode_sizes "7.7.3. Varnode Sizes"){.xref}), +the right-hand side must match this size. Furthermore, it is assumed +that any extra bits in the right-hand side expression are already set to +zero. +::: +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_varnode_sizes}7.7.3. Varnode Sizes {#varnode-sizes .title} + +
+ +
+::: + +All statements within the semantic section must be specified up to the +point where the sizes of all varnodes are unambiguously determined. Most +specific symbols, like registers, must have their size defined by +definition, but there are two sources of size ambiguity. + +::: {.informalexample} +::: {.itemizedlist} +- Constants +- Temporary Variables +::: +::: + +The SLEIGH compiler does not make assumptions about the size of a +constant variable based on the constant value itself. This is true of +values occurring explicitly in the specification and of values that are +calculated dynamically in a disassembly action. As described in +[Section 7.7.2.1, "Assignment Statements and Temporary +Variables"](sleigh_constructors.html#sleigh_assign_statements "7.7.2.1. Assignment Statements and Temporary Variables"){.xref}, +temporary variables do not need to have their size given explicitly. + +The SLEIGH compiler can usually fill in the required size by examining +these situations in the context of the entire semantic section. Most +p-code operations have size restrictions on their inputs and outputs, +which when put together can uniquely determine the unspecified sizes. +Referring to [Table 5, "Semantic Expression Operators and +Syntax"](sleigh_ref.html#syntaxref.htmltable "Table 5. Semantic Expression Operators and Syntax"){.xref} +in the Appendix, all arithmetic and logical operations, both integer and +floating point, must have inputs and outputs all of the same size. The +only exceptions are as follows. The overflow operators, +[*INT\_CARRY*]{.emphasis}, [*INT\_SCARRY*]{.emphasis}, +[*INT\_SBORROW*]{.emphasis}, and [*FLOAT\_NAN*]{.emphasis} have a +boolean output. The shift operators, [*INT\_LEFT*]{.emphasis}, +[*INT\_RIGHT*]{.emphasis}, and [*INT\_SRIGHT*]{.emphasis}, currently +place no restrictions on the [*shift amount*]{.emphasis} operand. All +the comparison operators, both integer and floating point, insist that +their inputs are all the same size, and the output must be a boolean +variable, with a size of 1 byte. + +The operators without a size constraint are the load and store +operators, the extension and truncation operators, and the conversion +operators. As discussed in [Section 7.7.1.2, "The \'\*\' +Operator"](sleigh_constructors.html#sleigh_star_operator "7.7.1.2. The '*' Operator"){.xref}, +the '\*' operator cannot get size information for the dynamic +(pointed-to) object from the pointer itself. The other operators by +definition involve a change of size from input to output. + +If the SLEIGH compiler cannot discover the sizes of constants and +temporaries, it will report an error stating that it could not resolve +variable sizes for that constructor. This can usually be fixed rapidly +by appending the size ':' modifier to either the '\*' operator, the +temporary variable definition, or to an explicit integer. Here are three +examples of statements that generate a size resolution error, each +followed by a variation which corrects the error. + +::: {.informalexample} +``` +:sta [r1],imm is opcode=0x3a & r1 & imm { + *r1 = imm; #Error +} +:sta [r1],imm is opcode=0x3a & r1 & imm { + *:4 r1 = imm; #Correct +} +:inc [r1] is opcode=0x3b & r1 { + tmp = *r1 + 1; *r1 = tmp; # Error +} +:inc [r1] is opcode=0x3b & r1 { + tmp:4 = *r1 + 1; *r1 = tmp; # Correct +} +:clr [r1] is opcode=0x3c & r1 { + * r1 = 0; # Error +} +:clr [r1] is opcode=0x3c & r1 { + * r1 = 0:4; # Correct +} +``` +::: +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_unimplemented_semantics}7.7.4. Unimplemented Semantics {#unimplemented-semantics .title} + +
+ +
+::: + +The semantic section must be present for every constructor in the +specification. But the designer can leave the semantics explicitly +unimplemented if the keyword [**unimpl**]{.bold} is put in the +constructor definition in place of the curly braces. This serves as a +placeholder if a specification is still in development or if the +designer does not intend to model data flow for portions of the +instruction set. Any instruction involving a constructor that is +unimplemented in this way will still be disassembled properly, but the +basic data flow routines will report an error when analyzing the +instruction. Analysis routines then can choose whether or not to +intentionally ignore the error, effectively treating the unimplemented +portion of the instruction as if it does nothing. + +::: {.informalexample} +``` +:cache r1 is opcode=0x45 & r1 unimpl +:nop is opcode=0x0 { } +``` +::: +::: +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_tables}7.8. Tables {#tables .title} + +
+ +
+::: + +A single constructor does not form a new specific symbol. The +[*table*]{.emphasis} that the constructor is associated with via its +table header is the actual symbol that can be reused to build up more +complicated elements. With all the basic building blocks now in place, +we outline the final elements for building symbols that represent larger +and larger portions of the disassembly and p- code translation process. + +The best analogy here is with grammar specifications and Regular +Language parsers. Those who have used [*yacc*]{.emphasis}, +[*bison*]{.emphasis}, or otherwise looked at BNF grammars should find +the concepts here familiar. + +With SLEIGH, there are in some sense two separate grammars being parsed +at the same time. A display grammar and a semantic grammar. To the +extent that the two grammars breakdown in the same way, SLEIGH can +exploit the similarity to produce an extremely concise description. + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_matching}7.8.1. Matching {#matching .title} + +
+ +
+::: + +If a table contains exactly one constructor, the meaning of the table as +a specific symbol is straightforward. The display meaning of the symbol +comes from the [*display section*]{.emphasis} of the constructor, and +the symbol's semantic meaning comes from the constructor's [*semantic +section*]{.emphasis}. + +::: {.informalexample} +``` +mode1: (r1) is addrmode=1 & r1 { export r1; } +``` +::: + +The table symbol in this example is [*mode1*]{.emphasis}. Assuming this +is the only constructor, the display meaning of the symbol are the +literal characters '(', and ')' concatenated with the display meaning of +[*r1*]{.emphasis}, presumably a register name that has been attached. +The semantic meaning of [*mode1*]{.emphasis}, because of the export +statement, becomes whatever register is matched by the +[*r1*]{.emphasis}. + +::: {.informalexample} +``` +mode1: (r1) is addrmode=1 & r1 { export r1; } +mode1: [r2] is addrmode=2 & r2 { export r2; } +``` +::: + +If there are two or more constructors defined for the same table, the +[*bit pattern section*]{.emphasis} is used to select between the +constructors in context. In the above example, the [*mode1*]{.emphasis} +table is now defined with two constructors and the distinguishing +feature of their bit patterns is that in one the [*addrmode*]{.emphasis} +field must be 1 and in the other it must be 2. In the context of a +particular instruction, the matching constructor can be determined +uniquely based on this field, and the [*mode1*]{.emphasis} symbol takes +on the display and semantic characteristics of the matching constructor. + +The bit patterns for constructors under a single table must be built so +that a constructor can be uniquely determined in context. The above +example shows the easiest way to accomplish this. The two sets of +instruction encodings, which match one or the other of the two +[*addrmode*]{.emphasis} constraints, are disjoint. In general, if each +constructor has a set of instruction encodings associated with it, and +if the sets for any two constructors are disjoint, then no two +constructors can match at the same time. + +It is possible for two sets to intersect, if one of the two sets +properly contains the other. In this situation, the constructor +corresponding to the smaller (contained) set is considered a [*special +case*]{.emphasis} of the other constructor. If an instruction encoding +matches the special case, that constructor is used to define the symbol, +even though the other constructor will also match. If the special case +does not match but the other more general constructor does, then the +general constructor is used to define the symbol. + +::: {.informalexample} +``` +zA: r1 is addrmode=3 & r1 { export r1; } +zA: “0” is addrmode=3 & r1=0 { export 0:4; } # Special case +``` +::: + +In this example, the symbol [*zA*]{.emphasis} takes on the same display +and semantic meaning as [*r1*]{.emphasis}, except in the special case +when the field [*r1*]{.emphasis} equals 0. In this case, +[*zA*]{.emphasis} takes on the display and semantic meaning of the +constant zero. Notice that the first constructor has only the one +constraint on [*addrmode*]{.emphasis}, which is also a constraint for +the second constructor. So any instruction that matches the second must +also match the first. + +The same exact rules apply when there are more than two constructors. +Any two sets defined by the bit patterns must be either disjoint or one +contained in the other. It is entirely possible to have one general case +with many special cases, or a special case of a special case, and so on. + +If the patterns for two constructors intersect, but one pattern does not +properly contain the other, this is generally an error in the +specification. Depending on the flags given to the SLEIGH compiler, it +may be more or less lenient with this kind of situation however. In the +case where an intersection is not flagged as an error, the +[*first*]{.emphasis} constructor that matches, in the order that the +constructors appear in the specification, is used. + +If two constructors intersect, but there is a third constructor whose +pattern is exactly equal to the intersection, then the third pattern is +said to [*resolve*]{.emphasis} the conflict produced by the first two +constructors. An instruction in the intersection will match the third +constructor, as a specialization, and the remaining pieces in the +patterns of the first two constructors are disjoint. A resolved conflict +like this is not flagged as an error even with the strictest checking. +Other types of intersections, in combination with lenient checking, can +be used for various tricks in the specification but should generally be +avoided. +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_specific_symbol_trees}7.8.2. Specific Symbol Trees {#specific-symbol-trees .title} + +
+ +
+::: + +When the SLEIGH parser analyzes an instruction, it starts with the root +symbol [*instruction*]{.emphasis}, and decides which of the constructors +defined under it match. This particular constructor is likely to be +defined in terms of one or more other family symbols. The parsing +process recurses at this point. Each of the unresolved family symbols is +analyzed in the same way to find the matching specific symbol. The +matching is accomplished either with a table lookup, as with a field +with attached registers, or with the matching algorithm described in +[Section 7.8.1, +"Matching"](sleigh_constructors.html#sleigh_matching "7.8.1. Matching"){.xref}. +By the end of the parsing process, we have a tree of specific symbols +representing the parsed instruction. We present a small but complete +SLEIGH specification to illustrate this hierarchy. + +::: {.informalexample} +``` +define endian=big; +define space ram type=ram_space size=4 default; +define space register type=register_space size=4; +define register offset=0 size=4 [ r0 r1 r2 r3 r4 r5 r6 r7 ]; + +define token instr(16) + op=(10,15) mode=(6,9) reg1=(3,5) reg2=(0,2) imm=(0,2) +; +attach variables [ reg1 reg2 ] [ r0 r1 r2 r3 r4 r5 r6 r7 ]; + +op2: reg2 is mode=0 & reg2 { export reg2; } +op2: imm is mode=1 & imm { export *[const]:4 imm; } +op2: [reg2] is mode=2 & reg2 { tmp = *:4 reg2; export tmp;} + +:and reg1,op2 is op=0x10 & reg1 & op2 { reg1 = reg1 & op2; } +:xor reg1,op2 is op=0x11 & reg1 & op2 { reg1 = reg1 ^ op2; } +:or reg1,op2 is op=0x12 & reg1 & op2 { reg1 = reg1 | op2; } +``` +::: + +This processor has 16 bit instructions. The high order 6 bits are the +main [*opcode*]{.emphasis} field, selecting between logical operations, +[*and*]{.emphasis}, [*or*]{.emphasis}, and [*xor*]{.emphasis}. The +logical operations each take two operands, [*reg1*]{.emphasis} and +[*op2*]{.emphasis}. The operand [*reg1*]{.emphasis} selects between the +8 registers of the processor, [*r0*]{.emphasis} through +[*r7*]{.emphasis}. The operand [*op2*]{.emphasis} is a table built out +of more complicated addressing modes, determined by the field +[*mode*]{.emphasis}. The addressing mode can either be direct, in which +[*op2*]{.emphasis} is really just the register selected by +[*reg2*]{.emphasis}, it can be immediate, in which case the same bits +are interpreted as a constant value [*imm*]{.emphasis}, or it can be an +indirect mode, where the register [*reg2*]{.emphasis} is interpreted as +a pointer to the actual operand. In any case, the two operands are +combined by the logical operation and the result is stored back in +[*reg1*]{.emphasis}. + +The parsing proceeds from the root symbol down. Once a particular +matching constructor is found, any disassembly action associated with +that constructor is executed. After that, each operand of the +constructor is resolved in turn. + +::: {.figure} +[]{#sleigh_encoding_image} + +::: {.figure-contents} +::: {.mediaobject align="center"} + -------------------------------------------------------------------------------------------------- + ![Two Encodings and the Resulting Specific Symbol Trees](Diagram1.png){width="540" height="225"} + -------------------------------------------------------------------------------------------------- +::: +::: + +**Figure 1. Two Encodings and the Resulting Specific Symbol Trees** +::: + +\ + +In [Figure 1, "Two Encodings and the Resulting Specific Symbol +Trees"](sleigh_constructors.html#sleigh_encoding_image "Figure 1. Two Encodings and the Resulting Specific Symbol Trees"){.xref}, +we can see the break down of two typical instructions in the example +instruction set. For each instruction, we see the how the encodings +split into the relevant fields and the resulting tree of specific +symbols. Each node in the trees are labeled with the base family symbol, +the portion of the bit pattern that matches, and then the resulting +specific symbol or constructor. Notice that the use of the overlapping +fields, [*reg2*]{.emphasis} and [*imm*]{.emphasis}, is determined by the +matching constructor for the [*op2*]{.emphasis} table. SLEIGH generates +the disassembly and p-code for these encodings by walking the trees. + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_disassembly_trees}7.8.2.1. Disassembly Trees {#disassembly-trees .title} + +
+ +
+::: + +If the nodes of each tree are replaced with the display information of +the corresponding specific symbol, we see how the disassembly statement +is built. + +::: {.figure} +[]{#sleigh_disassembly_image} + +::: {.figure-contents} +::: {.mediaobject align="center"} + ------------------------------------------------------------------ + ![Two Disassembly Trees](Diagram2.png){width="310" height="151"} + ------------------------------------------------------------------ +::: +::: + +**Figure 2. Two Disassembly Trees** +::: + +\ + +[Figure 2, "Two Disassembly +Trees"](sleigh_constructors.html#sleigh_disassembly_image "Figure 2. Two Disassembly Trees"){.xref}, +shows the resulting disassembly trees corresponding to the specific +symbol trees in [Figure 1, "Two Encodings and the Resulting Specific +Symbol +Trees"](sleigh_constructors.html#sleigh_encoding_image "Figure 1. Two Encodings and the Resulting Specific Symbol Trees"){.xref}. +The display information comes from constructor display sections, the +names of attached registers, or the integer interpretation of fields. +The identifiers in a constructor display section serves as placeholders +for the subtrees below them. By walking the tree, SLEIGH obtains the +final illustrated assembly statements corresponding to the original +instruction encodings. +::: + +::: {.sect4} +::: {.titlepage} +
+ +
+ +##### []{#sleigh_pcode_trees}7.8.2.2. P-code Trees {#p-code-trees .title} + +
+ +
+::: + +A similar procedure produces the resulting p-code translation of the +instruction. If each node in the specific symbol tree is replaced with +the corresponding p-code, we see how the final translation is built. + +::: {.figure} +[]{#sleigh_pcode_image} + +::: {.figure-contents} +::: {.mediaobject align="center"} + ------------------------------------------------------------- + ![Two P-code Trees](Diagram3.png){width="405" height="149"} + ------------------------------------------------------------- +::: +::: + +**Figure 3. Two P-code Trees** +::: + +\ + +[Figure 3, "Two P-code +Trees"](sleigh_constructors.html#sleigh_pcode_image "Figure 3. Two P-code Trees"){.xref} +lists the final p-code translation for our example instructions and +shows the trees from which the translation is derived. Symbol names +within the p-code for a particular node, as with the disassembly tree, +are placeholders for the subtree below them. The final translation is +put together by concatenating the p-code from each node, traversing the +nodes in a depth-first order. Thus the p-code of a child tends to come +before the p-code of the parent node (but see [Section 7.9, "P-code +Macros"](sleigh_constructors.html#sleigh_macros "7.9. P-code Macros"){.xref}). +Placeholders are filled in with the appropriate varnode, as determined +by the export statement of the root of the corresponding subtree. +::: +::: +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_macros}7.9. P-code Macros {#p-code-macros .title} + +
+ +
+::: + +SLEIGH supports a macro facility for encapsulating semantic actions. The +syntax, in effect, allows the designer to define p-code subroutines +which can be invoked as part of a constructor's semantic action. The +subroutine is expanded automatically at compile time. + +A macro definition is started with the [**macro**]{.bold} keyword, which +can occur anywhere in the file before its first use. This is followed by +the global identifier for the new macro and a parameter list, comma +separated and in parentheses. The body of the definition comes next, +surrounded by curly braces. The body is a sequence of semantic +statements with the same syntax as a constructor's semantic section. The +identifiers in the macro's parameter list are local in scope. The macro +can refer to these and any global specific symbol. + +::: {.informalexample} +``` +macro resultflags(op) { + zeroflag = (op == 0); + signflag = (op1 s< 0); +} + +:add r1,r2 is opcode=0xba & r1 & r2 { r1 = r1 + r2; resultflags(r1); } +``` +::: + +The macro is invoked in the semantic section of a constructor by using +the identifier with a functional syntax, listing the varnodes which are +to be passed into the macro. In the example above, the macro +[*resultflags*]{.emphasis} calculates the value of two global flags by +comparing its parameter to zero. The [*add*]{.emphasis} constructor +invokes the macro so that the [*r1*]{.emphasis} is used in the +comparisons. Parameters are passed by [*reference*]{.emphasis}, so the +value of varnodes passed into the macro can be changed. Currently, there +is no syntax for returning a value from the macro, except by writing to +a parameter or global symbol. + +Almost any statement that can be used in a constructor can also be used +in a macro. This includes assignment statements, branching statements, +[**delayslot**]{.bold} directives, and calls to other macros. A +[**build**]{.bold} directive however should not be used in a macro. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_build_directives}7.10. Build Directives {#build-directives .title} + +
+ +
+::: + +Because the nodes of a specific symbol tree are traversed in a +depth-first order, the p-code for a child node in general comes before +the p-code of the parent. Furthermore, without special intervention, the +specification designer has no control over the order in which the +children of a particular node are traversed. The [**build**]{.bold} +directive is used to affect these issues in the rare cases where it is +necessary. The [**build**]{.bold} directive occurs as another form of +statement in the semantic section of a constructor. The keyword +[**build**]{.bold} is followed by one of the constructor's operand +identifiers. Then, instead of filling in the operand's associated p-code +based on an arbitrary traversal of the symbol tree, the directive +specifies that the operand's p-code must occur at that point in the +p-code for the parent constructor. + +This directive is useful in situations where an instruction supports +prefixes or addressing modes with side-effects that must occur in a +particular order. Suppose for example that many instructions support a +condition bit in their encoding. If the bit is set, then the instruction +is executed only if a status flag is set. Otherwise, the instruction +always executes. This situation can be implemented by treating the +instruction variations as distinct constructors. However, if many +instructions support the same variation, it is probably more efficient +to treat the condition bit which distinguishes the variants as a special +operand. + +::: {.informalexample} +``` +cc: “c” is condition=1 { if (flag==1) goto inst_next; } +cc: is condition=0 { } + +:and^cc r1,r2 is opcode=0x67 & cc & r1 & r2 { + build cc; + r1 = r1 & r2; +} +``` +::: + +In this example, the conditional variant is distinguished by a 'c' +appended to the assembly mnemonic. The [*cc*]{.emphasis} operand +performs the conditional side-effect, checking a flag in one case, or +doing nothing in the other. The two forms of the instruction can now be +implemented with a single constructor. To make sure that the flag is +checked first, before the action of the instruction, the +[*cc*]{.emphasis} operand is forced to evaluate first with a +[**build**]{.bold} directive, followed by the normal action of the +instruction. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_delayslot_directives}7.11. Delay Slot Directives {#delay-slot-directives .title} + +
+ +
+::: + +For processors with a pipe-lined architecture, multiple instructions are +typically executing simultaneously. This can lead to processor +conventions where certain pairs of instructions do not seem to execute +sequentially. The standard examples are branching instructions that +execute the instruction in the [*delay slot*]{.emphasis}. Despite the +fact that execution of the branch instruction does not fall through, the +following instruction is executed anyway. Such semantics can be +implemented in SLEIGH with the [**delayslot**]{.bold} directive. + +This directive appears as a standalone statement in the semantic section +of a constructor. When p- code is generated for a matching instruction, +at the point where the directive occurs, p-code for the following +instruction(s) will be generated and inserted. The directive takes a +single integer argument, indicating the minimum number of bytes in the +delay slot. Additional machine instructions will be parsed and p-code +generated, until at least that many bytes have been disassembled. +Typically the value of 1 is used to indicate that there is exactly one +more instruction in the delay slot. + +::: {.informalexample} +``` +:beq r1,r2,dest is op=0xbc & r1 & r2 & dest { flag=(r1==r2); + delayslot(1); + if flag goto dest; } +``` +::: + +This is an example of a conditional branching instruction with a delay +slot. The p-code for the following instruction is inserted before the +final [*CBRANCH*]{.emphasis}. Notice that the [**delayslot**]{.bold} +directive can appear anywhere in the semantic section. In this example, +the condition governing the branch is evaluated before the directive +because the following instruction could conceivably affect the registers +checked by the condition. + +Because the [**delayslot**]{.bold} directive combines two or more +instructions into one, the meaning of the symbols +[*inst\_next*]{.emphasis} and [*inst\_next2*]{.emphasis} become +ambiguous. It is not clear anymore what exactly the "next instruction" +is. SLEIGH uses the following conventions for interpreting an +[*inst\_next*]{.emphasis} symbol. If it is used in the semantic section, +the symbol refers to the address of the instruction after any +instructions in the delay slot. However, if it is used in a disassembly +action, the [*inst\_next*]{.emphasis} symbol refers to the address of +the instruction immediately after the first instruction, even if there +is a delay slot. The use of the [*inst\_next2*]{.emphasis} symbol may be +inappropriate in conjunction with [**delayslot**]{.bold} use. While its +use of the next instruction address is identified by +[*inst\_next*]{.emphasis}, the length of the next instruction ignores +any delay slots it may have when computing the value of +[*inst\_next2*]{.emphasis}. +::: +::: + +::: {.navfooter} + +------------------------------------------------------------------------ + + ----------------------------- --------------------- ------------------------------ + [Prev](sleigh_tokens.html)     [Next](sleigh_context.html) + 6. Tokens and Fields  [Home](sleigh.html)  8. Using Context + ----------------------------- --------------------- ------------------------------ +::: diff --git a/sources/GhidraDocs/languages/html/sleigh_context.html b/sources/GhidraDocs/languages/html/sleigh_context.html new file mode 100644 index 0000000..0239994 --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_context.html @@ -0,0 +1,364 @@ + + + +8. Using Context + + + + + + + + + +
+ + + + + + + +
8. Using Context
+Prev   Next +
+
+
+
+

+8. Using Context

+

+For most practical specifications, the disassembly and semantic +meaning of an instruction can be determined by looking only at the +bits in the encoding of that instruction. SLEIGH syntax reflects this +fact as every constructor or attached register is ultimately decided +by examining fields, the syntactic representation +of these instruction bits. In some cases however, the instruction +encoding itself may not be enough. Additional information, which we +refer to as context, may be necessary to fully +resolve the meaning of the instruction. +

+

+In truth, almost every modern processor has multiple modes of +operation, where the exact interpretation of instructions may depend +on that mode. Typical examples include distinguishing between a 16-bit +mode and a 32-bit mode, or between a big endian mode or a little +endian mode. But for the specification designer, these are of little +consequence because most software for such a processor will run in +only one mode without ever changing it. The designer need only pick +the most popular or most important mode for his projects and design to +that. If there is in fact software that runs under a different mode, +the other mode can be described in a separate specification. +

+

+However, for certain processors or software, the need to distinguish +between different interpretations of the same instruction encoding, +based on context, may be a crucial part of the disassembly and +analysis process. There are two typical situations where this becomes +necessary. +

+
    +
  • + The processor supports two (or more) separate instruction + sets. The set to use is usually determined by special bits in a status + register, and a single piece of software frequently switches between + these modes. +
    • +
  • + The processor supports instructions that temporarily affect + the execution of the immediately following instruction(s). For + example, many processors support hardware loop instructions that + automatically cause the following instructions to repeat without an + explicit instruction causing the branching and loop counting. +
    • +
+

+

+

+SLEIGH solves these problems by introducing context +variables. The syntax for defining these symbols was +described in Section 6.4, “Context Variables”. As mentioned +there, the easiest and most common way to use a context variable is as +just another field to use in our bit patterns. It gives us the extra +information we need to distinguish between different instructions +whose encodings are otherwise the same. +

+
+

+8.1. Basic Use of Context Variables

+

+Suppose a processor supports the use of two different sets of +registers in its main addressing mode, based on the setting of a +status bit which can be changed dynamically. If an instruction is +executed with this bit cleared, then one set of registers is used, and +if the bit is set, the other registers are used. The instructions +otherwise behave identically. +

+
+define endian=big;
+define space ram type=ram_space size=4 default;
+define space register type=register_space size=4;
+define register offset=0 size=4 [ r0 r1 r2 r3 r4 r5 r6 r7 ];
+define register offset=0x100 size=4 [ s0 s1 s2 s3 s4 s5 s6 s7 ];
+define register offset=0x200 size=4 [ statusreg ]; # define context bits (if defined, size must be multiple of 4-bytes)
+
+define token instr(16)
+  op=(10,15) rreg1=(7,9) sreg1=(7,9) imm=(0,6)
+;
+define context statusreg
+  mode=(3,3)
+;
+attach variables [ rreg1 ] [ r0 r1 r2 r3 r4 r5 r6 r7 ];
+attach variables [ sreg1 ] [ s0 s1 s2 s3 s4 s5 s6 s7 ];
+
+Reg1: rreg1 is mode=0 & rreg1 { export rreg1; }
+Reg1: sreg1 is mode=1 & sreg1 { export sreg1; }
+
+:addi Reg1,#imm  is op=1 & Reg1 & imm { Reg1 = Reg1 + imm; }
+
+

+

+

+In this example the symbol Reg1 uses the 3 bits +(7,9) to select one of eight registers. If the context +variable mode is set to 0, it selects +an r register, through +the rreg1 field. If mode is +set to 1 on the other hand, an s register is +selected instead +via sreg1. The addi +instruction (encoded as 0x0590 for example) can disassemble in one of +two ways. +

+
+addi r3,#0x10    OR
+addi s3,#0x10
+
+

+

+

+This is the same behavior as if mode were defined +as a field instead of a context variable, except that there is nothing +in the instruction encoding itself which indicates which of the two +forms will be chosen. An engine doing the disassembly will have global +state associated with the mode variable that will +make the final decision about which form to generate. The setting of +this state is (at least partially) out of the control of SLEIGH, +although see the following sections. +

+
+
+

+8.2. Local Context Change

+

+SLEIGH can make direct modifications to context variables through +statements in the disassembly action section of a constructor. The +left-hand side of an assignment statement in this section can be a context variable, +see Section 7.5.2, “General Actions and Pattern Expressions”. Because the result of this +assignment is calculated in the middle of the instruction disassembly, +the change in value of the context variable can potentially affect any +remaining parsing for that instruction. A modal variable is being +added to what was otherwise a stateless grammar, a common technique in +many practical parsing engines. +

+

+Any assignment statement changing a context variable is immediately +executed upon the successful match of the constructor containing the +statement and can be used to guide the parsing of the constructor's +operands. We introduce two more instructions to the example +specification from the previous section. +

+
+:raddi Reg1,#imm is op=2 & Reg1 & imm [ mode=0; ] {
+    Reg1 = Reg1 + imm;
+}
+:saddi Reg1,#imm is op=3 & Reg1 & imm [ mode=1; ] {
+    Reg1 = Reg1 + imm;
+}
+
+

+

+

+Notice that both new constructors modify the context +variable mode. The raddi instruction sets mode to +0 and effectively guarantees that an r register +will be produced by the disassembly. Similarly, +the saddi instruction can force +an s register. Both are in contrast to +the addi instruction, which depends on a global +state. The changes to mode made by these +instructions only persist for parsing of that single instruction. For +any following instructions, if the matching constructors +use mode, its value will have reverted to its +original global state. The same holds for any context variable +modified with this syntax. If an instruction needs to permanently +modify the state of a context variable, the designer must use +constructions described in Section 8.3, “Global Context Change”. +

+

+Clearly, the behavior of the above example could be easily replicated +without using context variables at all and having the selection of a +register set simply depend directly on the op +field. But, with more complicated addressing modes, local modification +of context variables can drastically reduce the complexity and size of +a specification. +

+

+At the point where a modification is made to a context variable, the +specification designer has the guarantee that none of the operands of +the constructor have been evaluated yet, so if their matching depends +on this context variable, they will be affected by the change. In +contrast, the matching of any ancestor constructor cannot be +affected. Other constructors, which are not direct ancestors or +descendants, may or may not be affected by the change, depending on +the order of evaluation. It is usually best not to depend on this +ordering when designing the specification, with the possible exception +of orderings which are guaranteed +by build directives. +

+
+
+

+8.3. Global Context Change

+

+It is possible for an instruction to attempt a permanent change to a +context variable, which would then affect the parsing of other +instructions, by using the globalset +directive in a disassembly action. As mentioned in the previous +section, context variables have an associated global state, which can +be used during constructor matching. A complete model for this state +is, unfortunately, outside the scope of SLEIGH. The disassembly engine +has to make too many decisions about what is getting disassembled and +what assumptions are being made to give complete control of the +context to SLEIGH. Because of this caveat, SLEIGH syntax for making +permanent context changes should be viewed as a suggestion to the +disassembly engine. +

+

+For processors that support multiple modes, there are typically +specific instructions that switch between these modes. Extending the +example from the previous sections, we add two instructions to the +specification for permanently switching which register set is being +used. +

+
+:rmode is op=32 & rreg1=0 & imm=0
+       [ mode=0; globalset(inst_next,mode); ]
+{}
+:smode is op=33 & rreg1=0 & imm=0
+       [ mode=1; globalset(inst_next,mode); ]
+{}
+
+

+

+

+The register set is, as before, controlled by +the mode variable, and as with a local change to +context, the variable is assigned to inside the square +brackets. The rmode instruction +sets mode to 0, in order to +select r registers +via rreg1, and smode +sets mode to 1 in order to +select s registers. As is described in +Section 8.2, “Local Context Change”, these assignments by themselves +cause only a local context change. However, the +subsequent globalset directives make +the change persist outside of the the instructions +themselves. The globalset directive +takes two parameters, the second being the particular context variable +being changed. The first parameter indicates the first address where +the new context takes effect. In the example, the expectation is that +a mode change affects any subsequent instructions. So the first +parameter to globalset here +is inst_next, indicating that the new value +of mode begins at the next address. +

+
+

+8.3.1. Context Flow

+

+A global change to context that affects instruction decoding is typically +open-ended. I.e. once the mode switching instruction is executed, a permanent change +is made to the run-time processor state, and all future instruction decoding is +affected, until another mode switch is encountered. In terms of SLEIGH by default, +the effect of a globalset directive +follows flow. Starting from the address specified in the directive, +the change in context follows the control-flow of the instructions, through +branches and calls, until an execution path terminates or another context change +is encountered. +

+

+Flow following behavior can be overridden by adding the noflow +attribute to the definition of the context field. (See Section 6.4, “Context Variables”) +In this case, a globalset directive only affects the context +of a single instruction at the specified address. Subsequent instructions +retain their original context. This can be useful in a variety of situations but is typically +used to let one instruction alter the behavior, not necessarily the decoding, +of the following instruction. In the example below, +an indirect branch instruction jumps through a link register lr. If the previous +instruction moves the program counter in to lr, it communicates this to the +branch instruction through the LRset context variable so that the branch can +be interpreted as a return, rather than a generic indirect branch. +

+
+define context contextreg
+  LRset = (1,1) noflow  # 1 if the instruction before was a mov lr,pc
+;
+  ...
+mov lr,pc  is opcode=34 & lr & pc
+           [ LRset=1; globalset(inst_next,LRset); ] { lr = pc; }
+  ...
+blr        is opcode=35 & reg=15 & LRset=0 { goto [lr]; }
+blr        is opcode=35 & reg=15 & LRset=1 { return [lr]; }
+
+

+

+

+An alternative to the noflow attribute is to simply issue +multiple directives within a single constructor, so an explicit end to a context change +can be given. The value of the variable exported to the global state +is the one in effect at the point where the directive is issued. Thus, +after one globalset, the same context +variable can be assigned a different value, followed by +another globalset for a different +address. +

+

+Because context in SLEIGH is controlled by a disassembly process, +there are some basic caveats to the use of +the globalset directive. With +flowing context changes, +there is no guarantee of what global state will be in effect at a +particular address. During disassembly, at any given +point, the process may not have uncovered all the relevant directives, +and the known directives may not necessarily be consistent. In +general, for most processors, the disassembly at a particular address +is intended to be absolute. So given enough information, it should be +possible to make a definitive determination of what the context is at +a certain address, but there is no guarantee. It is up to the +disassembly process to fully determine where context changes begin and +end and what to do if there are conflicts. +

+
+
+
+
+
+ + + + + + + + + + + +
+Prev   Next +
7. Constructors Home 9. P-code Tables
+
+ + diff --git a/sources/GhidraDocs/languages/html/sleigh_context.md b/sources/GhidraDocs/languages/html/sleigh_context.md new file mode 100644 index 0000000..5bc68fb --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_context.md @@ -0,0 +1,379 @@ +--- +status: collected +title: 8. Using Context +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_context.html +--- + +::: {.navheader} +8. Using Context +::: + +[Prev](sleigh_constructors.html)  + +  + + [Next](sleigh_ref.html) + +------------------------------------------------------------------------ + +::: {.sect1} +::: {.titlepage} +
+ +
+ +[]{#sleigh_context}8. Using Context {#using-context .title style="clear: both"} +----------------------------------- + +
+ +
+::: + +For most practical specifications, the disassembly and semantic meaning +of an instruction can be determined by looking only at the bits in the +encoding of that instruction. SLEIGH syntax reflects this fact as every +constructor or attached register is ultimately decided by examining +[*fields*]{.emphasis}, the syntactic representation of these instruction +bits. In some cases however, the instruction encoding itself may not be +enough. Additional information, which we refer to as +[*context*]{.emphasis}, may be necessary to fully resolve the meaning of +the instruction. + +In truth, almost every modern processor has multiple modes of operation, +where the exact interpretation of instructions may depend on that mode. +Typical examples include distinguishing between a 16-bit mode and a +32-bit mode, or between a big endian mode or a little endian mode. But +for the specification designer, these are of little consequence because +most software for such a processor will run in only one mode without +ever changing it. The designer need only pick the most popular or most +important mode for his projects and design to that. If there is in fact +software that runs under a different mode, the other mode can be +described in a separate specification. + +However, for certain processors or software, the need to distinguish +between different interpretations of the same instruction encoding, +based on context, may be a crucial part of the disassembly and analysis +process. There are two typical situations where this becomes necessary. + +::: {.informalexample} +::: {.itemizedlist} +- The processor supports two (or more) separate instruction sets. The + set to use is usually determined by special bits in a status + register, and a single piece of software frequently switches between + these modes. +- The processor supports instructions that temporarily affect the + execution of the immediately following instruction(s). For example, + many processors support hardware [*loop*]{.emphasis} instructions + that automatically cause the following instructions to repeat + without an explicit instruction causing the branching and loop + counting. +::: +::: + +SLEIGH solves these problems by introducing [*context +variables*]{.emphasis}. The syntax for defining these symbols was +described in [Section 6.4, "Context +Variables"](sleigh_tokens.html#sleigh_context_variables "6.4. Context Variables"){.xref}. +As mentioned there, the easiest and most common way to use a context +variable is as just another field to use in our bit patterns. It gives +us the extra information we need to distinguish between different +instructions whose encodings are otherwise the same. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_context_basic}8.1. Basic Use of Context Variables {#basic-use-of-context-variables .title} + +
+ +
+::: + +Suppose a processor supports the use of two different sets of registers +in its main addressing mode, based on the setting of a status bit which +can be changed dynamically. If an instruction is executed with this bit +cleared, then one set of registers is used, and if the bit is set, the +other registers are used. The instructions otherwise behave identically. + +::: {.informalexample} +``` +define endian=big; +define space ram type=ram_space size=4 default; +define space register type=register_space size=4; +define register offset=0 size=4 [ r0 r1 r2 r3 r4 r5 r6 r7 ]; +define register offset=0x100 size=4 [ s0 s1 s2 s3 s4 s5 s6 s7 ]; +define register offset=0x200 size=4 [ statusreg ]; # define context bits (if defined, size must be multiple of 4-bytes) + +define token instr(16) + op=(10,15) rreg1=(7,9) sreg1=(7,9) imm=(0,6) +; +define context statusreg + mode=(3,3) +; +attach variables [ rreg1 ] [ r0 r1 r2 r3 r4 r5 r6 r7 ]; +attach variables [ sreg1 ] [ s0 s1 s2 s3 s4 s5 s6 s7 ]; + +Reg1: rreg1 is mode=0 & rreg1 { export rreg1; } +Reg1: sreg1 is mode=1 & sreg1 { export sreg1; } + +:addi Reg1,#imm is op=1 & Reg1 & imm { Reg1 = Reg1 + imm; } +``` +::: + +In this example the symbol [*Reg1*]{.emphasis} uses the 3 bits (7,9) to +select one of eight registers. If the context variable +[*mode*]{.emphasis} is set to 0, it selects an [*r*]{.emphasis} +register, through the [*rreg1*]{.emphasis} field. If [*mode*]{.emphasis} +is set to 1 on the other hand, an [*s*]{.emphasis} register is selected +instead via [*sreg1*]{.emphasis}. The [*addi*]{.emphasis} instruction +(encoded as 0x0590 for example) can disassemble in one of two ways. + +::: {.informalexample} +``` +addi r3,#0x10 OR +addi s3,#0x10 +``` +::: + +This is the same behavior as if [*mode*]{.emphasis} were defined as a +field instead of a context variable, except that there is nothing in the +instruction encoding itself which indicates which of the two forms will +be chosen. An engine doing the disassembly will have global state +associated with the [*mode*]{.emphasis} variable that will make the +final decision about which form to generate. The setting of this state +is (at least partially) out of the control of SLEIGH, although see the +following sections. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_local_change}8.2. Local Context Change {#local-context-change .title} + +
+ +
+::: + +SLEIGH can make direct modifications to context variables through +statements in the disassembly action section of a constructor. The +left-hand side of an assignment statement in this section can be a +context variable, see [Section 7.5.2, "General Actions and Pattern +Expressions"](sleigh_constructors.html#sleigh_general_actions "7.5.2. General Actions and Pattern Expressions"){.xref}. +Because the result of this assignment is calculated in the middle of the +instruction disassembly, the change in value of the context variable can +potentially affect any remaining parsing for that instruction. A modal +variable is being added to what was otherwise a stateless grammar, a +common technique in many practical parsing engines. + +Any assignment statement changing a context variable is immediately +executed upon the successful match of the constructor containing the +statement and can be used to guide the parsing of the constructor\'s +operands. We introduce two more instructions to the example +specification from the previous section. + +::: {.informalexample} +``` +:raddi Reg1,#imm is op=2 & Reg1 & imm [ mode=0; ] { + Reg1 = Reg1 + imm; +} +:saddi Reg1,#imm is op=3 & Reg1 & imm [ mode=1; ] { + Reg1 = Reg1 + imm; +} +``` +::: + +Notice that both new constructors modify the context variable +[*mode*]{.emphasis}. The raddi instruction sets mode to 0 and +effectively guarantees that an [*r*]{.emphasis} register will be +produced by the disassembly. Similarly, the [*saddi*]{.emphasis} +instruction can force an [*s*]{.emphasis} register. Both are in contrast +to the [*addi*]{.emphasis} instruction, which depends on a global state. +The changes to [*mode*]{.emphasis} made by these instructions only +persist for parsing of that single instruction. For any following +instructions, if the matching constructors use [*mode*]{.emphasis}, its +value will have reverted to its original global state. The same holds +for any context variable modified with this syntax. If an instruction +needs to permanently modify the state of a context variable, the +designer must use constructions described in [Section 8.3, "Global +Context +Change"](sleigh_context.html#sleigh_global_change "8.3. Global Context Change"){.xref}. + +Clearly, the behavior of the above example could be easily replicated +without using context variables at all and having the selection of a +register set simply depend directly on the [*op*]{.emphasis} field. But, +with more complicated addressing modes, local modification of context +variables can drastically reduce the complexity and size of a +specification. + +At the point where a modification is made to a context variable, the +specification designer has the guarantee that none of the operands of +the constructor have been evaluated yet, so if their matching depends on +this context variable, they will be affected by the change. In contrast, +the matching of any ancestor constructor cannot be affected. Other +constructors, which are not direct ancestors or descendants, may or may +not be affected by the change, depending on the order of evaluation. It +is usually best not to depend on this ordering when designing the +specification, with the possible exception of orderings which are +guaranteed by [**build**]{.bold} directives. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_global_change}8.3. Global Context Change {#global-context-change .title} + +
+ +
+::: + +It is possible for an instruction to attempt a permanent change to a +context variable, which would then affect the parsing of other +instructions, by using the [**globalset**]{.bold} directive in a +disassembly action. As mentioned in the previous section, context +variables have an associated global state, which can be used during +constructor matching. A complete model for this state is, unfortunately, +outside the scope of SLEIGH. The disassembly engine has to make too many +decisions about what is getting disassembled and what assumptions are +being made to give complete control of the context to SLEIGH. Because of +this caveat, SLEIGH syntax for making permanent context changes should +be viewed as a suggestion to the disassembly engine. + +For processors that support multiple modes, there are typically specific +instructions that switch between these modes. Extending the example from +the previous sections, we add two instructions to the specification for +permanently switching which register set is being used. + +::: {.informalexample} +``` +:rmode is op=32 & rreg1=0 & imm=0 + [ mode=0; globalset(inst_next,mode); ] +{} +:smode is op=33 & rreg1=0 & imm=0 + [ mode=1; globalset(inst_next,mode); ] +{} +``` +::: + +The register set is, as before, controlled by the [*mode*]{.emphasis} +variable, and as with a local change to context, the variable is +assigned to inside the square brackets. The [*rmode*]{.emphasis} +instruction sets [*mode*]{.emphasis} to 0, in order to select +[*r*]{.emphasis} registers via [*rreg1*]{.emphasis}, and +[*smode*]{.emphasis} sets [*mode*]{.emphasis} to 1 in order to select +[*s*]{.emphasis} registers. As is described in [Section 8.2, "Local +Context +Change"](sleigh_context.html#sleigh_local_change "8.2. Local Context Change"){.xref}, +these assignments by themselves cause only a local context change. +However, the subsequent [**globalset**]{.bold} directives make the +change persist outside of the the instructions themselves. The +[**globalset**]{.bold} directive takes two parameters, the second being +the particular context variable being changed. The first parameter +indicates the first address where the new context takes effect. In the +example, the expectation is that a mode change affects any subsequent +instructions. So the first parameter to [**globalset**]{.bold} here is +[*inst\_next*]{.emphasis}, indicating that the new value of +[*mode*]{.emphasis} begins at the next address. + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_contextflow}8.3.1. Context Flow {#context-flow .title} + +
+ +
+::: + +A global change to context that affects instruction decoding is +typically open-ended. I.e. once the mode switching instruction is +executed, a permanent change is made to the run-time processor state, +and all future instruction decoding is affected, until another mode +switch is encountered. In terms of SLEIGH by default, the effect of a +[**globalset**]{.bold} directive follows [*flow*]{.emphasis}. Starting +from the address specified in the directive, the change in context +follows the control-flow of the instructions, through branches and +calls, until an execution path terminates or another context change is +encountered. + +Flow following behavior can be overridden by adding the +[**noflow**]{.bold} attribute to the definition of the context field. +(See [Section 6.4, "Context +Variables"](sleigh_tokens.html#sleigh_context_variables "6.4. Context Variables"){.xref}) +In this case, a [**globalset**]{.bold} directive only affects the +context of a single instruction at the specified address. Subsequent +instructions retain their original context. This can be useful in a +variety of situations but is typically used to let one instruction alter +the behavior, not necessarily the decoding, of the following +instruction. In the example below, an indirect branch instruction jumps +through a link register [*lr*]{.emphasis}. If the previous instruction +moves the program counter in to [*lr*]{.emphasis}, it communicates this +to the branch instruction through the [*LRset*]{.emphasis} context +variable so that the branch can be interpreted as a return, rather than +a generic indirect branch. + +::: {.informalexample} +``` +define context contextreg + LRset = (1,1) noflow # 1 if the instruction before was a mov lr,pc +; + ... +mov lr,pc is opcode=34 & lr & pc + [ LRset=1; globalset(inst_next,LRset); ] { lr = pc; } + ... +blr is opcode=35 & reg=15 & LRset=0 { goto [lr]; } +blr is opcode=35 & reg=15 & LRset=1 { return [lr]; } +``` +::: + +An alternative to the [**noflow**]{.bold} attribute is to simply issue +multiple directives within a single constructor, so an explicit end to a +context change can be given. The value of the variable exported to the +global state is the one in effect at the point where the directive is +issued. Thus, after one [**globalset**]{.bold}, the same context +variable can be assigned a different value, followed by another +[**globalset**]{.bold} for a different address. + +Because context in SLEIGH is controlled by a disassembly process, there +are some basic caveats to the use of the [**globalset**]{.bold} +directive. With [*flowing*]{.emphasis} context changes, there is no +guarantee of what global state will be in effect at a particular +address. During disassembly, at any given point, the process may not +have uncovered all the relevant directives, and the known directives may +not necessarily be consistent. In general, for most processors, the +disassembly at a particular address is intended to be absolute. So given +enough information, it should be possible to make a definitive +determination of what the context is at a certain address, but there is +no guarantee. It is up to the disassembly process to fully determine +where context changes begin and end and what to do if there are +conflicts. +::: +::: +::: + +::: {.navfooter} + +------------------------------------------------------------------------ + + ----------------------------------- --------------------- -------------------------- + [Prev](sleigh_constructors.html)     [Next](sleigh_ref.html) + 7. Constructors  [Home](sleigh.html)  9. P-code Tables + ----------------------------------- --------------------- -------------------------- +::: diff --git a/sources/GhidraDocs/languages/html/sleigh_definitions.html b/sources/GhidraDocs/languages/html/sleigh_definitions.html new file mode 100644 index 0000000..1b615ac --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_definitions.html @@ -0,0 +1,354 @@ + + + +4. Basic Definitions + + + + + + + + + +
+ + + + + + + +
4. Basic Definitions
+Prev   Next +
+
+
+
+

+4. Basic Definitions

+

+SLEIGH files must start with all the definitions needed by the rest of +the specification. All definition statements start with the keyword +define and end with a semicolon ‘;’. +

+
+

+4.1. Endianness Definition

+

+The first definition in any SLEIGH specification must be for endianness. Either +

+
+define endian=big;            OR
+define endian=little;
+
+

+This defines how the processor interprets contiguous sequences of +bytes as integers or other values and globally affects values across +all address spaces. It also affects how integer fields +within an instruction are interpreted, (see Section 6.1, “Defining Tokens and Fields”), +although it is possible to override this setting in the rare case that endianness is +different for data versus instruction encoding. +The specification designer generally only needs to worry about +endianness when labeling instruction fields and when defining overlapping registers, +otherwise the specification language hides endianness issues. +

+
+
+

+4.2. Alignment Definition

+

+An alignment definition looks like +

+
+define alignment=integer;
+
+

+This specifies the byte alignment of instructions within their address +space. It defaults to 1 or no alignment. When disassembling an +instruction at a particular, the disassembler checks the alignment of +the address against this value and can opt to flag an unaligned +instruction as an error. +

+
+
+

+4.3. Space Definitions

+

+The definition of an address space looks like +

+
+define space spacename attributes ;
+
+

+The spacename is the name of the new space, +and attributes looks like zero or more of the +following lines: +

+
+type=(ram_space|rom_space|register_space)
+size=integer
+default
+wordsize=integer
+
+

+The only required attribute is size +which specifies the number of bytes needed to address any byte within +the space, for example a 32-bit address space has size 4. +

+

+A space of type ram_space is defined as follows: +

+
    +
  • + It is read/write. +
    • +
  • + It is part of the standard memory map of the processor. +
    • +
  • + It is addressable in the sense that the processor may load +and store from dynamic pointers into the space. +
    • +
+

+

+

+A space of type register_space is +intended to model the processor’s general-purpose registers. In terms +of accessing and manipulating data within the space, SLEIGH and p-code +make no distinction between the +type ram_space or the +type register_space. But there are +still some distinguishing properties of a space labeled +with register_space. +

+
    +
  • + It is read/write. +
    • +
  • + It is not part of the standard memory map of the processor. +
    • +
  • + In terms of GHIDRA, there will not be separate windows for + the space and references into the space will not be stored. +
    • +
  • + Named symbols within the space will have Register objects + associated with them in GHIDRA. +
    • +
  • + It is not addressable. Data-flow + analysis will assume that data within the space cannot be + manipulated indirectly via pointer, so there is no pointer + aliasing. Make sure this is true! +
    • +
+

+

+

+A space of type rom_space has seen +little use so far but is intended to be the same as +a ram_space that is not writable. +

+

+At least one space needs to be labeled with +the default attribute. This should be +the space that the processor accesses with its main address bus. In +terms of the rest of the specification file, this sets the default +space referred to by the ‘*’ operator (see +Section 7.7.1.2, “The '*' Operator”). It also has meaning to +GHIDRA. +

+

+The average 32-bit processor requires only the following two space definitions. +

+
+define space ram type=ram_space size=4 default;
+define space register type=register_space size=4;
+
+

+The wordsize attribute can be used to +specify the size of the memory location referred to with a single +address. If a space has wordsize two, +then each address of the space refers to 16 bits of data, rather than +8 bits. If the space has size two, +then there are still 216 different +addresses, but since each address accesses two bytes, there are twice +as many bytes, 217, in the space. If +the wordsize attribute is not +specified, the size of a memory location defaults to one byte (8 +bits). +

+
+
+

+4.4. Naming Registers

+

+The general purpose registers of the processors can be named with the +following define syntax: +

+
+define spacename offset=integer size=integer stringlist ;
+
+

+A stringlist is either a single string or a white +space separated list of strings in square brackets ‘[’ and ‘]’. A +string of just “_” indicates a skip in the sequence for that +definition. The offset corresponding to that position in the list of +names will not have a varnode defined at it. +

+

+This defines specific varnodes within the indicated address +space. Each name in the list is assigned to a varnode in turn starting +at the indicated offset within the space. Each varnode occupies the +indicated number of bytes in size. There is no restriction on size, +and by reusing the same offset in +different define statements, +overlapping varnodes are allowed. This is most often used to give +registers their standard names but could be used to label any semantic +variable that might need to be accessed globally by the +processor. Overlapping register sequences like the x86 EAX/AX/AL can +be easily modeled with overlapping varnode definitions. +

+

+Here is a typical example of register definition: +

+
+define register offset=0 size=4
+    [EAX ECX EDX EBX ESP EBP ESI EDI ];
+define register offset=0 size=2
+    [AX _ CX _ DX _ BX _ SP _ BP _ SI _ DI];
+define register offset=0 size=1
+    [AL AH _ _ CL CH _ _ DL DH _ _ BL BH ];
+
+

+

+
+
+

+4.5. Bit Range Registers

+

+Many processors define registers that either consist of a single bit +or otherwise don't use an integral number of bytes. A recurring +example in many processors is the status register which is further +subdivided into the overflow and result flags for the arithmetic +instructions. These flags are typically have labels like ZF for the +zero flag or CF for the carry flag and can be considered logical +registers contained within the status register. SLEIGH allows +registers to be defined like this using +the define bitrange statement, but +there are some important caveats with its use. A bit register like +this is problematic for the underlying p-code instructions that SLEIGH +models because the smallest object they can manipulate directly is a +byte. In order to manipulate single bits, p-code must use a +combination of bitwise logical, extension, and truncation +operations. So a register defined as a bit range is not really a +varnode as described in Section 1.2, “Varnodes”, but is +really just a signal to the SLEIGH compiler to fill in the proper +operators to simulate the bit manipulation. Using this feature may +greatly increase the complexity of the compiled specification with +little indication within the specification file itself. +

+
+define register offset=0x180 size=4 [ statusreg ];
+define bitrange zf=statusreg[10,1]
+                cf=statusreg[11,1]
+                sf=statusreg[12,1];
+
+

+

+

+A bit range register must be defined on top of another normal +register. In this example, statusreg is defined +first as a 4 byte register, and the bit registers themselves are built +by the following define bitrange +statement. A single bit register definition consists of an identifier +for the register, followed by ‘=’, then the name of the register +containing the bits, and finally a pair of numbers in square +brackets. The first number indicates the lowest significant bit in the +containing register of the bit range, where bit 0 is the least +significant bit. The second number indicates the number of bits in the +new register. Multiple definitions can be included in a +single define bitrange statement, and +the command is finally terminated with a semicolon. In the example, +three new registers are defined on top +of statusreg, each made up of 1 bit. The new +registers zf, cf, +and sf represent the tenth, eleventh, and twelfth +bit of statusreg respectively. +

+

+The syntax for defining a new bit register is consistent with the +pseudo bit range operator, described in +Section 7.7.1.5, “Bit Range Operator”, and the resulting symbol +is really just a placeholder for this operator. Whenever SLEIGH sees +this symbol it generates p-code precisely as if the designer had used +the bit range operator +instead. Section 7.7.1.5, “Bit Range Operator”, provides some +additional details about how p-code is generated, which apply to the +use of bit range registers. +

+

+If a defined bit range happens to fall on byte boundaries, the new +symbol will in fact be a normal varnode, so +the define bitrange statement can be +used as an alternate syntax for defining overlapping registers. +

+
+
+

+4.6. User-Defined Operations

+

+The specification designer can define new p-code operations using +a define pcodeop statement. This +statement automatically reserves an internal form for the new p-code +operation and associates an identifier with it. This identifier can +then be used in semantic expressions (see +Section 7.7.1.8, “User-Defined Operations”). The following example defines a +new p-code operation arctan. +

+
+define pcodeop arctan;
+
+

+

+

+This construction should be used sparingly. The definition does not +specify how the new operation is supposed to actually manipulate data, +and any analysis routines cannot know what the specification designer +intended. The operation will be treated as a black box. It will hold +its place in syntax trees, and the routines will understand how data +flows into and out of it. But, no other analysis will be possible. +

+

+New operations should be defined only after considering the above +points and the general philosophy of p-code. The designer should have +a detailed description of the new operation in mind, even though this +cannot be put in the specification. If it all possible, the operation +should be atomic, with specific inputs and outputs, and with no +side-effects. The most common use of a new operation is to encapsulate +actions that are too esoteric or too complicated to implement. +

+
+
+
+
+ + + + + + + + + + + +
+Prev   Next +
3. Preprocessing Home 5. Introduction to Symbols
+
+ + diff --git a/sources/GhidraDocs/languages/html/sleigh_definitions.md b/sources/GhidraDocs/languages/html/sleigh_definitions.md new file mode 100644 index 0000000..811fe16 --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_definitions.md @@ -0,0 +1,388 @@ +--- +status: collected +title: 4. Basic Definitions +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_definitions.html +--- + +::: {.navheader} +4. Basic Definitions +::: + +[Prev](sleigh_preprocessing.html)  + +  + + [Next](sleigh_symbols.html) + +------------------------------------------------------------------------ + +::: {.sect1} +::: {.titlepage} +
+ +
+ +[]{#sleigh_definitions}4. Basic Definitions {#basic-definitions .title style="clear: both"} +------------------------------------------- + +
+ +
+::: + +SLEIGH files must start with all the definitions needed by the rest of +the specification. All definition statements start with the keyword +[**define**]{.bold} and end with a semicolon ';'. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_endianness_definition}4.1. Endianness Definition {#endianness-definition .title} + +
+ +
+::: + +The first definition in any SLEIGH specification must be for endianness. +Either + +::: {.informalexample} +``` +define endian=big; OR +define endian=little; +``` +::: + +This defines how the processor interprets contiguous sequences of bytes +as integers or other values and globally affects values across all +address spaces. It also affects how integer fields within an instruction +are interpreted, (see [Section 6.1, "Defining Tokens and +Fields"](sleigh_tokens.html#sleigh_defining_tokens "6.1. Defining Tokens and Fields"){.xref}), +although it is possible to override this setting in the rare case that +endianness is different for data versus instruction encoding. The +specification designer generally only needs to worry about endianness +when labeling instruction fields and when defining overlapping +registers, otherwise the specification language hides endianness issues. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_alignment_definition}4.2. Alignment Definition {#alignment-definition .title} + +
+ +
+::: + +An alignment definition looks like + +::: {.informalexample} +``` +define alignment=integer; +``` +::: + +This specifies the byte alignment of instructions within their address +space. It defaults to 1 or no alignment. When disassembling an +instruction at a particular, the disassembler checks the alignment of +the address against this value and can opt to flag an unaligned +instruction as an error. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_space_definitions}4.3. Space Definitions {#space-definitions .title} + +
+ +
+::: + +The definition of an address space looks like + +::: {.informalexample} +``` +define space spacename attributes ; +``` +::: + +The [*spacename*]{.emphasis} is the name of the new space, and +[*attributes*]{.emphasis} looks like zero or more of the following +lines: + +::: {.informalexample} +``` +type=(ram_space|rom_space|register_space) +size=integer +default +wordsize=integer +``` +::: + +The only required attribute is [**size**]{.bold} which specifies the +number of bytes needed to address any byte within the space, for example +a 32-bit address space has size 4. + +A space of type [**ram\_space**]{.bold} is defined as follows: + +::: {.informalexample} +::: {.itemizedlist} +- It is read/write. +- It is part of the standard memory map of the processor. +- It is addressable in the sense that the processor may load and store + from dynamic pointers into the space. +::: +::: + +A space of type [**register\_space**]{.bold} is intended to model the +processor's general-purpose registers. In terms of accessing and +manipulating data within the space, SLEIGH and p-code make no +distinction between the type [**ram\_space**]{.bold} or the type +[**register\_space**]{.bold}. But there are still some distinguishing +properties of a space labeled with [**register\_space**]{.bold}. + +::: {.informalexample} +::: {.itemizedlist} +- It is read/write. +- It is [*not*]{.emphasis} part of the standard memory map of the + processor. +- In terms of GHIDRA, there will not be separate windows for the space + and references into the space will not be stored. +- Named symbols within the space will have Register objects associated + with them in GHIDRA. +- It is [*not*]{.emphasis} addressable. Data-flow analysis will assume + that data within the space cannot be manipulated indirectly via + pointer, so there is no pointer aliasing. Make sure this is true! +::: +::: + +A space of type [**rom\_space**]{.bold} has seen little use so far but +is intended to be the same as a [**ram\_space**]{.bold} that is not +writable. + +At least one space needs to be labeled with the [**default**]{.bold} +attribute. This should be the space that the processor accesses with its +main address bus. In terms of the rest of the specification file, this +sets the default space referred to by the '\*' operator (see +[Section 7.7.1.2, "The \'\*\' +Operator"](sleigh_constructors.html#sleigh_star_operator "7.7.1.2. The '*' Operator"){.xref}). +It also has meaning to GHIDRA. + +The average 32-bit processor requires only the following two space +definitions. + +::: {.informalexample} +``` +define space ram type=ram_space size=4 default; +define space register type=register_space size=4; +``` +::: + +The [**wordsize**]{.bold} attribute can be used to specify the size of +the memory location referred to with a single address. If a space has +[**wordsize**]{.bold} two, then each address of the space refers to 16 +bits of data, rather than 8 bits. If the space has [**size**]{.bold} +two, then there are still 2^16^ different addresses, but since each +address accesses two bytes, there are twice as many bytes, 2^17^, in the +space. If the [**wordsize**]{.bold} attribute is not specified, the size +of a memory location defaults to one byte (8 bits). +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_naming_registers}4.4. Naming Registers {#naming-registers .title} + +
+ +
+::: + +The general purpose registers of the processors can be named with the +following define syntax: + +::: {.informalexample} +``` +define spacename offset=integer size=integer stringlist ; +``` +::: + +A [*stringlist*]{.emphasis} is either a single string or a white space +separated list of strings in square brackets '\[' and '\]'. A string of +just "\_" indicates a skip in the sequence for that definition. The +offset corresponding to that position in the list of names will not have +a varnode defined at it. + +This defines specific varnodes within the indicated address space. Each +name in the list is assigned to a varnode in turn starting at the +indicated offset within the space. Each varnode occupies the indicated +number of bytes in size. There is no restriction on size, and by reusing +the same offset in different [**define**]{.bold} statements, overlapping +varnodes are allowed. This is most often used to give registers their +standard names but could be used to label any semantic variable that +might need to be accessed globally by the processor. Overlapping +register sequences like the x86 EAX/AX/AL can be easily modeled with +overlapping varnode definitions. + +Here is a typical example of register definition: + +::: {.informalexample} +``` +define register offset=0 size=4 + [EAX ECX EDX EBX ESP EBP ESI EDI ]; +define register offset=0 size=2 + [AX _ CX _ DX _ BX _ SP _ BP _ SI _ DI]; +define register offset=0 size=1 + [AL AH _ _ CL CH _ _ DL DH _ _ BL BH ]; +``` +::: +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_bitrange_registers}4.5. Bit Range Registers {#bit-range-registers .title} + +
+ +
+::: + +Many processors define registers that either consist of a single bit or +otherwise don\'t use an integral number of bytes. A recurring example in +many processors is the status register which is further subdivided into +the overflow and result flags for the arithmetic instructions. These +flags are typically have labels like ZF for the zero flag or CF for the +carry flag and can be considered logical registers contained within the +status register. SLEIGH allows registers to be defined like this using +the [**define bitrange**]{.bold} statement, but there are some important +caveats with its use. A bit register like this is problematic for the +underlying p-code instructions that SLEIGH models because the smallest +object they can manipulate directly is a byte. In order to manipulate +single bits, p-code must use a combination of bitwise logical, +extension, and truncation operations. So a register defined as a bit +range is not really a varnode as described in [Section 1.2, +"Varnodes"](sleigh.html#sleigh_varnodes "1.2. Varnodes"){.xref}, but is +really just a signal to the SLEIGH compiler to fill in the proper +operators to simulate the bit manipulation. Using this feature may +greatly increase the complexity of the compiled specification with +little indication within the specification file itself. + +::: {.informalexample} +``` +define register offset=0x180 size=4 [ statusreg ]; +define bitrange zf=statusreg[10,1] + cf=statusreg[11,1] + sf=statusreg[12,1]; +``` +::: + +A bit range register must be defined on top of another normal register. +In this example, [*statusreg*]{.emphasis} is defined first as a 4 byte +register, and the bit registers themselves are built by the following +[**define bitrange**]{.bold} statement. A single bit register definition +consists of an identifier for the register, followed by '=', then the +name of the register containing the bits, and finally a pair of numbers +in square brackets. The first number indicates the lowest significant +bit in the containing register of the bit range, where bit 0 is the +least significant bit. The second number indicates the number of bits in +the new register. Multiple definitions can be included in a single +[**define bitrange**]{.bold} statement, and the command is finally +terminated with a semicolon. In the example, three new registers are +defined on top of [*statusreg*]{.emphasis}, each made up of 1 bit. The +new registers [*zf*]{.emphasis}, [*cf*]{.emphasis}, and +[*sf*]{.emphasis} represent the tenth, eleventh, and twelfth bit of +[*statusreg*]{.emphasis} respectively. + +The syntax for defining a new bit register is consistent with the pseudo +bit range operator, described in [Section 7.7.1.5, "Bit Range +Operator"](sleigh_constructors.html#sleigh_bitrange_operator "7.7.1.5. Bit Range Operator"){.xref}, +and the resulting symbol is really just a placeholder for this operator. +Whenever SLEIGH sees this symbol it generates p-code precisely as if the +designer had used the bit range operator instead. [Section 7.7.1.5, "Bit +Range +Operator"](sleigh_constructors.html#sleigh_bitrange_operator "7.7.1.5. Bit Range Operator"){.xref}, +provides some additional details about how p-code is generated, which +apply to the use of bit range registers. + +If a defined bit range happens to fall on byte boundaries, the new +symbol will in fact be a normal varnode, so the [**define +bitrange**]{.bold} statement can be used as an alternate syntax for +defining overlapping registers. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_userdefined_operations}4.6. User-Defined Operations {#user-defined-operations .title} + +
+ +
+::: + +The specification designer can define new p-code operations using a +[**define pcodeop**]{.bold} statement. This statement automatically +reserves an internal form for the new p-code operation and associates an +identifier with it. This identifier can then be used in semantic +expressions (see [Section 7.7.1.8, "User-Defined +Operations"](sleigh_constructors.html#sleigh_userdef_op "7.7.1.8. User-Defined Operations"){.xref}). +The following example defines a new p-code operation +[*arctan*]{.emphasis}. + +::: {.informalexample} +``` +define pcodeop arctan; +``` +::: + +This construction should be used sparingly. The definition does not +specify how the new operation is supposed to actually manipulate data, +and any analysis routines cannot know what the specification designer +intended. The operation will be treated as a black box. It will hold its +place in syntax trees, and the routines will understand how data flows +into and out of it. But, no other analysis will be possible. + +New operations should be defined only after considering the above points +and the general philosophy of p-code. The designer should have a +detailed description of the new operation in mind, even though this +cannot be put in the specification. If it all possible, the operation +should be atomic, with specific inputs and outputs, and with no +side-effects. The most common use of a new operation is to encapsulate +actions that are too esoteric or too complicated to implement. +::: +::: + +::: {.navfooter} + +------------------------------------------------------------------------ + + ------------------------------------ --------------------- ------------------------------ + [Prev](sleigh_preprocessing.html)     [Next](sleigh_symbols.html) + 3. Preprocessing  [Home](sleigh.html)  5. Introduction to Symbols + ------------------------------------ --------------------- ------------------------------ +::: diff --git a/sources/GhidraDocs/languages/html/sleigh_layout.html b/sources/GhidraDocs/languages/html/sleigh_layout.html new file mode 100644 index 0000000..2a1497c --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_layout.html @@ -0,0 +1,122 @@ + + + +2. Basic Specification Layout + + + + + + + + + +
+ + + + + + + +
2. Basic Specification Layout
+Prev   Next +
+
+
+
+

+2. Basic Specification Layout

+

+A SLEIGH specification is typically contained in a single file, +although see Section 3.1, “Including Files”. The file must +follow a specific format as parsed by the SLEIGH compiler. In this +section, we list the basic formatting rules for this file as enforced +by the compiler. +

+
+

+2.1. Comments

+

+Comments start with the ‘#’ character and continue to the end of the +line. Comments can appear anywhere except the display section of a +constructor (see Section 7.3, “The Display Section”) where the ‘#’ character will be +interpreted as something that should be printed in disassembly. +

+
+
+

+2.2. Identifiers

+

+Identifiers are made up of letters a-z, capitals A-Z, digits 0-9 and +the characters ‘.’ and ‘_’. An identifier can use these characters in +any order and for any length, but it must not start with a digit. +

+
+
+

+2.3. Strings

+

+String literals can be used, when specifying names and when specifying +how disassembly should be printed, so that special characters are +treated as literals. Strings are surrounded by the double quote +character ‘”’ and all characters in between lose their special +meaning. +

+
+
+

+2.4. Integers

+

+Integers are specified either in a decimal format or in a standard +C-style hexadecimal format by prepending the +number with “0x”. Alternately, a binary representation of an integer +can be given by prepending the string of '0' and '1' characters with "0b". +

+
+1006789
+0xF5CC5
+0xf5cc5
+0b11110101110011000101
+
+

+Numbers are treated as unsigned +except when used in patterns where they are treated as signed (see +Section 7.4, “The Bit Pattern Section”). The number of bytes used to +encode the integer when specifying the semantics of an instruction is +inferred from other parts of the syntax (see +Section 7.3, “The Display Section”). Otherwise, integers should +be thought of as having arbitrary precision. Currently, SLEIGH stores +integers internally with 64 bits of precision. +

+
+
+

+2.5. White Space

+

+White space characters include space, tab, line-feed, vertical +line-feed, and carriage-return (‘ ‘, ‘\t’, ‘\r’, ‘\v’, +‘\n’). Variations in spacing have no effect on the parsing of the file +except in string literals. +

+
+
+
+
+ + + + + + + + + + + +
+Prev   Next +
SLEIGH Home 3. Preprocessing
+
+ + diff --git a/sources/GhidraDocs/languages/html/sleigh_layout.md b/sources/GhidraDocs/languages/html/sleigh_layout.md new file mode 100644 index 0000000..0f4a51d --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_layout.md @@ -0,0 +1,167 @@ +--- +status: collected +title: 2. Basic Specification Layout +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_layout.html +--- + +::: {.navheader} +2. Basic Specification Layout +::: + +[Prev](sleigh.html)  + +  + + [Next](sleigh_preprocessing.html) + +------------------------------------------------------------------------ + +::: {.sect1} +::: {.titlepage} +
+ +
+ +[]{#sleigh_layout}2. Basic Specification Layout {#basic-specification-layout .title style="clear: both"} +----------------------------------------------- + +
+ +
+::: + +A SLEIGH specification is typically contained in a single file, although +see [Section 3.1, "Including +Files"](sleigh_preprocessing.html#sleigh_including_files "3.1. Including Files"){.xref}. +The file must follow a specific format as parsed by the SLEIGH compiler. +In this section, we list the basic formatting rules for this file as +enforced by the compiler. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_comments}2.1. Comments {#comments .title} + +
+ +
+::: + +Comments start with the '\#' character and continue to the end of the +line. Comments can appear anywhere except the [*display +section*]{.emphasis} of a constructor (see [Section 7.3, "The Display +Section"](sleigh_constructors.html#sleigh_display_section "7.3. The Display Section"){.xref}) +where the '\#' character will be interpreted as something that should be +printed in disassembly. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_identifiers}2.2. Identifiers {#identifiers .title} + +
+ +
+::: + +Identifiers are made up of letters a-z, capitals A-Z, digits 0-9 and the +characters '.' and '\_'. An identifier can use these characters in any +order and for any length, but it must not start with a digit. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_strings}2.3. Strings {#strings .title} + +
+ +
+::: + +String literals can be used, when specifying names and when specifying +how disassembly should be printed, so that special characters are +treated as literals. Strings are surrounded by the double quote +character '"' and all characters in between lose their special meaning. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_integers}2.4. Integers {#integers .title} + +
+ +
+::: + +Integers are specified either in a decimal format or in a standard +[*C-style*]{.emphasis} hexadecimal format by prepending the number with +"0x". Alternately, a binary representation of an integer can be given by +prepending the string of \'0\' and \'1\' characters with \"0b\". + +::: {.informalexample} +``` +1006789 +0xF5CC5 +0xf5cc5 +0b11110101110011000101 +``` +::: + +Numbers are treated as unsigned except when used in patterns where they +are treated as signed (see [Section 7.4, "The Bit Pattern +Section"](sleigh_constructors.html#sleigh_bit_pattern "7.4. The Bit Pattern Section"){.xref}). +The number of bytes used to encode the integer when specifying the +semantics of an instruction is inferred from other parts of the syntax +(see [Section 7.3, "The Display +Section"](sleigh_constructors.html#sleigh_display_section "7.3. The Display Section"){.xref}). +Otherwise, integers should be thought of as having arbitrary precision. +Currently, SLEIGH stores integers internally with 64 bits of precision. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_white_space}2.5. White Space {#white-space .title} + +
+ +
+::: + +White space characters include space, tab, line-feed, vertical +line-feed, and carriage-return (' ', '\\t', '\\r', '\\v', '\\n'). +Variations in spacing have no effect on the parsing of the file except +in string literals. +::: +::: + +::: {.navfooter} + +------------------------------------------------------------------------ + + ---------------------- --------------------- ------------------------------------ + [Prev](sleigh.html)     [Next](sleigh_preprocessing.html) + SLEIGH  [Home](sleigh.html)  3. Preprocessing + ---------------------- --------------------- ------------------------------------ +::: diff --git a/sources/GhidraDocs/languages/html/sleigh_preprocessing.html b/sources/GhidraDocs/languages/html/sleigh_preprocessing.html new file mode 100644 index 0000000..3006f08 --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_preprocessing.html @@ -0,0 +1,214 @@ + + + +3. Preprocessing + + + + + + + + + +
+ + + + + + + +
3. Preprocessing
+Prev   Next +
+
+
+
+

+3. Preprocessing

+

+SLEIGH provides support for simple file inclusion, macros, and other +basic preprocessing functions. These are all invoked with directives +that start with the ‘@’ character, which must be the first character +in the line. +

+
+

+3.1. Including Files

+

+In general a single SLEIGH specification is contained in a single +file, and the compiler is invoked on one file at a time. Multiple +files can be put together for one specification by using +the @include directive. This must +appear at the beginning of the line and is followed by the path name +of the file to be included, enclosed in double quotes. +

+
@include "example.slaspec"
+

+Parsing proceeds as if the entire line is replaced with the contents +of the indicated file. Multiple inclusions are possible, and the +included files can have their +own @include directives. +

+
+
+

+3.2. Preprocessor Macros

+

+SLEIGH allows simple (unparameterized) macro definitions and +expansions. A macro definition occurs on one line and starts with +the @define directive. This is +followed by an identifier for the macro and then a string to which the +macro should expand. The string must either be a proper identifier +itself or surrounded with double quotes. The macro can then be +expanded with typical “$(identifier)” syntax at any other point in the +specification following the definition. +

+
+@define ENDIAN "big"
+  ...
+define endian=$(ENDIAN);
+
+

+This example defines a macro identified as ENDIAN +with the string “big”, and then expands the macro in a later SLEIGH +statement. Macro definitions can also be made from the command line +and in the “.spec” file, allowing multiple specification variations to +be derived from one file. SLEIGH also has +an @undef directive which removes the +definition of a macro from that point on in the file. +

+
@undef ENDIAN
+

+

+
+
+

+3.3. Conditional Compilation

+

+SLEIGH supports several directives that allow conditional inclusion of +parts of a specification, based on the existence of a macro, or its +value. The lines of the specification to be conditionally included are +bounded by one of the @if... +directives described below and at the bottom by +the @endif directive. If the +condition described by the @if... +directive is true, the bounded lines are evaluated as part of the +specification, otherwise they are skipped. Nesting of these directives +is allowed: a +second @if... @endif +pair can occur inside an initial @if +and @endif. +

+
+

+3.3.1. @ifdef and @ifndef

+

+The @ifdef directive is followed by a +macro identifier and evaluates to true if the macro is defined. +The @ifndef directive is similar +except it evaluates to true if the macro identifier +is not defined. +

+
+@ifdef ENDIAN
+define endian=$(ENDIAN);
+@else
+define endian=little;
+@endif
+
+

+This directive can only take a single identifier as an argument, any +other form is flagged as an error. For logically combining a test of +whether a macro is defined with other tests, use +the defined operator in +an @if +or @elif directive (See below). +

+
+
+

+3.3.2. @if

+

+The @if directive is followed by a +boolean expression with macros as the variables and strings as the +constants. Comparisons between macros and strings are currently +limited to string equality or inequality. But individual comparisons +can be combined arbitrarily using parentheses and the boolean +operators ‘&&’, ‘||’, and ‘^^’. These represent a logical +and, a logical or, and +a logical exclusive-or operation respectively. It +is possible to test whether a particular macro is defined within the +boolean expression for an @if +directive, by using the defined +operator. This exists as a keyword and a functional operator only +within a preprocessor boolean +expression. The defined keyword takes +as argument a macro identifier, and it evaluates to true if the macro +is defined. +

+
+@if defined(X_EXTENSION) || (VERSION == "5")
+  ...
+@endif
+
+

+

+
+
+

+3.3.3. @else and @elif

+

+An @else directive splits the lines +bounded by an @if directive and +an @endif directive into two +parts. The first part is included in the processing if the +initial @if directive evaluates to +true, otherwise the second part is included. +

+

+The @elif directive splits the +bounded lines up as with @else, but +the second part is included only if the +previous @if was false and the +condition specified in the @elif +itself is true. Between one @if +and @endif pair, there can be +multiple @elif directives, but only +one @else, which must occur after all +the @elif directives. +

+
+@if PROCESSOR == “mips”
+@ define ENDIAN “big”
+@elif ((PROCESSOR==”x86”)&&(OS!=”win”))
+@ define ENDIAN “little”
+@else
+@ define ENDIAN “unknown”
+@endif
+
+

+

+
+
+
+
+
+ + + + + + + + + + + +
+Prev   Next +
2. Basic Specification Layout Home 4. Basic Definitions
+
+ + diff --git a/sources/GhidraDocs/languages/html/sleigh_preprocessing.md b/sources/GhidraDocs/languages/html/sleigh_preprocessing.md new file mode 100644 index 0000000..6354e03 --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_preprocessing.md @@ -0,0 +1,255 @@ +--- +status: collected +title: 3. Preprocessing +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_preprocessing.html +--- + +::: {.navheader} +3. Preprocessing +::: + +[Prev](sleigh_layout.html)  + +  + + [Next](sleigh_definitions.html) + +------------------------------------------------------------------------ + +::: {.sect1} +::: {.titlepage} +
+ +
+ +[]{#sleigh_preprocessing}3. Preprocessing {#preprocessing .title style="clear: both"} +----------------------------------------- + +
+ +
+::: + +SLEIGH provides support for simple file inclusion, macros, and other +basic preprocessing functions. These are all invoked with directives +that start with the '@' character, which must be the first character in +the line. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_including_files}3.1. Including Files {#including-files .title} + +
+ +
+::: + +In general a single SLEIGH specification is contained in a single file, +and the compiler is invoked on one file at a time. Multiple files can be +put together for one specification by using the [**\@include**]{.bold} +directive. This must appear at the beginning of the line and is followed +by the path name of the file to be included, enclosed in double quotes. + +::: {.informalexample} +`@include "example.slaspec"`{.code} +::: + +Parsing proceeds as if the entire line is replaced with the contents of +the indicated file. Multiple inclusions are possible, and the included +files can have their own [**\@include**]{.bold} directives. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_preprocessor_macros}3.2. Preprocessor Macros {#preprocessor-macros .title} + +
+ +
+::: + +SLEIGH allows simple (unparameterized) macro definitions and expansions. +A macro definition occurs on one line and starts with the +[**\@define**]{.bold} directive. This is followed by an identifier for +the macro and then a string to which the macro should expand. The string +must either be a proper identifier itself or surrounded with double +quotes. The macro can then be expanded with typical "\$(identifier)" +syntax at any other point in the specification following the definition. + +::: {.informalexample} +``` +@define ENDIAN "big" + ... +define endian=$(ENDIAN); +``` +::: + +This example defines a macro identified as [*ENDIAN*]{.emphasis} with +the string "big", and then expands the macro in a later SLEIGH +statement. Macro definitions can also be made from the command line and +in the ".spec" file, allowing multiple specification variations to be +derived from one file. SLEIGH also has an [**\@undef**]{.bold} directive +which removes the definition of a macro from that point on in the file. + +::: {.informalexample} +`@undef ENDIAN`{.code} +::: +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_conditional_compilation}3.3. Conditional Compilation {#conditional-compilation .title} + +
+ +
+::: + +SLEIGH supports several directives that allow conditional inclusion of +parts of a specification, based on the existence of a macro, or its +value. The lines of the specification to be conditionally included are +bounded by one of the [**\@if\...**]{.bold} directives described below +and at the bottom by the [**\@endif**]{.bold} directive. If the +condition described by the [**\@if\...**]{.bold} directive is true, the +bounded lines are evaluated as part of the specification, otherwise they +are skipped. Nesting of these directives is allowed: a second +[**\@if\...**]{.bold} [**\@endif**]{.bold} pair can occur inside an +initial [**\@if**]{.bold} and [**\@endif**]{.bold}. + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_ifdef}3.3.1. \@ifdef and \@ifndef {#ifdef-and-ifndef .title} + +
+ +
+::: + +The [**\@ifdef**]{.bold} directive is followed by a macro identifier and +evaluates to true if the macro is defined. The [**\@ifndef**]{.bold} +directive is similar except it evaluates to true if the macro identifier +is [*not*]{.emphasis} defined. + +::: {.informalexample} +``` +@ifdef ENDIAN +define endian=$(ENDIAN); +@else +define endian=little; +@endif +``` +::: + +This directive can only take a single identifier as an argument, any +other form is flagged as an error. For logically combining a test of +whether a macro is defined with other tests, use the +[**defined**]{.bold} operator in an [**\@if**]{.bold} or +[**\@elif**]{.bold} directive (See below). +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_if}3.3.2. \@if {#if .title} + +
+ +
+::: + +The [**\@if**]{.bold} directive is followed by a boolean expression with +macros as the variables and strings as the constants. Comparisons +between macros and strings are currently limited to string equality or +inequality. But individual comparisons can be combined arbitrarily using +parentheses and the boolean operators '&&', '\|\|', and '\^\^'. These +represent a [*logical and*]{.emphasis}, a [*logical or*]{.emphasis}, and +a [*logical exclusive-or*]{.emphasis} operation respectively. It is +possible to test whether a particular macro is defined within the +boolean expression for an [**\@if**]{.bold} directive, by using the +[**defined**]{.bold} operator. This exists as a keyword and a functional +operator only within a preprocessor boolean expression. The +[**defined**]{.bold} keyword takes as argument a macro identifier, and +it evaluates to true if the macro is defined. + +::: {.informalexample} +``` +@if defined(X_EXTENSION) || (VERSION == "5") + ... +@endif +``` +::: +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_else}3.3.3. \@else and \@elif {#else-and-elif .title} + +
+ +
+::: + +An [**\@else**]{.bold} directive splits the lines bounded by an +[**\@if**]{.bold} directive and an [**\@endif**]{.bold} directive into +two parts. The first part is included in the processing if the initial +[**\@if**]{.bold} directive evaluates to true, otherwise the second part +is included. + +The [**\@elif**]{.bold} directive splits the bounded lines up as with +[**\@else**]{.bold}, but the second part is included only if the +previous [**\@if**]{.bold} was false and the condition specified in the +[**\@elif**]{.bold} itself is true. Between one [**\@if**]{.bold} and +[**\@endif**]{.bold} pair, there can be multiple [**\@elif**]{.bold} +directives, but only one [**\@else**]{.bold}, which must occur after all +the [**\@elif**]{.bold} directives. + +::: {.informalexample} +``` +@if PROCESSOR == “mips” +@ define ENDIAN “big” +@elif ((PROCESSOR==”x86”)&&(OS!=”win”)) +@ define ENDIAN “little” +@else +@ define ENDIAN “unknown” +@endif +``` +::: +::: +::: +::: + +::: {.navfooter} + +------------------------------------------------------------------------ + + -------------------------------- --------------------- ---------------------------------- + [Prev](sleigh_layout.html)     [Next](sleigh_definitions.html) + 2. Basic Specification Layout  [Home](sleigh.html)  4. Basic Definitions + -------------------------------- --------------------- ---------------------------------- +::: diff --git a/sources/GhidraDocs/languages/html/sleigh_ref.html b/sources/GhidraDocs/languages/html/sleigh_ref.html new file mode 100644 index 0000000..b21fc5f --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_ref.html @@ -0,0 +1,607 @@ + + + +9. P-code Tables + + + + + + + + +
+ + + + + + + +
9. P-code Tables
+Prev   
+
+
+
+

+9. P-code Tables

+

+We list all the p-code operations by name along with the syntax for +invoking them within the semantic section of a constructor definition +(see Section 7.7, “The Semantic Section”), and with a +description of the operator. The terms v0 +and v1 represent identifiers of individual input +varnodes to the operation. In terms of syntax, v0 +and v1 can be replaced with any semantic +expression, in which case the final output varnode of the expression +becomes the input to the operator. The term spc +represents the identifier of an address space, which is a special +input to the LOAD and STORE +operations. The identifier of any address space can be used. +

+

+This table lists all the operators for building semantic +expressions. The operators are listed in order of precedence, highest +to lowest. +

+
+
+

Table 5. Semantic Expression Operators and Syntax

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
P-code NameSLEIGH SyntaxDescription
SUBPIECE +
+ + + + + + + +
v0:2
v0(2)
+
+ 		The least significant n bytes of v0. + Truncate least significant n bytes of + v0. Most significant bytes may be + truncated depending on result size. +
POPCOUNTpopcount(v0)Count the number of 1 bits in v0. +
LZCOUNTlzcount(v0)Count the number of leading 0 bits in v0. +
(simulated)v0[6,1]Extract a range of bits from v0, + putting result in a minimum number of + bytes. The bracketed numbers give + respectively, the least significant + bit and the number of bits in the + range. +
LOAD +
+ + + + + + + + + + + + + +
* v1
*[spc]v1
*:2 v1
*[spc]:2 v1
+
+ 		Dereference v1 as pointer into + default space. Optionally specify + space to load from and size of data + in bytes. +
BOOL_NEGATE!v0Negation of boolean value v0.
INT_NEGATE~v0Bitwise negation of v0.
INT_2COMP-v0Twos complement of v0.
FLOAT_NEGf- v0Additive inverse of v0 as a floating-point number.
INT_MULTv0 * v1Integer multiplication of v0 and v1.
INT_DIVv0 / v1Unsigned division of v0 by v1.
INT_SDIVv0 s/ v1Signed division of v0 by v1.
INT_REMv0 % v1Unsigned remainder of v0 modulo v1.
INT_SREMv0 s% v1Signed remainder of v0 modulo v1.
FLOAT_DIVv0 f/ v1Division of v0 by v1 as floating-point numbers.
FLOAT_MULTv0 f* v1Multiplication of v0 and v1 as floating-point numbers.
INT_ADDv0 + v1Addition of v0 and v1 as integers.
INT_SUBv0 - v1Subtraction of v1 from v0 as integers.
FLOAT_ADDv0 f+ v1Addition of v0 and v1 as floating-point numbers.
FLOAT_SUBv0 f- v1Subtraction of v1 from v0 as floating-point numbers.
INT_LEFTv0 << v1Left shift of v0 by v1 bits.
INT_RIGHTv0 >> v1Unsigned (logical) right shift of v0 by v1 bits.
INT_SRIGHTv0 s>> v1Signed (arithmetic) right shift of v0 by b1 bits.
INT_SLESS +
+ + + + + + + +
v0 s< v1
v1 s> v0
+
+ 		True if v0 is less than v1 as a signed integer.
INT_SLESSEQUAL +
+ + + + + + + +
v0 s<= v1
v1 s>= v0
+
+ 		True if v0 is less than or equal to v1 as a signed integer.
INT_LESS +
+ + + + + + + +
v0 < v1
v1 > v0
+
+ 		True if v0 is less than v1 as an unsigned integer.
INT_LESSEQUAL +
+ + + + + + + +
v0 <= v1
v1 >= v0
+
+ 		True if v0 is less than or equal to v1 as an unsigned integer.
FLOAT_LESS +
+ + + + + + + +
v0 f< v1
v1 f> v0
+
+ 		True if v0 is less than v1 viewed as floating-point numbers.
FLOAT_LESSEQUAL +
+ + + + + + + +
v0 f<= v1
v1 f>= v0
+
+ 		True if v0 is less than or equal to v1 as floating-point.
INT_EQUALv0 == v1True if v0 equals v1.
INT_NOTEQUALv0 != v1True if v0 does not equal v1.
FLOAT_EQUALv0 f== v1True if v0 equals v1 viewed as floating-point numbers.
FLOAT_NOTEQUALv0 f!= v1True if v0 does not equal v1 viewed as floating-point numbers.
INT_ANDv0 & v1Bitwise Logical And of v0 with v1.
INT_XORv0 ^ v1Bitwise Exclusive Or of v0 with v1.
INT_ORv0 | v1Bitwise Logical Or of v0 with v1.
BOOL_XORv0 ^^ v1Exclusive-Or of booleans v0 and v1.
BOOL_ANDv0 && v1Logical-And of booleans v0 and v1.
BOOL_ORv0 || v1Logical-Or of booleans v0 and v1.
INT_ZEXTzext(v0)Zero extension of v0.
INT_SEXTsext(v0)Sign extension of v0.
INT_CARRYcarry(v0,v1)True if adding v0 and v1 would produce an unsigned carry.
INT_SCARRYscarry(v0,v1)True if adding v0 and v1 would produce a signed carry.
INT_SBORROWsborrow(v0,v1)True if subtracting v1 from v0 would produce a signed borrow.
FLOAT_NANnan(v0)True if v0 is not a valid floating-point number (NaN).
FLOAT_ABSabs(v0)Absolute value of v0 as floating point number.
FLOAT_SQRTsqrt(v0)Square root of v0 as floating-point number.
INT2FLOATint2float(v0)Floating-point representation of v0 viewed as an integer.
FLOAT2FLOATfloat2float(v0)Copy of floating-point number v0 with more or less precision.
TRUNCtrunc(v0)Signed integer obtained by truncating v0.
FLOAT_CEILceil(v0)Nearest integer greater than v0.
FLOAT_FLOORfloor(v0)Nearest integer less than v0.
FLOAT_ROUNDround(v0)Nearest integer to v0.
CPOOLREFcpool(v0,...)Access value from the constant pool.
NEWnewobject(v0)Allocate object of type described by v0.
USER_DEFINEDident(v0,...)User defined operator ident, with functional syntax.
+
+
+
+

+

+

+The following table lists the basic forms of a semantic statement. +

+
+
+

Table 6. Basic Statements and Associated Operators

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
P-code NameSLEIGH SyntaxDescription
COPY, otherv0 = v1;Assignment of v1 to v0.
STORE +
+ + + + + + + + + + + + + +
*v0 = v1
*[spc]v0 = v1;
*:4 v0 = v1;
*[spc]:4 v0 = v1;
+
+ 		Store v1 in default space using v0 + As pointer. Optionally specify space + to store in and size of data in + bytes. +
USER_DEFINEDident(v0,...);Invoke user-defined operation ident as a standalone statement, with no output.
v0[8,1] = v1;Fill a bit range within v0 using v1, leaving the rest of v0 unchanged.
ident(v0,...);Invoke the macro named ident.
build ident;Execute the p-code to build operand ident.
delayslot(1);Execute the p-code for the following instruction.
+
+
+
+

+

+

+The following table lists the branching operations and the statements which invoke them. +

+
+
+

Table 7. Branching Statements

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
P-code NameSLEIGH SyntaxDescription
BRANCHgoto v0;Branch execution to address of v0.
CBRANCHif (v0) goto v1;Branch execution to address of v1 if v0 equals 1 (true).
BRANCHINDgoto [v0];Branch execution to v0 viewed as an offset in current space.
CALLcall v0;Branch execution to address of v0. Hint that branch is subroutine call.
CALLINDcall [v0];Branch execution to v0 viewed as an offset in current space. Hint that branch is subroutine call.
RETURNreturn [v0];Branch execution to v0 viewed as an offset in current space. Hint that branch is a subroutine return.
+
+
+
+

+

+
+
+
+ + + + + + + + + + + +
+Prev   
8. Using Context Home 
+
+ + diff --git a/sources/GhidraDocs/languages/html/sleigh_ref.md b/sources/GhidraDocs/languages/html/sleigh_ref.md new file mode 100644 index 0000000..1ccac10 --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_ref.md @@ -0,0 +1,450 @@ +--- +status: collected +title: 9. P-code Tables +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_ref.html +--- + +::: {.navheader} +9. P-code Tables +::: + +[Prev](sleigh_context.html)  + +  + +  + +------------------------------------------------------------------------ + +::: {.sect1} +::: {.titlepage} +
+ +
+ +[]{#sleigh_ref}9. P-code Tables {#p-code-tables .title style="clear: both"} +------------------------------- + +
+ +
+::: + +We list all the p-code operations by name along with the syntax for +invoking them within the semantic section of a constructor definition +(see [Section 7.7, "The Semantic +Section"](sleigh_constructors.html#sleigh_semantic_section "7.7. The Semantic Section"){.xref}), +and with a description of the operator. The terms [*v0*]{.emphasis} and +[*v1*]{.emphasis} represent identifiers of individual input varnodes to +the operation. In terms of syntax, [*v0*]{.emphasis} and +[*v1*]{.emphasis} can be replaced with any semantic expression, in which +case the final output varnode of the expression becomes the input to the +operator. The term [*spc*]{.emphasis} represents the identifier of an +address space, which is a special input to the [*LOAD*]{.emphasis} and +[*STORE*]{.emphasis} operations. The identifier of any address space can +be used. + +This table lists all the operators for building semantic expressions. +The operators are listed in order of precedence, highest to lowest. + +::: {.informalexample} +::: {.table} +[]{#syntaxref.htmltable} + +**Table 5. Semantic Expression Operators and Syntax** + +::: {.table-contents} ++-----------------+-----------------+-----------------------------------+ +| [**P-code | [**SLEIGH | [**Description**]{.bold} | +| Name**]{.bold} | S | | +| | yntax**]{.bold} | | ++=================+=================+===================================+ +| `S | ::: { | The least significant n bytes of | +| UBPIECE`{.code} | .informaltable} | v0. Truncate least significant n | +| | []{#subpiec | bytes of v0. Most significant | +| | eref.htmltable} | bytes may be truncated depending | +| | | on result size. | +| | - | | +| | --------------- | | +| | `v0:2`{.code} | | +| | | | +| | `v0(2)`{.code} | | +| | - | | +| | --------------- | | +| | ::: | | ++-----------------+-----------------+-----------------------------------+ +| `P | `popco | Count the number of 1 bits in v0. | +| OPCOUNT`{.code} | unt(v0)`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| ` | `lzco | Count the number of leading 0 | +| LZCOUNT`{.code} | unt(v0)`{.code} | bits in v0. | ++-----------------+-----------------+-----------------------------------+ +| `(sim | ` | Extract a range of bits from v0, | +| ulated)`{.code} | v0[6,1]`{.code} | putting result in a minimum | +| | | number of bytes. The bracketed | +| | | numbers give respectively, the | +| | | least significant bit and the | +| | | number of bits in the range. | ++-----------------+-----------------+-----------------------------------+ +| `LOAD`{.code} | ::: { | Dereference v1 as pointer into | +| | .informaltable} | default space. Optionally specify | +| | []{#loa | space to load from and size of | +| | dref.htmltable} | data in bytes. | +| | | | +| | ------- | | +| | --------------- | | +| | `* v1`{.code} | | +| | `* | | +| | [spc]v1`{.code} | | +| | | | +| | `*:2 v1`{.code} | | +| | `*[sp | | +| | c]:2 v1`{.code} | | +| | ------- | | +| | --------------- | | +| | ::: | | ++-----------------+-----------------+-----------------------------------+ +| `BOOL | `!v0`{.code} | Negation of boolean value v0. | +| _NEGATE`{.code} | | | ++-----------------+-----------------+-----------------------------------+ +| `INT | `~v0`{.code} | Bitwise negation of v0. | +| _NEGATE`{.code} | | | ++-----------------+-----------------+-----------------------------------+ +| `IN | `-v0`{.code} | Twos complement of v0. | +| T_2COMP`{.code} | | | ++-----------------+-----------------+-----------------------------------+ +| `FL | `f- v0`{.code} | Additive inverse of v0 as a | +| OAT_NEG`{.code} | | floating-point number. | ++-----------------+-----------------+-----------------------------------+ +| `I | ` | Integer multiplication of v0 and | +| NT_MULT`{.code} | v0 * v1`{.code} | v1. | ++-----------------+-----------------+-----------------------------------+ +| ` | ` | Unsigned division of v0 by v1. | +| INT_DIV`{.code} | v0 / v1`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `I | `v | Signed division of v0 by v1. | +| NT_SDIV`{.code} | 0 s/ v1`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| ` | ` | Unsigned remainder of v0 modulo | +| INT_REM`{.code} | v0 % v1`{.code} | v1. | ++-----------------+-----------------+-----------------------------------+ +| `I | `v | Signed remainder of v0 modulo v1. | +| NT_SREM`{.code} | 0 s% v1`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `FL | `v | Division of v0 by v1 as | +| OAT_DIV`{.code} | 0 f/ v1`{.code} | floating-point numbers. | ++-----------------+-----------------+-----------------------------------+ +| `FLO | `v | Multiplication of v0 and v1 as | +| AT_MULT`{.code} | 0 f* v1`{.code} | floating-point numbers. | ++-----------------+-----------------+-----------------------------------+ +| ` | ` | Addition of v0 and v1 as | +| INT_ADD`{.code} | v0 + v1`{.code} | integers. | ++-----------------+-----------------+-----------------------------------+ +| ` | ` | Subtraction of v1 from v0 as | +| INT_SUB`{.code} | v0 - v1`{.code} | integers. | ++-----------------+-----------------+-----------------------------------+ +| `FL | `v | Addition of v0 and v1 as | +| OAT_ADD`{.code} | 0 f+ v1`{.code} | floating-point numbers. | ++-----------------+-----------------+-----------------------------------+ +| `FL | `v | Subtraction of v1 from v0 as | +| OAT_SUB`{.code} | 0 f- v1`{.code} | floating-point numbers. | ++-----------------+-----------------+-----------------------------------+ +| `I | `v | Left shift of v0 by v1 bits. | +| NT_LEFT`{.code} | 0 << v1`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `IN | `v | Unsigned (logical) right shift of | +| T_RIGHT`{.code} | 0 >> v1`{.code} | v0 by v1 bits. | ++-----------------+-----------------+-----------------------------------+ +| `INT | `v0 | Signed (arithmetic) right shift | +| _SRIGHT`{.code} | s>> v1`{.code} | of v0 by b1 bits. | ++-----------------+-----------------+-----------------------------------+ +| `IN | ::: { | True if v0 is less than v1 as a | +| T_SLESS`{.code} | .informaltable} | signed integer. | +| | []{#sles | | +| | sref.htmltable} | | +| | | | +| | ---- | | +| | --------------- | | +| | `v | | +| | 0 s< v1`{.code} | | +| | `v | | +| | 1 s> v0`{.code} | | +| | ---- | | +| | --------------- | | +| | ::: | | ++-----------------+-----------------+-----------------------------------+ +| `INT_SLE | ::: { | True if v0 is less than or equal | +| SSEQUAL`{.code} | .informaltable} | to v1 as a signed integer. | +| | []{#slessequa | | +| | lref.htmltable} | | +| | | | +| | ----- | | +| | --------------- | | +| | `v0 | | +| | s<= v1`{.code} | | +| | `v1 | | +| | s>= v0`{.code} | | +| | ----- | | +| | --------------- | | +| | ::: | | ++-----------------+-----------------+-----------------------------------+ +| `I | ::: { | True if v0 is less than v1 as an | +| NT_LESS`{.code} | .informaltable} | unsigned integer. | +| | []{#les | | +| | sref.htmltable} | | +| | | | +| | --- | | +| | --------------- | | +| | ` | | +| | v0 < v1`{.code} | | +| | ` | | +| | v1 > v0`{.code} | | +| | --- | | +| | --------------- | | +| | ::: | | ++-----------------+-----------------+-----------------------------------+ +| `INT_LE | ::: { | True if v0 is less than or equal | +| SSEQUAL`{.code} | .informaltable} | to v1 as an unsigned integer. | +| | []{#lessequa | | +| | lref.htmltable} | | +| | | | +| | ---- | | +| | --------------- | | +| | `v | | +| | 0 <= v1`{.code} | | +| | `v | | +| | 1 >= v0`{.code} | | +| | ---- | | +| | --------------- | | +| | ::: | | ++-----------------+-----------------+-----------------------------------+ +| `FLO | ::: { | True if v0 is less than v1 viewed | +| AT_LESS`{.code} | .informaltable} | as floating-point numbers. | +| | []{#fles | | +| | sref.htmltable} | | +| | | | +| | ---- | | +| | --------------- | | +| | `v | | +| | 0 f< v1`{.code} | | +| | `v | | +| | 1 f> v0`{.code} | | +| | ---- | | +| | --------------- | | +| | ::: | | ++-----------------+-----------------+-----------------------------------+ +| `FLOAT_LE | ::: { | True if v0 is less than or equal | +| SSEQUAL`{.code} | .informaltable} | to v1 as floating-point. | +| | []{#flessequa | | +| | lref.htmltable} | | +| | | | +| | ----- | | +| | --------------- | | +| | `v0 | | +| | f<= v1`{.code} | | +| | `v1 | | +| | f>= v0`{.code} | | +| | ----- | | +| | --------------- | | +| | ::: | | ++-----------------+-----------------+-----------------------------------+ +| `IN | `v | True if v0 equals v1. | +| T_EQUAL`{.code} | 0 == v1`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `INT_N | `v | True if v0 does not equal v1. | +| OTEQUAL`{.code} | 0 != v1`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `FLOA | `v0 | True if v0 equals v1 viewed as | +| T_EQUAL`{.code} | f== v1`{.code} | floating-point numbers. | ++-----------------+-----------------+-----------------------------------+ +| `FLOAT_N | `v0 | True if v0 does not equal v1 | +| OTEQUAL`{.code} | f!= v1`{.code} | viewed as floating-point numbers. | ++-----------------+-----------------+-----------------------------------+ +| ` | ` | Bitwise Logical And of v0 with | +| INT_AND`{.code} | v0 & v1`{.code} | v1. | ++-----------------+-----------------+-----------------------------------+ +| ` | ` | Bitwise Exclusive Or of v0 with | +| INT_XOR`{.code} | v0 ^ v1`{.code} | v1. | ++-----------------+-----------------+-----------------------------------+ +| `INT_OR`{.code} | ` | Bitwise Logical Or of v0 with v1. | +| | v0 | v1`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `B | `v | Exclusive-Or of booleans v0 and | +| OOL_XOR`{.code} | 0 ^^ v1`{.code} | v1. | ++-----------------+-----------------+-----------------------------------+ +| `B | `v | Logical-And of booleans v0 and | +| OOL_AND`{.code} | 0 && v1`{.code} | v1. | ++-----------------+-----------------+-----------------------------------+ +| ` | `v | Logical-Or of booleans v0 and v1. | +| BOOL_OR`{.code} | 0 || v1`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `I | `z | Zero extension of v0. | +| NT_ZEXT`{.code} | ext(v0)`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `I | `s | Sign extension of v0. | +| NT_SEXT`{.code} | ext(v0)`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `IN | `carry | True if adding v0 and v1 would | +| T_CARRY`{.code} | (v0,v1)`{.code} | produce an unsigned carry. | ++-----------------+-----------------+-----------------------------------+ +| `INT | `scarry | True if adding v0 and v1 would | +| _SCARRY`{.code} | (v0,v1)`{.code} | produce a signed carry. | ++-----------------+-----------------+-----------------------------------+ +| `INT_ | `sborrow | True if subtracting v1 from v0 | +| SBORROW`{.code} | (v0,v1)`{.code} | would produce a signed borrow. | ++-----------------+-----------------+-----------------------------------+ +| `FL | ` | True if v0 is not a valid | +| OAT_NAN`{.code} | nan(v0)`{.code} | floating-point number (NaN). | ++-----------------+-----------------+-----------------------------------+ +| `FL | ` | Absolute value of v0 as floating | +| OAT_ABS`{.code} | abs(v0)`{.code} | point number. | ++-----------------+-----------------+-----------------------------------+ +| `FLO | `s | Square root of v0 as | +| AT_SQRT`{.code} | qrt(v0)`{.code} | floating-point number. | ++-----------------+-----------------+-----------------------------------+ +| `IN | `int2fl | Floating-point representation of | +| T2FLOAT`{.code} | oat(v0)`{.code} | v0 viewed as an integer. | ++-----------------+-----------------+-----------------------------------+ +| `FLOA | `float2fl | Copy of floating-point number v0 | +| T2FLOAT`{.code} | oat(v0)`{.code} | with more or less precision. | ++-----------------+-----------------+-----------------------------------+ +| `TRUNC`{.code} | `tr | Signed integer obtained by | +| | unc(v0)`{.code} | truncating v0. | ++-----------------+-----------------+-----------------------------------+ +| `FLO | `c | Nearest integer greater than v0. | +| AT_CEIL`{.code} | eil(v0)`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `FLOA | `fl | Nearest integer less than v0. | +| T_FLOOR`{.code} | oor(v0)`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `FLOA | `ro | Nearest integer to v0. | +| T_ROUND`{.code} | und(v0)`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `C | `cpool( | Access value from the constant | +| POOLREF`{.code} | v0,...)`{.code} | pool. | ++-----------------+-----------------+-----------------------------------+ +| `NEW`{.code} | `newobj | Allocate object of type described | +| | ect(v0)`{.code} | by v0. | ++-----------------+-----------------+-----------------------------------+ +| `USER_ | `ident( | User defined operator | +| DEFINED`{.code} | v0,...)`{.code} | [*ident*]{.emphasis}, with | +| | | functional syntax. | ++-----------------+-----------------+-----------------------------------+ +::: +::: + +\ +::: + +The following table lists the basic forms of a semantic statement. + +::: {.informalexample} +::: {.table} +[]{#statementref.htmltable} + +**Table 6. Basic Statements and Associated Operators** + +::: {.table-contents} ++-----------------+-----------------+-----------------------------------+ +| [**P-code | [**SLEIGH | [**Description**]{.bold} | +| Name**]{.bold} | S | | +| | yntax**]{.bold} | | ++=================+=================+===================================+ +| `COPY | `v | Assignment of v1 to v0. | +| , other`{.code} | 0 = v1;`{.code} | | ++-----------------+-----------------+-----------------------------------+ +| `STORE`{.code} | ::: { | Store v1 in default space using | +| | .informaltable} | v0 As pointer. Optionally specify | +| | []{#stor | space to store in and size of | +| | eref.htmltable} | data in bytes. | +| | | | +| | ------------- | | +| | --------------- | | +| | `* | | +| | v0 = v1`{.code} | | +| | `*[spc]v | | +| | 0 = v1;`{.code} | | +| | `*:4 v | | +| | 0 = v1;`{.code} | | +| | `*[spc]:4 v | | +| | 0 = v1;`{.code} | | +| | ------------- | | +| | --------------- | | +| | ::: | | ++-----------------+-----------------+-----------------------------------+ +| `USER_ | `ident(v | Invoke user-defined operation | +| DEFINED`{.code} | 0,...);`{.code} | ident as a standalone statement, | +| | | with no output. | ++-----------------+-----------------+-----------------------------------+ +| | `v0[8,1 | Fill a bit range within v0 using | +| | ] = v1;`{.code} | v1, leaving the rest of v0 | +| | | unchanged. | ++-----------------+-----------------+-----------------------------------+ +| | `ident(v | Invoke the macro named | +| | 0,...);`{.code} | [*ident*]{.emphasis}. | ++-----------------+-----------------+-----------------------------------+ +| | `build | Execute the p-code to build | +| | ident;`{.code} | operand [*ident*]{.emphasis}. | ++-----------------+-----------------+-----------------------------------+ +| | `delays | Execute the p-code for the | +| | lot(1);`{.code} | following instruction. | ++-----------------+-----------------+-----------------------------------+ +::: +::: + +\ +::: + +The following table lists the branching operations and the statements +which invoke them. + +::: {.informalexample} +::: {.table} +[]{#branchref.htmltable} + +**Table 7. Branching Statements** + +::: {.table-contents} + ------------------------------------------------------------------------------------ + [**P-code [**SLEIGH Syntax**]{.bold} [**Description**]{.bold} + Name**]{.bold} + -------------------- --------------------------- ----------------------------------- + `BRANCH`{.code} `goto v0;`{.code} Branch execution to address of v0. + + `CBRANCH`{.code} `if (v0) goto v1;`{.code} Branch execution to address of v1 + if v0 equals 1 (true). + + `BRANCHIND`{.code} `goto [v0];`{.code} Branch execution to v0 viewed as an + offset in current space. + + `CALL`{.code} `call v0;`{.code} Branch execution to address of v0. + Hint that branch is subroutine + call. + + `CALLIND`{.code} `call [v0];`{.code} Branch execution to v0 viewed as an + offset in current space. Hint that + branch is subroutine call. + + `RETURN`{.code} `return [v0];`{.code} Branch execution to v0 viewed as an + offset in current space. Hint that + branch is a subroutine return. + ------------------------------------------------------------------------------------ +::: +::: + +\ +::: +::: + +::: {.navfooter} + +------------------------------------------------------------------------ + + ------------------------------ --------------------- --- + [Prev](sleigh_context.html)      + 8. Using Context  [Home](sleigh.html)   + ------------------------------ --------------------- --- +::: diff --git a/sources/GhidraDocs/languages/html/sleigh_symbols.html b/sources/GhidraDocs/languages/html/sleigh_symbols.html new file mode 100644 index 0000000..2022555 --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_symbols.html @@ -0,0 +1,229 @@ + + + +5. Introduction to Symbols + + + + + + + + + +
+ + + + + + + +
5. Introduction to Symbols
+Prev   Next +
+
+
+
+

+5. Introduction to Symbols

+

+After the definition section, we are prepared to start writing the +body of the specification. This part of the specification shows how +the bits in an instruction break down into opcodes, operands, +immediate values, and the other pieces of an instruction. Then once +this is figured out, the specification must also describe exactly how +the processor would manipulate the data and operands if this +particular instruction were executed. All of SLEIGH revolves around +these two major tasks of disassembling and following semantics. It +should come as no surprise then that the primary symbols defined and +manipulated in the specification all have two key properties. +

+
    +
  1. + How does the symbol get displayed as part of the disassembly? +
    2. +
  2. + What semantic variable is associated with the symbol, and how is it constructed? +
    3. +
+

+Formally a Specific Symbol is defined as an identifier associated with +

+
    +
  1. + A string displayed in disassembly. +
    2. +
  2. + varnode used in semantic actions, and any p-code used to construct that varnode. +
    3. +
+

+The named registers that we defined earlier are the simplest examples +of specific symbols (see +Section 4.4, “Naming Registers”). The symbol identifier +itself is the string that will get printed in disassembly and the +varnode associated with the symbol is the one constructed by the +define statement. +

+

+The other crucial part of the specification is how to map from the +bits of a particular instruction to the specific symbols that +apply. To this end we have the Family Symbol, +which is defined as an identifier associated with a map from machine +instructions to specific symbols. +

+
+Family Symbol: Instruction Encodings => Specific Symbols +
+

+The set of instruction encodings that map to a single specific symbol +is called an instruction pattern and is described +more fully in Section 7.4, “The Bit Pattern Section”. In most cases, this +can be thought of as a mask on the bits of the instruction and a value +that the remaining unmasked bits must match. At any rate, the family +symbol identifier, when taken out of context, represents the entire +collection of specific symbols involved in this map. But in the +context of a specific instruction, the identifier represents the one +specific symbol associated with the encoding of that instruction by +the family symbol map. +

+

+Given these maps, the idea of the specification is to build up more +and more complicated family symbols until we have a single root +symbol. This gives us a single map from the bits of an instruction to +the full disassembly of it and to the sequence of p-code instructions +that simulate the instruction. +

+

+The symbol responsible for combining smaller family symbols is called +a table, which is fully described in +Section 7.8, “Tables”. Any table symbol +can be used in the definition of other table +symbols until the root symbol is fully described. The root symbol has +the predefined identifier instruction. +

+
+

+5.1. Notes on Namespaces

+

+Almost all identifiers live in the same global "scope". The global scope includes +

+
+

+All of the names in this scope must be unique. Each +individual constructor (defined in Section 7, “Constructors”) +defines a local scope for operand names. As with most languages, a +local symbol with the same name as a global +symbol hides the global symbol while that scope +is in effect. +

+
+
+

+5.2. Predefined Symbols

+

+We list all of the symbols that are predefined by SLEIGH. +

+
+
+

Table 2. Predefined Symbols

+
+++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IdentifierMeaning
instructionThe root instruction table.
constSpecial address space for building constant varnodes.
uniqueAddress space for allocating temporary registers.
inst_startOffset of the address of the current instruction.
inst_nextOffset of the address of the next instruction.
inst_next2Offset of the address of the instruction after the next instruction.
epsilonA special identifier indicating an empty bit pattern.
+
+
+
+

+The most important of these to be aware of +are inst_start +and inst_next. These are family symbols which map +in the context of particular instruction to the integer offset of +either the address of the instruction or the address of the next +instruction respectively. These are used in any relative branching +situation. The inst_next2 is intended for conditional +skip instruction situations. The remaining symbols are rarely +used. The const and unique +identifiers are address spaces. The epsilon +identifier is inherited from SLED and is a specific symbol equivalent +to the constant zero. The instruction identifier +is the root instruction table. +

+
+
+
+
+ + + + + + + + + + + +
+Prev   Next +
4. Basic Definitions Home 6. Tokens and Fields
+
+ + diff --git a/sources/GhidraDocs/languages/html/sleigh_symbols.md b/sources/GhidraDocs/languages/html/sleigh_symbols.md new file mode 100644 index 0000000..09f2634 --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_symbols.md @@ -0,0 +1,218 @@ +--- +status: collected +title: 5. Introduction to Symbols +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_symbols.html +--- + +::: {.navheader} +5. Introduction to Symbols +::: + +[Prev](sleigh_definitions.html)  + +  + + [Next](sleigh_tokens.html) + +------------------------------------------------------------------------ + +::: {.sect1} +::: {.titlepage} +
+ +
+ +[]{#sleigh_symbols}5. Introduction to Symbols {#introduction-to-symbols .title style="clear: both"} +--------------------------------------------- + +
+ +
+::: + +After the definition section, we are prepared to start writing the body +of the specification. This part of the specification shows how the bits +in an instruction break down into opcodes, operands, immediate values, +and the other pieces of an instruction. Then once this is figured out, +the specification must also describe exactly how the processor would +manipulate the data and operands if this particular instruction were +executed. All of SLEIGH revolves around these two major tasks of +disassembling and following semantics. It should come as no surprise +then that the primary symbols defined and manipulated in the +specification all have two key properties. + +::: {.informalexample} +::: {.orderedlist} +1. How does the symbol get displayed as part of the disassembly? +2. What semantic variable is associated with the symbol, and how is it + constructed? +::: +::: + +Formally a [*Specific Symbol*]{.emphasis} is defined as an identifier +associated with + +::: {.informalexample} +::: {.orderedlist} +1. A string displayed in disassembly. +2. varnode used in semantic actions, and any p-code used to construct + that varnode. +::: +::: + +The named registers that we defined earlier are the simplest examples of +specific symbols (see [Section 4.4, "Naming +Registers"](sleigh_definitions.html#sleigh_naming_registers "4.4. Naming Registers"){.xref}). +The symbol identifier itself is the string that will get printed in +disassembly and the varnode associated with the symbol is the one +constructed by the define statement. + +The other crucial part of the specification is how to map from the bits +of a particular instruction to the specific symbols that apply. To this +end we have the [*Family Symbol*]{.emphasis}, which is defined as an +identifier associated with a map from machine instructions to specific +symbols. + +::: {.informalexample} +[**Family Symbol:**]{.bold} Instruction Encodings =\> Specific Symbols +::: + +The set of instruction encodings that map to a single specific symbol is +called an [*instruction pattern*]{.emphasis} and is described more fully +in [Section 7.4, "The Bit Pattern +Section"](sleigh_constructors.html#sleigh_bit_pattern "7.4. The Bit Pattern Section"){.xref}. +In most cases, this can be thought of as a mask on the bits of the +instruction and a value that the remaining unmasked bits must match. At +any rate, the family symbol identifier, when taken out of context, +represents the entire collection of specific symbols involved in this +map. But in the context of a specific instruction, the identifier +represents the one specific symbol associated with the encoding of that +instruction by the family symbol map. + +Given these maps, the idea of the specification is to build up more and +more complicated family symbols until we have a single root symbol. This +gives us a single map from the bits of an instruction to the full +disassembly of it and to the sequence of p-code instructions that +simulate the instruction. + +The symbol responsible for combining smaller family symbols is called a +[*table*]{.emphasis}, which is fully described in [Section 7.8, +"Tables"](sleigh_constructors.html#sleigh_tables "7.8. Tables"){.xref}. +Any [*table*]{.emphasis} symbol can be used in the definition of other +[*table*]{.emphasis} symbols until the root symbol is fully described. +The root symbol has the predefined identifier +[*instruction*]{.emphasis}. + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_notes_namespaces}5.1. Notes on Namespaces {#notes-on-namespaces .title} + +
+ +
+::: + +Almost all identifiers live in the same global \"scope\". The global +scope includes + +::: {.informalexample} +::: {.itemizedlist} +- Names of address spaces +- Names of tokens +- Names of fields +- Names of user-defined p-code ops +- Names of registers +- Names of macros (see [Section 7.9, "P-code + Macros"](sleigh_constructors.html#sleigh_macros "7.9. P-code Macros"){.xref}) +- Names of tables (see [Section 7.8, + "Tables"](sleigh_constructors.html#sleigh_tables "7.8. Tables"){.xref}) +::: +::: + +All of the names in this scope must be unique. Each individual +[*constructor*]{.emphasis} (defined in [Section 7, +"Constructors"](sleigh_constructors.html "7. Constructors"){.xref}) +defines a local scope for operand names. As with most languages, a local +symbol with the same name as a global symbol [*hides*]{.emphasis} the +global symbol while that scope is in effect. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_predefined_symbols}5.2. Predefined Symbols {#predefined-symbols .title} + +
+ +
+::: + +We list all of the symbols that are predefined by SLEIGH. + +::: {.informalexample} +::: {.table} +[]{#predefine.htmltable} + +**Table 2. Predefined Symbols** + +::: {.table-contents} + --------------------------------------------------------------------------- + [**Identifier**]{.bold} [**Meaning**]{.bold} + ------------------------- ------------------------------------------------- + `instruction`{.code} The root instruction table. + + `const`{.code} Special address space for building constant + varnodes. + + `unique`{.code} Address space for allocating temporary registers. + + `inst_start`{.code} Offset of the address of the current instruction. + + `inst_next`{.code} Offset of the address of the next instruction. + + `inst_next2`{.code} Offset of the address of the instruction after + the next instruction. + + `epsilon`{.code} A special identifier indicating an empty bit + pattern. + --------------------------------------------------------------------------- +::: +::: + +\ +::: + +The most important of these to be aware of are +[*inst\_start*]{.emphasis} and [*inst\_next*]{.emphasis}. These are +family symbols which map in the context of particular instruction to the +integer offset of either the address of the instruction or the address +of the next instruction respectively. These are used in any relative +branching situation. The [*inst\_next2*]{.emphasis} is intended for +conditional skip instruction situations. The remaining symbols are +rarely used. The [*const*]{.emphasis} and [*unique*]{.emphasis} +identifiers are address spaces. The [*epsilon*]{.emphasis} identifier is +inherited from SLED and is a specific symbol equivalent to the constant +zero. The [*instruction*]{.emphasis} identifier is the root instruction +table. +::: +::: + +::: {.navfooter} + +------------------------------------------------------------------------ + + ---------------------------------- --------------------- ----------------------------- + [Prev](sleigh_definitions.html)     [Next](sleigh_tokens.html) + 4. Basic Definitions  [Home](sleigh.html)  6. Tokens and Fields + ---------------------------------- --------------------- ----------------------------- +::: diff --git a/sources/GhidraDocs/languages/html/sleigh_tokens.html b/sources/GhidraDocs/languages/html/sleigh_tokens.html new file mode 100644 index 0000000..2ba08cd --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_tokens.html @@ -0,0 +1,285 @@ + + + +6. Tokens and Fields + + + + + + + + + +
+ + + + + + + +
6. Tokens and Fields
+Prev   Next +
+
+
+
+

+6. Tokens and Fields

+
+

+6.1. Defining Tokens and Fields

+

+A token is one of the byte-sized pieces that make +up the machine code instructions being modeled. +Instruction fields must be defined on top of +them. A field is a logical range of bits within +an instruction that can specify an opcode, or an operand etc. Together +tokens and fields determine the basic interpretation of bits and how +many bytes the instruction takes up. To define a token and the fields +associated with it, we use the define +token statement. +

+
+define token tokenname ( integer )
+  fieldname=(integer,integer) attributelist
+  ...
+;
+
+

+

+

+The first part of the definition defines the name of a token and the +number of bits it uses (this must be a multiple of 8). Following this +there are one or more field declarations specifying the name of the +field and the range of bits within the token making up the field. The +size of a field does not need to be a multiple of +8. The range is inclusive where the least significant bit in the token +is labeled 0. When defining tokens that are bigger than 1 byte, the +global endianness setting (See Section 4.1, “Endianness Definition”) +will affect this labeling. Although it is rarely required, it is possible to override +the global endianness setting for a specific token by appending either the qualifier +endian=little or endian=big +immediately after the token name and size. For instance: +

+
+  define token instr ( 32 ) endian=little op0=(0,15) ...
+
+

+The token instr is overridden to be little endian. +This override applies to all fields defined for the token but affects no other tokens. +

+

+After each field +declaration, there can be zero or more of the following attribute +keywords: +

+
+signed
+hex
+dec
+
+

+These attributes are defined in the next section. There can be any +manner of repeats and overlaps in the fields so long as they all have +different names. +

+
+
+

+6.2. Fields as Family Symbols

+

+Fields are the most basic form of family symbol; they define a natural +map from instruction bits to a specific symbol as follows. We take the +set of bits within the instruction as given by the field’s defining +range and treat them as an integer encoding. The resulting integer is +both the display portion and the semantic meaning of the specific +symbol. The display string is obtained by converting the integer into +either a decimal or hexadecimal representation (see below), and the +integer is treated as a constant varnode in any semantic action. +

+

+The attributes of the field affect the resulting specific symbol in +obvious ways. The signed attribute +determines whether the integer encoding should be treated as just an +unsigned encoding or if a twos-complement encoding should be used to +obtain a signed integer. The hex +or dec attributes describe whether +the integer should be displayed with a hexadecimal or decimal +representation. The default is hexadecimal. [Currently +the dec attribute is not supported] +

+
+
+

+6.3. Attaching Alternate Meanings to Fields

+

+The default interpretation of a field is probably the most natural but +of course processors interpret fields within an instruction in a wide +variety of ways. The attach keyword +is used to alter either the display or semantic meaning of fields into +the most common (and basic) interpretations. More complex +interpretations must be built up out of tables. +

+
+

+6.3.1. Attaching Registers

+

+Probably the most common processor interpretation +of a field is as an encoding of a particular register. In SLEIGH this +can be done with the attach variables +statement: +

+
+attach variables fieldlist registerlist;
+
+

+A fieldlist can be a single field identifier or a +space separated list of field identifiers surrounded by square +brackets. A registerlist must be a square bracket +surrounded and space separated list of register identifiers as created +with define statements (see Section +Section 4.4, “Naming Registers”). For each field in +the fieldlist, instead of having the display and +semantic meaning of an integer, the field becomes a look-up table for +the given list of registers. The original integer interpretation is +used as the index into the list starting at zero, so a specific +instruction that has all the bits in the field equal to zero yields +the first register (a specific varnode) from the list as the meaning +of the field in the context of that instruction. Note that both the +display and semantic meaning of the field are now taken from the new +register. +

+

+A particular integer can remain unspecified by putting a ‘_’ character +in the appropriate position of the register list or also if the length +of the register list is less than the integer. A specific integer +encoding of the field that is unspecified like this +does not revert to the original semantic and +display meaning. Instead this encoding is flagged as an invalid form +of the instruction. +

+
+
+

+6.3.2. Attaching Other Integers

+

+Sometimes a processor interprets a field as an integer but not the +integer given by the default interpretation. A different integer +interpretation of the field can be specified with +an attach values statement. +

+
+attach values fieldlist integerlist;
+
+

+The integerlist is surrounded by square brackets +and is a space separated list of integers. In the same way that a new +register interpretation is assigned to fields with +an attach variables statement, the +integers in the list are assigned to each field specified in +the fieldlist. [Currently SLEIGH does not support +unspecified positions in the list using a ‘_’] +

+
+
+

+6.3.3. Attaching Names

+

+It is possible to just modify the display characteristics of a field +without changing the semantic meaning. The need for this is rare, but +it is possible to treat a field as having influence on the display of +the disassembly but having no influence on the semantics. Even if the +bits of the field do have some semantic meaning, sometimes it is +appropriate to define overlapping fields, one of which is defined to +have no semantic meaning. The most convenient way to break down the +required disassembly may not be the most convenient way to break down +the semantics. It is also possible to have symbols with semantic +meaning but no display meaning (see Section 7.4.5, “Invisible Operands”). +

+

+At any rate we can list the display interpretation of a field directly +with an attach names statement. +

+
+attach names fieldlist stringlist;
+
+

+The stringlist is assigned to each of the fields +in the same manner as the attach +variables and attach +values statements. A specific encoding of the field now +displays as the string in the list at that integer position. Field +values greater than the size of the list are interpreted as invalid +encodings. +

+
+
+
+

+6.4. Context Variables

+

+SLEIGH supports the concept of context +variables. For the most part processor instructions can be +unambiguously decoded by examining only the bits of the instruction +encoding. But in some cases, decoding may depend on the state of +processor. Typically, the processor will have some set of status flags +that indicate what mode is being used to process instructions. In +terms of SLEIGH, a context variable is a field +which is defined on top of a register rather than the instruction +encoding (token). +

+
+define context contextreg
+  fieldname=(integer,integer) attributelist
+  ...
+;
+
+

+

+

+Context variables are defined with a define +context statement. The keywords must be followed by the +name of a defined register. The remaining part of the definition is +nearly identical to the normal definition of fields. Each context +variable defined on this register is listed in turn, specifying the +name, the bit range, and any attributes. All the normal field attributes, +signed, dec, and +hex, can also be used for context variables. +

+

+Context variables introduce a new, dedicated, attribute: noflow. +By default, globally setting a context variable affects instruction decoding +from the point of the change, forward, +following the flow of the instructions, but if the variable is labeled as +noflow, any change is limited to a +single instruction. (See Section 8.3.1, “Context Flow”) +

+

+Once the context variable is defined, in terms of the specification +syntax, it can be treated as if it were just another field. See +Section 8, “Using Context”, for a complete discussion of how to +use context variables. +

+
+
+
+
+ + + + + + + + + + + +
+Prev   Next +
5. Introduction to Symbols Home 7. Constructors
+
+ + diff --git a/sources/GhidraDocs/languages/html/sleigh_tokens.md b/sources/GhidraDocs/languages/html/sleigh_tokens.md new file mode 100644 index 0000000..45ecc8b --- /dev/null +++ b/sources/GhidraDocs/languages/html/sleigh_tokens.md @@ -0,0 +1,346 @@ +--- +status: collected +title: 6. Tokens and Fields +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_tokens.html +--- + +::: {.navheader} +6. Tokens and Fields +::: + +[Prev](sleigh_symbols.html)  + +  + + [Next](sleigh_constructors.html) + +------------------------------------------------------------------------ + +::: {.sect1} +::: {.titlepage} +
+ +
+ +[]{#sleigh_tokens}6. Tokens and Fields {#tokens-and-fields .title style="clear: both"} +-------------------------------------- + +
+ +
+::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_defining_tokens}6.1. Defining Tokens and Fields {#defining-tokens-and-fields .title} + +
+ +
+::: + +A [*token*]{.emphasis} is one of the byte-sized pieces that make up the +machine code instructions being modeled. Instruction +[*fields*]{.emphasis} must be defined on top of them. A +[*field*]{.emphasis} is a logical range of bits within an instruction +that can specify an opcode, or an operand etc. Together tokens and +fields determine the basic interpretation of bits and how many bytes the +instruction takes up. To define a token and the fields associated with +it, we use the [**define token**]{.bold} statement. + +::: {.informalexample} +``` +define token tokenname ( integer ) + fieldname=(integer,integer) attributelist + ... +; +``` +::: + +The first part of the definition defines the name of a token and the +number of bits it uses (this must be a multiple of 8). Following this +there are one or more field declarations specifying the name of the +field and the range of bits within the token making up the field. The +size of a field does [*not*]{.emphasis} need to be a multiple of 8. The +range is inclusive where the least significant bit in the token is +labeled 0. When defining tokens that are bigger than 1 byte, the global +endianness setting (See [Section 4.1, "Endianness +Definition"](sleigh_definitions.html#sleigh_endianness_definition "4.1. Endianness Definition"){.xref}) +will affect this labeling. Although it is rarely required, it is +possible to override the global endianness setting for a specific token +by appending either the qualifier [**endian=little**]{.bold} or +[**endian=big**]{.bold} immediately after the token name and size. For +instance: + +::: {.informalexample} +``` + define token instr ( 32 ) endian=little op0=(0,15) ... +``` +::: + +The token [*instr*]{.emphasis} is overridden to be little endian. This +override applies to all fields defined for the token but affects no +other tokens. + +After each field declaration, there can be zero or more of the following +attribute keywords: + +::: {.informalexample} +``` +signed +hex +dec +``` +::: + +These attributes are defined in the next section. There can be any +manner of repeats and overlaps in the fields so long as they all have +different names. +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_fields_family}6.2. Fields as Family Symbols {#fields-as-family-symbols .title} + +
+ +
+::: + +Fields are the most basic form of family symbol; they define a natural +map from instruction bits to a specific symbol as follows. We take the +set of bits within the instruction as given by the field's defining +range and treat them as an integer encoding. The resulting integer is +both the display portion and the semantic meaning of the specific +symbol. The display string is obtained by converting the integer into +either a decimal or hexadecimal representation (see below), and the +integer is treated as a constant varnode in any semantic action. + +The attributes of the field affect the resulting specific symbol in +obvious ways. The [**signed**]{.bold} attribute determines whether the +integer encoding should be treated as just an unsigned encoding or if a +twos-complement encoding should be used to obtain a signed integer. The +[**hex**]{.bold} or [**dec**]{.bold} attributes describe whether the +integer should be displayed with a hexadecimal or decimal +representation. The default is hexadecimal. \[Currently the +[**dec**]{.bold} attribute is not supported\] +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_alternate_meanings}6.3. Attaching Alternate Meanings to Fields {#attaching-alternate-meanings-to-fields .title} + +
+ +
+::: + +The default interpretation of a field is probably the most natural but +of course processors interpret fields within an instruction in a wide +variety of ways. The [**attach**]{.bold} keyword is used to alter either +the display or semantic meaning of fields into the most common (and +basic) interpretations. More complex interpretations must be built up +out of tables. + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_attaching_registers}6.3.1. Attaching Registers {#attaching-registers .title} + +
+ +
+::: + +Probably [*the*]{.emphasis} most common processor interpretation of a +field is as an encoding of a particular register. In SLEIGH this can be +done with the [**attach variables**]{.bold} statement: + +::: {.informalexample} +``` +attach variables fieldlist registerlist; +``` +::: + +A [*fieldlist*]{.emphasis} can be a single field identifier or a space +separated list of field identifiers surrounded by square brackets. A +[*registerlist*]{.emphasis} must be a square bracket surrounded and +space separated list of register identifiers as created with +[**define**]{.bold} statements (see Section [Section 4.4, "Naming +Registers"](sleigh_definitions.html#sleigh_naming_registers "4.4. Naming Registers"){.xref}). +For each field in the [*fieldlist*]{.emphasis}, instead of having the +display and semantic meaning of an integer, the field becomes a look-up +table for the given list of registers. The original integer +interpretation is used as the index into the list starting at zero, so a +specific instruction that has all the bits in the field equal to zero +yields the first register (a specific varnode) from the list as the +meaning of the field in the context of that instruction. Note that both +the display and semantic meaning of the field are now taken from the new +register. + +A particular integer can remain unspecified by putting a '\_' character +in the appropriate position of the register list or also if the length +of the register list is less than the integer. A specific integer +encoding of the field that is unspecified like this does +[*not*]{.emphasis} revert to the original semantic and display meaning. +Instead this encoding is flagged as an invalid form of the instruction. +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_attaching_integers}6.3.2. Attaching Other Integers {#attaching-other-integers .title} + +
+ +
+::: + +Sometimes a processor interprets a field as an integer but not the +integer given by the default interpretation. A different integer +interpretation of the field can be specified with an [**attach +values**]{.bold} statement. + +::: {.informalexample} +``` +attach values fieldlist integerlist; +``` +::: + +The [*integerlist*]{.emphasis} is surrounded by square brackets and is a +space separated list of integers. In the same way that a new register +interpretation is assigned to fields with an [**attach +variables**]{.bold} statement, the integers in the list are assigned to +each field specified in the [*fieldlist*]{.emphasis}. \[Currently SLEIGH +does not support unspecified positions in the list using a '\_'\] +::: + +::: {.sect3} +::: {.titlepage} +
+ +
+ +#### []{#sleigh_attaching_names}6.3.3. Attaching Names {#attaching-names .title} + +
+ +
+::: + +It is possible to just modify the display characteristics of a field +without changing the semantic meaning. The need for this is rare, but it +is possible to treat a field as having influence on the display of the +disassembly but having no influence on the semantics. Even if the bits +of the field do have some semantic meaning, sometimes it is appropriate +to define overlapping fields, one of which is defined to have no +semantic meaning. The most convenient way to break down the required +disassembly may not be the most convenient way to break down the +semantics. It is also possible to have symbols with semantic meaning but +no display meaning (see [Section 7.4.5, "Invisible +Operands"](sleigh_constructors.html#sleigh_invisible_operands "7.4.5. Invisible Operands"){.xref}). + +At any rate we can list the display interpretation of a field directly +with an [**attach names**]{.bold} statement. + +::: {.informalexample} +``` +attach names fieldlist stringlist; +``` +::: + +The [*stringlist*]{.emphasis} is assigned to each of the fields in the +same manner as the [**attach variables**]{.bold} and [**attach +values**]{.bold} statements. A specific encoding of the field now +displays as the string in the list at that integer position. Field +values greater than the size of the list are interpreted as invalid +encodings. +::: +::: + +::: {.sect2} +::: {.titlepage} +
+ +
+ +### []{#sleigh_context_variables}6.4. Context Variables {#context-variables .title} + +
+ +
+::: + +SLEIGH supports the concept of [*context variables*]{.emphasis}. For the +most part processor instructions can be unambiguously decoded by +examining only the bits of the instruction encoding. But in some cases, +decoding may depend on the state of processor. Typically, the processor +will have some set of status flags that indicate what mode is being used +to process instructions. In terms of SLEIGH, a context variable is a +[*field*]{.emphasis} which is defined on top of a register rather than +the instruction encoding (token). + +::: {.informalexample} +``` +define context contextreg + fieldname=(integer,integer) attributelist + ... +; +``` +::: + +Context variables are defined with a [**define context**]{.bold} +statement. The keywords must be followed by the name of a defined +register. The remaining part of the definition is nearly identical to +the normal definition of fields. Each context variable defined on this +register is listed in turn, specifying the name, the bit range, and any +attributes. All the normal field attributes, [**signed**]{.bold}, +[**dec**]{.bold}, and [**hex**]{.bold}, can also be used for context +variables. + +Context variables introduce a new, dedicated, attribute: +[**noflow**]{.bold}. By default, globally setting a context variable +affects instruction decoding from the point of the change, forward, +following the flow of the instructions, but if the variable is labeled +as [**noflow**]{.bold}, any change is limited to a single instruction. +(See [Section 8.3.1, "Context +Flow"](sleigh_context.html#sleigh_contextflow "8.3.1. Context Flow"){.xref}) + +Once the context variable is defined, in terms of the specification +syntax, it can be treated as if it were just another field. See +[Section 8, "Using +Context"](sleigh_context.html "8. Using Context"){.xref}, for a complete +discussion of how to use context variables. +::: +::: + +::: {.navfooter} + +------------------------------------------------------------------------ + + ------------------------------ --------------------- ----------------------------------- + [Prev](sleigh_symbols.html)     [Next](sleigh_constructors.html) + 5. Introduction to Symbols  [Home](sleigh.html)  7. Constructors + ------------------------------ --------------------- ----------------------------------- +::: diff --git a/sources/GhidraDocs/languages/manual_index.txt b/sources/GhidraDocs/languages/manual_index.txt new file mode 100644 index 0000000..60149bf --- /dev/null +++ b/sources/GhidraDocs/languages/manual_index.txt @@ -0,0 +1,54 @@ + +How to Create a Processor Language Manual Index File +---------------------------------------------------- + +The processor manual index file (*.idx) contains list of instructions mnemonic and page +numbers into an identified PDF manual. These files along with the corresponding PDF files +are generally located within the data/manuals directory of a Ghidra module +(e.g., Ghidra/Processors/x86/data/manuals/x86.idx). + +The first line of the .idx file must be a PDF manual selector preceeded by the @ character. + +Example: + +@68000.pdf [M68000 FAMILY Programmer's Reference Manual, 1992 (M68000PM/AD REV.1)] + +The manual selector specifies the PDF file name followed by the manual description within +brackets [ ]. The ".pdf" file extension is assumed if not specified, and the file path is +relative to the directory containing the index file. If the manual is omitted from the +distribution due to copyright or other restrictions, the bracketed text will be helpful +in allowing the user to obtain the manual on there own. + +The PDF manual selector is immediately followed by lines containing instruction +mnemonic, page number pairs which are contained within the specified PDF manual. +Additional PDF manuals may be referenced by repeating this pattern starting with +the @ character on a new line. + +Example: + +@Intel64_IA32_vol2a.pdf [Intel 64 and IA-32 Vol 2A: Instruction Set Reference, A-M, Nov 2008 (253666-029US)] +AAA, 74 +AAD, 76 +@Intel64_IA32_vol2b.pdf [Intel 64 and IA-32 Vol 2B: Instruction Set Reference, N-Z, Nov 2008 (253667-029US)] +NEG, 4 +NOP, 7 +NOT, 9 + +The AAA and AAD instructions will be found in Intel64_IA32_vol2a.pdf manual on +on page 74 and 76, respectively. Moreover, the NEG and NOP instructions +will be found in Intel64_IA32_vol2b.pdf on page 4 and 7 respectively. Also, the +remainder of the instructions will be found under Intel64_IA32_vol2b.pdf unless +another section is defined with the "@" symbol. + +Note: All files are expected to be stored relative to the directory +where the index file is located. The index file should be in the module's +data/manuals directory. + +The index file contains one line per instruction mnemonic or section header. +Each line of the index file for instruction mnemonics contains two strings: +the mnemonic and the corresponding instruction info page number in the PDF file in +its respective section. The instruction mnemonic may only specify the start of a +mnemonic if appropriate. For example a conditional branch instruction may include +a condition suffix on the mnemonic, but for simplification the suffix may be omitted +within the index file if all condition cases are handled together (e.g., index could +a mnemonic 'B' instead of listing all the condition cases BLT, BGT, BEQ, etc.). diff --git a/sources/GhidraDocs/languages/versioning.html b/sources/GhidraDocs/languages/versioning.html new file mode 100644 index 0000000..eef8ceb --- /dev/null +++ b/sources/GhidraDocs/languages/versioning.html @@ -0,0 +1,237 @@ + + + + + Language Versioning and Migration + + + +

Language Versioning and +Migration

+

This document discusses the mechanisms within Ghidra which mitigate +the impact of language modifications to existing user program +files.  There are two general classes of language modifications +which can be supported by the language translation capabilities within +Ghidra :
+

+
    +
  1. Version +Change - caused by modifications to a specific +language implementation which necessitates a re-disassembly of a programs +instructions.
    2. +
  2. Forced +Language Migration - caused when an existing language +implementation is completely replaced by a new implementation (language +name must be different).  It is important that an "old" language +file (*.lang) be generated for +a language before it is eliminated.   A simple or custom +language translator is required to facilitate the forced migration.
    +
    3. +
+

Any program opened within Ghidra whose language has had a version +change or has been replaced by a new implementation will be forced to +upgrade.  This will prevent such a program file from being opened +as immutable and will impose a delay due to the necessary +re-disassembly of all instructions.

+

In addition to a forced upgrade, Ghidra's Set Language capability will allow +a user to make certain transitions between similar language +implementations.  Such transitions are generally facilitated via a +default translator, although certain limitations are imposed based upon +address space sizes and register mappings.

+

Any changes made to a Data Organization could impact the packing of +components within a structure or union. While such changes should be avoided +due to the possible fallout, any such change to a +*.cspec should be made +in conjunction with a version change to all affected languages within +the relevant *.ldefs files. The +resulting program upgrade will allow affected data types to be updated. +
+

+

Language Versioning

+

A language's version is specified as a <major>.<minor> number pair (e.g., +1.0).  The decision to advance the major or minor version number +should be based upon the following criteria:
+

+
    +
  1. Major Version Change - +caused by modifications to a specific +language implementation which changes register addressing or context +register schema.  Addition of registers alone does not constitute +a major or minor change.
    +
    2. +
  2. Minor Version Change - +caused by modifications to a specific +language implementation which changes existing instruction or +subconstructor pattern matching.  Pcode changes and addition of +new instructions alone does not constitute a major or minor change.
    3. +
+

Anytime the major version number is advanced, the minor version +number should be reset to zero.
+

+

Only major version changes utilize a Language +Translator to facilitate the language transition.
+

+

Forced Language Migration
+

+

When eliminating an old language the following must be accomplished:
+

+
    +
  1. Establish a replacement language
    2. +
  2. Generate old-language specification file (*.lang)
    +
    3. +
  3. Establish one and only one Language +Translator from the final version of the eliminated language to +its replacement language.
    +
    4. +
+

Before eliminating a language a corresponding "old" language file +must be generated and stored somewhere within Ghidra's languages +directory (core/languages/old +directory has been established for this purpose).   In +addition, a simple or custom Language Translator +must be established to facilitate the language migration to the +replacement language. 
+

+

An old-language file may be generated automatically while the +language still exists using the GenerateOldLanguagePlugin +configured into Ghidra's project window.  In addition, if +appropriate, a draft simple Language Translator specification can +generated provided the replacement language is also available.
+

+

To generate an old-language file and optionally a draft simple +translator specification:
+

+
    +
  • Choose the menu item File>Generate Old Language File...
    • +
  • Select the language to be eliminated from the languages list and +click Generate...
    • +
  • From the file chooser select the output directory, enter a +suitable name for the file and click Create
    • +
  • Once the old-language file is generated you will be asked if you +would like to Create +a Simple Translator?  If the replacement language is +complete and available you can click Yes + and specify an output file with the file chooser.
    • +
+

Old Language Specification (*.lang)

+

An old-language specification file is used to describe the essential +elements of a language needed to instantiate an old program using that +language and to facilitate translation to a replacement language.
+

+

The specification file is an XML file which identifies a language's +description, address spaces and named registers.   Since it +should be generated using the GenerateOldLanguagePlugin, +its syntax is not defined here. +

+

Sample +Old-Language Specification File:
+

+
<?xml version="1.0" encoding="UTF-8"?>
<language version="1" endian="big">
    <description>
        <name>MyOldProcessorLanguage</name>
        <processor>MyOldProcessor</processor>
        <family>Motorola</family>
        <alias>MyOldProcessorLanguageAlias1</alias>
	<alias>MyOldProcessorLanguageAlias2</alias>
    </description>
    <spaces>
        <space name="ram" type="ram" size="4" default="yes" />
        <space name="register" type="register" size="4" />
        <space name="data" type="code" size="4" />
    </spaces>
    <registers>
	<context_register name="contextreg" offset="0x40" bitsize="8">
            <field name="ctxbit1" range="1,1" />
            <field name="ctxbit0" range="0,0" />
        </context_register>
        <register name="r0" offset="0x0" bitsize="32" />
        <register name="r1" offset="0x4" bitsize="32" />
        <register name="r2" offset="0x8" bitsize="32" />
        <register name="r3" offset="0xc" bitsize="32" />
        <register name="r4" offset="0x10" bitsize="32" />
    </registers>
</language>

+

Language Translators

+

A language translator facilitates the renaming of address spaces, +and relocation/renaming of registers.  In addition, stored +register values can be transformed - although limited knowledge is +available for decision making.  Through the process of +re-disassembly, language changes in instruction and subconstructor +pattern matching is handled.  Three forms of  translators are +supported:
+

+
    +
  1. Default Translator - in +the absence of a simple or custom translator, an attempt will be made +to map all address spaces and registers.  Stored register values +for unmapped registers will be discarded.  Forced language +migration can not use a default translator since it is the presence of +a translator with an old-language which specifies the migration path.
    +
    2. +
  2. Simple Translator - +extends the behavior of the default translator allowing specific +address space and register mappings to be specified via an XML file (*.trans).  See sample Simple Translator Specification.
    +
    3. +
  3. Custom Translator - +custom translators can be written as a Java class which extends LanguageTranslatorAdapter +or implements LanguageTranslator.  +This should generally be unnecessary but can provided additional +flexibility.  The default constructor must be public and will be used +for instantiation.  Extending LanguageTranslatorAdapter + will allow the default translator capabilities to be +leveraged with minimal coding.
    4. +
+ +

Sample +Simple Translator Specification File:

+
<?xml version="1.0" encoding="UTF-8"?>
+<language_translation>
+
+    <from_language version="1">MyOldProcessorLanguage</from_language>  
+    <to_language version="1">MyNewProcessorLanguage</to_language>
+
+    <!--
+        Obsolete space will be deleted with all code units in that space.
+    -->
+    <delete_space name="data" />
+
+    <!--
+        Spaces whose name has changed can be mapped over
+    -->
+    <map_space from="ram" to="ram" />
+
+    <!--
+        Registers whose name has changed can be mapped (size and offset changes are allowed)
+        The map_register may include a size attribute although it is ignored. 
+    --> 
+    <map_register from="r0" to="cr0" />
+    <map_register from="r1" to="cr1" />
+
+    <!--
+        All existing processor context can be cleared
+    -->
+    <clear_all_context/>
+
+    <!--
+        A specific context value can be painted across all of program memory
+        NOTE: sets occur after clear_all_context
+    -->
+    <set_context name="ctxbit0" value="1"/>
+    
+    <!--
+        Force a specific Java class which extends
+          ghidra.program.util.LanguagePostUpgradeInstructionHandler
+        to be invoked following translation and re-disassembly to allow for more
+        complex instruction context transformations/repair.
+    -->
+    <post_upgrade_handler class="ghidra.program.language.MyOldNewProcessorInstructionRepair" />
+
+</language_translation>
+
+
+

Translator Limitations
+

+

The current translation mechanism does not handle the potential need +for complete re-disassembly and associated auto-analysis.
+

+ + diff --git a/sources/GhidraDocs/languages/versioning.md b/sources/GhidraDocs/languages/versioning.md new file mode 100644 index 0000000..d692fd0 --- /dev/null +++ b/sources/GhidraDocs/languages/versioning.md @@ -0,0 +1,242 @@ +--- +status: collected +title: Language Versioning and Migration +author: Ghidra Developers Team +collector: Hornos3 +collected_date: 20240826 +link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/versioning.html +--- + +Language Versioning and Migration +================================= + +This document discusses the mechanisms within Ghidra which mitigate the +impact of language modifications to existing user program files.  There +are two general classes of language modifications which can be supported +by the language translation capabilities within Ghidra :\ + +1. [[Version Change]{style="font-weight: bold;"}](#versioning) - caused + by modifications to a specific language implementation which + necessitates a re-disassembly of a programs instructions. +2. [[Forced Language + Migration]{style="font-weight: bold;"}](#forcedMigration) - caused + when an existing language implementation is completely replaced by a + new implementation (language name must be different).  It is + important that an \"old\" language file + ([\*.lang]{style="font-style: italic;"}) be generated for a language + before it is eliminated.   A simple or custom language translator is + required to facilitate the forced migration.\ + +Any program opened within Ghidra whose language has had a version change +or has been replaced by a new implementation will be forced to upgrade.  +This will prevent such a program file from being opened as immutable and +will impose a delay due to the necessary re-disassembly of all +instructions. + +In addition to a forced upgrade, Ghidra\'s [Set +Language]{style="font-style: italic;"} capability will allow a user to +make certain transitions between similar language implementations.  Such +transitions are generally facilitated via a default translator, although +certain limitations are imposed based upon address space sizes and +register mappings. + +Any changes made to a Data Organization could impact the packing of +components within a structure or union. While such changes should be +avoided due to the possible fallout, any such change to a +[\*.cspec]{style="font-style: italic;"} should be made in conjunction +with a version change to all affected languages within the relevant +[\*.ldefs]{style="font-style: italic;"} files. The resulting program +upgrade will allow affected data types to be updated.\ + +[]{#versioning}Language Versioning +---------------------------------- + +A language\'s version is specified as a[ +\]{style="font-style: italic;"}[.]{style="font-weight: bold; font-style: italic;"}[\]{style="font-style: italic;"} +number pair (e.g., 1.0).  The decision to advance the major or minor +version number should be based upon the following criteria:\ + +1. [Major Version Change]{style="font-weight: bold;"} - caused by + modifications to a specific language implementation which changes + register addressing or context register schema.  Addition of + registers alone does not constitute a major or minor change.\ +2. [Minor Version Change]{style="font-weight: bold;"} - caused by + modifications to a specific language implementation which changes + existing instruction or subconstructor pattern matching.  Pcode + changes and addition of new instructions alone does not constitute a + major or minor change. + +Anytime the major version number is advanced, the minor version number +should be reset to zero.\ + +Only major version changes utilize a [Language Translator](#translators) +to facilitate the language transition.\ + +[]{#forcedMigration}Forced Language Migration +--------------------------------------------- + +When eliminating an old language the following must be accomplished:\ + +1. Establish a replacement language +2. Generate [old-language specification](#oldlang) file + ([\*.lang]{style="font-style: italic;"})\ +3. Establish one and only one [Language Translator](#translators) from + the final version of the eliminated language to its replacement + language.\ + +Before eliminating a language a corresponding \"old\" language file must +be generated and stored somewhere within Ghidra\'s languages directory +([core/languages/old]{style="font-style: italic;"} directory has been +established for this purpose).   In addition, a simple or custom +[Language Translator](#translators) must be established to facilitate +the language migration to the replacement language. \ + +An old-language file may be generated automatically while the language +still exists using the [GenerateOldLanguagePlugin +]{style="font-style: italic; font-weight: bold;"}configured into +Ghidra\'s project window.  In addition, if appropriate, a draft simple +Language Translator specification can generated provided the replacement +language is also available.\ + +To generate an old-language file and optionally a draft simple +translator specification:\ + +- Choose the menu item File\>Generate Old Language File\... +- Select the language to be eliminated from the languages list and + click [Generate\...]{style="font-weight: bold;"} +- From the file chooser select the output directory, enter a suitable + name for the file and click [Create]{style="font-weight: bold;"} +- Once the old-language file is generated you will be asked if you + would like to [Create a Simple + Translator?]{style="font-weight: bold; font-style: italic;"}  If the + replacement language is complete and available you can click [Yes + ]{style="font-weight: bold;"}and specify an output file with the + file chooser. + +[]{#oldlang}Old Language Specification ([\*.lang]{style="font-style: italic;"}) +------------------------------------------------------------------------------- + +An old-language specification file is used to describe the essential +elements of a language needed to instantiate an old program using that +language and to facilitate translation to a replacement language.\ + +The specification file is an XML file which identifies a language\'s +description, address spaces and named registers.   Since it should be +generated using the +[GenerateOldLanguagePlugin]{style="font-style: italic; font-weight: bold;"}, +its syntax is not defined here. + +[Sample Old-Language Specification +File:]{style="font-style: italic; font-weight: bold;"}\ + + + + + MyOldProcessorLanguage + MyOldProcessor + Motorola + MyOldProcessorLanguageAlias1 + MyOldProcessorLanguageAlias2 + + + + + + + + + + + + + + + + + + + +[]{#translators}Language Translators +------------------------------------ + +A language translator facilitates the renaming of address spaces, and +relocation/renaming of registers.  In addition, stored register values +can be transformed - although limited knowledge is available for +decision making.  Through the process of re-disassembly, language +changes in instruction and subconstructor pattern matching is handled.  +Three forms of  translators are supported:\ + +1. [Default Translator]{style="font-weight: bold;"} - in the absence of + a simple or custom translator, an attempt will be made to map all + address spaces and registers.  Stored register values for unmapped + registers will be discarded.  Forced language migration can not use + a default translator since it is the presence of a translator with + an old-language which specifies the migration path.\ +2. [Simple Translator]{style="font-weight: bold;"} - extends the + behavior of the default translator allowing specific address space + and register mappings to be specified via an XML file + ([\*.trans]{style="font-style: italic;"}).  See sample [Simple + Translator Specification](#transfile).\ +3. [Custom Translator]{style="font-weight: bold;"} - custom translators + can be written as a Java class which extends + [LanguageTranslatorAdapter]{style="font-weight: bold; font-style: italic;"} + or implements + [LanguageTranslator]{style="font-weight: bold; font-style: italic;"}.  + This should generally be unnecessary but can provided additional + flexibility.  The default constructor must be public and will be + used for instantiation.  Extending [LanguageTranslatorAdapter + ]{style="font-weight: bold; font-style: italic;"}will allow the + default translator capabilities to be leveraged with minimal coding. + +[[]{style="font-weight: bold;"}]{style="font-family: times new roman;"} + +[]{#transfile}Sample Simple Translator Specification File: + + + + + MyOldProcessorLanguage + MyNewProcessorLanguage + + + + + + + + + + + + + + + + + + + + + + +Translator Limitations\ + +The current translation mechanism does not handle the potential need for +complete re-disassembly and associated auto-analysis.\ From 6b2c787697b6920f84f66491af7cd411a1fd9f5e Mon Sep 17 00:00:00 2001 From: Hornos3 Date: Sun, 1 Sep 2024 14:42:15 +0800 Subject: [PATCH 2/2] Deleted /languages and /images Due to awful parsing of pandoc, the md files in /languages will be added gradually later. --- sources/GhidraDocs/images/B.gif | Bin 553 -> 0 bytes sources/GhidraDocs/images/D.gif | Bin 880 -> 0 bytes sources/GhidraDocs/images/F.gif | Bin 864 -> 0 bytes sources/GhidraDocs/images/GHIDRA_1.png | Bin 189819 -> 0 bytes sources/GhidraDocs/images/I.gif | Bin 868 -> 0 bytes sources/GhidraDocs/images/L.gif | Bin 863 -> 0 bytes sources/GhidraDocs/images/U.gif | Bin 881 -> 0 bytes sources/GhidraDocs/images/V_slash.png | Bin 281 -> 0 bytes sources/GhidraDocs/images/binaryData.gif | Bin 897 -> 0 bytes sources/GhidraDocs/images/dataTypes.png | Bin 596 -> 0 bytes .../GhidraDocs/images/decompileFunction.gif | Bin 111 -> 0 bytes sources/GhidraDocs/images/disk.png | Bin 620 -> 0 bytes .../GhidraDocs/images/document-properties.png | Bin 464 -> 0 bytes sources/GhidraDocs/images/down.png | Bin 192 -> 0 bytes sources/GhidraDocs/images/function_graph.png | Bin 444 -> 0 bytes sources/GhidraDocs/images/left.png | Bin 188 -> 0 bytes sources/GhidraDocs/images/memory16.gif | Bin 931 -> 0 bytes sources/GhidraDocs/images/notF.gif | Bin 882 -> 0 bytes sources/GhidraDocs/images/notes.gif | Bin 866 -> 0 bytes sources/GhidraDocs/images/play.png | Bin 562 -> 0 bytes sources/GhidraDocs/images/play_again.png | Bin 563 -> 0 bytes sources/GhidraDocs/images/redo.png | Bin 187 -> 0 bytes sources/GhidraDocs/images/registerGroup.png | Bin 192 -> 0 bytes sources/GhidraDocs/images/right.png | Bin 190 -> 0 bytes sources/GhidraDocs/images/sitemap_color.png | Bin 406 -> 0 bytes sources/GhidraDocs/images/table.png | Bin 566 -> 0 bytes sources/GhidraDocs/images/table_go.png | Bin 683 -> 0 bytes sources/GhidraDocs/images/undo.png | Bin 185 -> 0 bytes sources/GhidraDocs/images/up.png | Bin 193 -> 0 bytes sources/GhidraDocs/images/viewmagfit.png | Bin 975 -> 0 bytes .../languages/html/DefaultStyle.css | 92 - .../GhidraDocs/languages/html/Diagram1.png | Bin 11652 -> 0 bytes .../GhidraDocs/languages/html/Diagram2.png | Bin 4169 -> 0 bytes .../GhidraDocs/languages/html/Diagram3.png | Bin 7139 -> 0 bytes .../languages/html/additionalpcode.html | 453 --- .../languages/html/additionalpcode.md | 436 --- .../GhidraDocs/languages/html/languages.css | 26 - .../languages/html/pcodedescription.html | 3040 ----------------- .../languages/html/pcodedescription.md | 1168 ------- .../GhidraDocs/languages/html/pcoderef.html | 369 -- sources/GhidraDocs/languages/html/pcoderef.md | 155 - .../GhidraDocs/languages/html/pseudo-ops.html | 241 -- .../GhidraDocs/languages/html/pseudo-ops.md | 102 - .../GhidraDocs/languages/html/reference.html | 530 --- .../GhidraDocs/languages/html/reference.md | 84 - sources/GhidraDocs/languages/html/sleigh.html | 478 --- sources/GhidraDocs/languages/html/sleigh.md | 563 --- .../languages/html/sleigh_constructors.html | 2305 ------------- .../languages/html/sleigh_constructors.md | 2634 -------------- .../languages/html/sleigh_context.html | 364 -- .../languages/html/sleigh_context.md | 379 -- .../languages/html/sleigh_definitions.html | 354 -- .../languages/html/sleigh_definitions.md | 388 --- .../languages/html/sleigh_layout.html | 122 - .../languages/html/sleigh_layout.md | 167 - .../languages/html/sleigh_preprocessing.html | 214 -- .../languages/html/sleigh_preprocessing.md | 255 -- .../GhidraDocs/languages/html/sleigh_ref.html | 607 ---- .../GhidraDocs/languages/html/sleigh_ref.md | 450 --- .../languages/html/sleigh_symbols.html | 229 -- .../languages/html/sleigh_symbols.md | 218 -- .../languages/html/sleigh_tokens.html | 285 -- .../languages/html/sleigh_tokens.md | 346 -- sources/GhidraDocs/languages/manual_index.txt | 54 - sources/GhidraDocs/languages/versioning.html | 237 -- sources/GhidraDocs/languages/versioning.md | 242 -- 66 files changed, 17587 deletions(-) delete mode 100644 sources/GhidraDocs/images/B.gif delete mode 100644 sources/GhidraDocs/images/D.gif delete mode 100644 sources/GhidraDocs/images/F.gif delete mode 100644 sources/GhidraDocs/images/GHIDRA_1.png delete mode 100644 sources/GhidraDocs/images/I.gif delete mode 100644 sources/GhidraDocs/images/L.gif delete mode 100644 sources/GhidraDocs/images/U.gif delete mode 100644 sources/GhidraDocs/images/V_slash.png delete mode 100644 sources/GhidraDocs/images/binaryData.gif delete mode 100644 sources/GhidraDocs/images/dataTypes.png delete mode 100644 sources/GhidraDocs/images/decompileFunction.gif delete mode 100644 sources/GhidraDocs/images/disk.png delete mode 100644 sources/GhidraDocs/images/document-properties.png delete mode 100644 sources/GhidraDocs/images/down.png delete mode 100644 sources/GhidraDocs/images/function_graph.png delete mode 100644 sources/GhidraDocs/images/left.png delete mode 100644 sources/GhidraDocs/images/memory16.gif delete mode 100644 sources/GhidraDocs/images/notF.gif delete mode 100644 sources/GhidraDocs/images/notes.gif delete mode 100644 sources/GhidraDocs/images/play.png delete mode 100644 sources/GhidraDocs/images/play_again.png delete mode 100644 sources/GhidraDocs/images/redo.png delete mode 100644 sources/GhidraDocs/images/registerGroup.png delete mode 100644 sources/GhidraDocs/images/right.png delete mode 100644 sources/GhidraDocs/images/sitemap_color.png delete mode 100644 sources/GhidraDocs/images/table.png delete mode 100644 sources/GhidraDocs/images/table_go.png delete mode 100644 sources/GhidraDocs/images/undo.png delete mode 100644 sources/GhidraDocs/images/up.png delete mode 100644 sources/GhidraDocs/images/viewmagfit.png delete mode 100644 sources/GhidraDocs/languages/html/DefaultStyle.css delete mode 100644 sources/GhidraDocs/languages/html/Diagram1.png delete mode 100644 sources/GhidraDocs/languages/html/Diagram2.png delete mode 100644 sources/GhidraDocs/languages/html/Diagram3.png delete mode 100644 sources/GhidraDocs/languages/html/additionalpcode.html delete mode 100644 sources/GhidraDocs/languages/html/additionalpcode.md delete mode 100644 sources/GhidraDocs/languages/html/languages.css delete mode 100644 sources/GhidraDocs/languages/html/pcodedescription.html delete mode 100644 sources/GhidraDocs/languages/html/pcodedescription.md delete mode 100644 sources/GhidraDocs/languages/html/pcoderef.html delete mode 100644 sources/GhidraDocs/languages/html/pcoderef.md delete mode 100644 sources/GhidraDocs/languages/html/pseudo-ops.html delete mode 100644 sources/GhidraDocs/languages/html/pseudo-ops.md delete mode 100644 sources/GhidraDocs/languages/html/reference.html delete mode 100644 sources/GhidraDocs/languages/html/reference.md delete mode 100644 sources/GhidraDocs/languages/html/sleigh.html delete mode 100644 sources/GhidraDocs/languages/html/sleigh.md delete mode 100644 sources/GhidraDocs/languages/html/sleigh_constructors.html delete mode 100644 sources/GhidraDocs/languages/html/sleigh_constructors.md delete mode 100644 sources/GhidraDocs/languages/html/sleigh_context.html delete mode 100644 sources/GhidraDocs/languages/html/sleigh_context.md delete mode 100644 sources/GhidraDocs/languages/html/sleigh_definitions.html delete mode 100644 sources/GhidraDocs/languages/html/sleigh_definitions.md delete mode 100644 sources/GhidraDocs/languages/html/sleigh_layout.html delete mode 100644 sources/GhidraDocs/languages/html/sleigh_layout.md delete mode 100644 sources/GhidraDocs/languages/html/sleigh_preprocessing.html delete mode 100644 sources/GhidraDocs/languages/html/sleigh_preprocessing.md delete mode 100644 sources/GhidraDocs/languages/html/sleigh_ref.html delete mode 100644 sources/GhidraDocs/languages/html/sleigh_ref.md delete mode 100644 sources/GhidraDocs/languages/html/sleigh_symbols.html delete mode 100644 sources/GhidraDocs/languages/html/sleigh_symbols.md delete mode 100644 sources/GhidraDocs/languages/html/sleigh_tokens.html delete mode 100644 sources/GhidraDocs/languages/html/sleigh_tokens.md delete mode 100644 sources/GhidraDocs/languages/manual_index.txt delete mode 100644 sources/GhidraDocs/languages/versioning.html delete mode 100644 sources/GhidraDocs/languages/versioning.md diff --git a/sources/GhidraDocs/images/B.gif b/sources/GhidraDocs/images/B.gif deleted file mode 100644 index 49b267ab77a8967611521f6e019cfb8af9f3e2c2..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 553 zcmW+zyK0nC7#vYhQm3&L?2g?uiv2D=z4>fB*vu;0Qn!DVuUpc2%fSRjQ_1R9y}^ z<&vAc$lD3p0sO|FE0>lq#I1`XE|@vA?@A>mQ7!y@T<*d$fVU>$U0r)-yP1C-FtcXl1PV6Zz^v}q;m*@h>*`~H+%Wuy^r_!!{f(~_qet8VC7{675v6| zf{PVgRFI#7;4qIl{CGU(SaX_XXaEO4YbNZAe9@u(!*g6l9X zWDUf1C;_JmYRxod7}E17C54y*2FQRIP=JGcX2f*BuuHE)sVLgSxlOc-{D<}ufEG$MaJ~9`v4Q0WZ zg~b+316duhfU3eNU=g@XHVcbr88kA~V+e(+GYgA|4Ezjk3|ql+3RuK+3S*FEh+`-P zC!ZOo9EQ{$`;xtLTLod7qm+Y?U5_0}CD=wmn5Isdh73J=l2T9+^z7!vqC|+#(o}JFwBYt+q+75yWj50y2$kwJ1az=g1aY zNk}A!>@{u^Zo7EM9Rx`sQ-!JSAeF_DMn$;iCY{-PF!Pw<2gAq5JZ(Q&efXk=8h+s{ z(fNwbD=JP=bWp?|d^((RYBq_)so92b>s=GWImP0hMG&a1FMN zyosa%CE(RTW0+;snn6G*DZ~u0Kn^5;0z4Em6J{go9)m8WqUaE77VR9(1Puk@p-wYp zHl{WVhLnAZlt?Y&9AN@q!S&$KkQu4TfRv=*3^NOxBTtYhC=cE|EXJ@QavzBc<-nVV z#Wrjcc>{@ns>3T`5x7V;4~uA9G;=f(2!*;g4~vK`!W@1ASHba0Sj21wYmw(j5-0_) zn3-lAYnp&V$^MzGk}$(b#*t<(U{_KJc2E*#XfkG+I$$6v1w{!96PgjT9(9+2qU=zt zUBtqaX3We`4;l0+({o|}V}T`MB`lnto}QeX93LMa9UTn@gZ=&eG)=d+x8pe8+}sSq zaARY`_x<(tb=P%Ut(N0B%gf74OH0*im4Bx@J9|+S6>h-dxw9&|*oxfvbGZUkaJRTE zenbseXyVesRrzJ->zjqj?Ps4?c6Z;_Dy#RudE>{pa_{EiyRGry{k2=KzyE&uak#bk Up!)OGk3Cn5=Z7EetX#*Vf2#?v#Q*>R diff --git a/sources/GhidraDocs/images/GHIDRA_1.png b/sources/GhidraDocs/images/GHIDRA_1.png deleted file mode 100644 index 659c3f9d9c33db40d31f014375db95e6e2d5444c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 189819 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

FpGh+&{h&+QPCjM{<3P0qQG;m{ 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 diff --git a/sources/GhidraDocs/images/I.gif b/sources/GhidraDocs/images/I.gif deleted file mode 100644 index 88b7a0478302ebda3a9ded2857523d53f4975a87..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 868 zcmZvbKWG#|9EIPaMXGSvT}WZT2|+Bpt^C6Uw9vT~WDAqC2mzOL3qhD}3t16jA(;zX zELI_bAhOrEO}OonAa@`bP^Jpgcn87qNTVX$bCb^8J(zjS@PpywV;(mi-MRasf(m}& zJn_YfFDfoiaePq59(?#Rb|f>w3^qX#Aq}8B_%1jw?B#50wn8e&rr;86 z14SKa4NAbTg2phN=4BmmMj_t>M3dp!bg>6 z$h=Q&7BUp=~K$=1+ z_~pznXJ6BV>`HddZH);t9OUe2wnMfgm0%NN!VFE$TvLY(C8eMk!@_{3$GlD5VyGya z6ib(}Fr?`-H`HB*9m?!N*#B7In6NP{oSmJWo}QkZoE#q?9~~X-@9$?>w!OWbB+16c zMifQs>+3-fEH5v6p0~KT=(_Iw{QS(!%=Gj${|_t*M5HA`})ptaQ`1yPq5nn diff --git a/sources/GhidraDocs/images/L.gif b/sources/GhidraDocs/images/L.gif deleted file mode 100644 index 71667ab326fb30a287335646df9409dc6dad6188..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 863 zcmeH`F=!M)6o$V*iiph?DRN+8kO2h?_X<(t38Lui6*5goCwT3a(_OWoC@5^?kg2Ui zE*5T=0gI%`NlMvrs!L&er8f7wq>NWv`N8Ay;5Fal{ZET0ckaH($oTn&j_SOs^Hz0J zRULJtqfe&`En3YRwY5%49a>F|rlbjROc>#ZxIQ{-HEVQGYrmAY+B4cE6~qA{#~WM^ zwXK>)b*-|LwK8T22_gjW;OKVF)XY>LsN9$JGJ9e-QA7rT++!R)wF@<{9 diff --git a/sources/GhidraDocs/images/U.gif b/sources/GhidraDocs/images/U.gif deleted file mode 100644 index 975f78da36debc219510b60473530bc63aab2074..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 881 zcmZvbF=!J}9LB%WBE?F{QZPY;7GAI*Vh#sI(m|wNPLx~PI5_Az$w8O5=;3f!s33TO z0}otEgi_?PcuUD`HIzggI>?*KTTDvlw2O$4&uce(`QW{e_xQu($B*}*wtV}}^8yO^ zjnnvN%RehWJNf=@7QMUuW5}UmKcNcPb=fu<3&zkPQV)>>X~8zYfnqOVD`3N=G+7s1 zfvzE~BC0?N*hNq&CJBRpu1nLT5F~Qe zic~`;eFlndmu8zHCSr{+g%`n*uxuDqWI_g{OPZwM2qO)hB8?D9NE`MzEQZh?QU{R* zX}}(b#Ts-KX$6shEW*xV5jama4vVO1R8v$U2#KOS4vPpiycA9ZOTw^oSj1=qt&ygP zB1j24n;9nT2UIS*CfldBa>5h`33~xsE*mDLU>!MOiYj3eFmUObGzCQt3j?YilNN&p zT}iV}v2q>@L#jR##h^>KO*1|d_CFSw6PClm$;rvl(b2)d!T$b!r_1jXJ`3$*lce3zMr`Pv*%7L>uk$1|7U6f zn85YyHv16;VEQp8r>~e_o8Q(iOk8_<`Pt`tZ*i%1YpVHc@BQSQ_2$d*{N9J+VtH!u s=0dlz@NoP7>z{|;Ki-&G-g=U}=zN-ac~!kSK790Udi~;Dserrx09Ed^>i_@% diff --git a/sources/GhidraDocs/images/V_slash.png b/sources/GhidraDocs/images/V_slash.png deleted file mode 100644 index c0d71a7021c47306dc2dabb6d09dbed92ec02488..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 281 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`jKx9jP7LeL$-D$|*pj^6U4Zmf zhOgfl8^wVv&H|6fVg?3oVGw3ym^DWND9B#o>Fdh=fJIWslI@pEKpId;vcxr_#5q4V zH#M(>!MP|ku_QG`p**uBL&4qCHz2%`4`f)0r;B5V#p$yXck>=l;Bkq6mGeMyljpNk z;j{$itmTUF2Z|=OP0sLp_A}?OK$jBN7rD0cTf|)ir%h3KGI`Ir>fW+Hv%h!<6`Q90dYbKBc^}HEJc*x>_3!CMz{a2h z$_b!6!N3v6z{?=vu|dI+nS)U#;>3o9P7IvE7{DV*mPlteD7bm;KA)Q)c#ZfxM&>^^Kt8@}X5Ie=bVzn=MFZUjYdmCwDp#8yF z?&W;~#$GgC@+%sc?o-nF-4K&3zot+3`G-N|qHL0AClfCI!0+R;~5E9JhUc8y*0 zgRr2Ksyl-nRx9N`FZN5m<_F>B6o5$@06Yoq1O;-yCpRWNt^ zfO6d$BtPv6bd&jqH<+24V6D2ro!J-E-#%dO?iHRsUjs4RyVW3l<|40FJ^-9{2B8H= z3o#MHS(v_gp29?qck7=p$u6QJ#6*Z`{aZRHXRu=drU@d5{)LzrkpwaOwn1V+|z`(|!17rhL z3NSD*n`G>|6DwdP_S&TIse0-1`%7~sEA%8P^Dv90IldO%ELbdh_T2-vJ4$Q@DB{M6?B9ctN}~YB=-OS diff --git a/sources/GhidraDocs/images/disk.png b/sources/GhidraDocs/images/disk.png deleted file mode 100644 index 99d532e8b1750115952f97302a92d713c0486f97..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 620 zcmV-y0+aoTP)~H+MJzd|s z^YP1Hc07G_>)Lgir!F1{Qn4GcTg%?koHo<=1qRN{}nPDolOeI^o4N5I>! zU$N=L=sg~ zDx#dOA*B0N~cqPsWI(^rbbkh)DS0_H_UN0C4l_kvWIm2#Kyy6%BCh z(yIUf003&1xdx>t$*eR2ZvXxT0001Z_R$y3Iju92q*wg58};}zm(OaAH=p|y0002M zh5O5#fxp|~jc?yi@+7$`d4Q6Hl%z;WiWG??NXR{Hx%)pMd~SE0000OQI diff --git a/sources/GhidraDocs/images/document-properties.png b/sources/GhidraDocs/images/document-properties.png deleted file mode 100644 index ab0e8ea377db9a6bb702f0a374b75841bcab0b62..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 464 zcmV;>0WbcEP)r z=%QrMoYg6I5Q8zI2z{r+`*EJ{?;HUbkH_CZ5WMl6-uwOj7XYs79-o!#x<`QQC33&t z6GagKA`<)Ovxtz%WH3!LjwJw56yf`R;=-jwgnGT6@Uqv9)oL{Wdc9ukbvhkNrBVtA z@N%8O_kC8Y743E#tu`Ffm|-fd_JdAsoVyL2ui8cJ8&F_^?HqA807Q$$M4`YxFn>} zXs}!^?*lG}b}iF1DVNJBKMP>n_RnB2czxz8+P3}4f9Mb3j-%#nF`Fa+0000&A-ej;gyuG&s$%wkdfKA;H|vEO|L+|vIXqdaF_A89qTKGV%LqLqA&{k|D2>yV7qLmg~*x1@cbjz3zP!z2FhV16<-TNNz zuIz$fLNt0{xWmll%$dUkM1*+|PHJ2ZGvdmC35A3UoF6R(-~DS$BH+@Xy#VYsLyQ>z zxq>v8$ny|FSR~0W2u4ic`k5mcbEIiLksz4Y#KyE{9LLn}_oq&%6$}Oga?Zh83$3-^ zU4V1$eaMkz85m>bTh*c{3ch%tltQ=L4Q7$u>-Ff*JP6K)r(~Ul_41v6uR1rSij#*! zl14&E?hS3Iagod#Oo#p}d7WbijUO{Mqc5?@<$>unxw*22 z?bQuGkPsSMOgEm)qR1=cLLyZOm>T65_V?)|o0p=i_uUiST44Cz-W mqJp!8r`H!$*8T4x&4Leh&Epbde3h>N0000@<_-eJUEzeVCjP{!CMd6l-4+GmSw0uY%c1!IOGXX OKZB>MpUXO@geCw_@BkYSfQDeEO1Dg_KqE_4P)QTxJ`x_{ zHlhNGh6rVyZiSYlQKDL;;t-CHoQI4JT_C9;MoGG)MH-|^Dr}(P!}s9Xumyw$trZq? z@H6mq*hz>Ov{qP5z>mX=!d4(6(3-Fa93*RnMI?O0Jw$CN0uikh7LoIj@u1sC3dFP~ zETYkX@5A$8+Yka;FjIF~u_z6eR2KJaH3^ffx-45P7|f~^3e#v3CMjLI7A=E@N>!oK zgoP?)nQnnrmWH63rZRpI3w6p0T}i7%qe#`+7xq6E*d(k83%k3!wOVa^dwX+pbA5e% zb#>KooW;e(TrM{^HpIadjm>hK{a*>-Sa`-p+@6+wL62SYh_qshc0a zOzH3L|J?b|UO&97;@jCa^T^D}LA!tQTbCaXOumucOzq0k{%coXztElxJ?x!7 xKRngFw2^Y(UwAgKF!AXTcK&W{-2HLxLAN_J@qOqvX1lhQZWy2QUl9u7%s-|%&Cmb< diff --git a/sources/GhidraDocs/images/notF.gif b/sources/GhidraDocs/images/notF.gif deleted file mode 100644 index 9b5fbc0cf8bfb4a158d6ea0a3420d204003f848f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 882 zcmZvbF=!J}9LB$33qhn*K`^C4wY(zYU=G2Gq>E55hv+R$aI?1_bnrPH4ku!8y3`wP zENK;y%i=kd+*VVYfJ3J@g*Qk7okKf_2>HBrv&jeVeZ0pX9zTA($K}=K2kWz##c!O( zKU@A;`Ps?$_p<1{&p(G8D)tkqfE|}Dld)h79U}D*Igl1?0~{!J6E*|ZT}qQx!8PbI z(h{N~q<~!jm12@G2`%jAORcM%z#OkL6dHsrlhD6YZ~Pgr3gg{VWU7b zWYTA#=yqtfC}JYk2vc|w90|*YK}9BHK)R$!3XU++&?(Xgk%Y8iPr_md?ICp#S&#_81m18bNEMDWV8c z!p>%f3Ht$+%Z|y`sjV?#ii3pRfK8WmlTxsXF=2`-VG=NK>6$bJ#TXU_R9z-b26eiU zW|d;?JQjvjeI|-Qhi;2zd?xIFEO1QN7#5C?kB^RydcEG^;bFVo-re1e<9KUpD-6S0 zt>$^&#>R%@IF(ApvaFSr6~i!=mX_w`=4NJQ_;=W7eDZxia|342omSS_mgUBusT`2Q zo$NOI5wk%487}1K&99B`Z>LXkc{H~7Yty+~Q!l>k9K5@HwetFXaq%F?7oNVl_HBFh q(Zb@+{PUL|+nbl}TTjZHH?0r%rh7k@Pk!ycxw3xo`t7?5c=!(tNVGHn diff --git a/sources/GhidraDocs/images/notes.gif b/sources/GhidraDocs/images/notes.gif deleted file mode 100644 index 38168ce839605d0604664240446f11f0dfd36f68..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 866 zcmc(ey-M6s5XDa*fh+_}iaO5eaLYBT1R`ODmvQ!Oi0*O(2DRLVhHw&{gt6t3A-NG&1s(DcM zun5brYFc!ATBK!KHA{xQEXuO1nlvI{4NZ7Kgw3o18!)D6r_KW>+|#{UA&a?3c!pOC zh6m+H&-7~j(4srav%K04+`=CGzyK5@5lx7IH8kM`5jF!2HegKCPMrr%MpRpgLKbt+ zjA~~Q3=hg#QEfD_kORi!G}huJ=HV9h;0Fev7>SSu3)awt7ev?$G}wSKO*?fSIMtb9 zB??*0y*fhjCvXxbQZghoQX&>|z<8X-TD-&#STc+s7=U6VLK-YsLla&QVKdNR1I9G% z)Oq0aFYy^ZA0J-6kZv?H-aYpjHdh=?2?Ze%_rQh$S ox3-V3H!prn55AA?ua3U#O%7HcH|B2t?!Oo^^BKu&iCH? zJy%qflaQM4(Ce3g^6yfUoY&H7J4|rn2C}~BVnuaSE4VV^oM{8FKaL1Ag-C-#`<`y? z1PKGVGrxkNFUgvDis=lt%sv$i!OG!&BeKS3XWVoe}&y> zj}QINiShUrDqjw|M9zwC?F0q@R#Ycz<|#M=u zFpj#h1zZ`?>z53me7x;H;DVcDV`-Il@ouJ?vT>U5Z(spU_Q%m_q#r?#N1vW?|NUbo zI++%ynx;k0Yq7hRB2rH7VQ@I2JNU}&H+N^hG*SpOMb2v(T5X4jH0TTmaq+=8;K9cy zlwRFR=AknjAkxrkJ3Moc{!f&TaHeC5<6qAC7Z^O`>TW}{+5i9m07*qoM6N<$f>ba1 A#{d8T diff --git a/sources/GhidraDocs/images/play_again.png b/sources/GhidraDocs/images/play_again.png deleted file mode 100644 index 11fad1a750982523a644416eb0f71a8d43c21421..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 563 zcmV-30?hr1P)mtOO)WGxIaq-e5;7!PZ;WBs5 z9Om3RqNDwl~*aCQBs2{wc`1bCoxffgdw&~i5#De-I_K$bS2jQKM>+Ww< zzvS{V+amSMJ$?H1$FNDH44|qtnYzla4}bHmUj^1xwK0>xfN&bv1a1QtfEsWxMp*;4 zRkdbZzGlGoAV5_o25<@Z02C*2oE99GjH+5!?H`I$;~R7kKHC5Q002ovPDHLkV1nxY B|JeWl diff --git a/sources/GhidraDocs/images/redo.png b/sources/GhidraDocs/images/redo.png deleted file mode 100644 index 88035efeec2a63f14a19433d0f82255e00ee4afd..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 187 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!73?$#)eFPFP2=EDU{r~?zkjc=%(9i&)fHaU; zv}jR7Ljy?SKLc1ENPt*CpgCP>15li?B*-tA!Qt7BG$6;))5S5Q;#TijYd!`A9;Sd9 zyAC}uy}M`MgbIepU%x!LYMxf?x0=YX+_1INQ0#_jcbwIMR|^*W+ovLKti`;>#4K+T P&=3YsS3j3^P6~8&^BNXqw$@AekqAsLX(YVXpvB V!;Q%=qJbtcc)I$ztaD0e0ssNkLMH$K diff --git a/sources/GhidraDocs/images/right.png b/sources/GhidraDocs/images/right.png deleted file mode 100644 index e6d41926bad3d250d62f3f82be954c50506c9590..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 190 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!73?$#)eFPFP2=EDU1=0;*+yJH;fV_r=0|yQ? zG&KANivMT$|DVBQ%P$}eWC1||yCM@%oV_H-FBmNFpFzr-*$pUU=IP=XQgJKU!@HTG z%_PN*NxG+y;h4qYX~!7Y()pGcewf3^Y$oxTfvuT$p~O1bs}5!*-i|yB*NZJ`b)!Ry QfhI6`y85}Sb4q9e0A+bS!vFvP diff --git a/sources/GhidraDocs/images/sitemap_color.png b/sources/GhidraDocs/images/sitemap_color.png deleted file mode 100644 index c64582bcd4f2c8d04451e6ca914ab06df6ac211c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 406 zcmV;H0crk;P) zk}*reKp2Lbf0AEO7ypA}amXNqYyp>Y;Fci-g4`}4WOLWH+9@cGQs}0F*iEjOG*W}4 zm%wK(ZQw2m_=MnyjyI)bdn5JojW9_ApWwoHWG)HAlBv>up3c{Bd7V)Nj z@iR8U_45rBpRWSDU5?-*Tkw3&gP5hEC2ui07*qoM6N<$f(bUU AHUIzs diff --git a/sources/GhidraDocs/images/table.png b/sources/GhidraDocs/images/table.png deleted file mode 100644 index abcd93689a08ec9bdbf0984927e8da06c043c7cd..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 566 zcmV-60?GY}P)>q?GuNnCdgP^*Bj5V_b?dAq2Ppn9^MBB^YUM zad0N-T{Ujg*A6d~mYV4na=hT4Nz+_}SGTgW|Iir!%$ z;@OGkWI6+j0H}~K4RYR%!7y|zM`O@*K>rL{*&}x3lR**HrMXC1->#slU>X|w!U1xQ zqc&Lm&p%aeyiM6U{&J)Zzehs6~qcg z1!K+DX=Sr^zrF)w?A~pFj1Mhkw|6ytB@m3*Ef1_!0J{5Ay8>LU$tBzlkaYmSjnfHU z4a{=AA%8R1Gc-$c-Bvue80=JFtfI~l^`U1lh3|Xx4yA~A;H@{^>pDl;EYVc{nu?-B zgeC*uF;DGCO|}YDsT!>58jRZ!uO%| z#aWyhLKQ+0j^vh5T5yV`V1?G+DzbUD4Iqkhjw~N8oy?y)Yaaf}M024fA2YfDrYonhIm@?o-n z-UASkj0YZ^uZk1(A&>yELViv$1v$q!d@xCtA0sdOD5KK@e4O~oYDmqN2hLGZe1M<7 z(;Ux_k(M<&2Okq^NFX7}co}ucMuw;Q8J!uUBKA~!+FL%aKO{HM-aTF&THSBNV#E@Y zZlYEZE93y5W*UijF$TuJP_pL<3oD7Y0Fm8(=VV)C#j3wAtu~o@15li?B*-tA!Qt7BG$6;^)5S5Q;#P8k0^bJiY0RE( z3b71HhFly>I~~qwL@)^HGZ?WrykcqKnIK|4gHc4QMe2Zt!xUczBN65o6N)Xj0gYhr MboFyt=akR{0Pznvr~m)} diff --git a/sources/GhidraDocs/images/up.png b/sources/GhidraDocs/images/up.png deleted file mode 100644 index b76e535c48e3f15f23a9376f72fbee71e19832e7..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 193 zcmeAS@N?(olHy`uVBq!ia0vp^0wB!73?$#)eFPFP2=EDU1=0;*+yJH;fV_r=0|yQ? zG&KANivMT$|DVBQ%P$}eWC1||yCM@%oV_H-FBmNFpFzr-*$pUU>FMGaQgLhPsg1l0 z3OvjQ*9RGXeeE#;0d&1g<&dsx@tpjRw00M!k1rYC|9;Q#?caBxBmXgYhpY0=W6 zGwe*95(&033 znV6pb{QW~UWoF`24rWfiTB}-ykKaEsY<#(qft8sRtc>k18^hlpe;EG!`@_J-%mUKI z01!a1Fo2ly=YOcGv?iCfga*U?kM|jFy}8Bk=j$JaUrfKis($|a$-u(H!tn3Ue}*sL zzx@M=0R#{{41luf>atqXwq$Q+V&!CFNIa6naP`ww25uH^u+u@d{slrF5nhJBzyC43 z{O}HJDnI}+fi?eONKutho3<`}4HF~le}3&}CKuXkrS{rWV60J{Lg$8R4Q zB)Oy*CYeoQFqbf6VEWC(AjK}l@bKj`hVQ?AyaDM22q3TvzW@BbZ`QHd41fOoVTe(Q zVc`11#qjpsTLuXx35G?^3m8O!E?9kX8$-W!AA_HQ55wh0w}659{SHVkKmaj-lX51I zmB6q$W>)uKyUEL_ba2u=qa+6i#ga&tM>5 z1=0%;K!|8$XYgHeXyGn4Mt0ZkfOZCNWiN(bKo5mb&G4W7EGq-&|KGoU%l x86y81q>hyfnDV~;KXjD=Ab=Pt&CUP;1^|O#NU%BBugCxZ002ovPDHLkV1ite$F2YX diff --git a/sources/GhidraDocs/languages/html/DefaultStyle.css b/sources/GhidraDocs/languages/html/DefaultStyle.css deleted file mode 100644 index 4e712f3..0000000 --- a/sources/GhidraDocs/languages/html/DefaultStyle.css +++ /dev/null @@ -1,92 +0,0 @@ -/* ### - * IP: GHIDRA - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -/* - WARNING! - Java Help Note: JavaHelp does not accept sizes (like in 'margin-top') in anything but - px (pixel) or with no type marking. - - The blockquote tag is used heavily to control indentation throughout the help docs. Place the - blockquote tag around other elements to create a standard indentation. The default values of - blockquote are: - - blockquote { - display: block; - margin-top: 1em; - margin-bottom: 1em; - margin-left: 40px; - margin-right: 40px; - } - -*/ - - -/* - Add some indentation for lists to show their relation to the preceding text. The value is - chosen based on the left margin of the body and the blockquote. -*/ -ul { margin-left: 50px; } -ol { margin-left: 50px; } -li { font-family:times new roman; font-size:14pt; margin-left: 5px; } - - -h1 { color:#000080; font-family:times new roman; font-size:36pt; font-style:italic; font-weight:bold; text-align:center; } -h2 { margin: 10px; margin-top: 20px; color:#984c4c; font-family:times new roman; font-size:18pt; font-weight:bold; } -h3 { margin-left: 10px; margin-top: 20px; color:#0000ff; font-family:times new roman; font-size:14pt; font-weight:bold; } -h4 { margin-left: 10px; margin-top: 20px; font-family:times new roman; font-size:14pt; font-style:italic; } -h5 { margin-left: 10px; margin-top: 20px; font-family:times new roman; font-size:12pt; font-style:italic; } - - -/* - A class to be used for showing screenshot style images. These images will have padding above - and below the image and will be centered. To apply this to a file path, use this syntax: -

-*/ -div.image { margin-top: 20px; margin-bottom: 40px; text-align: center; } - - - -/* - P tag code. Most of the help files nest P tags inside of blockquote tags (the was the - way it had been done in the beginning). The net effect is that the text is indented. In - modern HTML we would use CSS to do this. We need to support the Ghidra P tags, nested in - blockquote tags, as well as naked P tags. The following two lines accomplish this. Note - that the 'blockquote p' definition will inherit from the first 'p' definition. -*/ -p { margin-left: 40px; font-family:times new roman; font-size:14pt; } -blockquote p { margin-left: 10px; } -p.providedbyplugin { color:#7f7f7f; margin-left: 10px; font-size:14pt; margin-top:100px } -p.relatedtopic { color:#800080; margin-left: 10px; font-size:14pt; } -p.image { margin-top: 100; margin-bottom: 100; } - - -/* - We wish for a tables to have space between it and the preceding element, so that text - is not too close to the top of the table. Also, nest the table a bit so that it is clear - the table relates to the preceding text. -*/ -table { margin-left: 20px; margin-top: 10px; width: 80%;} -td { font-family:times new roman; font-size:14pt; vertical-align: top; } -th { font-family:times new roman; font-size:14pt; font-weight:bold; background-color: #EDF3FE; } - - - -/* - Code-like formatting for things such as file system paths and proper names of classes, - methods, etc. To apply this to a file path, use this syntax: - ... -*/ -code { color: black; font-weight: bold; font-family: courier new, monospace; font-size: 14pt; white-space: nowrap; } -code.path { color: #4682B4; font-weight: bold; font-family: courier new, monospace; font-size: 14pt; white-space: nowrap; } diff --git a/sources/GhidraDocs/languages/html/Diagram1.png b/sources/GhidraDocs/languages/html/Diagram1.png deleted file mode 100644 index 2ab61badc1b14b13c6a86335a02a12ded488a7cb..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 11652 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 L9A2Vx^U;3*djl?J diff --git a/sources/GhidraDocs/languages/html/Diagram3.png b/sources/GhidraDocs/languages/html/Diagram3.png deleted file mode 100644 index 157da0302678692bdf3dc4a4d51e4d97df4fad4f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 7139 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%0D8g>2*Ksx*@CPCmw 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 - - -Additional P-CODE Operations - - - - - - - - - -
- - - - - - - -
Additional P-CODE Operations
-Prev   Next -
-
-
-
-

-Additional P-CODE Operations

-

-The following opcodes are not generated as part of the raw translation -of a machine instruction into p-code operations, so none of them can be used -in a processor specification. But, they may be -introduced at a later stage by various analysis algorithms. -

-
-

-MULTIEQUAL

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode to merge from first basic block.
input1Varnode to merge from second basic block.
[...]Varnodes to merge from additional basic blocks.
outputMerged varnode for basic block containing op.
Semantic statement
Cannot be explicitly coded.
-
-

-This operation represents a copy from one or more possible -locations. From the compiler theory concept of Static Single Assignment form, this is -a phi-node. Each input corresponds to a control-flow path -flowing into the basic block containing the MULTIEQUAL. -The operator copies a particular input into the output varnode depending on what path -was last executed. All inputs and outputs must be the same size. -

-
-
-

-INDIRECT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode on which output may depend.
input1(special)Code iop of instruction causing effect.
outputVarnode containing result of effect.
Semantic statement
Cannot be explicitly coded.
-
-

-An INDIRECT operator copies input0 into output, -but the value may be altered in an indirect way -by the operation referred to by input1. The varnode input1 is not part of the -machine state but is really an internal reference to a specific p-code operator that -may be affecting the value of the output varnode. A special address space indicates -input1's use as an internal reference encoding. -An INDIRECT op is a placeholder for possible -indirect effects (such as pointer aliasing or missing code) when data-flow -algorithms do not have enough information to follow the data-flow directly. Like -the MULTIEQUAL, this op is used -for generating Static Single Assignment form. -

-

-A constant varnode (zero) for input0 is used by analysis to indicate that the output -of the INDIRECT is produced solely by the p-code operation -producing the indirect effect, and there is no possibility that the value existing prior -to the operation was used or preserved. -

-
-
-

-PTRADD

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode containing pointer to an array.
input1Varnode containing integer index.
input2(constant)Constant varnode indicating element size.
outputVarnode result containing pointer to indexed array entry.
Semantic statement
Cannot be explicitly coded.
-
-

-This operator serves as a more compact representation of the pointer calculation, -input0 + input1 * input2, but also indicates explicitly that -input0 is a reference to -an array data-type. Input0 is a pointer to the beginning of the array, input1 is an -index into the array, and input2 is a constant indicating the size of -an element in the array. As an -operation, PTRADD produces the -pointer value of the element at the indicated index in the array -and stores it in output. -

-
-
-

-PTRSUB

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode containing pointer to structure.
input1Varnode containing integer offset to a subcomponent.
outputVarnode result containing pointer to the subcomponent.
Semantic statement
Cannot be explicitly coded.
-
-

-A PTRSUB performs the simple pointer calculation, -input0 + input1, but also indicates explicitly that input0 is a -reference to a structured data-type -and one of its subcomponents is being accessed. Input0 is a pointer -to the beginning of the structure, and input1 is a byte offset to the subcomponent. -As an operation, PTRSUB produces a -pointer to the subcomponent and stores it in output. -

-
-
-

-CAST

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode containing value to be copied.
outputVarnode result of copy.
Semantic statement
Cannot be explicitly coded.
-
-

-A CAST performs identically to the COPY -operator but also indicates that there is a forced change in the data-types associated with the varnodes -at this point in the code. The value input0 is strictly copied into output; it is not a conversion cast. -This operator is intended specifically for when the value doesn't change but its -interpretation as a data-type changes at this point. -

-
-
-

-INSERT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode where the value will be inserted.
input1Integer varnode containing the value to insert.
position(constant)Constant indicating the bit position to insert at.
size(constant)Constant indicating the number of bits to insert.
outputVarnode result containing input0 with input1 inserted.
Semantic statement
Cannot be explicitly coded.
-
-

-The values position and size must be constants. -The least significant size bits from input1 are -inserted into input0, overwriting a range of bits of the same size, -but leaving any other bits in input0 unchanged. The least significant bit of the overwritten -range is given by position, where bits in index0 are labeled from least significant -to most significant, starting at 0. The value obtained after this overwriting is returned -as output. -Varnodes input0 and output must be the same size and are intended to be the same varnode. -The value size must be not be bigger than the varnode input1, and -size + position must not be bigger than the varnode input0. -

-

-This operation is never generated as raw p-code, even though it is equivalent -to SLEIGH bitrange syntax such as input0[10,1] = input1. -

-
-
-

-EXTRACT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode to extract a value from.
position(constant)Constant indicating the bit position to extract from.
size(constant)Constant indicating the number of bits to extract.
outputVarnode result containing the extracted value.
Semantic statement
Cannot be explicitly coded.
-
-

-The values position and size must be constants. -The operation extracts size bits from input0 and returns it in output. -The position indicates the least significant bit in the range being extracted, with -the bits in input0 labeled from least to most significant, starting at 0. The varnodes input0 and output -can be different sizes, and the extracted value is zero extended into output. -The value size must not be bigger than the varnode output, and -size + position must not be bigger -than the varnode input0. -

-

-This operation is never generated as raw p-code, even though it is equivalent -to SLEIGH bitrange syntax such as output = input0[10,1]. -

-
-
-
-
- - - - - - - - - - - -
-Prev   Next -
Pseudo P-CODE Operations Home Syntax Reference
-
- - diff --git a/sources/GhidraDocs/languages/html/additionalpcode.md b/sources/GhidraDocs/languages/html/additionalpcode.md deleted file mode 100644 index 0c1aa84..0000000 --- a/sources/GhidraDocs/languages/html/additionalpcode.md +++ /dev/null @@ -1,436 +0,0 @@ ---- -status: collected -title: Additional P-CODE Operations -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/additionalpcode.html ---- - -::: {.navheader} -Additional P-CODE Operations -::: - -[Prev](pseudo-ops.html)  - -  - - [Next](reference.html) - ------------------------------------------------------------------------- - -::: {.sect1} -::: {.titlepage} -
- -
- -[]{#additionalpcode}Additional P-CODE Operations {#additional-p-code-operations .title style="clear: both"} ------------------------------------------------- - -
- -
-::: - -The following opcodes are not generated as part of the raw translation -of a machine instruction into p-code operations, so none of them can be -used in a processor specification. But, they may be introduced at a -later stage by various analysis algorithms. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#cpui_multiequal}MULTIEQUAL {#multiequal .title} - -
- -
-::: - -::: {.informalexample} -::: {.table} -[]{#multiequal.htmltable} - -[**Parameters**]{.bold} -::: -::: -::: -::: - -[**Description**]{.bold} - -input0 - -Varnode to merge from first basic block. - -input1 - -Varnode to merge from second basic block. - -\[\...\] - -Varnodes to merge from additional basic blocks. - -output - -Merged varnode for basic block containing op. - -[**Semantic statement**]{.bold} - -[*Cannot be explicitly coded.*]{.emphasis} - -This operation represents a copy from one or more possible locations. -From the compiler theory concept of Static Single Assignment form, this -is a [**phi-node**]{.bold}. Each input corresponds to a control-flow -path flowing into the basic block containing the -[**MULTIEQUAL**]{.bold}. The operator copies a particular input into the -output varnode depending on what path was last executed. All inputs and -outputs must be the same size. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#cpui_indirect}INDIRECT {#indirect .title} - -
- -
-::: - -::: {.informalexample} -::: {.table} -[]{#indirect.htmltable} - -[**Parameters**]{.bold} -::: -::: -::: - -[**Description**]{.bold} - -input0 - -Varnode on which output may depend. - -input1 - -([**special**]{.bold}) - -Code iop of instruction causing effect. - -output - -Varnode containing result of effect. - -[**Semantic statement**]{.bold} - -[*Cannot be explicitly coded.*]{.emphasis} - -An [**INDIRECT**]{.bold} operator copies input0 into output, but the -value may be altered in an indirect way by the operation referred to by -input1. The varnode input1 is not part of the machine state but is -really an internal reference to a specific p-code operator that may be -affecting the value of the output varnode. A special address space -indicates input1\'s use as an internal reference encoding. An -[**INDIRECT**]{.bold} op is a placeholder for possible indirect effects -(such as pointer aliasing or missing code) when data-flow algorithms do -not have enough information to follow the data-flow directly. Like the -[**MULTIEQUAL**]{.bold}, this op is used for generating Static Single -Assignment form. - -A constant varnode (zero) for input0 is used by analysis to indicate -that the output of the [**INDIRECT**]{.bold} is produced solely by the -p-code operation producing the indirect effect, and there is no -possibility that the value existing prior to the operation was used or -preserved. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#cpui_ptradd}PTRADD {#ptradd .title} - -
- -
-::: - -::: {.informalexample} -::: {.table} -[]{#ptradd.htmltable} - -[**Parameters**]{.bold} -::: -::: -::: - -[**Description**]{.bold} - -input0 - -Varnode containing pointer to an array. - -input1 - -Varnode containing integer index. - -input2 - -([**constant**]{.bold}) - -Constant varnode indicating element size. - -output - -Varnode result containing pointer to indexed array entry. - -[**Semantic statement**]{.bold} - -[*Cannot be explicitly coded.*]{.emphasis} - -This operator serves as a more compact representation of the pointer -calculation, input0 + input1 \* input2, but also indicates explicitly -that input0 is a reference to an array data-type. Input0 is a pointer to -the beginning of the array, input1 is an index into the array, and -input2 is a constant indicating the size of an element in the array. As -an operation, [**PTRADD**]{.bold} produces the pointer value of the -element at the indicated index in the array and stores it in output. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#cpui_ptrsub}PTRSUB {#ptrsub .title} - -
- -
-::: - -::: {.informalexample} -::: {.table} -[]{#ptrsub.htmltable} - -[**Parameters**]{.bold} -::: -::: -::: - -[**Description**]{.bold} - -input0 - -Varnode containing pointer to structure. - -input1 - -Varnode containing integer offset to a subcomponent. - -output - -Varnode result containing pointer to the subcomponent. - -[**Semantic statement**]{.bold} - -[*Cannot be explicitly coded.*]{.emphasis} - -A [**PTRSUB**]{.bold} performs the simple pointer calculation, input0 + -input1, but also indicates explicitly that input0 is a reference to a -structured data-type and one of its subcomponents is being accessed. -Input0 is a pointer to the beginning of the structure, and input1 is a -byte offset to the subcomponent. As an operation, [**PTRSUB**]{.bold} -produces a pointer to the subcomponent and stores it in output. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#cpui_cast}CAST {#cast .title} - -
- -
-::: - -::: {.informalexample} -::: {.table} -[]{#cast.htmltable} - -[**Parameters**]{.bold} -::: -::: -::: - -[**Description**]{.bold} - -input0 - -Varnode containing value to be copied. - -output - -Varnode result of copy. - -[**Semantic statement**]{.bold} - -[*Cannot be explicitly coded.*]{.emphasis} - -A [**CAST**]{.bold} performs identically to the [**COPY**]{.bold} -operator but also indicates that there is a forced change in the -data-types associated with the varnodes at this point in the code. The -value input0 is strictly copied into output; it is not a conversion -cast. This operator is intended specifically for when the value doesn\'t -change but its interpretation as a data-type changes at this point. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#cpui_insert}INSERT {#insert .title} - -
- -
-::: - -::: {.informalexample} -::: {.table} -[]{#insert.htmltable} - -[**Parameters**]{.bold} -::: -::: -::: - -[**Description**]{.bold} - -input0 - -Varnode where the value will be inserted. - -input1 - -Integer varnode containing the value to insert. - -position - -([**constant**]{.bold}) - -Constant indicating the bit position to insert at. - -size - -([**constant**]{.bold}) - -Constant indicating the number of bits to insert. - -output - -Varnode result containing input0 with input1 inserted. - -[**Semantic statement**]{.bold} - -[*Cannot be explicitly coded.*]{.emphasis} - -The values [*position*]{.emphasis} and [*size*]{.emphasis} must be -constants. The least significant [*size*]{.emphasis} bits from input1 -are inserted into input0, overwriting a range of bits of the same size, -but leaving any other bits in input0 unchanged. The least significant -bit of the overwritten range is given by [*position*]{.emphasis}, where -bits in index0 are labeled from least significant to most significant, -starting at 0. The value obtained after this overwriting is returned as -output. Varnodes input0 and output must be the same size and are -intended to be the same varnode. The value [*size*]{.emphasis} must be -not be bigger than the varnode input1, and [*size*]{.emphasis} + -[*position*]{.emphasis} must not be bigger than the varnode input0. - -This operation is never generated as raw p-code, even though it is -equivalent to SLEIGH [**bitrange**]{.bold} syntax such as input0\[10,1\] -= input1. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#cpui_extract}EXTRACT {#extract .title} - -
- -
-::: - -::: {.informalexample} -::: {.table} -[]{#extract.htmltable} - -[**Parameters**]{.bold} -::: -::: -::: - -[**Description**]{.bold} - -input0 - -Varnode to extract a value from. - -position - -([**constant**]{.bold}) - -Constant indicating the bit position to extract from. - -size - -([**constant**]{.bold}) - -Constant indicating the number of bits to extract. - -output - -Varnode result containing the extracted value. - -[**Semantic statement**]{.bold} - -[*Cannot be explicitly coded.*]{.emphasis} - -The values [*position*]{.emphasis} and [*size*]{.emphasis} must be -constants. The operation extracts [*size*]{.emphasis} bits from input0 -and returns it in output. The [*position*]{.emphasis} indicates the -least significant bit in the range being extracted, with the bits in -input0 labeled from least to most significant, starting at 0. The -varnodes input0 and output can be different sizes, and the extracted -value is zero extended into output. The value [*size*]{.emphasis} must -not be bigger than the varnode output, and [*size*]{.emphasis} + -[*position*]{.emphasis} must not be bigger than the varnode input0. - -This operation is never generated as raw p-code, even though it is -equivalent to SLEIGH [**bitrange**]{.bold} syntax such as output = -input0\[10,1\]. - -::: {.navfooter} - ------------------------------------------------------------------------- - - --------------------------- ----------------------- ------------------------- - [Prev](pseudo-ops.html)     [Next](reference.html) - Pseudo P-CODE Operations  [Home](pcoderef.html)  Syntax Reference - --------------------------- ----------------------- ------------------------- -::: diff --git a/sources/GhidraDocs/languages/html/languages.css b/sources/GhidraDocs/languages/html/languages.css deleted file mode 100644 index d0a955c..0000000 --- a/sources/GhidraDocs/languages/html/languages.css +++ /dev/null @@ -1,26 +0,0 @@ -/* ### - * IP: GHIDRA - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -/* - This file contains non-Ghidra style sheet markup. This file will be loaded in addition to - FrontPage.css. -*/ - -h5 { margin-left: 10px; } -div.informalexample { margin-left: 50px; } -div.example-contents { margin-left: 50px; } -span.term { font-family:times new roman; font-size:14pt; font-weight:bold; } -span.code { font-weight: bold; font-family: courier new; font-size: 14pt; color:#000000; } - diff --git a/sources/GhidraDocs/languages/html/pcodedescription.html b/sources/GhidraDocs/languages/html/pcodedescription.html deleted file mode 100644 index 067fc2b..0000000 --- a/sources/GhidraDocs/languages/html/pcodedescription.html +++ /dev/null @@ -1,3040 +0,0 @@ - - - -P-Code Operation Reference - - - - - - - - - -
- - - - - - - -
P-Code Operation Reference
-Prev   Next -
-
-
-
-

-P-Code Operation Reference

-

-For each possible p-code operation, we give a brief description and -provide a table that lists the inputs that must be present and their -meaning. We also list the basic syntax for denoting the operation when -describing semantics in a processor specification file. -

-
-

-COPY

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Source varnode.
outputDestination varnode.
Semantic statement
output = input0;
-
-

-Copy a sequence of contiguous bytes from anywhere to anywhere. Size of -input0 and output must be the same. -

-
-
-

-LOAD

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0(special)Constant ID of space to load from.
input1Varnode containing pointer offset to data.
outputDestination varnode.
Semantic statement
output = *input1;
output = *[input0]input1;
-
-

-This instruction loads data from a dynamic location into the output -variable by dereferencing a pointer. The “pointer” comes in two -pieces. One piece, input1, is a normal variable containing the offset -of the object being pointed at. The other piece, input0, is a constant -indicating the space into which the offset applies. The data in input1 -is interpreted as an unsigned offset and should have the same size as -the space referred to by the ID, i.e. a 4-byte address space requires -a 4-byte offset. The space ID is not manually entered by a user but is -automatically generated by the p-code compiler. The amount of data -loaded by this instruction is determined by the size of the output -variable. It is easy to confuse the address space of the output and -input1 variables and the Address Space represented by the ID, which -could all be different. Unlike many programming models, there are -multiple spaces that a “pointer” can refer to, and so an extra ID is -required. -

-

-It is possible for the addressable unit of an address -space to be bigger than a single byte. If -the wordsize attribute of the space -given by the ID is bigger than one, the offset into the space obtained -from input1 must be multiplied by this value in order to obtain the -correct byte offset into the space. -

-
-
-

-STORE

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0(special)Constant ID of space to store into.
input1Varnode containing pointer offset of destination.
input2Varnode containing data to be stored.
Semantic statement
*input1 = input2;
*[input0]input1 = input2;
-
-

-This instruction is the complement -of LOAD. The data in the variable -input2 is stored at a dynamic location by dereferencing a pointer. As -with LOAD, the “pointer” comes in two -pieces: a space ID part, and an offset variable. The size of input1 -must match the address space specified by the ID, and the amount of -data stored is determined by the size of input2. -

-

-Its possible for the addressable unit of an address -space to be bigger than a single byte. If -the wordsize attribute of the space -given by the ID is bigger than one, the offset into the space obtained -from input1 must be multiplied by this value in order to obtain the -correct byte offset into the space. -

-
-
-

-BRANCH

-
- ---- - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0(special)Location of next instruction to execute.
Semantic statement
goto input0;
-
-

-This is an absolute jump instruction. The varnode parameter input0 encodes -the destination address (address space and offset) of the jump. The varnode is not -treated as a variable for this instruction and does not store the destination. Its address space and -offset are the destination. The size of input0 is irrelevant. -

-

-Confusion about the meaning of this instruction can result because of -the translation from machine instructions to p-code. The destination of the jump is -a machine address and refers to -the machine instruction at that address. When -attempting to determine which p-code instruction is executed next, the -rule is: execute the first p-code instruction resulting from the -translation of the machine instruction(s) at that address. The -resulting p-code instruction may not be attached directly to the -indicated address due to NOP instructions and delay slots. -

-

-If input0 is constant, i.e. its address space -is the constant -address space, then it encodes a p-code relative branch. -In this case, the offset of input0 is considered a relative offset into -the indexed list of p-code operations corresponding to the translation -of the current machine instruction. This allows branching within the -operations forming a single instruction. For example, if -the BRANCH occurs as the pcode -operation with index 5 for the instruction, it can branch to operation -with index 8 by specifying a constant destination “address” of -3. Negative constants can be used for backward branches. -

-
-
-

-CBRANCH

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0(special)Location of next instruction to execute.
input1Boolean varnode indicating whether branch is taken.
Semantic statement
if (input1) goto input0;
-
-

-This is a conditional branch instruction where the dynamic condition -for taking the branch is determined by the 1 byte variable input1. If -this variable is non-zero, the condition is -considered true and the branch is taken. As in -the BRANCH instruction the parameter -input0 is not treated as a variable but as an address and is -interpreted in the same way. Furthermore, a constant space address is -also interpreted as a relative address so that -a CBRANCH can do p-code -relative branching. See the discussion for the -BRANCH operation. -

-
-
-

-BRANCHIND

-
- ---- - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode containing offset of next instruction.
Semantic statement
goto [input0];
-
-

-This is an indirect branching instruction. The address to branch to is -determined dynamically (at runtime) by examining the contents of the -variable input0. As this instruction is currently defined, the -variable input0 only contains the offset of the -destination, and the address space is taken from the address -associated with the branching instruction -itself. So execution can only branch within the same address -space via this instruction. The size of the variable input0 -must match the size of offsets for the current address space. P-code -relative branching is not possible with BRANCHIND. -

-
-
-

-CALL

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0(special)Location of next instruction to execute.
[input1]First parameter to call (never present in raw p-code)
...Additional parameters to call (never present in raw p-code)
Semantic statement
call [input0];
-
-

-This instruction is semantically equivalent to -the BRANCH instruction. -Beware: This instruction does not -behave like a typical function call. In particular, there is no -internal stack in p-code for saving the return address. Use of this -instruction instead of BRANCH is -intended to provide a hint to algorithms that try to follow code flow. -It indicates that the original machine instruction, of which this -p-code instruction is only a part, is intended to be a function -call. The p-code instruction does not implement the full semantics of -the call itself; it only implements the final branch. -

-

-In the raw p-code translation process, this operation can only take -input0, but in follow-on analysis, it can take arbitrary additional inputs. -These represent (possibly partial) recovery of the parameters being -passed to the logical call represented by this -operation. These additional parameters have no effect on the original -semantics of the raw p-code but naturally hold the varnode values flowing -into the call. -

-
-
-

-CALLIND

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode containing offset of next instruction.
[input1]First parameter to call (never present in raw p-code)
...Additional parameters to call (never present in raw p-code)
Semantic statement
call [input0];
-
-

-This instruction is semantically equivalent to -the BRANCHIND instruction. It does -not perform a function call in the usual sense of the term. It merely -indicates that the original machine instruction is intended to be an -indirect call. See the discussion for -the CALL instruction. -

-

As with the CALL instruction, -this operation may take additional inputs when not in raw form, representing -the parameters being passed to the logical call. -

-
-
-

-RETURN

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode containing offset of next instruction.
[input1]Value returned from call (never present in raw p-code)
Semantic statement
return [input0];
-
-

-This instruction is semantically equivalent to -the BRANCHIND instruction. It does -not perform a return from subroutine in the usual sense of the -term. It merely indicates that the original machine instruction is -intended to be a return from subroutine. See the discussion for -the CALL instruction. -

-

-Similarly to CALL and CALLIND, -this operation may take an additional input when not in raw form. If input1 is -present it represents the value being returned by this operation. -This is used by analysis algorithms to hold the value logically flowing back to the parent -subroutine. -

-
-
-

-PIECE

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode containing most significant data to merge.
input1Varnode containing least significant data to merge.
outputVarnode to contain resulting concatenation.
Semantic statement
Cannot (currently) be explicitly coded
-
-

-This is a concatenation operator that understands the endianness of the -data. The size of input0 and input1 must add up to the size of -output. The data from the inputs is concatenated in such a way that, -if the inputs and output are considered integers, the first input -makes up the most significant part of the output. -

-
-
-

-SUBPIECE

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode containing source data to truncate.
input1(constant)Constant indicating how many bytes to truncate.
outputVarnode to contain result of truncation.
Semantic statement
output = input0(input1);
-
-

-This is a truncation operator that understands the endianness of the -data. Input1 indicates the number of least significant bytes of input0 -to be thrown away. Output is then filled with any remaining bytes of -input0 up to the size of output. If the size of -output is smaller than the size of input0 minus the constant input1, -then the additional most significant bytes of input0 will also be -truncated. -

-
-
-

-POPCOUNT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Input varnode to count.
outputResulting integer varnode containing count.
Semantic statement
output = popcount(input0);
-
-

-This is a bit count (population count) operator. Within the binary representation of the value -contained in the input varnode, the number of 1 bits are counted and then returned in the -output varnode. A value of 0 returns 0, a 4-byte varnode containing the value 232-1 -(all bits set) returns 32, for instance. The input and output varnodes can have any size. The resulting -count is zero extended into the output varnode. -

-
-
-

-LZCOUNT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Input varnode to count.
outputResulting integer varnode containing count.
Semantic statement
output = lzcount(input0);
-
-

-This operator counts the number of zeros starting at the most significant bit. -For instance, for a 4-byte varnode, a value of 0 returns 32, a value of 1 -returns 31, and the value 231 returns 0. -The resulting count is zero extended into the output varnode. -

-
-
-

-INT_EQUAL

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode to compare.
input1Second varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 == input1;
-
-

-This is the integer equality operator. Output is -assigned true, if input0 equals input1. It works -for signed, unsigned, or any contiguous data where the match must be -down to the bit. Both inputs must be the same size, and the output -must have a size of 1. -

-
-
-

-INT_NOTEQUAL

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode to compare.
input1Second varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 != input1;
-
-

-This is the integer inequality operator. Output is -assigned true, if input0 does not equal -input1. It works for signed, unsigned, or any contiguous data where -the match must be down to the bit. Both inputs must be the same size, -and the output must have a size of 1. -

-
-
-

-INT_LESS

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First unsigned varnode to compare.
input1Second unsigned varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 < input1;
-
-

-This is an unsigned integer comparison operator. If the unsigned -integer input0 is strictly less than the unsigned integer input1, -output is set to true. Both inputs must be the -same size, and the output must have a size of 1. -

-
-
-

-INT_SLESS

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First signed varnode to compare.
input1Second signed varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 s< input1;
-
-

-This is a signed integer comparison operator. If the signed integer -input0 is strictly less than the signed integer input1, output is set -to true. Both inputs must be the same size, and -the output must have a size of 1. -

-
-
-

-INT_LESSEQUAL

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First unsigned varnode to compare.
input1Second unsigned varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 <= input1;
-
-

-This is an unsigned integer comparison operator. If the unsigned -integer input0 is less than or equal to the unsigned integer input1, -output is set to true. Both inputs must be the -same size, and the output must have a size of 1. -

-
-
-

-INT_SLESSEQUAL

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First signed varnode to compare.
input1Second signed varnode to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 s<= input1;
-
-

-This is a signed integer comparison operator. If the signed integer -input0 is less than or equal to the signed integer input1, output is -set to true. Both inputs must be the same size, -and the output must have a size of 1. -

-
-
-

-INT_ZEXT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode to zero-extend.
outputVarnode containing zero-extended result.
Semantic statement
output = zext(input0);
-
-

-Zero-extend the data in input0 and store the result in output. Copy -all the data from input0 into the least significant positions of -output. Fill out any remaining space in the most significant bytes of -output with zero. The size of output must be strictly bigger than the -size of input. -

-
-
-

-INT_SEXT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode to sign-extend.
outputVarnode containing sign-extended result.
Semantic statement
output = sext(input0);
-
-

-Sign-extend the data in input0 and store the result in output. Copy -all the data from input0 into the least significant positions of -output. Fill out any remaining space in the most significant bytes of -output with either zero or all ones (0xff) depending on the most -significant bit of input0. The size of output must be strictly bigger -than the size of input0. -

-
-
-

-INT_ADD

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode to add.
input1Second varnode to add.
outputVarnode containing result of integer addition.
Semantic statement
output = input0 + input1;
-
-

-This is standard integer addition. It works for either unsigned or -signed interpretations of the integer encoding (twos complement). Size -of both inputs and output must be the same. The addition is of course -performed modulo this size. Overflow and carry conditions are -calculated by other -operations. See INT_CARRY -and INT_SCARRY. -

-
-
-

-INT_SUB

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode input.
input1Varnode to subtract from first.
outputVarnode containing result of integer subtraction.
Semantic statement
output = input0 - input1;
-
-

-This is standard integer subtraction. It works for either unsigned or -signed interpretations of the integer encoding (twos complement). Size -of both inputs and output must be the same. The subtraction is of -course performed modulo this size. Overflow and borrow conditions are -calculated by other -operations. See INT_SBORROW -and INT_LESS. -

-
-
-

-INT_CARRY

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode to add.
input1Second varnode to add.
outputBoolean result containing carry condition.
Semantic statement
output = carry(input0,input1);
-
-

-This operation checks for unsigned addition overflow or carry -conditions. If the result of adding input0 and input1 as unsigned -integers overflows the size of the varnodes, output is -assigned true. Both inputs must be the same size, -and output must be size 1. -

-
-
-

-INT_SCARRY

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode to add.
input1Second varnode to add.
outputBoolean result containing signed overflow condition.
Semantic statement
output = scarry(input0,input1);
-
-

-This operation checks for signed addition overflow or carry -conditions. If the result of adding input0 and input1 as signed -integers overflows the size of the varnodes, output is -assigned true. Both inputs must be the same size, -and output must be size 1. -

-
-
-

-INT_SBORROW

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode input.
input1Varnode to subtract from first.
outputBoolean result containing signed overflow condition.
Semantic statement
output = sborrow(input0,input1);
-
-

-This operation checks for signed subtraction overflow or borrow -conditions. If the result of subtracting input1 from input0 as signed -integers overflows the size of the varnodes, output is -assigned true. Both inputs must be the same size, -and output must be size 1. Note that the equivalent unsigned -subtraction overflow condition -is INT_LESS. -

-
-
-

-INT_2COMP

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First to negate.
outputVarnode result containing twos complement.
Semantic statement
output = -input0;
-
-

-This is the twos complement or arithmetic negation operation. Treating input0 as a signed -integer, the result is the same integer value but with the opposite sign. This is equivalent -to doing a bitwise negation of input0 and then adding one. Both input0 and output must -be the same size. -

-
-
-

-INT_NEGATE

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode to negate.
outputVarnode result containing bitwise negation.
Semantic statement
output = ~input0;
-
-

-This is the bitwise negation operation. Output is the result of taking -every bit of input0 and flipping it. Both input0 and output must be -the same size. -

-
-
-

-INT_XOR

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First input to exclusive-or.
input1Second input to exclusive-or.
outputVarnode result containing exclusive-or of inputs.
Semantic statement
output = input0 ^ input1;
-
-

-This operation performs a logical Exclusive-Or on the bits of input0 -and input1. Both inputs and output must be the same size. -

-
-
-

-INT_AND

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First input to logical-and.
input1Second input to logical-and.
outputVarnode result containing logical-and of inputs.
Semantic statement
output = input0 & input1;
-
-

-This operation performs a Logical-And on the bits of input0 and input1. Both inputs and -output must be the same size. -

-
-
-

-INT_OR

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First input to logical-or.
input1Second input to logical-or.
outputVarnode result containing logical-or of inputs.
Semantic statement
output = input0 | input1;
-
-

-This operation performs a Logical-Or on the bits of input0 and input1. Both inputs and -output must be the same size. -

-
-
-

-INT_LEFT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode input being shifted.
input1Varnode indicating number of bits to shift.
outputVarnode containing shifted result.
Semantic statement
output = input0 << input1;
-
-

-This operation performs a left shift on input0. The value given by -input1, interpreted as an unsigned integer, indicates the number of -bits to shift. The vacated (least significant) bits are filled with -zero. If input1 is zero, no shift is performed and input0 is copied -into output. If input1 is larger than the number of bits in output, -the result is zero. Both input0 and output must be the same -size. Input1 can be any size. -

-
-
-

-INT_RIGHT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode input being shifted.
input1Varnode indicating number of bits to shift.
outputVarnode containing shifted result.
Semantic statement
output = input0 >> input1;
-
-

-This operation performs an unsigned (logical) right shift on -input0. The value given by input1, interpreted as an unsigned integer, -indicates the number of bits to shift. The vacated (most significant) -bits are filled with zero. If input1 is zero, no shift is performed -and input0 is copied into output. If input1 is larger than the number -of bits in output, the result is zero. Both input0 and output must be -the same size. Input1 can be any size. -

-
-
-

-INT_SRIGHT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode input being shifted.
input1Varnode indicating number of bits to shift.
outputVarnode containing shifted result.
Semantic statement
output = input0 s>> input1;
-
-

-This operation performs a signed (arithmetic) right shift on -input0. The value given by input1, interpreted as an unsigned integer, -indicates the number of bits to shift. The vacated bits are filled -with the original value of the most significant (sign) bit of input0. -If input1 is zero, no shift is performed and input0 is copied into -output. If input1 is larger than the number of bits in output, the -result is zero or all 1-bits (-1), depending on the original sign of -input0. Both input0 and output must be the same size. Input1 can be -any size. -

-
-
-

-INT_MULT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode to be multiplied.
input1Second varnode to be multiplied.
outputVarnode containing result of multiplication.
Semantic statement
output = input0 * input1;
-
-

-This is an integer multiplication operation. The result of multiplying -input0 and input1, viewed as integers, is stored in output. Both -inputs and output must be the same size. The multiplication is -performed modulo the size, and the result is true for either a signed -or unsigned interpretation of the inputs and output. To get extended -precision results, the inputs must first by zero-extended or -sign-extended to the desired size. -

-
-
-

-INT_DIV

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode input.
input1Second varnode input (divisor).
outputVarnode containing result of division.
Semantic statement
output = input0 / input1;
-
-

-This is an unsigned integer division operation. Divide input0 by -input1, truncating the result to the nearest integer, and store the -result in output. Both inputs and output must be the same size. There -is no handling of division by zero. To simulate a processor’s handling -of a division-by-zero trap, other operations must be used before -the INT_DIV. -

-
-
-

-INT_REM

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode input.
input1Second varnode input (divisor).
outputVarnode containing remainder of division.
Semantic statement
output = input0 % input1;
-
-

-This is an unsigned integer remainder operation. The remainder of -performing the unsigned integer division of input0 and input1 is put -in output. Both inputs and output must be the same size. If q = -input0/input1, using the INT_DIV -operation defined above, then output satisfies the equation q*input1 + -output = input0, using the INT_MULT -and INT_ADD operations. -

-
-
-

-INT_SDIV

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode input.
input1Second varnode input (divisor).
outputVarnode containing result of signed division.
Semantic statement
output = input0 s/ input1;
-
-

-This is a signed integer division operation. The resulting integer is -the one closest to the rational value input0/input1 but which is still -smaller in absolute value. Both inputs and output must be the same -size. There is no handling of division by zero. To simulate a -processor’s handling of a division-by-zero trap, other operations must -be used before the INT_SDIV. -

-
-
-

-INT_SREM

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First varnode input.
input1Second varnode input (divisor).
outputVarnode containing remainder of signed division.
Semantic statement
output = input0 s% input1;
-
-

-This is a signed integer remainder operation. The remainder of -performing the signed integer division of input0 and input1 is put in -output. Both inputs and output must be the same size. If q = input0 s/ -input1, using the INT_SDIV operation -defined above, then output satisfies the equation q*input1 + output = -input0, using the INT_MULT -and INT_ADD operations. -

-
-
-

-BOOL_NEGATE

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Boolean varnode to negate.
outputBoolean varnode containing result of negation.
Semantic statement
output = !input0;
-
-

-This is a logical negate operator, where we assume input0 and output -are boolean values. It puts the logical complement of input0, treated -as a single bit, into output. Both input0 and output are size -1. Boolean values are implemented with a full byte, but are still -considered to only support a value of true -or false. -

-
-
-

-BOOL_XOR

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First boolean input to exclusive-or.
input1Second boolean input to exclusive-or.
outputBoolean varnode containing result of exclusive-or.
Semantic statement
output = input0 ^^ input1;
-
-

-This is an Exclusive-Or operator, where we assume the inputs and -output are boolean values. It puts the exclusive-or of input0 and -input1, treated as single bits, into output. Both inputs and output -are size 1. Boolean values are implemented with a full byte, but are -still considered to only support a value of true -or false. -

-
-
-

-BOOL_AND

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First boolean input to logical-and.
input1Second boolean input to logical-and.
outputBoolean varnode containing result of logical-and.
Semantic statement
output = input0 && input1;
-
-

-This is a Logical-And operator, where we assume the inputs and output -are boolean values. It puts the logical-and of input0 and input1, -treated as single bits, into output. Both inputs and output are size -1. Boolean values are implemented with a full byte, but are still -considered to only support a value of true -or false. -

-
-
-

-BOOL_OR

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First boolean input to logical-or.
input1Second boolean input to logical-or.
outputBoolean varnode containing result of logical-or.
Semantic statement
output = input0 || input1;
-
-

-This is a Logical-Or operator, where we assume the inputs and output -are boolean values. It puts the logical-or of input0 and input1, -treated as single bits, into output. Both inputs and output are size -1. Boolean values are implemented with a full byte, but are still -considered to only support a value of true -or false. -

-
-
-

-FLOAT_EQUAL

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First floating-point input to compare.
input1Second floating-point input to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 f== input1;
-
-

-This is a floating-point equality operator. Output is -assigned true, if input0 and input1 are -considered equal as floating-point values. Both inputs must be the -same size, and output is size 1. If either input -is NaN, output is set -to false. -

-
-
-

-FLOAT_NOTEQUAL

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First floating-point input to compare.
input1Second floating-point input to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 f!= input1;
-
-

-This is a floating-point inequality operator. Output is -assigned true, if input0 and input1 are not -considered equal as floating-point values. Both inputs must be the -same size, and output is size 1. If either input -is NaN, output is set -to false. -

-
-
-

-FLOAT_LESS

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First floating-point input to compare.
input1Second floating-point input to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 f< input1;
-
-

-This is a comparison operator, where both inputs are considered -floating-point values. Output is assigned true, -if input0 is less than input1. Both inputs must be the same size, and -output is size 1. If either input -is NaN, output is set -to false. -

-
-
-

-FLOAT_LESSEQUAL

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First floating-point input to compare.
input1Second floating-point input to compare.
outputBoolean varnode containing result of comparison.
Semantic statement
output = input0 f<= input1;
-
-

-This is a comparison operator, where both inputs are considered -floating-point values. Output is assigned true, -if input0 is less than or equal to input1. Both inputs must be the -same size, and output is size 1. If either input -is NaN, output is set -to false. -

-
-
-

-FLOAT_ADD

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First floating-point input to add.
input1Second floating-point input to add.
outputVarnode containing result of addition.
Semantic statement
output = input0 f+ input1;
-
-

-This is a floating-point addition operator. The result of adding -input0 and input1 as floating-point values is stored in output. Both -inputs and output must be the same size. If either input -is NaN, output is set -to NaN. If any overflow condition -occurs, output is set to NaN. -

-
-
-

-FLOAT_SUB

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First floating-point input.
input1Floating-point varnode to subtract from first.
outputVarnode containing result of subtraction.
Semantic statement
output = input0 f- input1;
-
-

-This is a floating-point subtraction operator. The result of -subtracting input1 from input0 as floating-point values is stored in -output. Both inputs and output must be the same size. If either input -is NaN, output is set -to NaN. If any overflow condition -occurs, output is set to NaN. -

-
-
-

-FLOAT_MULT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First floating-point input to multiply.
input1Second floating-point input to multiply.
outputVarnode containing result of multiplication.
Semantic statement
output = input0 f* input1;
-
-

-This is a floating-point multiplication operator. The result of -multiplying input0 to input1 as floating-point values is stored in -output. Both inputs and output must be the same size. If either input -is NaN, output is set -to NaN. If any overflow condition -occurs, output is set to NaN. -

-
-
-

-FLOAT_DIV

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0First floating-point input.
input1Second floating-point input (divisor).
outputVarnode containing result of division.
Semantic statement
output = input0 f/ input1;
-
-

-This is a floating-point division operator. The result of dividing -input1 into input0 as floating-point values is stored in output. Both -inputs and output must be the same size. If either input -is NaN, output is set -to NaN. If any overflow condition -occurs, output is set to NaN. -

-
-
-

-FLOAT_NEG

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Floating-point varnode to negate.
outputVarnode containing result of negation.
Semantic statement
output = f- input0;
-
-

-This is a floating-point negation operator. The floating-point value -in input0 is stored in output with the opposite sign. Both input and -output must be the same size. If input -is NaN, output is set -to NaN. -

-
-
-

-FLOAT_ABS

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Floating-point input.
outputVarnode result containing absolute-value.
Semantic statement
output = abs(input0);
-
-

-This is a floating-point absolute-value operator. The absolute value -of input0 is stored in output. Both input0 and output must be the same -size. If input0 is NaN, output is set -to NaN. -

-
-
-

-FLOAT_SQRT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Floating-point input.
outputVarnode result containing square root.
Semantic statement
output = sqrt(input0);
-
-

-This is a floating-point square-root operator. The square root of -input0 is stored in output. Both input0 and output must be the same -size. If input0 is NaN, output is set -to NaN. -

-
-
-

-FLOAT_CEIL

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Floating-point input.
outputVarnode result containing result of truncation.
Semantic statement
output = ceil(input0);
-
-

-This operation rounds input0, as a signed floating-point value, towards positive infinity. -For instance, the value 1.2 rounds to 2.0; -1.2 rounds to -1.0. -The integral value obtained by rounding input0 up is stored in output, as a floating-point -value. Both input0 and output must be the same size. If input0 -is NaN, output is set -to NaN. -

-
-
-

-FLOAT_FLOOR

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Floating-point input.
outputVarnode result containing result of truncation.
Semantic statement
output = floor(input0);
-
-

-This operation rounds input0, as a floating-point value, towards negative infinity. -For instance, the value 1.2 rounds to 1.0 and -1.2 rounds to -2.0. -The integral value obtained by rounding input0 down is stored in output, as a floating-point -value. FLOAT_FLOOR does not produce -a twos complement integer output (See the TRUNC operator). -Both input0 and output must be the same size. If input0 -is NaN, output is set -to NaN. -

-
-
-

-FLOAT_ROUND

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Floating-point input.
outputVarnode result containing result of truncation.
Semantic statement
output = round(input0);
-
-

-This is a floating-point rounding operator. The integral value closest to the -floating-point value in input0 is stored in output, as a floating-point value. -For example, 1.2 rounds to 1.0 and 1.9 rounds to 2.0. -FLOAT_ROUND does not -produce a twos complement integer output (See the TRUNC operator). -Both input0 and output must be the same size. If -input0 is NaN, output is set -to NaN. -

-
-
-

-FLOAT_NAN

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Floating-point input.
outputBoolean varnode containing result of NaN test.
Semantic statement
output = nan(input0);
-
-

-This operator returns true in output if input0 is -interpreted as NaN. Output must be -size 1, and input0 can be any size. -

-
-
-

-INT2FLOAT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Signed integer input.
outputResult containing floating-point conversion.
Semantic statement
output = int2float(input0);
-
-

-This is an integer to floating-point conversion operator. Input0 -viewed as a signed integer is converted to floating-point format and -stored in output. Input0 and output do not need to be the same -size. The conversion to floating-point may involve a loss of -precision. -

-
-
-

-FLOAT2FLOAT

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Floating-point input varnode.
outputResult varnode containing conversion.
Semantic statement
output = float2float(input0);
-
-

-This is a floating-point precision conversion operator. The -floating-point value in input0 is converted to a floating-point value -of a different size and stored in output. If output is smaller than -input0, then the operation will lose precision. Input0 and output -should be different sizes. If input0 -is NaN, then output is set -to NaN. -

-
-
-

-TRUNC

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Floating-point input varnode.
outputResulting integer varnode containing conversion.
Semantic statement
output = trunc(input0);
-
-

-This is a floating-point to integer conversion operator. The -floating-point value in input0 is converted to a signed integer and -stored in output using the default twos complement encoding. -The fractional part of input0 is dropped in the conversion by rounding towards zero. -Input0 and output can be different sizes. -

-
-
-
-
- - - - - - - - - - - -
-Prev   Next -
P-Code Reference Manual Home Pseudo P-CODE Operations
-
- - diff --git a/sources/GhidraDocs/languages/html/pcodedescription.md b/sources/GhidraDocs/languages/html/pcodedescription.md deleted file mode 100644 index 65c538d..0000000 --- a/sources/GhidraDocs/languages/html/pcodedescription.md +++ /dev/null @@ -1,1168 +0,0 @@ ---- -status: collected -title: P-Code Operation Reference -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/pcodedescription.html ---- - -# P-Code Operation Reference - -For each possible p-code operation, we give a brief description and -provide a table that lists the inputs that must be present and their -meaning. We also list the basic syntax for denoting the operation when -describing semantics in a processor specification file. - -### COPY - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Source varnode.| -|output|Destination varnode.| - -**Semantic statement** - -`output = input0;` - -Copy a sequence of contiguous bytes from anywhere to anywhere. Size of -input0 and output must be the same. - -### LOAD - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Constant ID of space to load from.| -|input1|Varnode containing pointer offset to data.| -|output|Destination varnode.| - -**Semantic statement** - -`output = *input1;` - -`output = *[input0]input1;` - -This instruction loads data from a dynamic location into the output -variable by dereferencing a pointer. The "pointer" comes in two pieces. -One piece, input1, is a normal variable containing the offset of the -object being pointed at. The other piece, input0, is a constant -indicating the space into which the offset applies. The data in input1 -is interpreted as an unsigned offset and should have the same size as -the space referred to by the ID, i.e. a 4-byte address space requires a -4-byte offset. The space ID is not manually entered by a user but is -automatically generated by the p-code compiler. The amount of data -loaded by this instruction is determined by the size of the output -variable. It is easy to confuse the address space of the output and -input1 variables and the Address Space represented by the ID, which -could all be different. Unlike many programming models, there are -multiple spaces that a "pointer" can refer to, and so an extra ID is -required. - -It is possible for the addressable unit of an address space to be bigger -than a single byte. If the **wordsize** attribute of the space -given by the ID is bigger than one, the offset into the space obtained -from input1 must be multiplied by this value in order to obtain the -correct byte offset into the space. - -### STORE - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Constant ID of space to store into.| -|input1|Varnode containing pointer offset of destination.| -|output|Varnode containing data to be stored.| - -**Semantic statement** - -`*input1 = input2;` - -`*[input0]input1 = input2; ` - -This instruction is the complement of **LOAD**. The data in the -variable input2 is stored at a dynamic location by dereferencing a -pointer. As with **LOAD**, the "pointer" comes in two pieces: a -space ID part, and an offset variable. The size of input1 must match the -address space specified by the ID, and the amount of data stored is -determined by the size of input2. - -Its possible for the addressable unit of an address space to be bigger -than a single byte. If the **wordsize** attribute of the space -given by the ID is bigger than one, the offset into the space obtained -from input1 must be multiplied by this value in order to obtain the -correct byte offset into the space. - -### BRANCH - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Location of next instruction to execute.| - -**Semantic statement** - -`goto input0;` - -This is an absolute jump instruction. The varnode parameter input0 -encodes the destination address (address space and offset) of the jump. -The varnode is not treated as a variable for this instruction and does -not store the destination. Its address space and offset -*are* the destination. The size of input0 is irrelevant. - -Confusion about the meaning of this instruction can result because of -the translation from machine instructions to p-code. The destination of -the jump is a *machine* address and refers to the -*machine* instruction at that address. When attempting to -determine which p-code instruction is executed next, the rule is: -execute the first p-code instruction resulting from the translation of -the machine instruction(s) at that address. The resulting p-code -instruction may not be attached directly to the indicated address due to -NOP instructions and delay slots. - -If input0 is constant, i.e. its address space is the -**constant** address space, then it encodes a *p-code relative -branch*. In this case, the offset of input0 is considered a -relative offset into the indexed list of p-code operations corresponding -to the translation of the current machine instruction. This allows -branching within the operations forming a single instruction. For -example, if the **BRANCH** occurs as the pcode operation with -index 5 for the instruction, it can branch to operation with index 8 by -specifying a constant destination "address" of 3. Negative constants can -be used for backward branches. - -### CBRANCH - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Location of next instruction to execute.| -|input1|Boolean varnode indicating whether branch is taken.| - -**Semantic statement** - -`if (input1) goto input0;` - -This is a conditional branch instruction where the dynamic condition for -taking the branch is determined by the 1 byte variable input1. If this -variable is non-zero, the condition is considered *true* -and the branch is taken. As in the **BRANCH** instruction the -parameter input0 is not treated as a variable but as an address and is -interpreted in the same way. Furthermore, a constant space address is -also interpreted as a relative address so that a **CBRANCH** -can do *p-code relative branching*. See the discussion for -the **BRANCH** operation. - -### BRANCHIND - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Varnode containing offset of next instruction.| - -**Semantic statement** - -`goto [input0];` - -This is an indirect branching instruction. The address to branch to is -determined dynamically (at runtime) by examining the contents of the -variable input0. As this instruction is currently defined, the variable -input0 only contains the *offset* of the destination, and -the address space is taken from the address associated with the -branching instruction itself. So *execution can only branch within the -same address space* via this instruction. The size of the -variable input0 must match the size of offsets for the current address -space. P-code relative branching is not possible with -**BRANCHIND**. - -### CALL - -|**Parameters**|**Description**| -|:-:|:-| -|input0(**special**)|Location of next instruction to execute.| -|[input1]|First parameter to call (never present in raw p-code)| -|...|Additional parameters to call (never present in raw p-code)| - -**Semantic statement** - -`call [input0];` - -This instruction is semantically equivalent to the **BRANCH** -instruction. **Beware:** This instruction does not behave like -a typical function call. In particular, there is no internal stack in -p-code for saving the return address. Use of this instruction instead of -**BRANCH** is intended to provide a hint to algorithms that try -to follow code flow. It indicates that the original machine instruction, -of which this p-code instruction is only a part, is intended to be a -function call. The p-code instruction does not implement the full -semantics of the call itself; it only implements the final branch. - -In the raw p-code translation process, this operation can only take -input0, but in follow-on analysis, it can take arbitrary additional -inputs. These represent (possibly partial) recovery of the parameters -being passed to the logical *call* represented by this -operation. These additional parameters have no effect on the original -semantics of the raw p-code but naturally hold the varnode values -flowing into the call. - -### CALLIND - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Varnode containing offset of next instruction.| -|[input1]|First parameter to call (never present in raw p-code)| -|...|Additional parameters to call (never present in raw p-code)| - -**Semantic statement** - -`call [input0];` - -This instruction is semantically equivalent to the -**BRANCHIND** instruction. It does not perform a function call -in the usual sense of the term. It merely indicates that the original -machine instruction is intended to be an indirect call. See the -discussion for the **CALL** instruction. - -As with the **CALL** instruction, this operation may take -additional inputs when not in raw form, representing the parameters -being passed to the logical call. - -### RETURN - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Varnode containing offset of next instruction.| -|[input1]|Value returned from call (never present in raw p-code)| - -**Semantic statement** - -`return [input0];` - -This instruction is semantically equivalent to the -**BRANCHIND** instruction. It does not perform a return from -subroutine in the usual sense of the term. It merely indicates that the -original machine instruction is intended to be a return from subroutine. -See the discussion for the **CALL** instruction. - -Similarly to **CALL** and **CALLIND**, this operation -may take an additional input when not in raw form. If input1 is present -it represents the value being *returned* by this operation. -This is used by analysis algorithms to hold the value logically flowing -back to the parent subroutine. - -### PIECE - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Varnode containing most significant data to merge.| -|input1|Varnode containing least significant data to merge.| -|output|Varnode to contain resulting concatenation.| - -**Semantic statement** - -*Cannot (currently) be explicitly coded* - -This is a concatenation operator that understands the endianness of the -data. The size of input0 and input1 must add up to the size of output. -The data from the inputs is concatenated in such a way that, if the -inputs and output are considered integers, the first input makes up the -most significant part of the output. - -### SUBPIECE - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Varnode containing source data to truncate.| -|input1(**constant**)|Constant indicating how many bytes to truncate.| -|output|Varnode to contain result of truncation.| - -**Semantic statement** - -`output = input0(input1);` - -This is a truncation operator that understands the endianness of the -data. Input1 indicates the number of least significant bytes of input0 -to be thrown away. Output is then filled with any remaining bytes of -input0 *up to the size of output*. If the size of output is -smaller than the size of input0 minus the constant input1, then the -additional most significant bytes of input0 will also be truncated. - -### POPCOUNT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Input varnode to count.| -|output|Resulting integer varnode containing count.| - -**Semantic statement** - -`output = popcount(input0);` - -This is a bit count (population count) operator. Within the binary -representation of the value contained in the input varnode, the number -of 1 bits are counted and then returned in the output varnode. A value -of 0 returns 0, a 4-byte varnode containing the value 2^32^-1 (all bits -set) returns 32, for instance. The input and output varnodes can have -any size. The resulting count is zero extended into the output varnode. - -### LZCOUNT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Input varnode to count.| -|output|Resulting integer varnode containing count.| - -**Semantic statement** - -`output = lzcount(input0);` - -This operator counts the number of zeros starting at the most -significant bit. For instance, for a 4-byte varnode, a value of 0 -returns 32, a value of 1 returns 31, and the value 2^31^ returns 0. The -resulting count is zero extended into the output varnode. - -### INT_EQUAL - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode to compare.| -|input1|Second varnode to compare.| -|output|Boolean varnode containing result of comparison.| - -**Semantic statement** - -`output = input0 == input1;` - -This is the integer equality operator. Output is assigned -*true*, if input0 equals input1. It works for signed, -unsigned, or any contiguous data where the match must be down to the -bit. Both inputs must be the same size, and the output must have a size -of 1. - -### INT_NOTEQUAL - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode to compare.| -|input1|Second varnode to compare.| -|output|Boolean varnode containing result of comparison.| - -**Semantic statement** - -`output = input0 != input1;` - -This is the integer inequality operator. Output is assigned -*true*, if input0 does not equal input1. It works for -signed, unsigned, or any contiguous data where the match must be down to -the bit. Both inputs must be the same size, and the output must have a -size of 1. - -### INT_LESS - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode to compare.| -|input1|Second varnode to compare.| -|output|Boolean varnode containing result of comparison.| - -**Semantic statement** - -`output = input0 < input1;` - -This is an unsigned integer comparison operator. If the unsigned integer -input0 is strictly less than the unsigned integer input1, output is set -to *true*. Both inputs must be the same size, and the -output must have a size of 1. - -### INT_SLESS - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode to compare.| -|input1|Second varnode to compare.| -|output|Boolean varnode containing result of comparison.| - -**Semantic statement** - -`output = input0 s< input1;` - -This is a signed integer comparison operator. If the signed integer -input0 is strictly less than the signed integer input1, output is set to -*true*. Both inputs must be the same size, and the output -must have a size of 1. - -### INT_LESSEQUAL - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode to compare.| -|input1|Second varnode to compare.| -|output|Boolean varnode containing result of comparison.| - -**Semantic statement** - -`output = input0 <= input1;` - -This is an unsigned integer comparison operator. If the unsigned integer -input0 is less than or equal to the unsigned integer input1, output is -set to *true*. Both inputs must be the same size, and the -output must have a size of 1. - -### INT_SLESSEQUAL - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode to compare.| -|input1|Second varnode to compare.| -|output|Boolean varnode containing result of comparison.| - -**Semantic statement** - -`output = input0 s<= input1;` - -This is a signed integer comparison operator. If the signed integer -input0 is less than or equal to the signed integer input1, output is set -to *true*. Both inputs must be the same size, and the -output must have a size of 1. - -### INT_ZEXT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Varnode to zero-extend.| -|output|Varnode containing zero-extended result.| - -**Semantic statement** - -`output = zext(input0);` - -Zero-extend the data in input0 and store the result in output. Copy all -the data from input0 into the least significant positions of output. -Fill out any remaining space in the most significant bytes of output -with zero. The size of output must be strictly bigger than the size of -input. - -### INT_SEXT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Varnode to sign-extend.| -|output|Varnode containing sign-extended result.| - -**Semantic statement** - -`output = sext(input0);` - -Sign-extend the data in input0 and store the result in output. Copy all -the data from input0 into the least significant positions of output. -Fill out any remaining space in the most significant bytes of output -with either zero or all ones (0xff) depending on the most significant -bit of input0. The size of output must be strictly bigger than the size -of input0. - -### INT_ADD - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode to add.| -|input1|Second varnode to add.| -|output|Varnode containing result of integer addition.| - -**Semantic statement** - -`output = input0 + input1;` - -This is standard integer addition. It works for either unsigned or -signed interpretations of the integer encoding (twos complement). Size -of both inputs and output must be the same. The addition is of course -performed modulo this size. Overflow and carry conditions are calculated -by other operations. See **INT_CARRY** and -**INT_SCARRY**. - -### INT_SUB - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode input.| -|input1|Varnode to subtract from first.| -|output|Varnode containing result of integer subtraction.| - -**Semantic statement** - -`output = input0 - input1;` - -This is standard integer subtraction. It works for either unsigned or -signed interpretations of the integer encoding (twos complement). Size -of both inputs and output must be the same. The subtraction is of course -performed modulo this size. Overflow and borrow conditions are -calculated by other operations. See **INT_SBORROW** and -**INT_LESS**. - -### INT_CARRY - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode to add.| -|input1|Second varnode to add.| -|output|Boolean result containing carry condition.| - -**Semantic statement** - -`output = carry(input0,input1);` - -This operation checks for unsigned addition overflow or carry -conditions. If the result of adding input0 and input1 as unsigned -integers overflows the size of the varnodes, output is assigned -*true*. Both inputs must be the same size, and output must -be size 1. - -### INT_SCARRY - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode to add.| -|input1|Second varnode to add.| -|output|Boolean result containing signed overflow condition.| - -**Semantic statement** - -`output = scarry(input0,input1);` - -This operation checks for signed addition overflow or carry conditions. -If the result of adding input0 and input1 as signed integers overflows -the size of the varnodes, output is assigned *true*. Both -inputs must be the same size, and output must be size 1. - -### INT_SBORROW - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode input.| -|input1|Varnode to subtract from first.| -|output|Boolean result containing signed overflow condition.| - -**Semantic statement** - -`output = sborrow(input0,input1);` - -This operation checks for signed subtraction overflow or borrow -conditions. If the result of subtracting input1 from input0 as signed -integers overflows the size of the varnodes, output is assigned -*true*. Both inputs must be the same size, and output must -be size 1. Note that the equivalent unsigned subtraction overflow -condition is **INT_LESS**. - -### INT_2COMP - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First to negate.| -|output|Varnode result containing twos complement.| - -**Semantic statement** - -`output = -input0;` - -This is the twos complement or arithmetic negation operation. Treating -input0 as a signed integer, the result is the same integer value but -with the opposite sign. This is equivalent to doing a bitwise negation -of input0 and then adding one. Both input0 and output must be the same -size. - -### INT_NEGATE - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Varnode to negate.| -|output|Varnode result containing bitwise negation.| - -**Semantic statement** - -`output = ~input0;` - -This is the bitwise negation operation. Output is the result of taking -every bit of input0 and flipping it. Both input0 and output must be the -same size. - -### INT_XOR - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First input to exclusive-or.| -|input1|Second input to exclusive-or.| -|output|Varnode result containing exclusive-or of inputs.| - -**Semantic statement** - -`output = input0 ^ input1;` - -This operation performs a logical Exclusive-Or on the bits of input0 and -input1. Both inputs and output must be the same size. - -### INT_AND - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First input to logical-and.| -|input1|Second input to logical-and.| -|output|Varnode result containing logical-and of inputs.| - -**Semantic statement** - -`output = input0 & input1;` - -This operation performs a Logical-And on the bits of input0 and input1. -Both inputs and output must be the same size. - -### INT_OR - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First input to logical-or.| -|input1|Second input to logical-or.| -|output|Varnode result containing logical-or of inputs.| - -**Semantic statement** - -`output = input0 | input1;` - -This operation performs a Logical-Or on the bits of input0 and input1. -Both inputs and output must be the same size. - -### INT_LEFT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Varnode input being shifted.| -|input1|Varnode indicating number of bits to shift.| -|output|Varnode containing shifted result.| - -**Semantic statement** - -`output = input0 << input1;` - -This operation performs a left shift on input0. The value given by -input1, interpreted as an unsigned integer, indicates the number of bits -to shift. The vacated (least significant) bits are filled with zero. If -input1 is zero, no shift is performed and input0 is copied into output. -If input1 is larger than the number of bits in output, the result is -zero. Both input0 and output must be the same size. Input1 can be any -size. - -### INT_RIGHT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Varnode input being shifted.| -|input1|Varnode indicating number of bits to shift.| -|output|Varnode containing shifted result.| - -**Semantic statement** - -`output = input0 >> input1;` - -This operation performs an unsigned (logical) right shift on input0. The -value given by input1, interpreted as an unsigned integer, indicates the -number of bits to shift. The vacated (most significant) bits are filled -with zero. If input1 is zero, no shift is performed and input0 is copied -into output. If input1 is larger than the number of bits in output, the -result is zero. Both input0 and output must be the same size. Input1 can -be any size. - -### INT_SRIGHT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Varnode input being shifted.| -|input1|Varnode indicating number of bits to shift.| -|output|Varnode containing shifted result.| - -**Semantic statement** - -`output = input0 s>> input1;` - -This operation performs a signed (arithmetic) right shift on input0. The -value given by input1, interpreted as an unsigned integer, indicates the -number of bits to shift. The vacated bits are filled with the original -value of the most significant (sign) bit of input0. If input1 is zero, -no shift is performed and input0 is copied into output. If input1 is -larger than the number of bits in output, the result is zero or all -1-bits (-1), depending on the original sign of input0. Both input0 and -output must be the same size. Input1 can be any size. - -### INT_MULT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode to be multiplied.| -|input1|Second varnode to be multiplied.| -|output|Varnode containing result of multiplication.| - -**Semantic statement** - -`output = input0 * input1;` - -This is an integer multiplication operation. The result of multiplying -input0 and input1, viewed as integers, is stored in output. Both inputs -and output must be the same size. The multiplication is performed modulo -the size, and the result is true for either a signed or unsigned -interpretation of the inputs and output. To get extended precision -results, the inputs must first by zero-extended or sign-extended to the -desired size. - -### INT_DIV - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode input.| -|input1|Second varnode input (divisor).| -|output|Varnode containing result of division.| - -**Semantic statement** - -`output = input0 / input1;` - -This is an unsigned integer division operation. Divide input0 by input1, -truncating the result to the nearest integer, and store the result in -output. Both inputs and output must be the same size. There is no -handling of division by zero. To simulate a processor's handling of a -division-by-zero trap, other operations must be used before the -**INT_DIV**. - -### INT_REM - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode input.| -|input1|Second varnode input (divisor).| -|output|Varnode containing remainder of division.| - -**Semantic statement** - -`output = input0 % input1;` - -This is an unsigned integer remainder operation. The remainder of -performing the unsigned integer division of input0 and input1 is put in -output. Both inputs and output must be the same size. If q = -input0/input1, using the **INT_DIV** operation defined above, -then output satisfies the equation q*input1 + output = input0, using -the **INT_MULT** and **INT_ADD** operations. - -### INT_SDIV - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode input.| -|input1|Second varnode input (divisor).| -|output|Varnode containing result of signed division.| - -**Semantic statement** - -`output = input0 s/ input1;` - -This is a signed integer division operation. The resulting integer is -the one closest to the rational value input0/input1 but which is still -smaller in absolute value. Both inputs and output must be the same size. -There is no handling of division by zero. To simulate a processor's -handling of a division-by-zero trap, other operations must be used -before the **INT_SDIV**. - -### INT_SREM - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First varnode input.| -|input1|Second varnode input (divisor).| -|output|Varnode containing remainder of signed division.| - -**Semantic statement** - -`output = input0 s% input1;` - -This is a signed integer remainder operation. The remainder of -performing the signed integer division of input0 and input1 is put in -output. Both inputs and output must be the same size. If q = input0 s/ -input1, using the **INT_SDIV** operation defined above, then -output satisfies the equation q*input1 + output = input0, using the -**INT_MULT** and **INT_ADD** operations. - -### BOOL_NEGATE - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Boolean varnode to negate.| -|output|Boolean varnode containing result of negation.| - -**Semantic statement** - -`output = !input0;` - -This is a logical negate operator, where we assume input0 and output are -boolean values. It puts the logical complement of input0, treated as a -single bit, into output. Both input0 and output are size 1. Boolean -values are implemented with a full byte, but are still considered to -only support a value of *true* or *false*. - -### BOOL_XOR - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First boolean input to exclusive-or.| -|input1|Second boolean input to exclusive-or.| -|output|Boolean varnode containing result of exclusive-or.| - -**Semantic statement** - -`output = input0 ^^ input1;` - -This is an Exclusive-Or operator, where we assume the inputs and output -are boolean values. It puts the exclusive-or of input0 and input1, -treated as single bits, into output. Both inputs and output are size 1. -Boolean values are implemented with a full byte, but are still -considered to only support a value of *true* or -*false*. - -### BOOL_AND - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First boolean input to logical-and.| -|input1|Second boolean input to logical-and.| -|output|Boolean varnode containing result of logical-and.| - -**Semantic statement** - -`output = input0 && input1;` - -This is a Logical-And operator, where we assume the inputs and output -are boolean values. It puts the logical-and of input0 and input1, -treated as single bits, into output. Both inputs and output are size 1. -Boolean values are implemented with a full byte, but are still -considered to only support a value of *true* or -*false*. - -### BOOL_OR - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First boolean input to logical-or.| -|input1|Second boolean input to logical-or.| -|output|Boolean varnode containing result of logical-or.| - -**Semantic statement** - -`output = input0 || input1;` - -This is a Logical-Or operator, where we assume the inputs and output are -boolean values. It puts the logical-or of input0 and input1, treated as -single bits, into output. Both inputs and output are size 1. Boolean -values are implemented with a full byte, but are still considered to -only support a value of *true* or *false*. - -### FLOAT_EQUAL - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First floating-point input to compare.| -|input1|Second floating-point input to compare.| -|output|Boolean varnode containing result of comparison.| - -**Semantic statement** - -`output = input0 f== input1;` - -This is a floating-point equality operator. Output is assigned -*true*, if input0 and input1 are considered equal as -floating-point values. Both inputs must be the same size, and output is -size 1. If either input is **NaN**, output is set to -*false*. - -### FLOAT_NOTEQUAL - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First floating-point input to compare.| -|input1|Second floating-point input to compare.| -|output|Boolean varnode containing result of comparison.| - -**Semantic statement** - -`output = input0 f!= input1;` - -This is a floating-point inequality operator. Output is assigned -*true*, if input0 and input1 are not considered equal as -floating-point values. Both inputs must be the same size, and output is -size 1. If either input is **NaN**, output is set to -*false*. - -### FLOAT_LESS - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First floating-point input to compare.| -|input1|Second floating-point input to compare.| -|output|Boolean varnode containing result of comparison.| - -**Semantic statement** - -`output = input0 f< input1;` - -This is a comparison operator, where both inputs are considered -floating-point values. Output is assigned *true*, if input0 -is less than input1. Both inputs must be the same size, and output is -size 1. If either input is **NaN**, output is set to -*false*. - -### FLOAT_LESSEQUAL - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First floating-point input to compare.| -|input1|Second floating-point input to compare.| -|output|Boolean varnode containing result of comparison.| - -**Semantic statement** - -`output = input0 f<= input1;` - -This is a comparison operator, where both inputs are considered -floating-point values. Output is assigned *true*, if input0 -is less than or equal to input1. Both inputs must be the same size, and -output is size 1. If either input is **NaN**, output is set to -*false*. - -### FLOAT_ADD - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First floating-point input to add.| -|input1|Second floating-point input to add.| -|output|Varnode containing result of addition.| - -**Semantic statement** - -`output = input0 f+ input1;` - -This is a floating-point addition operator. The result of adding input0 -and input1 as floating-point values is stored in output. Both inputs and -output must be the same size. If either input is **NaN**, -output is set to **NaN**. If any overflow condition occurs, -output is set to **NaN**. - -### FLOAT_SUB - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First floating-point input.| -|input1|Floating-point varnode to subtract from first.| -|output|Varnode containing result of subtraction.| - -**Semantic statement** - -`output = input0 f- input1;` - -This is a floating-point subtraction operator. The result of subtracting -input1 from input0 as floating-point values is stored in output. Both -inputs and output must be the same size. If either input is -**NaN**, output is set to **NaN**. If any overflow -condition occurs, output is set to **NaN**. - -### FLOAT_MULT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First floating-point input to multiply.| -|input1|Second floating-point input to multiply.| -|output|Varnode containing result of multiplication.| - -**Semantic statement** - -`output = input0 f* input1;` - -This is a floating-point multiplication operator. The result of -multiplying input0 to input1 as floating-point values is stored in -output. Both inputs and output must be the same size. If either input is -**NaN**, output is set to **NaN**. If any overflow -condition occurs, output is set to **NaN**. - -### FLOAT_DIV - -|**Parameters**|**Description**| -|:-:|:-| -|input0|First floating-point input.| -|input1|Second floating-point input (divisor).| -|output|Varnode containing result of division.| - -**Semantic statement** - -`output = input0 f/ input1;` - -This is a floating-point division operator. The result of dividing -input1 into input0 as floating-point values is stored in output. Both -inputs and output must be the same size. If either input is -**NaN**, output is set to **NaN**. If any overflow -condition occurs, output is set to **NaN**. - -### FLOAT_NEG - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Floating-point varnode to negate.| -|output|Varnode containing result of negation.| - -**Semantic statement** - -`output = f- input0;` - -This is a floating-point negation operator. The floating-point value in -input0 is stored in output with the opposite sign. Both input and output -must be the same size. If input is **NaN**, output is set to -**NaN**. - -### FLOAT_ABS - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Floating-point input.| -|output|Varnode result containing absolute-value.| - -**Semantic statement** - -`output = abs(input0);` - -This is a floating-point absolute-value operator. The absolute value of -input0 is stored in output. Both input0 and output must be the same -size. If input0 is **NaN**, output is set to **NaN**. - -### FLOAT_SQRT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Floating-point input.| -|output|Varnode result containing square root.| - -**Semantic statement** - -`output = sqrt(input0);` - -This is a floating-point square-root operator. The square root of input0 -is stored in output. Both input0 and output must be the same size. If -input0 is **NaN**, output is set to **NaN**. - -### FLOAT_CEIL - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Floating-point input.| -|output|Varnode result containing result of truncation.| - -**Semantic statement** - -`output = ceil(input0);` - -This operation rounds input0, as a signed floating-point value, towards -*positive infinity*. For instance, the value 1.2 rounds to -2.0; -1.2 rounds to -1.0. The integral value obtained by rounding input0 -up is stored in output, as a floating-point value. Both input0 and -output must be the same size. If input0 is **NaN**, output is -set to **NaN**. - -### FLOAT_FLOOR - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Floating-point input.| -|output|Varnode result containing result of truncation.| - -**Semantic statement** - -`output = floor(input0);` - -This operation rounds input0, as a floating-point value, towards -*negative infinity*. For instance, the value 1.2 rounds to -1.0 and -1.2 rounds to -2.0. The integral value obtained by rounding -input0 down is stored in output, as a floating-point value. -**FLOAT_FLOOR** does *not* produce a twos -complement integer output (See the **TRUNC** operator). Both -input0 and output must be the same size. If input0 is **NaN**, -output is set to **NaN**. - -### FLOAT_ROUND - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Floating-point input.| -|output|Varnode result containing result of truncation.| - -**Semantic statement** - -`output = round(input0);` - -This is a floating-point rounding operator. The integral value closest -to the floating-point value in input0 is stored in output, as a -floating-point value. For example, 1.2 rounds to 1.0 and 1.9 rounds to -2.0. **FLOAT_ROUND** does *not* produce a twos -complement integer output (See the **TRUNC** operator). Both -input0 and output must be the same size. If input0 is **NaN**, -output is set to **NaN**. - -### FLOAT_NAN - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Floating-point input.| -|output|Boolean varnode containing result of NaN test.| - -**Semantic statement** - -`output = nan(input0);` - -This operator returns *true* in output if input0 is -interpreted as **NaN**. Output must be size 1, and input0 can -be any size. - -### INT2FLOAT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Signed integer input.| -|output|Result containing floating-point conversion.| - -**Semantic statement** - -`output = int2float(input0);` - -This is an integer to floating-point conversion operator. Input0 viewed -as a signed integer is converted to floating-point format and stored in -output. Input0 and output do not need to be the same size. The -conversion to floating-point may involve a loss of precision. - -### FLOAT2FLOAT - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Floating-point input varnode.| -|output|Result varnode containing conversion.| - -**Semantic statement** - -`output = float2float(input0);` - -This is a floating-point precision conversion operator. The -floating-point value in input0 is converted to a floating-point value of -a different size and stored in output. If output is smaller than input0, -then the operation will lose precision. Input0 and output should be -different sizes. If input0 is **NaN**, then output is set to -**NaN**. - -### TRUNC - -|**Parameters**|**Description**| -|:-:|:-| -|input0|Floating-point input varnode.| -|output|Resulting integer varnode containing conversion.| - -**Semantic statement** - -`output = trunc(input0);` - -This is a floating-point to integer conversion operator. The -floating-point value in input0 is converted to a signed integer and -stored in output using the default twos complement encoding. The -fractional part of input0 is dropped in the conversion by rounding -*towards zero*. Input0 and output can be different sizes. \ No newline at end of file diff --git a/sources/GhidraDocs/languages/html/pcoderef.html b/sources/GhidraDocs/languages/html/pcoderef.html deleted file mode 100644 index 5347599..0000000 --- a/sources/GhidraDocs/languages/html/pcoderef.html +++ /dev/null @@ -1,369 +0,0 @@ - - - -P-Code Reference Manual - - - - - - - -
- - - - - - - -
P-Code Reference Manual
   Next -
-
-
-
-
-
-

-P-Code Reference Manual

-

Last updated March 2, 2023

-
-
-
-
- ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
COPYINT_ADDBOOL_OR
LOADINT_SUBFLOAT_EQUAL
STOREINT_CARRYFLOAT_NOTEQUAL
BRANCHINT_SCARRYFLOAT_LESS
CBRANCHINT_SBORROWFLOAT_LESSEQUAL
BRANCHINDINT_2COMPFLOAT_ADD
CALLINT_NEGATEFLOAT_SUB
CALLINDINT_XORFLOAT_MULT
USERDEFINEDINT_ANDFLOAT_DIV
RETURNINT_ORFLOAT_NEG
PIECEINT_LEFTFLOAT_ABS
SUBPIECEINT_RIGHTFLOAT_SQRT
POPCOUNTINT_SRIGHTFLOAT_CEIL
LZCOUNTINT_MULTFLOAT_FLOOR
INT_EQUALINT_DIVFLOAT_ROUND
INT_NOTEQUALINT_REMFLOAT_NAN
INT_LESSINT_SDIVINT2FLOAT
INT_SLESSINT_SREMFLOAT2FLOAT
INT_LESSEQUALBOOL_NEGATETRUNC
INT_SLESSEQUALBOOL_XORCPOOLREF
INT_ZEXTBOOL_ANDNEW
INT_SEXT
-
-
-

-A Brief Introduction to P-Code

-

-P-code is a register transfer language designed -for reverse engineering applications. The language is general enough -to model the behavior of many different processors. By modeling in -this way, the analysis of different processors is put into a common -framework, facilitating the development of retargetable analysis -algorithms and applications. -

-

-Fundamentally, p-code works by translating individual processor instructions -into a sequence of p-code operations that take -parts of the processor state as input and output variables -(varnodes). The set of unique p-code operations -(distinguished by opcode) comprise a fairly tight set -of the arithmetic and logical actions performed by general purpose processors. -The direct translation of instructions into these operations is referred -to as raw p-code. Raw p-code can be used to directly emulate -instruction execution and generally follows the same control-flow, -although it may add some of its own internal control-flow. The subset of -opcodes that can occur in raw p-code is described in -the section called “P-Code Operation Reference” and in the section called “Pseudo P-CODE Operations”, making up -the bulk of this document. -

-

-P-code is designed specifically to facilitate the -construction of data-flow graphs for follow-on analysis of -disassembled instructions. Varnodes and -p-code operators can be thought of explicitly as nodes in these graphs. -Generation of raw p-code is a necessary first step in graph construction, -but additional steps are required, which introduces some new -opcodes. Two of these, -MULTIEQUAL and INDIRECT, -are specific to the graph construction process, but other opcodes can be introduced during -subsequent analysis and transformation of a graph and help hold recovered data-type relationships. -All of the new opcodes are described in the section called “Additional P-CODE Operations”, none of which can occur -in the original raw p-code translation. Finally, a few of the p-code operators, -CALL, -CALLIND, and RETURN, -may have their input and output varnodes changed during analysis so that they no -longer match their raw p-code form. -

-

-The core concepts of p-code are: -

-
-

-Address Space

-

-The address space for p-code is a generalization -of RAM. It is defined simply as an indexed sequence of bytes that can -be read and written by the p-code operations. For a specific byte, the unique index -that labels it is the byte's address. An address space has a -name to identify it, a size that indicates the number of distinct -indices into the space, and an endianness -associated with it that indicates how integers and other multi-byte -values are encoded into the space. A typical processor -will have a ram space, to model -memory accessible via its main data bus, and -a register space for modeling the -processor's general purpose registers. Any data that a processor -manipulates must be in some address space. The specification for a -processor is free to define as many address spaces as it needs. There -is always a special address space, called -a constant address space, which is -used to encode any constant values needed for p-code operations. Systems generating -p-code also generally use a dedicated temporary -space, which can be viewed as a bottomless source of temporary registers. These -are used to hold intermediate values when modeling instruction behavior. - -

-

-P-code specifications allow the addressable unit of an address -space to be bigger than just a byte. Each address space has -a wordsize attribute that can be set -to indicate the number of bytes in a unit. A wordsize which is bigger -than one makes little difference to the representation of p-code. All -the offsets into an address space are still represented internally as -a byte offset. The only exceptions are -the LOAD and -STORE p-code -operations. These operations read a pointer offset that must be scaled properly to get the -right byte offset when dereferencing the pointer. The wordsize attribute has no effect on -any of the other p-code operations. -

-
-
-

-Varnode

-

-A varnode is a generalization of -either a register or a memory location. It is represented by the formal triple: -an address space, an offset into the space, and a size. Intuitively, a -varnode is a contiguous sequence of bytes in some address space that -can be treated as a single value. All manipulation of data by p-code -operations occurs on varnodes. -

-

-Varnodes by themselves are just a contiguous chunk of bytes, -identified by their address and size, and they have no type. The -p-code operations however can force one of three type interpretations -on the varnodes: integer, boolean, and floating-point. -

-
    -
  • - Operations that manipulate integers always interpret a varnode as a - twos-complement encoding using the endianness associated with the - address space containing the varnode. -
    • -
  • - A varnode being used as a boolean value is assumed to be a single byte - that can only take the value 0, for false, and 1, - for true. -
    • -
  • - Floating-point operations use the encoding expected by the processor being modeled, - which varies depending on the size of the varnode. - For most processors, these encodings are described by the IEEE 754 standard, but - other encodings are possible in principle. -
    • -
-

-

-

-If a varnode is specified as an offset into -the constant address space, that -offset is interpreted as a constant, or immediate value, in any p-code -operation that uses that varnode. The size of the varnode, in this -case, can be treated as the size or precision available for the encoding -of the constant. As with other varnodes, constants only have a type forced -on them by the p-code operations that use them. -

-
-
-

-P-code Operation

-

-A p-code operation is the analog of a -machine instruction. All p-code operations have the same basic format -internally. They all take one or more varnodes as input and optionally -produce a single output varnode. The action of the operation is determined by -its opcode. -For almost all p-code operations, only the output varnode can have its -value modified; there are no indirect effects of the operation. -The only possible exceptions are pseudo operations, -see the section called “Pseudo P-CODE Operations”, which are sometimes necessary when there -is incomplete knowledge of an instruction's behavior. -

-

-All p-code operations are associated with the address of the original -processor instruction they were translated from. For a single instruction, -a 1-up counter, starting at zero, is used to enumerate the -multiple p-code operations involved in its translation. The address and -counter as a pair are referred to as the p-code op's -unique sequence number. Control-flow of -p-code operations generally follows sequence number order. When execution -of all p-code for one instruction is completed, if the -instruction has fall-through semantics, p-code -control-flow picks up with the first p-code operation in sequence corresponding to -the instruction at the fall-through address. Similarly, if a p-code operation -results in a control-flow branch, the first p-code operation in sequence executes -at the destination address. -

-

-The list of possible -opcodes are similar to many RISC based instruction sets. The effect of -each opcode is described in detail in the following sections, -and a reference table is given -in the section called “Syntax Reference”. In general, the size or -precision of a particular p-code operation is determined by the size -of the varnode inputs or output, not by the opcode. -

-
-
-
-
-
- - - - - - - - - - - -
   Next -
   P-Code Operation Reference
-
- - diff --git a/sources/GhidraDocs/languages/html/pcoderef.md b/sources/GhidraDocs/languages/html/pcoderef.md deleted file mode 100644 index d1d7274..0000000 --- a/sources/GhidraDocs/languages/html/pcoderef.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -status: collected -title: A Brief Introduction to P-Code -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/pcoderef.html ---- - -# A Brief Introduction to P-Code - -P-code is a *register transfer language* designed for -reverse engineering applications. The language is general enough to -model the behavior of many different processors. By modeling in this -way, the analysis of different processors is put into a common -framework, facilitating the development of retargetable analysis -algorithms and applications. - -Fundamentally, p-code works by translating individual processor -instructions into a sequence of **p-code operations** that take -parts of the processor state as input and output variables -(**varnodes**). The set of unique p-code operations -(distinguished by **opcode**) comprise a fairly tight set of -the arithmetic and logical actions performed by general purpose -processors. The direct translation of instructions into these operations -is referred to as **raw p-code**. Raw p-code can be used to -directly emulate instruction execution and generally follows the same -control-flow, although it may add some of its own internal control-flow. -The subset of opcodes that can occur in raw p-code is described in [the -section called "P-Code Operation -Reference"](pcodedescription.md "P-Code Operation Reference") -and in [the section called "Pseudo P-CODE -Operations"](pseudo-ops.md "Pseudo P-CODE Operations"), making -up the bulk of this document. - -P-code is designed specifically to facilitate the construction of -*data-flow* graphs for follow-on analysis of disassembled -instructions. Varnodes and p-code operators can be thought of explicitly -as nodes in these graphs. Generation of raw p-code is a necessary first -step in graph construction, but additional steps are required, which -introduces some new opcodes. Two of these, **MULTIEQUAL** and -**INDIRECT**, are specific to the graph construction process, -but other opcodes can be introduced during subsequent analysis and -transformation of a graph and help hold recovered data-type -relationships. All of the new opcodes are described in [the section -called "Additional P-CODE -Operations"](additionalpcode.md "Additional P-CODE Operations"), -none of which can occur in the original raw p-code translation. Finally, -a few of the p-code operators, **CALL**, **CALLIND**, -and **RETURN**, may have their input and output varnodes -changed during analysis so that they no longer match their *raw -p-code* form. - -The core concepts of p-code are: - -### Address Space - -The **address space** for p-code is a generalization of RAM. It -is defined simply as an indexed sequence of bytes that can be read and -written by the p-code operations. For a specific byte, the unique index -that labels it is the byte\'s **address**. An address space has -a name to identify it, a size that indicates the number of distinct -indices into the space, and an **endianness** associated with -it that indicates how integers and other multi-byte values are encoded -into the space. A typical processor will have a **ram** space, -to model memory accessible via its main data bus, and a -**register** space for modeling the processor\'s general -purpose registers. Any data that a processor manipulates must be in some -address space. The specification for a processor is free to define as -many address spaces as it needs. There is always a special address -space, called a **constant** address space, which is used to -encode any constant values needed for p-code operations. Systems -generating p-code also generally use a dedicated **temporary** -space, which can be viewed as a bottomless source of temporary -registers. These are used to hold intermediate values when modeling -instruction behavior. - -P-code specifications allow the addressable unit of an address space to -be bigger than just a byte. Each address space has a -**wordsize** attribute that can be set to indicate the number -of bytes in a unit. A wordsize which is bigger than one makes little -difference to the representation of p-code. All the offsets into an -address space are still represented internally as a byte offset. The -only exceptions are the **LOAD** and **STORE** p-code -operations. These operations read a pointer offset that must be scaled -properly to get the right byte offset when dereferencing the pointer. -The wordsize attribute has no effect on any of the other p-code -operations. - -### Varnode - -A **varnode** is a generalization of either a register or a -memory location. It is represented by the formal triple: an address -space, an offset into the space, and a size. Intuitively, a varnode is a -contiguous sequence of bytes in some address space that can be treated -as a single value. All manipulation of data by p-code operations occurs -on varnodes. - -Varnodes by themselves are just a contiguous chunk of bytes, identified -by their address and size, and they have no type. The p-code operations -however can force one of three *type* interpretations on -the varnodes: integer, boolean, and floating-point. - -- Operations that manipulate integers always interpret a varnode as a - twos-complement encoding using the endianness associated with the - address space containing the varnode. -- A varnode being used as a boolean value is assumed to be a single - byte that can only take the value 0, for *false*, and - 1, for *true*. -- Floating-point operations use the encoding expected by the processor - being modeled, which varies depending on the size of the varnode. - For most processors, these encodings are described by the IEEE 754 - standard, but other encodings are possible in principle. - -If a varnode is specified as an offset into the **constant** -address space, that offset is interpreted as a constant, or immediate -value, in any p-code operation that uses that varnode. The size of the -varnode, in this case, can be treated as the size or precision available -for the encoding of the constant. As with other varnodes, constants only -have a type forced on them by the p-code operations that use them. - -### P-code Operation - -A **p-code operation** is the analog of a machine instruction. -All p-code operations have the same basic format internally. They all -take one or more varnodes as input and optionally produce a single -output varnode. The action of the operation is determined by its -**opcode**. For almost all p-code operations, only the output -varnode can have its value modified; there are no indirect effects of -the operation. The only possible exceptions are *pseudo* -operations, see [the section called "Pseudo P-CODE -Operations"](pseudo-ops.md "Pseudo P-CODE Operations"), which -are sometimes necessary when there is incomplete knowledge of an -instruction\'s behavior. - -All p-code operations are associated with the address of the original -processor instruction they were translated from. For a single -instruction, a 1-up counter, starting at zero, is used to enumerate the -multiple p-code operations involved in its translation. The address and -counter as a pair are referred to as the p-code op\'s unique **sequence -number**. Control-flow of p-code operations generally follows -sequence number order. When execution of all p-code for one instruction -is completed, if the instruction has *fall-through* -semantics, p-code control-flow picks up with the first p-code operation -in sequence corresponding to the instruction at the fall-through -address. Similarly, if a p-code operation results in a control-flow -branch, the first p-code operation in sequence executes at the -destination address. - -The list of possible opcodes are similar to many RISC based instruction -sets. The effect of each opcode is described in detail in the following -sections, and a reference table is given in [the section called "Syntax -Reference"](reference.md "Syntax Reference"). In general, the -size or precision of a particular p-code operation is determined by the -size of the varnode inputs or output, not by the opcode. \ No newline at end of file diff --git a/sources/GhidraDocs/languages/html/pseudo-ops.html b/sources/GhidraDocs/languages/html/pseudo-ops.html deleted file mode 100644 index bbcc9f6..0000000 --- a/sources/GhidraDocs/languages/html/pseudo-ops.html +++ /dev/null @@ -1,241 +0,0 @@ - - - -Pseudo P-CODE Operations - - - - - - - - - -
- - - - - - - -
Pseudo P-CODE Operations
-Prev   Next -
-
-
-
-

-Pseudo P-CODE Operations

-

-Practical analysis systems need to be able to describe operations, whose exact effect on a machine's -memory state is not fully modeled. P-code allows for this by defining a small set of -pseudo operators. Such an operator is generally treated as a placeholder -for some, possibly large, sequence of changes to the machine state. In terms of analysis, -either the operator is just carried through as a black-box or it serves as a plug-in point for operator -substitution or other specially tailored transformation. Pseudo operators may violate the requirement -placed on other p-code operations that all effects must be explicit. -

-
-

-USERDEFINED

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0(special)Constant ID of user-defined op to perform.
input1First parameter of user-defined op.
...Additional parameters of user-defined op.
[output]Optional output of user-defined op.
Semantic statement
userop(input1, ... );
output = userop(input1,...);
-
-

-This is a placeholder for (a family of) user-definable p-code -instructions. It allows p-code instructions to be defined with -semantic actions that are not fully specified. Machine instructions -that are too complicated or too esoteric to fully implement can use -one or more USERDEFINED instructions -as placeholders for their semantics. -

-

-The first input parameter input0 is a constant ID assigned by the specification -to a particular semantic action. Depending on how the specification -defines the action associated with the ID, -the USERDEFINED instruction can take -an arbitrary number of input parameters and optionally have an output -parameter. Exact details are processor and specification dependent. -Ideally, the output parameter is determined by the input -parameters, and no variable is affected except the output -parameter. But this is no longer a strict requirement, side-effects are possible. -Analysis should generally treat these instructions as a “black-box” which -still have normal data-flow and can be manipulated symbolically. -

-
-
-

-CPOOLREF

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode containing pointer offset to object.
input1(special)Constant ID indicating type of value to return.
...Additional parameters describing value to return.
outputVarnode to contain requested size, offset, or address.
Semantic statement
output = cpool(input0,intput1);
-
-

-This operator returns specific run-time dependent values from the -constant pool. This is a concept for object-oriented -instruction sets and other managed code environments, where some details about -how instructions behave can be deferred -until run-time and are not directly encoded in the instruction. -The CPOOLREF operator acts a query to the system to -recover this type of information. The first parameter is a -pointer to a specific object, and subsequent parameters are IDs or other special constants -describing exactly what value is requested, relative to the object. The canonical example -is requesting a method address given just an ID describing the method and a specific object, but -CPOOLREF can be used as a placeholder for recovering -any important value the system knows about. Details about this instruction, in terms -of emulation and analysis, are necessarily architecture dependent. -

-
-
-

-NEW

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParametersDescription
input0Varnode containing class reference
[input1]If present, varnode containing count of objects to allocate.
outputVarnode to contain pointer to allocated memory.
Semantic statement
output = new(input0);
-
-

-This operator allocates memory for an object described by the first parameter and -returns a pointer to that memory. -This is used to model object-oriented instruction sets where object allocation is an atomic operation. -Exact details about how memory is affected by a NEW operation is generally -not modeled in these cases, so the operator serves as a placeholder to allow analysis to proceed. -

-
-
-
-
- - - - - - - - - - - -
-Prev   Next -
P-Code Operation Reference Home Additional P-CODE Operations
-
- - diff --git a/sources/GhidraDocs/languages/html/pseudo-ops.md b/sources/GhidraDocs/languages/html/pseudo-ops.md deleted file mode 100644 index 5107c79..0000000 --- a/sources/GhidraDocs/languages/html/pseudo-ops.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -status: collected -title: Pseudo P-CODE Operations -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/pseudo-ops.html ---- - -# Pseudo P-CODE Operations - -Practical analysis systems need to be able to describe operations, whose -exact effect on a machine\'s memory state is not fully modeled. P-code -allows for this by defining a small set of *pseudo*{.emphasis} -operators. Such an operator is generally treated as a placeholder for -some, possibly large, sequence of changes to the machine state. In terms -of analysis, either the operator is just carried through as a black-box -or it serves as a plug-in point for operator substitution or other -specially tailored transformation. Pseudo operators may violate the -requirement placed on other p-code operations that all effects must be -explicit. - -### USERDEFINED - -|Parameters|Description| -|:-:|-:| -|input0(**special**)|Constant ID of user-defined op to perform.| -|input1|First parameter of user-defined op.| -|...|Additional parameters of user-defined op.| -|[output]|Optional output of user-defined op.| - -**Semantic statement** - -`userop(input1, ... );` - -`output = userop(input1,...);` - -This is a placeholder for (a family of) user-definable p-code -instructions. It allows p-code instructions to be defined with semantic -actions that are not fully specified. Machine instructions that are too -complicated or too esoteric to fully implement can use one or more -**USERDEFINED** instructions as placeholders for their -semantics. - -The first input parameter input0 is a constant ID assigned by the -specification to a particular semantic action. Depending on how the -specification defines the action associated with the ID, the -**USERDEFINED** instruction can take an arbitrary number of -input parameters and optionally have an output parameter. Exact details -are processor and specification dependent. Ideally, the output parameter -is determined by the input parameters, and no variable is affected -except the output parameter. But this is no longer a strict requirement, -side-effects are possible. Analysis should generally treat these -instructions as a "black-box" which still have normal data-flow and can -be manipulated symbolically. - -### CPOOLREF - -|Parameters|Description| -|:-:|-:| -|input0|Varnode containing pointer offset to object.| -|input1(**special**)|Constant ID indicating type of value to return.| -|...|Additional parameters describing value to return.| -|output|Varnode to contain requested size, offset, or address.| - -**Semantic statement** - -`output = cpool(input0,intput1);` - -This operator returns specific run-time dependent values from the -*constant pool*{.emphasis}. This is a concept for object-oriented -instruction sets and other managed code environments, where some details -about how instructions behave can be deferred until run-time and are not -directly encoded in the instruction. The **CPOOLREF** operator -acts a query to the system to recover this type of information. The -first parameter is a pointer to a specific object, and subsequent -parameters are IDs or other special constants describing exactly what -value is requested, relative to the object. The canonical example is -requesting a method address given just an ID describing the method and a -specific object, but **CPOOLREF** can be used as a placeholder -for recovering any important value the system knows about. Details about -this instruction, in terms of emulation and analysis, are necessarily -architecture dependent. - -### NEW - -|Parameters|Description| -|:-:|-:| -|input0|Varnode containing class reference| -|[input1]|If present, varnode containing count of objects to allocate.| -|output|Varnode to contain pointer to allocated memory.| - -**Semantic statement** - -`output = new(input0);` - -This operator allocates memory for an object described by the first -parameter and returns a pointer to that memory. This is used to model -object-oriented instruction sets where object allocation is an atomic -operation. Exact details about how memory is affected by a -**NEW** operation is generally not modeled in these cases, so -the operator serves as a placeholder to allow analysis to proceed. \ No newline at end of file diff --git a/sources/GhidraDocs/languages/html/reference.html b/sources/GhidraDocs/languages/html/reference.html deleted file mode 100644 index 0212d3e..0000000 --- a/sources/GhidraDocs/languages/html/reference.html +++ /dev/null @@ -1,530 +0,0 @@ - - - -Syntax Reference - - - - - - - - -
- - - - - - - -
Syntax Reference
-Prev   
-
-
-
-

-Syntax Reference

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameSyntaxDescription
COPYv0 = v1;Copy v1 into v0.
LOAD -
- - - - - - - - - - - - - -
* v1
*[spc]v1
*:2 v1
*[spc]:2 v1
-
- 		Dereference v1 as pointer into default space. Optionally specify a space - to load from and size of data in bytes.
STORE -
- - - - - - - - - - - - - -
*v0 = v1;
*[spc]v0 = v1;
*:4 v0 = v1;
*[spc]:4 v0 = v1;
-
- 		Store in v1 in default space using v0 as pointer. Optionally specify space to store in - and size of data in bytes.
BRANCHgoto v0;Branch execution to address of v0.
CBRANCHif (v0) goto v1;Branch execution to address of v1 if v0 equals 1 (true).
BRANCHINDgoto [v0];Branch execution to value in v0 viewed as an offset into the current space.
CALLcall v0;Branch execution to address of v0. Hint that the branch is a subroutine call.
CALLINDcall [v0];Branch execution to value in v0 viewed as an offset into the current space. - Hint that the branch is a subroutine call.
RETURNreturn [v0];Branch execution to value in v0 viewed as an offset into the current space. - Hint that the branch is a subroutine return.
PIECE<na>Concatenate two varnodes into a single varnode.
SUBPIECEv0:2The least signficant n bytes of v0.
SUBPIECEv0(2)All but the least significant n bytes of v0.
POPCOUNTpopcount(v0)Count 1 bits in v0.
LZCOUNTlzcount(v0)Counts the number of leading zero bits in v0.
INT_EQUALv0 == v1True if v0 equals v1.
INT_NOTEQUALv0 != v1True if v0 does not equal v1.
INT_LESS -
- - - - - - - -
v0 < v1
v1 > v0
-
- 		True if v0 is less than v1 as an unsigned integer.
INT_SLESS -
- - - - - - - -
v0 s< v1
v1 s> v0
-
- 		True if v0 is less than v1 as a signed integer.
INT_LESSEQUAL -
- - - - - - - -
v0 <= v1
v1 >= v0
-
- 		True if v0 is less than or equal to v1 as an unsigned integer.
INT_SLESSEQUAL -
- - - - - - - -
v0 s<= v1
v1 s>= v0
-
- 		True if v0 is less than or equal to v1 as a signed integer.
INT_ZEXTzext(v0)Zero extension of v0.
INT_SEXTsext(v0)Sign extension of v0.
INT_ADDv0 + v1Addition of v0 and v1 as integers.
INT_SUBv0 - v1Subtraction of v1 from v0 as integers.
INT_CARRYcarry(v0,v1)True if adding v0 and v1 would produce an unsigned carry.
INT_SCARRYscarry(v0,v1)True if adding v0 and v1 would produce an signed carry.
INT_SBORROWsborrow(v0,v1)True if subtracting v1 from v0 would produce a signed borrow.
INT_2COMP-v0Twos complement of v0.
INT_NEGATE~v0Bitwise negation of v0.
INT_XORv0 ^ v1Bitwise Exclusive Or of v0 with v1.
INT_ANDv0 & v1Bitwise Logical And of v0 with v1.
INT_ORv0 | v1Bitwise Logical Or of v0 with v1.
INT_LEFTv0 << v1Left shift of v0 by v1 bits.
INT_RIGHTv0 >> v1Unsigned (logical) right shift of v0 by v1 bits.
INT_SRIGHTv0 s>> v1Signed (arithmetic) right shift of v0 by v1 bits.
INT_MULTv0 * v1Integer multiplication of v0 and v1.
INT_DIVv0 / v1Unsigned division of v0 by v1.
INT_REMv0 % v1Unsigned remainder of v0 modulo v1.
INT_SDIVv0 s/ v1Signed division of v0 by v1.
INT_SREMv0 s% v1Signed remainder of v0 modulo v1.
BOOL_NEGATE!v0Negation of boolean value v0.
BOOL_XORv0 ^^ v1Exclusive-Or of booleans v0 and v1.
BOOL_ANDv0 && v1Logical-And of booleans v0 and v1.
BOOL_ORv0 || v1Logical-Or of booleans v0 and v1.
FLOAT_EQUALv0 f== v1True if v0 equals v1 viewed as floating-point numbers.
FLOAT_NOTEQUALv0 f!= v1True if v0 does not equal v1 viewed as floating-point numbers.
FLOAT_LESS -
- - - - - - - -
v0 f< v1
v1 f> v0
-
- 		True if v0 is less than v1 viewed as floating-point numbers.
FLOAT_LESSEQUAL -
- - - - - - - -
v0 f<= v1
v1 f>= v0
-
- 		True if v0 is less than or equal to v1 viewed as floating-point numbers.
FLOAT_ADDv0 f+ v1Addition of v0 and v1 as floating-point numbers.
FLOAT_SUBv0 f- v1Subtraction of v1 from v0 as floating-point numbers.
FLOAT_MULTv0 f* v1Multiplication of v0 and v1 as floating-point numbers.
FLOAT_DIVv0 f/ v1Division of v0 by v1 as floating-point numbers.
FLOAT_NEGf- v0Additive inverse of v0 as a floating-point number.
FLOAT_ABSabs(v0)Absolute value of v0 as a floating-point number.
FLOAT_SQRTsqrt(v0)Square root of v0 as a floating-point number.
FLOAT_CEILceil(v0)Nearest integral floating-point value greater than v0, viewed as a floating-point number.
FLOAT_FLOORfloor(v0)Nearest integral floating-point value less than v0, viewed as a floating-point number.
FLOAT_ROUNDround(v0)Nearest integral floating-point to v0, viewed as a floating-point number.
FLOAT_NANnan(v0)True if v0 is not a valid floating-point number (NaN).
INT2FLOATint2float(v0)Floating-point representation of v0 viewed as an integer.
FLOAT2FLOATfloat2float(v0)Copy of floating-point number v0 with more or less precision.
TRUNCtrunc(v0)Signed integer obtained by truncating v0 viewed as a floating-point number.
CPOOLREFcpool(v0,...)Obtain constant pool value.
NEW -
- - - - - - - -
newobject(v0)
newobject(v0,v1)
-
- 		Allocate an object or an array of objects.
MULTIEQUAL<na>Compiler phi-node: values merging from multiple control-flow paths.
INDIRECT<na>Indirect effect from input varnode to output varnode.
CAST<na>Copy from input to output. A hint that the underlying datatype has changed.
PTRADD<na>Construct a pointer to an element from a pointer to the start of an array and an index.
PTRSUB<na>Construct a pointer to a field from a pointer to a structure and an offset.
INSERT<na>Insert a value as a bit-range into a varnode
EXTRACT<na>Extract a bit-range from a varnode
-
-
-
-
- - - - - - - - - - - -
-Prev   
Additional P-CODE Operations Home 
-
- - diff --git a/sources/GhidraDocs/languages/html/reference.md b/sources/GhidraDocs/languages/html/reference.md deleted file mode 100644 index 6fd2b2c..0000000 --- a/sources/GhidraDocs/languages/html/reference.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -status: collected -title: Syntax Reference -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/reference.html ---- - -# Syntax Reference - -Name|Syntax|Description -:-|:-|:- -COPY|`v0 = v1;`|Copy v1 into v0. -LOAD|`*v1`
`*[spc]v1`
`*:2 v1`
`*[spc]:2 v1`|Dereference v1 as pointer into default space. Optionally specify a space to load from and size of data in bytes. -STORE|`*v0 = v1`
`*[spc]v0 = v1`
`*;4 v0 = v1`
`*[spc]:4 v0 = v1`|Store in v1 in default space using v0 as pointer. Optionally specify space to store in and size of data in bytes. -BRANCH|`goto v0`|Branch execution to address of v0. -CBRANCH|`if (v0) goto v1;`|Branch execution to address of v1 if v0 equals 1 (true). -BRANCHIND|`goto [v0];`|Branch execution to value in v0 viewed as an offset into the current space. -CALL|`call v0;`|Branch execution to address of v0. Hint that the branch is a subroutine call. -CALLIND|`call [v0];`|Branch execution to value in v0 viewed as an offset into the current space. Hint that the branch is a subroutine call. -RETURN|`return [v0];`|Branch execution to value in v0 viewed as an offset into the current space. Hint that the branch is a subroutine return. -PIECE|``|Concatenate two varnodes into a single varnode. -SUBPIECE|`v0:2`|The least signficant n bytes of v0. -SUBPIECE|`v0(2)`|All but the least significant n bytes of v0. -POPCOUNT|`popcount(v0)`|Count 1 bits in v0. -LZCOUNT|`lzcount(v0)`|Counts the number of leading zero bits in v0. -INT_EQUAL|`v0 == v1`|True if v0 equals v1. -INT_NOTEQUAL|`v0 != v1`|True if v0 does not equal v1. -INT_LESS|`v0 < v1`
`v1 > v0`|True if v0 is less than v1 as an unsigned integer. -INT_SLESS|`v0 s< v1`
`v1 s> v0`|True if v0 is less than v1 as a signed integer. -INT_LESSEQUAL|`v0 <= v1`
`v1 >= v0`|True if v0 is less than or equal to v1 as an unsigned integer. -INT_SLESSEQUAL|`v0 s<= v1`
`v1 s>= v0`|True if v0 is less than or equal to v1 as a signed integer. -INT_ZEXT|`zext(v0)`|Zero extension of v0. -INT_SEXT|`sext(v0)`|Sign extension of v0. -INT_ADD|`v0 + v1`|Addition of v0 and v1 as integers. -INT_SUB|`v0 - v1`|Subtraction of v1 from v0 as integers. -INT_CARRY|`carry(v0,v1)`|True if adding v0 and v1 would produce an unsigned carry. -INT_SCARRY|`scarry(v0,v1)`|True if adding v0 and v1 would produce an signed carry. -INT_SBORROW|`sborrow(v0,v1)`|True if subtracting v1 from v0 would produce a signed borrow. -INT_2COMP|`~v0`|Twos complement of v0. -INT_NEGATE|`~v0`|Bitwise negation of v0. -INT_XOR|`v0 ^ v1`|Bitwise Exclusive Or of v0 with v1. -INT_AND|`v0 & v1`|Bitwise Logical And of v0 with v1. -INT_OR|`v0 | v1`|Bitwise Logical Or of v0 with v1. -INT_LEFT|`v0 << v1`|Left shift of v0 by v1 bits. -INT_RIGHT|`v0 >> v1`|Unsigned (logical) right shift of v0 by v1 bits. -INT_SRIGHT|`v0 s>> v1`|Signed (arithmetic) right shift of v0 by v1 bits. -INT_MULT|`v0 * v1`|Integer multiplication of v0 and v1. -INT_DIV|`v0 / v1`|Unsigned division of v0 by v1. -INT_REM|`v0 % v1`|Unsigned remainder of v0 modulo v1. -INT_SDIV|`v0 s/ v1`|Signed division of v0 by v1. -INT_SREM|`v0 s% v1`|Signed remainder of v0 modulo v1. -BOOL_NEGATE|`!v0`|Negation of boolean value v0. -BOOL_XOR|`v0 ^^ v1`|Exclusive-Or of booleans v0 and v1. -BOOL_AND|`v0 && v1`|Logical-And of booleans v0 and v1. -BOOL_OR|`v0 || v1`|Logical-Or of booleans v0 and v1. -FLOAT_EQUAL|`v0 f== v1`|True if v0 equals v1 viewed as floating-point numbers. -FLOAT_NOTEQUAL|`v0 f!= v1`|True if v0 does not equal v1 viewed as floating-point numbers. -FLOAT_LESS|`v0 f< v1`
`v1 f> v0`|True if v0 is less than v1 viewed as floating-point numbers. -FLOAT_LESSEQUAL|`v0 f<= v1`
`v1 f>= v0`|True if v0 is less than or equal to v1 viewed as floating-point numbers. -FLOAT_ADD|`v0 f+ v1`|Addition of v0 and v1 as floating-point numbers. -FLOAT_SUB|`v0 f- v1`|Subtraction of v1 from v0 as floating-point numbers. -FLOAT_MULT|`v0 f* v1`|Multiplication of v0 and v1 as floating-point numbers. -FLOAT_DIV|`v0 f/ v1`| Division of v0 by v1 as floating-point numbers. -FLOAT_NEG|`f- v0`|Additive inverse of v0 as a floating-point number. -FLOAT_ABS|`abs(v0)`|Absolute value of v0 as a floating-point number. -FLOAT_SQRT|`sqrt(v0)`|Square root of v0 as a floating-point number. -FLOAT_CEIL|`ceil(v0)`|Nearest integral floating-point value greater than v0, viewed as a floating-point number. -FLOAT_FLOOR|`floor(v0)`|Nearest integral floating-point value less than v0, viewed as a floating-point number. -FLOAT_ROUND|`round(v0)`|Nearest integral floating-point to v0, viewed as a floating-point number. -FLOAT_NAN|`nan(v0)`|True if v0 is not a valid floating-point number (NaN). -INT2FLOAT|`int2float(v0)`|Floating-point representation of v0 viewed as an integer. -FLOAT2FLOAT|`float2float(v0)`|Copy of floating-point number v0 with more or less precision. -TRUNC|`trunc(v0)`|Signed integer obtained by truncating v0 viewed as a floating-point number. -CPOOLREF|`cpool(v0,...)`|Obtain constant pool value. -NEW|`newobject(v0)`
`newobject(v0,v1)`|Allocate an object or an array of objects. -MULTIEQUAL|``|Compiler phi-node: values merging from multiple control-flow paths. -INDIRECT|``|Indirect effect from input varnode to output varnode. -CAST|``|Copy from input to output. A hint that the underlying datatype has changed. -PTRADD|``|Construct a pointer to an element from a pointer to the start of an array and an index. -PTRSUB|``|Construct a pointer to a field from a pointer to a structure and an offset. -INSERT|``|Insert a value as a bit-range into a varnode -EXTRACT|``|Extract a bit-range from a varnode \ No newline at end of file diff --git a/sources/GhidraDocs/languages/html/sleigh.html b/sources/GhidraDocs/languages/html/sleigh.html deleted file mode 100644 index 4ab92f7..0000000 --- a/sources/GhidraDocs/languages/html/sleigh.html +++ /dev/null @@ -1,478 +0,0 @@ - - - -SLEIGH - - - - - - - -
- - - - - - - -
SLEIGH
   Next -
-
-
-
-
-
-

-SLEIGH

-

A Language for Rapid Processor Specification

-

Last updated October 31, 2023

-

Originally published December 16, 2005

-
-
-
-
-

Table of Contents

-
-
1. Introduction to P-Code
-
-
1.1. Address Spaces
-
1.2. Varnodes
-
1.3. Operations
-
-
2. Basic Specification Layout
-
-
2.1. Comments
-
2.2. Identifiers
-
2.3. Strings
-
2.4. Integers
-
2.5. White Space
-
-
3. Preprocessing
-
-
3.1. Including Files
-
3.2. Preprocessor Macros
-
3.3. Conditional Compilation
-
-
4. Basic Definitions
-
-
4.1. Endianness Definition
-
4.2. Alignment Definition
-
4.3. Space Definitions
-
4.4. Naming Registers
-
4.5. Bit Range Registers
-
4.6. User-Defined Operations
-
-
5. Introduction to Symbols
-
-
5.1. Notes on Namespaces
-
5.2. Predefined Symbols
-
-
6. Tokens and Fields
-
-
6.1. Defining Tokens and Fields
-
6.2. Fields as Family Symbols
-
6.3. Attaching Alternate Meanings to Fields
-
6.4. Context Variables
-
-
7. Constructors
-
-
7.1. The Five Sections of a Constructor
-
7.2. The Table Header
-
7.3. The Display Section
-
7.4. The Bit Pattern Section
-
7.5. Disassembly Actions Section
-
7.6. The With Block
-
7.7. The Semantic Section
-
7.8. Tables
-
7.9. P-code Macros
-
7.10. Build Directives
-
7.11. Delay Slot Directives
-
-
8. Using Context
-
-
8.1. Basic Use of Context Variables
-
8.2. Local Context Change
-
8.3. Global Context Change
-
-
9. P-code Tables
-
-
-
-

-History

-

- This document describes the syntax for the SLEIGH processor - specification language, which was developed for the GHIDRA - project. The language that is now called SLEIGH has undergone - several redesign iterations, but it can still trace its heritage - from the language SLED, from whom its name is derived. SLED, the - “Specification Language for Encoding and Decoding”, was defined by - Norman Ramsey and Mary F. Fernández in [3] - as a concise way to define the - translation, in both directions, between machine instructions and - their corresponding assembly statements. This facilitated the - development of architecture independent disassemblers and - assemblers, such as the New Jersey Machine-code Toolkit. -

-

- The direct predecessor of SLEIGH was an implementation of SLED for - GHIDRA, which concentrated on its reverse-engineering - capabilities. The main addition of SLEIGH is the ability to provide - semantic descriptions of instructions for data-flow and decompilation - analysis. This piece of SLEIGH borrowed ideas from the Semantic Syntax Language (SSL), - a specification language developed in [2] for the - University of Queensland Binary Translator (UQBT) project by - Cristina Cifuentes, Mike Van Emmerik and Norman Ramsey. -

-

- Dr. Cristina Cifuentes' work, in general, was an important starting point for the GHIDRA decompiler. - Its design follows the basic structure layed out in her 1994 thesis "Reverse Compilation Techniques": -

-
    -
  • - Disassembly of machine instructions and translation to an intermediate representation (IR). -
    • -
  • - Transformation toward a high-level representation via -
      -
    • - Data-flow analysis, including dead code analysis and copy propagation. -
      • -
    • - Control-flow analysis, using graph reducibility to achieve a structured representation. -
      • -
    -
    • -
  • - Back-end code generation from the transformed representation. -
    • -
-

- In keeping with her philosophy of decompilation, SLEIGH is GHIDRA's implementation of the first step. - It efficiently couples disassembly of machine instructions with the initial translation into an IR. -

-
-

References

-
-

[1] Cristina Cifuentes. Reverse Compilation Techniques. 1994. Ph.D. Dissertation. Queensland University of Technology. Brisbane City, QLD, Australia.

-
-
-

[2] Cristina Cifuentes and Mike Van Emmerik. “UQBT: Adaptable Binary Translation at Low Cost”. Computer. (Mar. 2000). pp. 60-66.

-
-
-

[3] Norman Ramsey and Mary F. Fernández. “Specifying Representations of Machine Instructions”. ACM Trans. Programming Languages and Systems. (May 1997). pp. 492-524.

-
-
-
-
-

-Overview

-

-SLEIGH is a language for describing the instruction sets of general -purpose microprocessors, in order to facilitate the reverse -engineering of software written for them. SLEIGH was designed for the -GHIDRA reverse engineering platform and is used to describe -microprocessors with enough detail to facilitate two major components -of GHIDRA, the disassembly and decompilation engines. For disassembly, -SLEIGH allows a concise description of the translation from the bit -encoding of machine instructions to human-readable assembly language -statements. Moreover, it does this with enough detail to allow the -disassembly engine to break apart the statement into the mnemonic, -operands, sub-operands, and associated syntax. For decompilation, -SLEIGH describes the translation from machine instructions into -p-code. P-code is a Register Transfer Language -(RTL), distinct from SLEIGH, designed to specify -the semantics of machine instructions. By -semantics, we mean the detailed description of -how an instruction actually manipulates data, in registers and in -RAM. This provides the foundation for the data-flow analysis performed -by the decompiler. -

-

-A SLEIGH specification typically describes a single microprocessor and -is contained in a single file. The term processor -will always refer to this target of the specification. -

-

-Italics are used when defining terms and for named entities. Bold is used for SLEIGH keywords. -

-
-
-

-1. Introduction to P-Code

-

-Although p-code is a distinct language from SLEIGH, because a major -purpose of SLEIGH is to specify the translation from machine code to -p-code, this document serves as a primer for p-code. The key concepts -and terminology are presented in this section, and more detail is -given in Section 7.7, “The Semantic Section”. There is also a complete set -of tables which list syntax and descriptions for p-code operations in -the Appendix. -

-

-The design criteria for p-code was to have a language that looks much -like modern assembly instruction sets but capable of modeling any -general purpose processor. Code for different processors can be -translated in a straightforward manner into p-code, and then a single -suite of analysis software can be used to do data-flow analysis and -decompilation. In this way, the analysis software -becomes retargetable, and it isn’t necessary to -redesign it for each new processor being analyzed. It is only -necessary to specify the translation of the processor’s instruction -set into p-code. -

-

-So the key properties of p-code are -

-
    -
  • - The language is machine independent. -
    • -
  • - The language is designed to model general purpose processors. -
    • -
  • - Instructions operate on user defined registers and address spaces. -
    • -
  • - All data is manipulated explicitly. Instructions have no indirect effects. -
    • -
  • - Individual p-code operations mirror typical processor tasks and concepts. -
    • -
-

-

-

-SLEIGH is the language which specifies the translation from a machine -instruction to p-code. It specifies both this translation and how to -display the instruction as an assembly statement. -

-

-A model for a particular processor is built out of three concepts: -the address space, -the varnode, and -the operation. These are generalizations of the -computing concepts of RAM, registers, and machine instructions -respectively. -

-
-

-1.1. Address Spaces

-

-An address space for p-code is a generalization of -the indexed memory (RAM) that a typical processor has access to, and -it is defined simply as an indexed sequence of -memory words that can be read and written by -p-code. In almost all cases, a word of the space -is a byte (8 bits), and we will usually use the -term byte instead -of word. However, see the discussion of -the wordsize attribute of address -spaces below. -

-

-The defining characteristics of a space are its name and its size. The -size of a space indicates the number of distinct indices into the -space and is usually given as the number of bytes required to encode -an arbitrary index into the space. A space of size 4 requires a 32 bit -integer to specify all indices and contains -232 bytes. The index of a byte is usually -referred to as the offset, and the offset -together with the name of the space is called -the address of the byte. -

-

-Any manipulation of data that p-code operations perform happens in -some address space. This includes the modeling of data stored in RAM -but also includes the modeling of processor registers. Registers must -be modeled as contiguous sequences of bytes at a specific offset (see -the definition of varnodes below), typically in their own distinct -address space. In order to facilitate the modeling of many different -processors, a SLEIGH specification provides complete control over what -address spaces are defined and where registers are located within -them. -

-

-Typically, a processor can be modeled with only two spaces, -a ram address space that represents the main -memory accessible to the processor via its data-bus, and -a register address space that is used to -implement the processor’s registers. However, the specification -designer can define as many address spaces as needed. -

-

-There is one address space that is automatically defined for a SLEIGH -specification. This space is used to allocate temporary storage when -the SLEIGH compiler breaks down the expressions describing processor -semantics into individual p-code operations. It is called -the unique space. There is also a special address -space, called the const space, used as a -placeholder for constant operands of p-code instructions. For the most -part, a SLEIGH specification doesn’t need to be aware of this space, -but it can be used in certain situations to force values to be -interpreted as constants. -

-
-
-

-1.2. Varnodes

-

-A varnode is the unit of data manipulated by -p-code. It is simply a contiguous sequence of bytes in some address -space. The two defining characteristics of a varnode are -

-
    -
  • - The address of the first byte. -
    • -
  • - The number of bytes (size). -
    • -
-

-With the possible exception of constants treated as varnodes, there is -never any distinction made between one varnode and another. They can -have any size, they can overlap, and any number of them can be -defined. -

-

-Varnodes by themselves are typeless. An individual p-code operation -forces an interpretation on each varnode that it uses, as either an -integer, a floating-point number, or a boolean value. In the case of -an integer, the varnode is interpreted as having a big endian or -little endian encoding, depending on the specification (see -Section 4.1, “Endianness Definition”). Certain instructions -also distinguish between signed and unsigned interpretations. For a -signed integer, the varnode is considered to have a standard twos -complement encoding. For a boolean interpretation, the varnode must be -a single byte in size. In this special case, the zero encoding of the -byte is considered a false value and an encoding -of 1 is a true value. -

-

-These interpretations only apply to the varnode for a particular -operation. A different operation can interpret the same varnode in a -different way. Any consistent meaning assigned to a particular varnode -must be provided and enforced by the specification designer. -

-
-
-

-1.3. Operations

-

-P-code is intended to emulate a target processor by substituting a -sequence of p-code operations for each machine instruction. Thus every -p-code operation is naturally associated with the address of a -specific machine instruction, but there is usually more than one -p-code operation associated with a single machine instruction. Except -in the case of branching, p-code operations have fall-through control -flow, both within and across machine instructions. For a single -machine instruction, the associated p-code operations execute from -first to last. And if there is no branching, execution picks up with -the first operation corresponding to the next machine instruction. -

-

-Every p-code operation can take one or more varnodes as input and can -optionally have one varnode as output. The operation can only make a -change to this output varnode, which is always indicated -explicitly. Because of this rule, all manipulation of data is -explicit. The operations have no indirect effects. In general, there -is absolutely no restriction on what varnodes can be used as inputs -and outputs to p-code operations. The only exceptions to this are that -constants cannot be used as output varnodes and certain operations -impose restrictions on the size of their varnode operands. -

-

-The actual operations should be familiar to anyone who has studied -general purpose processor instruction sets. They break up into groups. -

-
-
-

Table 1. P-code Operations

-
--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Operation CategoryList of Operations
Data MovingCOPY, LOAD, STORE
ArithmeticINT_ADD, INT_SUB, INT_CARRY, INT_SCARRY, INT_SBORROW, - INT_2COMP, INT_MULT, INT_DIV, INT_SDIV, INT_REM, INT_SREM
LogicalINT_NEGATE, INT_XOR, INT_AND, INT_OR, INT_LEFT, INT_RIGHT, INT_SRIGHT, - POPCOUNT, LZCOUNT
Integer ComparisonINT_EQUAL, INT_NOTEQUAL, INT_SLESS, INT_SLESSEQUAL, INT_LESS, INT_LESSEQUAL
BooleanBOOL_NEGATE, BOOL_XOR, BOOL_AND, BOOL_OR
Floating PointFLOAT_ADD, FLOAT_SUB, FLOAT_MULT, FLOAT_DIV, FLOAT_NEG, - FLOAT_ABS, FLOAT_SQRT, FLOAT_NAN
Floating Point CompareFLOAT_EQUAL, FLOAT_NOTEQUAL, FLOAT_LESS, FLOAT_LESSEQUAL
Floating Point ConversionINT2FLOAT, FLOAT2FLOAT, TRUNC, CEIL, FLOOR, ROUND
BranchingBRANCH, CBRANCH, BRANCHIND, CALL, CALLIND, RETURN
Extension/TruncationINT_ZEXT, INT_SEXT, PIECE, SUBPIECE
Managed CodeCPOOLREF, NEW
-
-
-
-

-We postpone a full discussion of the individual operations until Section 7.7, “The Semantic Section”. -

-
-
-
-
-
- - - - - - - - - - - -
   Next -
   2. Basic Specification Layout
-
- - diff --git a/sources/GhidraDocs/languages/html/sleigh.md b/sources/GhidraDocs/languages/html/sleigh.md deleted file mode 100644 index 6578a22..0000000 --- a/sources/GhidraDocs/languages/html/sleigh.md +++ /dev/null @@ -1,563 +0,0 @@ ---- -status: collected -title: SLEIGH -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh.html ---- - -::: {.navheader} -SLEIGH -::: - -  - -  - - [Next](sleigh_layout.html) - ------------------------------------------------------------------------- - -::: {.article} -::: {.titlepage} -
- -
- -
- -
- -### *A Language for Rapid Processor Specification* {#a-language-for-rapid-processor-specification .subtitle} - -
- -
- -Last updated October 31, 2023 - -
- -
- -Originally published December 16, 2005 - -
- -
- ------------------------------------------------------------------------- -::: - -::: {.toc} -**Table of Contents** - -[[1. Introduction to P-Code](sleigh.html#sleigh_introduction)]{.sect1} - -[[1.1. Address Spaces](sleigh.html#sleigh_address_spaces)]{.sect2} - -[[1.2. Varnodes](sleigh.html#sleigh_varnodes)]{.sect2} - -[[1.3. Operations](sleigh.html#sleigh_operations)]{.sect2} - -[[2. Basic Specification Layout](sleigh_layout.html)]{.sect1} - -[[2.1. Comments](sleigh_layout.html#sleigh_comments)]{.sect2} - -[[2.2. Identifiers](sleigh_layout.html#sleigh_identifiers)]{.sect2} - -[[2.3. Strings](sleigh_layout.html#sleigh_strings)]{.sect2} - -[[2.4. Integers](sleigh_layout.html#sleigh_integers)]{.sect2} - -[[2.5. White Space](sleigh_layout.html#sleigh_white_space)]{.sect2} - -[[3. Preprocessing](sleigh_preprocessing.html)]{.sect1} - -[[3.1. Including -Files](sleigh_preprocessing.html#sleigh_including_files)]{.sect2} - -[[3.2. Preprocessor -Macros](sleigh_preprocessing.html#sleigh_preprocessor_macros)]{.sect2} - -[[3.3. Conditional -Compilation](sleigh_preprocessing.html#sleigh_conditional_compilation)]{.sect2} - -[[4. Basic Definitions](sleigh_definitions.html)]{.sect1} - -[[4.1. Endianness -Definition](sleigh_definitions.html#sleigh_endianness_definition)]{.sect2} - -[[4.2. Alignment -Definition](sleigh_definitions.html#sleigh_alignment_definition)]{.sect2} - -[[4.3. Space -Definitions](sleigh_definitions.html#sleigh_space_definitions)]{.sect2} - -[[4.4. Naming -Registers](sleigh_definitions.html#sleigh_naming_registers)]{.sect2} - -[[4.5. Bit Range -Registers](sleigh_definitions.html#sleigh_bitrange_registers)]{.sect2} - -[[4.6. User-Defined -Operations](sleigh_definitions.html#sleigh_userdefined_operations)]{.sect2} - -[[5. Introduction to Symbols](sleigh_symbols.html)]{.sect1} - -[[5.1. Notes on -Namespaces](sleigh_symbols.html#sleigh_notes_namespaces)]{.sect2} - -[[5.2. Predefined -Symbols](sleigh_symbols.html#sleigh_predefined_symbols)]{.sect2} - -[[6. Tokens and Fields](sleigh_tokens.html)]{.sect1} - -[[6.1. Defining Tokens and -Fields](sleigh_tokens.html#sleigh_defining_tokens)]{.sect2} - -[[6.2. Fields as Family -Symbols](sleigh_tokens.html#sleigh_fields_family)]{.sect2} - -[[6.3. Attaching Alternate Meanings to -Fields](sleigh_tokens.html#sleigh_alternate_meanings)]{.sect2} - -[[6.4. Context -Variables](sleigh_tokens.html#sleigh_context_variables)]{.sect2} - -[[7. Constructors](sleigh_constructors.html)]{.sect1} - -[[7.1. The Five Sections of a -Constructor](sleigh_constructors.html#sleigh_sections_constructor)]{.sect2} - -[[7.2. The Table -Header](sleigh_constructors.html#sleigh_table_header)]{.sect2} - -[[7.3. The Display -Section](sleigh_constructors.html#sleigh_display_section)]{.sect2} - -[[7.4. The Bit Pattern -Section](sleigh_constructors.html#sleigh_bit_pattern)]{.sect2} - -[[7.5. Disassembly Actions -Section](sleigh_constructors.html#sleigh_disassembly_actions)]{.sect2} - -[[7.6. The With -Block](sleigh_constructors.html#sleigh_with_block)]{.sect2} - -[[7.7. The Semantic -Section](sleigh_constructors.html#sleigh_semantic_section)]{.sect2} - -[[7.8. Tables](sleigh_constructors.html#sleigh_tables)]{.sect2} - -[[7.9. P-code Macros](sleigh_constructors.html#sleigh_macros)]{.sect2} - -[[7.10. Build -Directives](sleigh_constructors.html#sleigh_build_directives)]{.sect2} - -[[7.11. Delay Slot -Directives](sleigh_constructors.html#sleigh_delayslot_directives)]{.sect2} - -[[8. Using Context](sleigh_context.html)]{.sect1} - -[[8.1. Basic Use of Context -Variables](sleigh_context.html#sleigh_context_basic)]{.sect2} - -[[8.2. Local Context -Change](sleigh_context.html#sleigh_local_change)]{.sect2} - -[[8.3. Global Context -Change](sleigh_context.html#sleigh_global_change)]{.sect2} - -[[9. P-code Tables](sleigh_ref.html)]{.sect1} -::: - -::: {.simplesect} -::: {.titlepage} -
- -
- -[]{#sleigh_history}History {#history .title style="clear: both"} --------------------------- - -
- -
-::: - -This document describes the syntax for the SLEIGH processor -specification language, which was developed for the GHIDRA project. The -language that is now called SLEIGH has undergone several redesign -iterations, but it can still trace its heritage from the language SLED, -from whom its name is derived. SLED, the "Specification Language for -Encoding and Decoding", was defined by Norman Ramsey and Mary F. -Fernández in [\[3\]](sleigh.html#Ramsey97){.xref} as a concise way to -define the translation, in both directions, between machine instructions -and their corresponding assembly statements. This facilitated the -development of architecture independent disassemblers and assemblers, -such as the New Jersey Machine-code Toolkit. - -The direct predecessor of SLEIGH was an implementation of SLED for -GHIDRA, which concentrated on its reverse-engineering capabilities. The -main addition of SLEIGH is the ability to provide semantic descriptions -of instructions for data-flow and decompilation analysis. This piece of -SLEIGH borrowed ideas from the Semantic Syntax Language (SSL), a -specification language developed in -[\[2\]](sleigh.html#Cifuentes00){.xref} for the University of Queensland -Binary Translator (UQBT) project by Cristina Cifuentes, Mike Van Emmerik -and Norman Ramsey. - -Dr. Cristina Cifuentes\' work, in general, was an important starting -point for the GHIDRA decompiler. Its design follows the basic structure -layed out in her 1994 thesis \"Reverse Compilation Techniques\": - -::: {.informalexample} -::: {.itemizedlist} -- Disassembly of machine instructions and translation to an - intermediate representation (IR). -- Transformation toward a high-level representation via - ::: {.itemizedlist} - - Data-flow analysis, including dead code analysis and copy - propagation. - - Control-flow analysis, using graph reducibility to achieve a - structured representation. - ::: -- Back-end code generation from the transformed representation. -::: -::: - -In keeping with her philosophy of decompilation, SLEIGH is GHIDRA\'s -implementation of the first step. It efficiently couples disassembly of -machine instructions with the initial translation into an IR. - -::: {.bibliolist} -**References** - -::: {.biblioentry} -[]{#Cifuentes94} - -\[1\] [[Cristina]{.firstname} [Cifuentes]{.surname}. -]{.authorgroup}[*Reverse Compilation Techniques*. ]{.title}[1994. -]{.pubdate}[[Ph.D. Dissertation. Queensland University of Technology. -]{.publishername}[[Brisbane City]{.city}, [QLD]{.state}, -[Australia]{.country}. ]{.address}]{.publisher} -::: - -::: {.biblioentry} -[]{#Cifuentes00} - -\[2\] [[[Cristina]{.firstname} [Cifuentes]{.surname} and -[Mike]{.firstname} [Van Emmerik]{.surname}. ]{.authorgroup}"UQBT: -Adaptable Binary Translation at Low Cost". ]{.biblioset}[*Computer*. -[(Mar. 2000). ]{.date}[pp. 60-66. ]{.pagenums}]{.biblioset} -::: - -::: {.biblioentry} -[]{#Ramsey97} - -\[3\] [[[Norman]{.firstname} [Ramsey]{.surname} and [Mary -F.]{.firstname} [Fernández]{.surname}. ]{.authorgroup}"Specifying -Representations of Machine Instructions". ]{.biblioset}[*ACM Trans. -Programming Languages and Systems*. [(May 1997). ]{.date}[pp. 492-524. -]{.pagenums}]{.biblioset} -::: -::: -::: - -::: {.simplesect} -::: {.titlepage} -
- -
- -[]{#sleigh_overview}Overview {#overview .title style="clear: both"} ----------------------------- - -
- -
-::: - -SLEIGH is a language for describing the instruction sets of general -purpose microprocessors, in order to facilitate the reverse engineering -of software written for them. SLEIGH was designed for the GHIDRA reverse -engineering platform and is used to describe microprocessors with enough -detail to facilitate two major components of GHIDRA, the disassembly and -decompilation engines. For disassembly, SLEIGH allows a concise -description of the translation from the bit encoding of machine -instructions to human-readable assembly language statements. Moreover, -it does this with enough detail to allow the disassembly engine to break -apart the statement into the mnemonic, operands, sub-operands, and -associated syntax. For decompilation, SLEIGH describes the translation -from machine instructions into [*p-code*]{.emphasis}. P-code is a -Register Transfer Language (RTL), distinct from SLEIGH, designed to -specify the [*semantics*]{.emphasis} of machine instructions. By -[*semantics*]{.emphasis}, we mean the detailed description of how an -instruction actually manipulates data, in registers and in RAM. This -provides the foundation for the data-flow analysis performed by the -decompiler. - -A SLEIGH specification typically describes a single microprocessor and -is contained in a single file. The term [*processor*]{.emphasis} will -always refer to this target of the specification. - -Italics are used when defining terms and for named entities. Bold is -used for SLEIGH keywords. -::: - -::: {.sect1} -::: {.titlepage} -
- -
- -[]{#sleigh_introduction}1. Introduction to P-Code {#introduction-to-p-code .title style="clear: both"} -------------------------------------------------- - -
- -
-::: - -Although p-code is a distinct language from SLEIGH, because a major -purpose of SLEIGH is to specify the translation from machine code to -p-code, this document serves as a primer for p-code. The key concepts -and terminology are presented in this section, and more detail is given -in [Section 7.7, "The Semantic -Section"](sleigh_constructors.html#sleigh_semantic_section "7.7. The Semantic Section"){.xref}. -There is also a complete set of tables which list syntax and -descriptions for p-code operations in the Appendix. - -The design criteria for p-code was to have a language that looks much -like modern assembly instruction sets but capable of modeling any -general purpose processor. Code for different processors can be -translated in a straightforward manner into p-code, and then a single -suite of analysis software can be used to do data-flow analysis and -decompilation. In this way, the analysis software becomes -[*retargetable*]{.emphasis}, and it isn't necessary to redesign it for -each new processor being analyzed. It is only necessary to specify the -translation of the processor's instruction set into p-code. - -So the key properties of p-code are - -::: {.informalexample} -::: {.itemizedlist} -- The language is machine independent. -- The language is designed to model general purpose processors. -- Instructions operate on user defined registers and address spaces. -- All data is manipulated explicitly. Instructions have no indirect - effects. -- Individual p-code operations mirror typical processor tasks and - concepts. -::: -::: - -SLEIGH is the language which specifies the translation from a machine -instruction to p-code. It specifies both this translation and how to -display the instruction as an assembly statement. - -A model for a particular processor is built out of three concepts: the -[*address space*]{.emphasis}, the [*varnode*]{.emphasis}, and the -[*operation*]{.emphasis}. These are generalizations of the computing -concepts of RAM, registers, and machine instructions respectively. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_address_spaces}1.1. Address Spaces {#address-spaces .title} - -
- -
-::: - -An [*address*]{.emphasis} space for p-code is a generalization of the -indexed memory (RAM) that a typical processor has access to, and it is -defined simply as an indexed sequence of memory [*words*]{.emphasis} -that can be read and written by p-code. In almost all cases, a -[*word*]{.emphasis} of the space is a [*byte*]{.emphasis} (8 bits), and -we will usually use the term [*byte*]{.emphasis} instead of -[*word*]{.emphasis}. However, see the discussion of the -[**wordsize**]{.bold} attribute of address spaces below. - -The defining characteristics of a space are its name and its size. The -size of a space indicates the number of distinct indices into the space -and is usually given as the number of bytes required to encode an -arbitrary index into the space. A space of size 4 requires a 32 bit -integer to specify all indices and contains 2^32^ bytes. The index of a -byte is usually referred to as the [*offset*]{.emphasis}, and the offset -together with the name of the space is called the [*address*]{.emphasis} -of the byte. - -Any manipulation of data that p-code operations perform happens in some -address space. This includes the modeling of data stored in RAM but also -includes the modeling of processor registers. Registers must be modeled -as contiguous sequences of bytes at a specific offset (see the -definition of varnodes below), typically in their own distinct address -space. In order to facilitate the modeling of many different processors, -a SLEIGH specification provides complete control over what address -spaces are defined and where registers are located within them. - -Typically, a processor can be modeled with only two spaces, a -[*ram*]{.emphasis} address space that represents the main memory -accessible to the processor via its data-bus, and a -[*register*]{.emphasis} address space that is used to implement the -processor's registers. However, the specification designer can define as -many address spaces as needed. - -There is one address space that is automatically defined for a SLEIGH -specification. This space is used to allocate temporary storage when the -SLEIGH compiler breaks down the expressions describing processor -semantics into individual p-code operations. It is called the -[*unique*]{.emphasis} space. There is also a special address space, -called the [*const*]{.emphasis} space, used as a placeholder for -constant operands of p-code instructions. For the most part, a SLEIGH -specification doesn't need to be aware of this space, but it can be used -in certain situations to force values to be interpreted as constants. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_varnodes}1.2. Varnodes {#varnodes .title} - -
- -
-::: - -A [*varnode*]{.emphasis} is the unit of data manipulated by p-code. It -is simply a contiguous sequence of bytes in some address space. The two -defining characteristics of a varnode are - -::: {.informalexample} -::: {.itemizedlist} -- The address of the first byte. -- The number of bytes (size). -::: -::: - -With the possible exception of constants treated as varnodes, there is -never any distinction made between one varnode and another. They can -have any size, they can overlap, and any number of them can be defined. - -Varnodes by themselves are typeless. An individual p-code operation -forces an interpretation on each varnode that it uses, as either an -integer, a floating-point number, or a boolean value. In the case of an -integer, the varnode is interpreted as having a big endian or little -endian encoding, depending on the specification (see [Section 4.1, -"Endianness -Definition"](sleigh_definitions.html#sleigh_endianness_definition "4.1. Endianness Definition"){.xref}). -Certain instructions also distinguish between signed and unsigned -interpretations. For a signed integer, the varnode is considered to have -a standard twos complement encoding. For a boolean interpretation, the -varnode must be a single byte in size. In this special case, the zero -encoding of the byte is considered a [*false*]{.emphasis} value and an -encoding of 1 is a [*true*]{.emphasis} value. - -These interpretations only apply to the varnode for a particular -operation. A different operation can interpret the same varnode in a -different way. Any consistent meaning assigned to a particular varnode -must be provided and enforced by the specification designer. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_operations}1.3. Operations {#operations .title} - -
- -
-::: - -P-code is intended to emulate a target processor by substituting a -sequence of p-code operations for each machine instruction. Thus every -p-code operation is naturally associated with the address of a specific -machine instruction, but there is usually more than one p-code operation -associated with a single machine instruction. Except in the case of -branching, p-code operations have fall-through control flow, both within -and across machine instructions. For a single machine instruction, the -associated p-code operations execute from first to last. And if there is -no branching, execution picks up with the first operation corresponding -to the next machine instruction. - -Every p-code operation can take one or more varnodes as input and can -optionally have one varnode as output. The operation can only make a -change to this [*output varnode*]{.emphasis}, which is always indicated -explicitly. Because of this rule, all manipulation of data is explicit. -The operations have no indirect effects. In general, there is absolutely -no restriction on what varnodes can be used as inputs and outputs to -p-code operations. The only exceptions to this are that constants cannot -be used as output varnodes and certain operations impose restrictions on -the [*size*]{.emphasis} of their varnode operands. - -The actual operations should be familiar to anyone who has studied -general purpose processor instruction sets. They break up into groups. - -::: {.informalexample} -::: {.table} -[]{#ops.htmltable} - -**Table 1. P-code Operations** - -::: {.table-contents} - --------------------------------------------------------------------------------------------------------------------------------------------------------- - [**Operation [**List of Operations**]{.bold} - Category**]{.bold} - ---------------------------- ---------------------------------------------------------------------------------------------------------------------------- - Data Moving `COPY, LOAD, STORE`{.code} - - Arithmetic `INT_ADD, INT_SUB, INT_CARRY, INT_SCARRY, INT_SBORROW, INT_2COMP, INT_MULT, INT_DIV, INT_SDIV, INT_REM, INT_SREM`{.code} - - Logical `INT_NEGATE, INT_XOR, INT_AND, INT_OR, INT_LEFT, INT_RIGHT, INT_SRIGHT, POPCOUNT, LZCOUNT`{.code} - - Integer Comparison `INT_EQUAL, INT_NOTEQUAL, INT_SLESS, INT_SLESSEQUAL, INT_LESS, INT_LESSEQUAL`{.code} - - Boolean `BOOL_NEGATE, BOOL_XOR, BOOL_AND, BOOL_OR`{.code} - - Floating Point `FLOAT_ADD, FLOAT_SUB, FLOAT_MULT, FLOAT_DIV, FLOAT_NEG, FLOAT_ABS, FLOAT_SQRT, FLOAT_NAN`{.code} - - Floating Point Compare `FLOAT_EQUAL, FLOAT_NOTEQUAL, FLOAT_LESS, FLOAT_LESSEQUAL`{.code} - - Floating Point Conversion `INT2FLOAT, FLOAT2FLOAT, TRUNC, CEIL, FLOOR, ROUND`{.code} - - Branching `BRANCH, CBRANCH, BRANCHIND, CALL, CALLIND, RETURN`{.code} - - Extension/Truncation `INT_ZEXT, INT_SEXT, PIECE, SUBPIECE`{.code} - - Managed Code `CPOOLREF, NEW`{.code} - --------------------------------------------------------------------------------------------------------------------------------------------------------- -::: -::: - -\ -::: - -We postpone a full discussion of the individual operations until -[Section 7.7, "The Semantic -Section"](sleigh_constructors.html#sleigh_semantic_section "7.7. The Semantic Section"){.xref}. -::: -::: -::: - -::: {.navfooter} - ------------------------------------------------------------------------- - - --- --- -------------------------------- -      [Next](sleigh_layout.html) -      2. Basic Specification Layout - --- --- -------------------------------- -::: diff --git a/sources/GhidraDocs/languages/html/sleigh_constructors.html b/sources/GhidraDocs/languages/html/sleigh_constructors.html deleted file mode 100644 index 3b4dde0..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_constructors.html +++ /dev/null @@ -1,2305 +0,0 @@ - - - -7. Constructors - - - - - - - - - -
- - - - - - - -
7. Constructors
-Prev   Next -
-
-
-
-

-7. Constructors

-

-Fields are the basic building block for family symbols. The mechanisms -for building up from fields to the -root instruction symbol are -the constructor and table. -

-

-A constructor is the unit of syntax for building -new symbols. In essence a constructor describes how to build a new -family symbol, by describing, in turn, how to build a new display -meaning, how to build a new semantic meaning, and how encodings map to -these new meanings. A table is a set of one or -more constructors and is the final step in creating a new family -symbol identifier associated with the pieces defined by -constructors. The name of the table is this new identifier, and it is -this identifier which can be used in the syntax for subsequent -constructors. -

-

-The difference between a constructor and table is slightly confusing -at first. In short, the syntactical elements described in this -chapter, for combining existing symbols into new symbols, are all used -to describe a single constructor. Specifications for multiple -constructors are combined to describe a single table. Since many -tables are built with only one constructor, it is natural and correct -to think of a constructor as a kind of table in and of itself. But it -is only the table that has an actual family symbol identifier -associated with it. Most of this chapter is devoted to describing how -to define a single constructor. The issues involved in combining -multiple constructors into a single table are addressed in Section 7.8, “Tables”. -

-
-

-7.1. The Five Sections of a Constructor

-

-A single complex statement in the specification file describes a -constructor. This statement is always made up of five distinct -sections that are listed below in the order in which the must occur. -

-
    -
  1. - Table Header -
    2. -
  2. - Display Section -
    3. -
  3. - Bit Pattern Sections -
    4. -
  4. - Disassembly Actions Section -
    5. -
  5. - Semantics Actions Section -
    6. -
-

-The full set of rules for correctly writing each section is long and -involved, but for any given constructor in a real specification file, -the syntax typically fits on a single line. We describe each section -in turn. -

-
-
-

-7.2. The Table Header

-

-Every constructor must be part of a table, which is the element with -an actual family symbol identifier associated with it. So each -constructor starts with the identifier of the table it belongs to -followed by a colon ‘:’. -

-
-mode1:           ...
-
-

-

-

-The above line starts the definition of a constructor that is part of -the table identified as mode1. If the identifier -has not appeared before, a new table is created. If other constructors -have used the identifier, the new constructor becomes an additional -part of that same table. A constructor in the -root instruction table is defined by omitting the -identifier. -

-
-:                ...
-
-

-

-

-The identifier instruction is actually reserved -for the root table, but should not be used in the table header as the -SLEIGH parser uses the blank identifier to help distinguish assembly -mnemonics from operands (see Section 7.3.1, “Mnemonic”). -

-
-
-

-7.3. The Display Section

-

-The display section consists of all characters -after the table header ‘:’ up to the SLEIGH -keyword is. The section’s primary -purpose is to assign disassembly display meaning to the -constructor. The section’s secondary purpose is to define local -identifiers for the pieces out of which the constructor is being -built. Characters in the display section are treated as literals with -the following exceptions. -

-
    -
  • - Legal identifiers are not treated literally unless -
      -
    1. - The identifier is surrounded by double quotes. -
      2. -
    2. - The identifier is considered a mnemonic (see below). -
      3. -
    -
    • -
  • - The character ‘^’ has special meaning. -
    • -
  • - White space is trimmed from the beginning and end of the section. -
    • -
  • - Other sequences of white space characters are condensed into a single space. -
    • -
-

-

-

-In particular, all punctuation except ‘^’ loses its special -meaning. Those identifiers that are not treated as literals are -considered to be new, initially undefined, family symbols. We refer to -these new symbols as the operands of the constructor. And for root -constructors, these operands frequently correspond to the natural -assembly operands. Thinking of it as a family symbol, the -constructor’s display meaning becomes the string of literals itself, -with each identifier replaced with the display meaning of the symbol -corresponding to that identifier. -

-
-mode1: ( op1 ),op2 is          ...
-
-

-

-

-In the above example, a constructor for -table mode1 is being built out of two pieces, -symbol op1 and -symbol op2. The characters ‘(‘, ’)’, and ‘,’ -become literal parts of the disassembly display for symbol -mode1. After the display strings for op1 -and op2 are found, they are inserted into the -string of literals, forming the constructor’s display string. The -white space characters surrounding the op1 -identifier are preserved as part of this string. -

-

-The identifiers op1 and op2 -are local to the constructor and can mask global symbols with the same -names. The symbols will (must) be defined in the following sections, -but only their identifiers are established in the display section. -

-
-

-7.3.1. Mnemonic

-

-If the constructor is part of the root instruction table, the first -string of characters in the display section that does not contain -white space is treated as the literal mnemonic of -the instruction and is not considered a local symbol identifier even -if it is legal. -

-
-:and (var1) is                 ...
-
-

-

-

-In the above example, the string “var1” is treated as a symbol -identifier, but the string “and” is considered to be the mnemonic of -the instruction. -

-

-There is nothing that special about the mnemonic. As far as the -display meaning of the constructor is concerned, it is just a sequence -of literal characters. Although the current parser does not concern -itself with this, the mnemonic of any assembly language instruction in -general is used to guarantee the uniqueness of the assembly -representation. It is conceivable that a forward engineering engine -built on SLEIGH would place additional requirements on the mnemonic to -assure uniqueness, but for reverse engineering applications there is -no such requirement. -

-
-
-

-7.3.2. The '^' character

-

-The ‘^’ character in the display section is used to separate -identifiers from other characters where there shouldn’t be white space -in the disassembly display. This can be used in any manner but is -usually used to attach display characters from a local symbol to the -literal characters of the mnemonic. -

-
-:bra^cc op1,op2 is             ...
-
-

-

-

-In the above example, “bra” is treated as literal characters in the -resulting display string followed immediately, with no intervening -spaces, by the display string of the local -symbol cc. Thus the whole constructor actually -has three operands, denoted by the three -identifiers cc, op1, -and op2. -

-

-If the ‘^’ is used as the first (non-whitespace) character in the -display section of a base constructor, this inhibits the first -identifier in the display from being considered the mnemonic, as -described in Section 7.3.1, “Mnemonic”. This allows -specification of less common situations, where the first part of the -mnemonic, rather than perhaps a later part, needs to be considered as -an operand. An initial ‘^’ character can also facilitate certain -recursive constructions. -

-
-
-
-

-7.4. The Bit Pattern Section

-

-Syntactically, this section comes between the -keyword is and the delimiter for the -following section, either an ‘{‘ or an ‘[‘. The bit pattern -section describes a -constructor’s pattern, the subset of possible -instruction encodings that the designer wants -to match the constructor being defined. -

-
-

-7.4.1. Constraints

-

-The patterns required for processor specifications can almost always -be described as a mask and value pair. Given a specific instruction -encoding, we can decide if the encoding matches our pattern by looking -at just the bits specified by the mask and seeing -if they match a specific value. The fields, as -defined in Section 6.1, “Defining Tokens and Fields”, typically give us -our masks. So to construct a pattern, we can simply require that the -field take on a specific value, as in the example below. -

-
-:halt is opcode=0x15 {         ...
-
-

-Assuming the symbol opcode was defined as a field, this says that a -root constructor with mnemonic “halt” matches any instruction where -the bits defining this field have the value 0x15. The equation -“opcode=0x15” is called a constraint. -

-

-The standard bit encoding of the integer is used when restricting the -value of a field. This encoding is used even if -an attach statement has assigned a -different meaning to the field. The alternate meaning does not apply -within the pattern. This can be slightly confusing, particularly in -the case of an attach values -statement, which provides an alternate integer interpretation of the -field. -

-
-
-

-7.4.2. The '&' and '|' Operators

-

-More complicated patterns are built out of logical operators. The -meaning of these are fairly straightforward. We can force two or more -constraints to be true at the same time, a logical -and ‘&’, or we can require that either one constraint or -another must be true, a logical or ‘|’. By using these with -constraints and parentheses for grouping, arbitrarily complicated -patterns can be constructed. -

-
-:nop is (opcode=0 & mode=0) | (opcode=15) { ...
-
-

-

-

-Of the two operators, the logical and is much -more common. The SLEIGH compiler typically can group together several -constraints that are combined with this operator into a single -efficient mask/value check, so this operator is to be preferred if at -all possible. The logical or operator usually -requires two or more mask/value style checks to correctly implement. -

-
-
-

-7.4.3. Defining Operands and Invoking Subtables

-

-The principle way of defining a constructor operand, left undefined -from the display section, is done in the bit pattern section. If an -operand’s identifier is used by itself, not as part of a constraint, -then the operand takes on both the display and semantic definition of -the global symbol with the same identifier. The syntax is slightly -confusing at first. The identifier must appear in the pattern as if it -were a term in a sequence of constraints but without the operator and -right-hand side of the constraint. -

-
-define token instr(32)
-    opcode = (0,5)
-    r1 = (6,10)
-    r2 = (11,15);
-attach variables [ r1 r2 ] [ reg0 reg1 reg2 reg3 ];
-
-:add r1,r2 is opcode=7 & r1 & r2 { ...
-
-

-

-

-This is a typical example. The add instruction -must have the bits in the opcode field set -specifically. But it also uses two fields in the instruction which -specify registers. The r1 -and r2 identifiers are defined to be local -because they appear in the display section, but their use in the -pattern section of the definition links the local symbols with the -global register symbols defined as fields with attached registers. The -constructor is essentially saying that it is building the -full add instruction encoding out of the register -fields r1 and r2 but is not -specifying their value. -

-

-The syntax makes a little more sense keeping in mind this principle: -

-
  • - The pattern must somehow specify all the bits and symbols - being used by the constructor, even if the bits are not restricted - to specific values. -
-

-The linkage from local symbol to global symbol will happen for any -global identifier which represents a family symbol, including table -symbols. This is in fact the principle mechanism for recursively -building new symbols from old symbols. For those familiar with grammar -parsers, a SLEIGH specification is in part a grammar -specification. The terminal symbols, or tokens, are the bits of an -instruction, and the constructors and tables are the non-terminating -symbols. These all build up to the root instruction table, the -grammar’s start symbol. So this link from local to global is simply a -statement of the grouping of old symbols into the new constructor. -

-
-
-

-7.4.4. Variable Length Instructions

-

-There are some additional complexities to designing a specification -for a processor with variable length instructions. Some initial -portion of an instruction must always be parsed. But depending on the -fields in this first portion, additional portions of varying lengths -may need to be read. The key to incorporating this behavior into a -SLEIGH specification is the token. Recall that all fields are built on -top of a token which is defined to be a specific number of bytes. If a -processor has fixed length instructions, the specification needs to -define only a single token representing the entire instruction, and -all fields are built on top of this one token. For processors with -variable length instructions however, more than one token needs to be -defined. Each token has different fields defined upon it, and the -SLEIGH compiler can distinguish which tokens are involved in a -particular constructor by examining the fields it uses. The tokens -that are actually used by any matching constructors determine the -final length of the instruction. SLEIGH has two operators that are -specific to variable length instruction sets and that give the -designer control over how tokens fit together. -

-
-
-7.4.4.1. The ';' Operator
-

-The most important operator for patterns defining variable length -instructions is the concatenation operator ‘;’. When building a -constructor with fields from two or more tokens, the pattern must -explicitly define the order of the tokens. In terms of the logic of -the pattern expressions themselves, the ‘;’ operator has the same -meaning as the ‘&’ operator. The combined expression matches only if -both subexpressions are true. However, it also requires that the -subexpressions involve multiple tokens and explicitly indicates an -order for them. -

-
-define token base(8)
-    op=(0,3)
-    mode=(4,4)
-    reg=(5,7);
-define token immtoken(16)
-    imm16 = (0,15);
-
-:inc reg       is op=2 & reg        { ...
-:add reg,imm16 is op=3 & reg; imm16 { ...
-
-

-

-

-In the above example, we see the definitions of two different -tokens, base -and immtoken. For the first -instruction, inc, the constructor uses -fields op and reg, both -defined on base. Thus, the pattern applies -constraints to just a single byte, the size of base, in the -corresponding encoding. The second -instruction, add, uses -fields op and reg, but it -also uses field imm16 contained -in immtoken. The ‘;’ operator indicates that -token base (via its fields) comes first in the -encoding, followed by immtoken. The constraints -on base will therefore correspond to constraints -on the first byte of the encoding, and the constraints -on immtoken will apply to the second and third -bytes. The length of the final encoding for add -will be 3 bytes, the sum of the lengths of the two tokens. -

-

-If two pattern expressions are combined with the ‘&’ or ‘|’ operator, -where the concatenation operator ‘;’ is also being used, the designer -must make sure that the tokens underlying each expression are the same -and come in the same order. In the example add -instruction for instance, the ‘&’ operator combines the “op=3” and -“reg” expressions. Both of these expressions involve only the -token base, so the matching requirement is -satisfied. The ‘&’ and ‘|’ operators can combine expressions built out -of more than one token, but the tokens must come in the same -order. Also these operators have higher precedence than the ‘;’ -operator, so parentheses may be necessary to get the intended meaning. -

-
-
-
-7.4.4.2. The '...' Operator
-

-The ellipsis operator ‘...’ is used to satisfy the token matching -requirements of the ‘&’ and ‘|’ operators (described in the previous -section), when the operands are of different lengths. The ellipsis is -a unary operator applied to a pattern expression that extends its -token length before it is combined with another expression. Depending -on what side of the expression the ellipsis is applied, the -expression's tokens are either right or left justified within the -extension. -

-
-addrmode: reg is reg & mode=0    {     ...
-addrmode: #imm16 is mode=1; imm16    {  ...
-
-:xor “A”,addrmode is op=4 ... & addrmode {	...
-
-

-

-

-Extending the example from the previous section, we add a -subtable addrmode, representing an operand that -can be encoded either as a register, if mode is -set to zero, or as an immediate value, if -the mode bit is one. If the immediate value mode -is selected, the operand is built by reading an additional two bytes -directly from the instruction encoding. So -the addrmode table can represent a 1 byte or a 3 -byte encoding depending on the mode. In the -following xor -instruction, addrmode is used as an operand. The -particular instruction is selected by encoding a 4 in -the op field, so it requires a constraint on that -field in the pattern expression. Since the instruction uses -the addrmode operand, it must combine the -constraint on op with the pattern -for addrmode. But op -involves only the token base, -while addrmode may also -involve immtoken. The ellipsis operator resolves -the conflict by extending the op constraint to be -whatever the length of addrmode turns out to be. -

-

-Since the op constraint occurs to the left of the -ellipsis, it is considered left justified, and the matching -requirement for ‘&’ will insist that base is the -first token in all forms of addrmode. This allows -the xor instruction's constraint -on op and the addrmode -constraint on mode to be combined into -constraints on a single byte in the final encoding. -

-
-
-
-

-7.4.5. Invisible Operands

-

-It is not necessary for a global symbol, which is needed by a -constructor, to appear in the display section of the definition. If -the global identifier is used in the pattern section as it would be -for a normal operand definition but the identifier was not used in the -display section, then the constructor defines an invisible -operand. Such an operand behaves and is parsed exactly like -any other operand but there is absolutely no visible indication of the -operand in the final display of the assembly instruction. The one -common type of instruction that uses this is the relative branch (see -Section 7.5.1, “Relative Branches”) but it is otherwise needed -only in more esoteric instructions. It is useful in situations where -you need to break up the parsing of an instruction along lines that -don’t quite match the assembly. -

-
-
-

-7.4.6. Empty Patterns

-

-Occasionally there is a need for an empty pattern when building -tables. An empty pattern matches everything. There is a predefined -symbol epsilon which has been traditionally used -to indicate an empty pattern. -

-
-
-

-7.4.7. Advanced Constraints

-

-A constraint does not have to be of the form “field = constant”, -although this is almost always what is needed. In certain situations, -it may be more convenient to use a different kind of -constraint. Special care should be taken when designing these -constraints because they can substantially deviate from the mask/value -model used to implement most constraints. These more general -constraints are implemented by splitting it up into smaller states -which can be modeled as a mask/value pair. This is all done -automatically, and the designer may inadvertently create huge numbers -of parsing states for a single constraint. -

-

-A constraint can actually be built out of arbitrary -expressions. These pattern expressions are more -commonly used in disassembly actions and are defined in -Section 7.5.2, “General Actions and Pattern Expressions”, but they can also be used in -constraints. So in general, a constraint is any equation where the -left-hand side is a single family symbol, the right-hand side is an -arbitrary pattern expression, and the constraint operator is one of -the following: -

-
-
-

Table 3. Constraint Operators

-
--- - - - - - - - - - - - - - - - - - - - - - -
Operator NameSyntax
Integer equality=
Integer inequality!=
Integer less-than<
Integer greater-than>
-
-
-
-

-For a particular instruction encoding, each variable evaluates to a -specific integer depending on the encoding. A constraint is satisfied -if, when all the variables are evaluated, the equation is true. -

-
-:xor r1,r2 is opcode=0xcd & r1 & r2 { r1 = r1 ^ r2; }
-:clr r1    is opcode=0xcd & r1 & r1=r2 { r1 = 0; }
-
-

-

-

-The above example illustrates a situation that does come up -occasionally. A processor uses an exclusive-or instruction to clear a -register by setting both operands of the instruction to the same -register. The first line in the example illustrates such an -instruction. However, processor documentation stipulates, and analysts -prefer, that, in this case, the disassembler should print a -pseudo-instruction clr. The distinguishing -feature of clr from xor is -that the two fields, specifying the two register inputs -to xor, are equal. The easiest way to specify -this special case is with the general constraint, -“r1 = r2”, as in the second -line of the example. The SLEIGH compiler will implement this by -enumerating all the cases where r1 -equals r2, creating as many states as there are -registers. But the specification itself, at least, remains compact. -

-
-
-
-

-7.5. Disassembly Actions Section

-

-After the bit pattern section, there can optionally be a section for -doing dynamic calculations, which must be between square brackets. For -certain kinds of instructions, there is a need to calculate values -that depend on the specific bits of the instruction, but which cannot -be obtained as an integer interpretation of a field or by building -with an attach values statement. So -SLEIGH provides a mechanism to build values of arbitrary -complexity. This section is not intended to emulate the execution of -the processor (this is the job of the semantic section) but is -intended to produce only those values that are needed at disassembly -time, usually for part of the disassembly display. -

-
-

-7.5.1. Relative Branches

-

-The canonical example of an action at disassembly time is a branch -relocation. A jump instruction encodes the address of where it jumps -to as a relative offset to the instruction’s address, for -instance. But when we display the assembly, we want to show the -absolute address of the jump destination. The correct way to specify -this is to reserve an identifier in the display section which -represents the absolute address, but then, instead of defining it in -the pattern section, we define it in the disassembly action section as -a function of the current address and the relative offset. -

-
-jmpdest: reloc is simm8 [ reloc=inst_next + simm8*4; ] { ...
-
-

-

-

-The identifier reloc is reserved in the display -section for this constructor, but the identifier is not defined in the -pattern section. Instead, an invisible -operand simm8 is defined which is attached to a -global field definition. The reloc identifier is -defined in the action section as the integer obtained by adding a -multiple of simm8 -to inst_next, a symbol predefined to be equal to -the address of the following instruction (see -Section 5.2, “Predefined Symbols”). Now reloc -is a specific symbol with both semantic and display meaning equal to -the desired absolute address. This address is calculated separately, -at disassembly time, for every instruction that this constructor -matches. -

-
-
-

-7.5.2. General Actions and Pattern Expressions

-

-In general, the disassembly actions are encoded as a sequence of -assignments separated by semicolons. The left-hand side of each -statement must be a single operand identifier, and the right-hand side -must be a pattern expression. A pattern -expression is made up of both integer constants and family -symbols that have retained their semantic meaning as integers, and it -is built up out of the following typical operators: -

-
-
-

Table 4. Pattern Expression Operators

-
--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Operator NameSyntax
Integer addition+
Integer subtraction-
Integer multiplication*
Integer division/
Left-shift<<
Arithmetic right-shift>>
Bitwise and -
- - - - - - - -
$and
& (within square brackets)
-
-
Bitwise or -
- - - - - - - -
$or
| (within square brackets)
-
-
Bitwise xor -
- - - - - - - -
$xor
^
-
-
Bitwise negation~
-
-
-
-

-For the sake of these expressions, integers are considered signed -values of arbitrary precision. Expressions can also make use of -parentheses. A family symbol can be used in an expression, only if it -can be resolved to a particular specific symbol. This generally means -that a global family symbol, such as a field, must be attached to a -local identifier before it can be used. -

-

-The left-hand side of an assignment statement can be a context -variable (see Section 6.4, “Context Variables”). An -assignment to such a variable changes the context in which the current -instruction is being disassembled and can potentially have a drastic -effect on how the rest of the instruction is disassembled. An -assignment of this form is considered local to the instruction and -will not affect how other instructions are parsed. The context -variable is reset to its original value before parsing other -instructions. The disassembly action may also contain one or -more globalset directives, which -cause changes to context variables to become more permanent. This -directive is distinct from the operators in a pattern expression and -must be invoked as a separate statement. See -Section 8, “Using Context”, for a discussion of how to -effectively use context variables and -Section 8.3, “Global Context Change”, for details of -the globalset directive. -

-

-Note that there are two syntax forms for the logical operators in a -pattern expression. When an expression is used as part of a -constraint, the “$and” and “$or” forms of the operators must be used -in order to distinguish the bitwise operators from the special pattern -combining operators, ‘&’ and ‘|’ (as described in -Section 7.4.2, “The '&' and '|' Operators”). However inside the square braces -of the disassembly action section, ‘&’ and ‘|’ are interpreted as -the usual logical operators. -

-
-
-
-

-7.6. The With Block

-

-To avoid tedious repetition and to ease the maintenance of specifications -already having many, many constructors and tables, the with -block is provided. It is a syntactic construct that allows a -designer to apply a table header, bit pattern constraints, and/or disassembly -actions to a group of constructors. The block starts at the -with directive and ends with a closing brace. -All constructors within the block are affected: -

-
-with op1 : mode=1 [ mode=2; ] {
-  :reg   is reg & ind=0 [ mode=1; ] { ... }
-  :[reg] is reg & ind=1             { ... }
-}
-
-

-In the example, both constructors are added to the table identified by -op1. Both require the context field -mode to be equal to 1. The listed constraints take the -form described in Section 7.4, “The Bit Pattern Section”, and they are joined to -those given in the constructor statement as if prepended using ‘&’. Similarly, -the actions take the form described in Section 7.5, “Disassembly Actions Section” -and are prepended to the actions given in the constructor statement. Prepending -the actions allows the statement to override actions in the with block. Both -technically occur, but only the last one has a noticeable effect. The above -example could have been equivalently specified: -

-
-op1:reg   is mode=1 & reg & ind=0 [ mode=2; mode=1; ] { ... }
-op1:[ref] is mode=1 & reg & ind=1 [ mode=2; ]         { ... }
-
-

-

-

-The three parts (table header, bit pattern section, and disassembly actions -section) of the with block are all optional. Any of them may be omitted, -though omitting all of them is rather pointless. With blocks may also be nested. -The innermost with block having a table header specifies the default header of -the constructors it contains. The constraints and actions are combined outermost -to innermost, left to right. - -Note that when a with block has a table header specifying a table that does not -yet exist, the table is created immediately. Inside a with block that has a -table header, a nested with block may specify the instruction -table by name, as in "with instruction : {...}". -Inside such a block, the rule regarding mnemonic literals is restored (see -Section 7.3.1, “Mnemonic”). -

-
-
-

-7.7. The Semantic Section

-

-The final section of a constructor definition is the semantic -section. This is a description of how the processor would manipulate -data if it actually executed an instruction that matched the -constructor. From the perspective of a single constructor, the basic -idea is that all the operands for the constructor have been defined in -the bit pattern or disassembly action sections as either specific or -family symbols. In context, all the family symbols map to specific -symbols, and the semantic section uses these and possibly other global -specific symbols in statements that describe the action of the -constructor. All specific symbols have a varnode associated with them, -so within the semantic section, symbols are manipulated as if they -were varnodes. -

-

-The semantic section for one constructor is surrounded by curly braces -‘{‘ and ‘}’ and consists of zero or more statements separated by -semicolons ‘;’. Most statements are built up out of C-like syntax, -where the variables are the symbols visible to the constructor. There -is a direct correspondence between each type of operator used in the -statements and a p-code operation. The SLEIGH compiler generates -p-code operations and varnodes corresponding to the SLEIGH operators -and symbols by collapsing the syntax trees represented by the -statements and creating temporary storage within -the unique space when it needs to. -

-
-:add r1,r2 is opcode=0x26 & r1 & r2 { r1 = r1 + r2; }
-
-

-

-

-The above example generates exactly one integer addition -operation, INT_ADD, where the input varnodes -are r1 and r2 and the output -varnode is r1. -

-
-

-7.7.1. Expressions

-

-Expressions are built out of symbols and the binary and unary -operators listed in Table 5, “Semantic Expression Operators and Syntax” in the -Appendix. All expressions evaluate to an integer, floating point, or -boolean value, depending on the final operation of the expression. The -value is then used depending on the kind of statement. Most of the -operators require that their input and output varnodes all be the same -size (see Section 7.7.3, “Varnode Sizes”). The operators all -have a precedence, which is used by the SLEIGH compiler to determine -the ordering of the final p-code operations. Parentheses can be used -within expressions to affect this order. -

-
-
-7.7.1.1. Arithmetic, Logical and Boolean Operators
-

-For the most part these operators should be familiar to software -developers. The only real differences arise from the fact that -varnodes are typeless. So for instance, there has to be separate -operators to distinguish between dividing unsigned numbers ‘/’, -dividing signed numbers ‘s/’, and dividing floating point numbers -‘f/’. -

-

-Carry, borrow, and overflow calculations are implemented with separate -operations, rather than having indirect effects with the arithmetic -operations. Thus -the INT_CARRY, INT_SCARRY, -and INT_SBORROW operations may be unfamiliar to -some people in this form (see the descriptions in the Appendix). -

-
-
-
-7.7.1.2. The '*' Operator
-

-The dereference operator, which generates LOAD -operations (and STORE operations), has slightly -unfamiliar syntax. The ‘*’ operator, as is usual in many programming -languages, indicates that the affected variable is a pointer and that -the expression is dereferencing the data being -pointed to. Unlike most languages, in SLEIGH, it is not immediately -clear what address space the variable is pointing into because there -may be multiple address spaces defined. In the absence of any other -information, SLEIGH assumes that the variable points into -the default space, as labeled in the definition -of one of the address spaces with -the default attribute. If that is not -the space desired, the default can be overridden by putting the -identifier for the space in square brackets immediately after the ‘*’. -

-

-It is also frequently not clear what the size of the dereferenced data -is because the pointer variable is typeless. The SLEIGH compiler can -frequently deduce what the size must be by looking at the operation in -the context of the entire statement (see -Section 7.7.3, “Varnode Sizes”). But in some situations, this -may not be possible, so there is a way to specify the size -explicitly. The operator can be followed by a colon ‘:’ and an integer -indicating the number of bytes being dereferenced. This can be used -with or without the address space override. We give an example of each -kind of override in the example below. -

-
-:load  r1,[r2] is opcode=0x99 & r1 & r2 { r1 = * r2; }
-:load2 r1,[r2] is opcode=0x9a & r1 & r2 { r1 = *[other] r2; }
-:load3 r1,[r2] is opcode=0x9b & r1 & r2 { r1 = *:2 r2; }
-:load4 r1,[r2] is opcode=0x9c & r1 & r2 { r1 = *[other]:2 r2; }
-
-

-Keep in mind that the address represented by the pointer is not a byte -address if the wordsize attribute is -set to something other than one. -

-
-
-
-7.7.1.3. Extension
-

-Most processors have instructions that extend small values into big -values, and many instructions do these minor data manipulations -implicitly. In keeping with the p-code philosophy, these operations -must be specified explicitly with the INT_ZEXT -and INT_SEXT operators in the semantic -section. The INT_ZEXT, does a -so-called zero extension. The low-order bits are -copied from the input, and any remaining high-order bits in the result -are set to zero. The INT_SEXT, does -a signed extension. The low-order bits are copied -from the input, but any remaining high-order bits in the result are -set to the value of the high-order bit of the -input. The INT_ZEXT operation is invoked with -the zext operator, and -the INT_SEXT operation is invoked with -the sext operator. -

-
-
-
-7.7.1.4. Truncation
-

-There are two forms of syntax indicating a truncation of the input -varnode. In one the varnode is followed by a colon ‘:’ and an integer -indicating the number of bytes to copy into the output, starting with -the least significant byte. In the second form, the varnode is -followed by an integer, surrounded by parentheses, indicating the -number of least significant bytes to truncate from the input. This -second form doesn’t directly specify the size of the output, which -must be inferred from context. -

-
-:split r1,lo,hi is opcode=0x81 & r1 & lo & hi {
-    lo = r1:4;
-    hi = r1(4);
-}
-
-

-This is an example using both forms of truncation to split a large -value r1 into two smaller -pieces, lo -and hi. Assuming r1 is an 8 -byte value, lo receives the least significant -half and hi receives the most significant half. -

-
-
-
-7.7.1.5. Bit Range Operator
-

-A specific subrange of bits within a varnode can be explicitly -referenced. Depending on the range, this may amount to just a -variation on the truncation syntax described earlier. But for this -operator, the size and boundaries of the range do not have to be -restricted to byte alignment. -

-
-:bit3 r1,r2 is op=0x7e & r1 & r2 { r1 = zext(r2[3,1]); }
-
-

-

-

-A varnode, r2 in this example, is immediately -followed by square brackets ‘[’ and ‘]’ indicating a bit range, and -within the brackets, there are two parameters separated by a -comma. The first parameter is an integer indicating the least -significant bit of the resulting bit range. The bits of the varnode -are labeled in order of significance, with the least significant bit -of the varnode being 0. The second parameter is an integer indicating -the number of bits in the range. In the example, a single bit is -extracted from r2, and its value is extended to -fill r1. Thus r1 takes -either the value 0 or 1, depending on bit 3 -of r2. -

-

-There are some caveats associated with using this operator. Bit range -extraction is really a pseudo operator, as real p-code can only work -with memory down to byte resolution. The bit range operator will -generate some combination -of INT_RIGHT, INT_AND, -and SUBPIECE to simulate the extraction of -smaller or unaligned pieces. The “r2[3,1]” from the example generates -the following p-code, for instance. -

-
-u1 = INT_RIGHT r2,#3
-u2 = SUBPIECE u1,0
-u3 = INT_AND u2,#0x1
-
-

-

-

-The result of any bit range operator still has a size in bytes. This -size is always the minimum number of bytes needed to contain the -resulting bit range, and if there are any extra bits in the result -these are automatically set to zero. -

-

-This operator can also be used on the left-hand side of assignments -with similar behavior and caveats (see Section 7.7.2.8, “Bit Range Assignments”). -

-
-
-
-7.7.1.6. Address-of Operator
-

-There is an address-of operator for generating -the address offset of a selected varnode as an integer value for use -in expressions. Use of this operator is a little subtle because it -does not generate a p-code operation that -calculates the desired value. The address is only calculated at -disassembly time and not during execution. The operator can only be -used if the symbol referenced has a static address. -

-
-

Warning

-

The current SLEIGH compiler cannot distinguish when -the symbol has an address that can always be resolved during -disassembly. So improper use may not be flagged as an error, and the -specification may produce unexpected results. -

-
-

-There ‘&’ operator in front of a symbol invokes this function. The -ampersand can also be followed by a colon ‘:’ and an integer -explicitly indicating the size of the resulting constant as a varnode. -

-
-:copyr r1 is op=0x3b & r1 { tmp:4 = &r1 + 4; r1 = *[register]tmp;}
-
-

-

-

-The above is a contrived example of using the address-of operator to -copy from a register that is not explicitly indicated by the -instruction. This example constructs the address of the register -following r1 within -the register space, and then -loads r1 with data from that address. The net -effect of all this is that the register -following r1 is copied -into r1, even though it is not mentioned directly -in the instruction. Notice that the address-of operator only produces -the offset portion of the address, and to copy the desired value, the -‘*’ operator must have a register space override. -

-
-
-
-7.7.1.7. Managed Code Operations
-

-SLEIGH provides basic support for instructions where encoding and context -don't provide a complete description of the semantics. This is the case -typically for managed code instruction sets where generation -of the semantic details of an instruction may be deferred until run-time. Support for -these operators is architecture dependent, otherwise they just act as black-box -functions. -

-

-The constant pool operator, cpool, -returns sizes, offsets, addresses, and other structural constants. It behaves like a -query to the architecture about these constants. The first -parameter is generally an object reference, and additional parameters -are constants describing the particular query. The operator returns the requested value. -In the following example, an object reference -regParamC and the encoded constant METHOD_INDEX -are sent as part of a query to obtain the final destination address of an object method. -

-
-:invoke_direct METHOD_INDEX,regParamC
-               is inst0=0x70 ; N_PARAMS=1 & METHOD_INDEX & regParamC
-{
-	iv0 = regParamC;
-	destination:4 = cpool( regParamC, METHOD_INDEX, $(CPOOL_METHOD));
-	call [ destination ];
-}
-
-

-

-

-If object memory allocation is an atomic feature of the instruction set, the specification -designer can use the newobject functional operator to -implement it in SLEIGH. It takes one -or two parameters. The first parameter is a class reference or other value -describing the object to be allocated, and the second parameter is an optional count of the number -of objects to allocate. It returns a pointer to the allocated object. -

-
-
-
-7.7.1.8. User-Defined Operations
-

-Any identifier that has been defined as a new p-code operation, using -the define pcodeop statement, can be -invoked as an operator using functional syntax. The SLEIGH compiler -assumes that the operator can take an arbitrary number of inputs, and -if used in an expression, the compiler assumes the operation returns -an output. Using this syntax of course generates the particular p-code -operation reserved for the identifier. -

-
-define pcodeop arctan;
-  ...
-:atan r1,r2 is opcode=0xa3 & r1 & r2 { r1 = arctan(r2); }
-
-

-

-
-
-
-

-7.7.2. Statements

-

-We describe the types of semantic statements that are allowed in SLEIGH. -

-
-
-7.7.2.1. Assignment Statements and Temporary Variables
-

-Of course SLEIGH allows assignment statements with the ‘=’ operator, -where the right-hand side is an arbitrary expression and the left-hand -side is the varnode being assigned. The assigned varnode can be any -specific symbol in the scope of the constructor, either a global -symbol or a local operand. -

-

-In SLEIGH, the keyword local -is used to allocate temporary variables. If an assignment -statement is prepended with local, -and the identifier on the left-hand side of an assignment does not match -any symbol in the scope of the constructor, a named temporary varnode is -created in the unique address space to hold the -result of the expression. The new symbol becomes part of the local -scope of the constructor, and can be referred to in the following -semantic statements. The size of the new varnode is calculated by -examining the statement in context (see -Section 7.7.3, “Varnode Sizes”). It is also possible to -explicitly indicate the size by using the colon ‘:’ operator followed -by an integer size in bytes. The following examples demonstrate the -temporary variable tmp being defined using both -forms. -

-
-:swap r1,r2 is opcode=0x41 & r1 & r2 {
-    local tmp = r1;
-    r1 = r2;
-    r2 = tmp;
-}
-:store r1,imm is opcode=0x42 & r1 & imm {
-    local tmp:4 = imm+0x20;
-    *r1 = tmp;
-}
-
-

-

-

-The local keyword can also be used -to declare a named temporary varnode, without an assignment statement. -This is useful for temporaries that are immediately passed into a macro. -

-
-:pushflags r1 is opcode=0x43 & r1 {
-    local tmp:4;
-    packflags(tmp);
-    * r1 = tmp;
-    r1 = r1 - 4;
-}
-
-

-

-
-

Warning

-

Currently, the SLEIGH compiler does not need the -local keyword to create a temporary -variable. For any assignment statement, if the left-hand side has a new -identifier, a new temporary symbol will be created using this identifier. -Unfortunately, this can cause SLEIGH to blindly accept assignment statements -where the left-hand side identifier is a misspelling of an existing symbol. -Use of the local keyword is preferred -and may be enforced in future compiler versions. -

-
-
-
-
-7.7.2.2. Storage Statements
-

-SLEIGH supports fairly standard storage statement -syntax to complement the load operator. The left-hand side of an -assignment statement uses the ‘*’ operator to indicate a dynamic -storage location, followed by an arbitrary expression to calculate the -location. This syntax of course generates the -p-code STORE operator as the final step of the -statement. -

-
-:sta [r1],r2 is opcode=0x20 & r1 & r2 { *r1 = r2; }
-:stx [r1],r2 is opcode=0x21 & r1 & r2 { *[other] r1 = r2; }
-:sti [r1],imm is opcode=0x22 & r1 & imm { *:4 r1 = imm; }
-
-

-

-

-The same size and address space considerations that apply to the ‘*’ -operator when it is used as a load operator also apply when it is used -as a store operator, see -Section 7.7.1.2, “The '*' Operator”. Unless explicit modifiers are -given, the default address space is assumed as the storage -destination, and the size of the data being stored is calculated from -context. Keep in mind that the address represented by the pointer is -not a byte address if the wordsize -attribute is set to something other than one. -

-
-
-
-7.7.2.3. Exports
-

-The semantic section doesn’t just specify how to generate p-code for a -constructor. Except for those constructors in the root table, this -section also associates a semantic meaning to the table symbol the -constructor is part of, allowing the table to be used as an operand in -other tables. The mechanism for making this association is -the export statement. This must be the last -statement in the section and consists of -the export keyword followed by the -specific symbol to be associated with the constructor. In general, the -constructor will have a sequence of assignment statements building a -final value, and then the varnode containing the value will be -exported. However, anything can be exported. -

-
-mode: reg++ is addrmode=0x2 & reg { tmp=reg; reg=reg+1; export tmp; }
-
-

-

-

-This is an example of a post-increment addressing mode that would be -used to build more complicated instructions. The constructor -increments a register reg but stores a copy of its -original value in tmp. The -varnode tmp is then exported, associating it with -the table symbol mode. When this constructor is -matched, as part of a more complicated instruction, the -symbol mode will represent the original semantic -value of reg but with the standard post-increment -side-effect. -

-

-The table symbol associated with the constructor becomes -a reference to the varnode being exported, not a -copy of the value. If the table symbol is written to, as the left-hand -side of an assignment statement, in some other constructor, the -exported varnode is affected. A constant can be exported if its size -as a varnode is given explicitly with the ‘:’ operator. -

-

-It is not legal to put a full expression in -an export statement, any expression -must appear in an earlier statement. However, a single ‘&’ -operator is allowed as part of the statement and it behaves as it -would in a normal expression (see -Section 7.7.1.6, “Address-of Operator”). It causes the address of the -varnode being modified to be exported as an integer constant. -

-
-
-
-7.7.2.4. Dynamic References
-

-The only other operator allowed as part of -an export statement, is the ‘*’ -operator. The semantic meaning of this operator is the same as if it -were used in an expression (see -Section 7.7.1.2, “The '*' Operator”), but it is worth examining the -effects of this form of export in detail. Bearing in mind that -an export statement exports -a reference, using the ‘*’ operator in the -statement exports a dynamic reference. The -varnode being modified by the ‘*’ is interpreted as a pointer to -another varnode. It is this varnode being pointed to which is -exported, even though the address may be dynamic and cannot be -determined at disassembly time. This is not the same as dereferencing -the pointer into a temporary variable that is then exported. The -dynamic reference can be both read -and written. Internally, the SLEIGH compiler -keeps track of the pointer and inserts a LOAD -or STORE operation when the symbol associated -with the dynamic reference is referred to in other constructors. -

-
-mode: reg[off] is addr=1 & reg & off {
-    ea = reg + off;
-    export *:4 ea;
-}
-dest: reloc    is abs [ reloc = abs * 4; ] {
-    export *[ram]:4 reloc;
-}
-
-

-

-

-In the first example, the effective address of an operand is -calculated from a register reg and a field of the -instruction off. The constructor does not export -the resulting pointer ea, it exports the location -being pointed to by ea. Notice the size of this -location (4) is given explicitly with the ‘:’ modifier. The ‘*’ -operator can also be used on constant pointers. In the second example, -the constant operand reloc is used as the offset -portion of an address into the ram address -space. The constant reloc is calculated at -disassembly time from the instruction -field abs. This is a very common construction for -jump destinations (see Section 7.5.1, “Relative Branches”) but -can be used in general. This particular combination of a disassembly -time action and a dynamic export is a very general way to construct a -family of varnodes. -

-

-Dynamic references are a key construction for effectively separating -addressing mode implementations from instruction semantics at higher -levels. -

-
-
-
-7.7.2.5. Branching Statements
-

-This section discusses statements that generate p-code branching -operations. These are listed in Table 7, “Branching Statements”, in the Appendix. -

-

-There are six forms covering the gamut of typical assembly language -branches, but in terms of actual semantics there are really only -three. With p-code, -

-
    -
  • -CALL is semantically equivalent to BRANCH, -
    • -
  • -CALLIND is semantically equivalent to BRANCHIND, and -
    • -
  • -RETURN is semantically equivalent to BRANCHIND. -
    • -
-

-The reason for this is that calls and returns imply the presence of -some sort of a stack. Typically an assembly language call instruction -does several separate actions, manipulating a stack pointer, storing a -return value, and so on. When translating the call instruction into -p-code, these actions must be implemented with explicit -operations. The final step of the instruction, the actual jump to the -destination of the call is now just a branch, stripped of its implied -meaning. The CALL, CALLIND, -and RETURN operations, are kept as distinct from -their BRANCH counterparts in order to provide -analysis software a hint as to the higher level meaning of the branch. -

-

-There are actually two fundamentally different ways of indicating a -destination for these branch operations. By far the most common way to -specify a destination is to give the address of a -machine instruction. It bears repeating here that there is typically -more than one p-code operation per machine instruction. So specifying -a destination address really means that the -destination is the first p-code operation for the (translated) machine -instruction at that address. For most cases, this is the only kind of -branching needed. The rarer case of p-code -relative branching is discussed in the following section -(Section 7.7.2.6, “P-code Relative Branching”), but for the remainder of -this section, we assume the destination is ultimately given as an -address. -

-

-There are two ways to specify a branching operation’s destination -address; directly and indirectly. Where a direct address is needed, as -for the BRANCH, CBRANCH, -and CALL instructions, The specification can give -the integer offset of the jump destination within the address space of -the current instruction. Optionally, the offset can be followed by the -name of another address space in square brackets, if the destination -is in another address space. -

-
-:reset is opcode=0x0 { goto 0x1000; }
-:modeshift is opcode=0x1 { goto 0x0[codespace]; }
-
-

-

-

-Of course, most branching instructions encode the destination of the -jump within the instruction somehow. So the jump destination is almost -always represented by an operand symbol and its associated -varnode. For a direct branch, the destination is given by the address -space and the offset defining the varnode. In this case, the varnode -itself is really just an annotation of the jump destination and not -used as a variable. The best way to define varnodes which annotate -jump destinations in this way is with a dynamic export. -

-
-dest: rel is simm8 [ rel = inst_next + simm8*4; ] {
-    export *[ram]:4 rel;
-}
-
-

-

-

-In this example, the operand rel is defined with -a disassembly action in terms of the address of the following -instruction, inst_next, and a field specifying a -relative relocation, simm8. The resulting -exported varnode has rel as its offset -and ram as its address space, by virtue of the -dynamic form of the export. The symbol associated with this -varnode, dest, can now be used in branch -operations. -

-
-:jmp dest is opcode=3 & dest {
-    goto dest;
-}
-:call dest is opcode=4 & dest {
-    *:4 sp = inst_next;
-    sp=sp-4;
-    call dest;
-}
-
-

-

-

-The above examples illustrate the direct forms of -the goto -and call operators, which generate -the p- code BRANCH and CALL -operations respectively. Both these operations take a single -annotation varnode as input, indicating the destination address of the -jump. Notice the explicit manipulation of a stack -pointer sp, for the call -instruction. The CBRANCH operation takes two -inputs, a boolean value indicating whether or not the branch should be -taken, and a destination annotation. -

-
-:bcc dest is opcode=5 & dest { if (carryflag==0) goto dest; }
-
-

-

-

-As in the above example, the CBRANCH operation -takes two inputs, a boolean value indicating whether or operation is -invoked with the if goto operation -takes two inputs, a boolean value indicating whether or syntax. The -condition of the if operation takes -two inputs, a boolean value indicating whether or can be any semantic -expression that results in a boolean value. The destination must be an -annotation varnode. -

-

-The -operators BRANCHIND, CALLIND, -and RETURN all have the same semantic meaning and -all use the same syntax to specify an indirect address. -

-
-:b [reg] is opcode=6 & reg {
-    goto [reg];
-}
-:call (reg) is opcode=7 & reg {
-    *:4 sp = inst_next;
-    sp=sp-4;
-    call [reg];
-}
-:ret is opcode=8 {
-    sp=sp+4;
-    tmp:4 = * sp;
-    return [tmp];
-}
-
-

-

-

-Square brackets surround the varnode containing the -address. Currently, any indirect address must be in the address space -containing the branch instruction. The offset of the destination -address is taken dynamically from the varnode. The size of the varnode -must match the size of the destination space. -

-
-
-
-7.7.2.6. P-code Relative Branching
-

-In some cases, the semantics of an instruction may require -branching within the semantics of a single -instruction, so specifying a destination address is too coarse. In -this case, SLEIGH is capable of p-code relative -branching. Individual p-code operations can be identified by -a label, and this label can be used as the -destination specifier, after the goto -keyword. A label, within the semantic section, is -any identifier surrounded by the ‘<’ and ‘>’ characters. If this -construction occurs at the beginning of a statement, we say the label -is defined, and that identifier is now associated -with the first p-code operation corresponding to the following -statement. Any label must be defined exactly once in this way. When -the construction is used as a destination, immediately after -a goto -or call, this is referred to as a -label reference. Of course the p-code destination meant by a label -reference is the operation at the point where the label was -defined. Multiple references to the same label are allowed. -

-
-:sum r1,r2,r3 is opcode=7 & r1 & r2 & r3 {
-     tmp:4 = 0;
-     r1 = 0;
-   <loopstart>
-     r1 = r1 + *r2;
-     r2 = r2 + 4;
-     tmp = tmp + 1;
-     if (tmp < r3) goto <loopstart>;
-}
-
-

-

-

-In the example above, the string “loopstart” is the label identifier -which appears twice; once at the point where the label is defined at -the top of the loop, after the initialization, and once as a reference -where the conditional branch is made for the loop. -

-

-References to labels can refer to p-code that occurs either before or -after the branching statement. But label references can only be used -in a branching statement, they cannot be used as a varnode in other -expressions. The label identifiers are local symbols and can only be -referred to within the semantic section of the constructor that -defines them. Branching into the middle of some completely different -instruction is not possible. -

-

-Internally, branches to labels are encoded as a relative index. Each -p-code operation is assigned an index corresponding to the operation’s -position within the entire translation of the instruction. Then the -branch can be expressed as a relative offset between the branch -operation’s index and the destination operation’s index. The SLEIGH -compiler encodes this offset as a constant varnode that is used as -input to -the BRANCH, CBRANCH, -or CALL operation. -

-
-
-
-7.7.2.7. Skip Instruction Branching
-

-Many processors have a conditional-skip-instruction which must branch over the next instruction -based upon some condition. The inst_next2 symbol has been provided for -this purpose. -

-
-:skip.eq is opcode=10 {
-    if (zeroflag!=0) goto inst_next2;
-}
-
-

-

-

-In the example above, the branch address will be determined by adding the parsed-length of the next -instruction to the value of inst_next causing a branch over the next -instruction when the condition is satisfied. -

-
-
-
-7.7.2.8. Bit Range Assignments
-

-The bit range operator can appear on the left-hand side of an -assignment. But as with the ‘*’ operator, its meaning is slightly -different when used on this side. The bit range is specified in square -brackets, as before, by giving the integer specifying the least -significant bit of the range, followed by the number of bits in the -range. In contrast with its use on the right however (see -Section 7.7.1.5, “Bit Range Operator”), the indicated bit range -is filled rather than extracted. Bits obtained from evaluating the -expression on the right are extracted and spliced into the result at -the indicated bit offset. -

-
-:bitset3 r1 is op=0x7d & r1 { r1[3,1] = 1; }
-
-

-In this example, bit 3 of varnode r1 is set to 1, -leaving all other bits unaffected. -

-

-As in the right-hand case, the desired insertion is achieved by -piecing together some combination of the p-code -operations INT_LEFT, INT_ZEXT, INT_AND, -and INT_OR. -

-

-In terms of the rest of the assignment expression, the bit range -operator is again assumed to have a size equal to the minimum number -of bytes needed to hold the bit range. In particular, in order to -satisfy size restrictions (see -Section 7.7.3, “Varnode Sizes”), the right-hand side must -match this size. Furthermore, it is assumed that any extra bits in the -right-hand side expression are already set to zero. -

-
-
-
-

-7.7.3. Varnode Sizes

-

-All statements within the semantic section must be specified up to the -point where the sizes of all varnodes are unambiguously -determined. Most specific symbols, like registers, must have their -size defined by definition, but there are two sources of size -ambiguity. -

-
    -
  • - Constants -
    • -
  • - Temporary Variables -
    • -
-

-

-

-The SLEIGH compiler does not make assumptions about the size of a -constant variable based on the constant value itself. This is true of -values occurring explicitly in the specification and of values that -are calculated dynamically in a disassembly action. As described in -Section 7.7.2.1, “Assignment Statements and Temporary Variables”, temporary variables do not -need to have their size given explicitly. -

-

-The SLEIGH compiler can usually fill in the required size by examining -these situations in the context of the entire semantic section. Most -p-code operations have size restrictions on their inputs and outputs, -which when put together can uniquely determine the unspecified -sizes. Referring to Table 5, “Semantic Expression Operators and Syntax” in the -Appendix, all arithmetic and logical operations, both integer and -floating point, must have inputs and outputs all of the same size. The -only exceptions are as follows. The overflow -operators, INT_CARRY, INT_SCARRY, INT_SBORROW, -and FLOAT_NAN have a boolean output. The shift -operators, INT_LEFT, INT_RIGHT, -and INT_SRIGHT, currently place no restrictions -on the shift amount operand. All the comparison -operators, both integer and floating point, insist that their inputs -are all the same size, and the output must be a boolean variable, with -a size of 1 byte. -

-

-The operators without a size constraint are the load and store -operators, the extension and truncation operators, and the conversion -operators. As discussed in Section 7.7.1.2, “The '*' Operator”, the -‘*’ operator cannot get size information for the dynamic (pointed-to) -object from the pointer itself. The other operators by definition -involve a change of size from input to output. -

-

-If the SLEIGH compiler cannot discover the sizes of constants and -temporaries, it will report an error stating that it could not resolve -variable sizes for that constructor. This can usually be fixed rapidly -by appending the size ‘:’ modifier to either the ‘*’ operator, the -temporary variable definition, or to an explicit integer. Here are -three examples of statements that generate a size resolution error, -each followed by a variation which corrects the error. -

-
-:sta [r1],imm is opcode=0x3a & r1 & imm {
-    *r1 = imm;                                      #Error
-}
-:sta [r1],imm is opcode=0x3a & r1 & imm {
-    *:4 r1 = imm;                                   #Correct
-}
-:inc [r1]     is opcode=0x3b & r1       {
-    tmp = *r1 + 1; *r1 = tmp;                       # Error
-}
-:inc [r1]     is opcode=0x3b & r1       {
-    tmp:4 = *r1 + 1; *r1 = tmp;                     # Correct
-}
-:clr [r1]     is opcode=0x3c & r1       {
-    * r1 = 0;                                       # Error
-}
-:clr [r1]     is opcode=0x3c & r1       {
-    * r1 = 0:4;                                     # Correct
-}
-
-

-

-
-
-

-7.7.4. Unimplemented Semantics

-

-The semantic section must be present for every constructor in the -specification. But the designer can leave the semantics explicitly -unimplemented if the keyword unimpl -is put in the constructor definition in place of the curly -braces. This serves as a placeholder if a specification is still in -development or if the designer does not intend to model data flow for -portions of the instruction set. Any instruction involving a -constructor that is unimplemented in this way will still be -disassembled properly, but the basic data flow routines will report an -error when analyzing the instruction. Analysis routines then can -choose whether or not to intentionally ignore the error, effectively -treating the unimplemented portion of the instruction as if it does -nothing. -

-
-:cache r1 is opcode=0x45 & r1  unimpl
-:nop      is opcode=0x0        { }
-
-

-

-
-
-
-

-7.8. Tables

-

-A single constructor does not form a new specific -symbol. The table that the constructor is -associated with via its table header is the actual symbol that can be -reused to build up more complicated elements. With all the basic -building blocks now in place, we outline the final elements for -building symbols that represent larger and larger portions of the -disassembly and p- code translation process. -

-

-The best analogy here is with grammar specifications and Regular -Language parsers. Those who have -used yacc, bison, or -otherwise looked at BNF grammars should find the concepts here -familiar. -

-

-With SLEIGH, there are in some sense two separate grammars being -parsed at the same time. A display grammar and a semantic grammar. To -the extent that the two grammars breakdown in the same way, SLEIGH can -exploit the similarity to produce an extremely concise description. -

-
-

-7.8.1. Matching

-

-If a table contains exactly one constructor, the meaning of the table -as a specific symbol is straightforward. The display meaning of the -symbol comes from the display section of the -constructor, and the symbol’s semantic meaning comes from the -constructor’s semantic section. -

-
-mode1: (r1) is addrmode=1 & r1 { export r1; }
-
-

-

-

-The table symbol in this example -is mode1. Assuming this is the only constructor, -the display meaning of the symbol are the literal characters ‘(‘, and -‘)’ concatenated with the display meaning of r1, -presumably a register name that has been attached. The semantic -meaning of mode1, because of the export -statement, becomes whatever register is matched by -the r1. -

-
-mode1: (r1) is addrmode=1 & r1 { export r1; }
-mode1: [r2] is addrmode=2 & r2 { export r2; }
-
-

-

-

-If there are two or more constructors defined for the same table, -the bit pattern section is used to select between -the constructors in context. In the above example, -the mode1 table is now defined with two -constructors and the distinguishing feature of their bit patterns is -that in one the addrmode field must be 1 and in -the other it must be 2. In the context of a particular instruction, -the matching constructor can be determined uniquely based on this -field, and the mode1 symbol takes on the display -and semantic characteristics of the matching constructor. -

-

-The bit patterns for constructors under a single table must be built -so that a constructor can be uniquely determined in context. The above -example shows the easiest way to accomplish this. The two sets of -instruction encodings, which match one or the other of the -two addrmode constraints, are disjoint. In -general, if each constructor has a set of instruction encodings -associated with it, and if the sets for any two constructors are -disjoint, then no two constructors can match at the same time. -

-

-It is possible for two sets to intersect, if one of the two sets -properly contains the other. In this situation, the constructor -corresponding to the smaller (contained) set is considered -a special case of the other constructor. If an -instruction encoding matches the special case, that constructor is -used to define the symbol, even though the other constructor will also -match. If the special case does not match but the other more general -constructor does, then the general constructor is used to define the -symbol. -

-
-zA: r1  is addrmode=3 & r1   { export r1; }
-zA: “0” is addrmode=3 & r1=0 { export 0:4; } # Special case
-
-

-

-

-In this example, the symbol zA takes on the same -display and semantic meaning as r1, except in the -special case when the field r1 equals 0. In this -case, zA takes on the display and semantic -meaning of the constant zero. Notice that the first constructor has -only the one constraint on addrmode, which is -also a constraint for the second constructor. So any instruction that -matches the second must also match the first. -

-

-The same exact rules apply when there are more than two -constructors. Any two sets defined by the bit patterns must be either -disjoint or one contained in the other. It is entirely possible to -have one general case with many special cases, or a special case of a -special case, and so on. -

-

-If the patterns for two constructors intersect, but one pattern does -not properly contain the other, this is generally an error in the -specification. Depending on the flags given to the SLEIGH compiler, it -may be more or less lenient with this kind of situation however. In -the case where an intersection is not flagged as an error, -the first constructor that matches, in the order -that the constructors appear in the specification, is used. -

-

-If two constructors intersect, but there is a third constructor whose -pattern is exactly equal to the intersection, then the third pattern -is said to resolve the conflict produced by the -first two constructors. An instruction in the intersection will match -the third constructor, as a specialization, and the remaining pieces -in the patterns of the first two constructors are disjoint. A resolved -conflict like this is not flagged as an error even with the strictest -checking. Other types of intersections, in combination with lenient -checking, can be used for various tricks in the specification but -should generally be avoided. -

-
-
-

-7.8.2. Specific Symbol Trees

-

-When the SLEIGH parser analyzes an instruction, it starts with the -root symbol instruction, and decides which of the -constructors defined under it match. This particular constructor is -likely to be defined in terms of one or more other family symbols. The -parsing process recurses at this point. Each of the unresolved family -symbols is analyzed in the same way to find the matching specific -symbol. The matching is accomplished either with a table lookup, as -with a field with attached registers, or with the matching algorithm -described in Section 7.8.1, “Matching”. By the end of the -parsing process, we have a tree of specific symbols representing the -parsed instruction. We present a small but complete SLEIGH -specification to illustrate this hierarchy. -

-

-

-
-define endian=big;
-define space ram type=ram_space size=4 default;
-define space register type=register_space size=4;
-define register offset=0 size=4 [ r0 r1 r2 r3 r4 r5 r6 r7 ];
-
-define token instr(16)
-  op=(10,15) mode=(6,9) reg1=(3,5) reg2=(0,2) imm=(0,2)
-;
-attach variables [ reg1 reg2 ] [ r0 r1 r2 r3 r4 r5 r6 r7 ];
-
-op2: reg2 is mode=0 & reg2   { export reg2; }
-op2: imm is mode=1 & imm     { export *[const]:4 imm; }
-op2: [reg2] is mode=2 & reg2 { tmp = *:4 reg2; export tmp;}
-
-:and reg1,op2 is op=0x10 & reg1 & op2 { reg1 = reg1 & op2; }
-:xor reg1,op2 is op=0x11 & reg1 & op2 { reg1 = reg1 ^ op2; }
-:or  reg1,op2 is op=0x12 & reg1 & op2 { reg1 = reg1 | op2; }
-
-

-

-

-This processor has 16 bit instructions. The high order 6 bits are the -main opcode field, selecting between logical -operations, and, or, -and xor. The logical operations each take two -operands, reg1 and op2. The -operand reg1 selects between the 8 registers of -the processor, r0 -through r7. The operand op2 -is a table built out of more complicated addressing modes, determined -by the field mode. The addressing mode can either -be direct, in which op2 is really just the -register selected by reg2, it can be immediate, -in which case the same bits are interpreted as a constant -value imm, or it can be an indirect mode, where -the register reg2 is interpreted as a pointer to -the actual operand. In any case, the two operands are combined by the -logical operation and the result is stored back -in reg1. -

-

-The parsing proceeds from the root symbol down. Once a particular -matching constructor is found, any disassembly action associated with -that constructor is executed. After that, each operand of the -constructor is resolved in turn. -

-
-
Two Encodings and the Resulting Specific Symbol Trees
-

Figure 1. Two Encodings and the Resulting Specific Symbol Trees

-
-

-In Figure 1, “Two Encodings and the Resulting Specific Symbol Trees”, we can see the break down -of two typical instructions in the example instruction set. For each -instruction, we see the how the encodings split into the relevant -fields and the resulting tree of specific symbols. Each node in the -trees are labeled with the base family symbol, the portion of the bit -pattern that matches, and then the resulting specific symbol or -constructor. Notice that the use of the overlapping -fields, reg2 and imm, is -determined by the matching constructor for -the op2 table. SLEIGH generates the disassembly -and p-code for these encodings by walking the trees. -

-
-
-7.8.2.1. Disassembly Trees
-

-If the nodes of each tree are replaced with the display information of -the corresponding specific symbol, we see how the disassembly -statement is built. -

-
-
Two Disassembly Trees
-

Figure 2. Two Disassembly Trees

-
-

-Figure 2, “Two Disassembly Trees”, shows the resulting -disassembly trees corresponding to the specific symbol trees in -Figure 1, “Two Encodings and the Resulting Specific Symbol Trees”. The display information comes -from constructor display sections, the names of attached registers, or -the integer interpretation of fields. The identifiers in a constructor -display section serves as placeholders for the subtrees below them. By -walking the tree, SLEIGH obtains the final illustrated assembly -statements corresponding to the original instruction encodings. -

-
-
-
-7.8.2.2. P-code Trees
-

-A similar procedure produces the resulting p-code translation of the -instruction. If each node in the specific symbol tree is replaced with -the corresponding p-code, we see how the final translation is built. -

-
-
Two P-code Trees
-

Figure 3. Two P-code Trees

-
-

-Figure 3, “Two P-code Trees” lists the final p-code -translation for our example instructions and shows the trees from -which the translation is derived. Symbol names within the p-code for a -particular node, as with the disassembly tree, are placeholders for -the subtree below them. The final translation is put together by -concatenating the p-code from each node, traversing the nodes in a -depth-first order. Thus the p-code of a child tends to come before the -p-code of the parent node (but see -Section 7.9, “P-code Macros”). Placeholders are filled in with the -appropriate varnode, as determined by the export statement of the root -of the corresponding subtree. -

-
-
-
-
-

-7.9. P-code Macros

-

-SLEIGH supports a macro facility for encapsulating semantic -actions. The syntax, in effect, allows the designer to define p-code -subroutines which can be invoked as part of a constructor’s semantic -action. The subroutine is expanded automatically at compile time. -

-

-A macro definition is started with -the macro keyword, which can occur -anywhere in the file before its first use. This is followed by the -global identifier for the new macro and a parameter list, comma -separated and in parentheses. The body of the definition comes next, -surrounded by curly braces. The body is a sequence of semantic -statements with the same syntax as a constructor’s semantic -section. The identifiers in the macro’s parameter list are local in -scope. The macro can refer to these and any global specific symbol. -

-
-macro resultflags(op) {
-  zeroflag = (op == 0);
-  signflag = (op1 s< 0);
-}
-
-:add r1,r2 is opcode=0xba & r1 & r2 { r1 = r1 + r2; resultflags(r1); }
-
-

-

-

-The macro is invoked in the semantic section of a constructor by using -the identifier with a functional syntax, listing the varnodes which -are to be passed into the macro. In the example above, the -macro resultflags calculates the value of two -global flags by comparing its parameter to zero. -The add constructor invokes the macro so that -the r1 is used in the comparisons. Parameters are -passed by reference, so the value of varnodes -passed into the macro can be changed. Currently, there is no syntax -for returning a value from the macro, except by writing to a parameter -or global symbol. -

-

-Almost any statement that can be used in a constructor can also be -used in a macro. This includes assignment statements, branching -statements, delayslot directives, and -calls to other macros. A build -directive however should not be used in a macro. -

-
-
-

-7.10. Build Directives

-

-Because the nodes of a specific symbol tree are traversed in a -depth-first order, the p-code for a child node in general comes before -the p-code of the parent. Furthermore, without special intervention, -the specification designer has no control over the order in which the -children of a particular node are -traversed. The build directive is -used to affect these issues in the rare cases where it is -necessary. The build directive occurs -as another form of statement in the semantic section of a -constructor. The keyword build is -followed by one of the constructor’s operand identifiers. Then, -instead of filling in the operand’s associated p-code based on an -arbitrary traversal of the symbol tree, the directive specifies that -the operand’s p-code must occur at that point in the p-code for the -parent constructor. -

-

-This directive is useful in situations where an instruction supports -prefixes or addressing modes with side-effects that must occur in a -particular order. Suppose for example that many instructions support a -condition bit in their encoding. If the bit is set, then the -instruction is executed only if a status flag is set. Otherwise, the -instruction always executes. This situation can be implemented by -treating the instruction variations as distinct constructors. However, -if many instructions support the same variation, it is probably more -efficient to treat the condition bit which distinguishes the variants -as a special operand. -

-
-cc: “c” is condition=1 { if (flag==1) goto inst_next; }
-cc:     is condition=0 { }
-
-:and^cc  r1,r2 is opcode=0x67 & cc & r1 & r2 {
-    build cc;
-    r1 = r1 & r2;
-}
-
-

-

-

-In this example, the conditional variant is distinguished by a ‘c’ -appended to the assembly mnemonic. The cc operand -performs the conditional side-effect, checking a flag in one case, or -doing nothing in the other. The two forms of the instruction can now -be implemented with a single constructor. To make sure that the flag -is checked first, before the action of the instruction, -the cc operand is forced to evaluate first with -a build directive, followed by the -normal action of the instruction. -

-
-
-

-7.11. Delay Slot Directives

-

-For processors with a pipe-lined architecture, multiple instructions -are typically executing simultaneously. This can lead to processor -conventions where certain pairs of instructions do not seem to execute -sequentially. The standard examples are branching instructions that -execute the instruction in the delay -slot. Despite the fact that execution of the branch -instruction does not fall through, the following instruction is -executed anyway. Such semantics can be implemented in SLEIGH with -the delayslot directive. -

-

-This directive appears as a standalone statement in the semantic -section of a constructor. When p- code is generated for a matching -instruction, at the point where the directive occurs, p-code for the -following instruction(s) will be generated and inserted. The directive -takes a single integer argument, indicating the minimum number of -bytes in the delay slot. Additional machine instructions will be -parsed and p-code generated, until at least that many bytes have been -disassembled. Typically the value of 1 is used to indicate that there -is exactly one more instruction in the delay slot. -

-
-:beq r1,r2,dest is op=0xbc & r1 & r2 & dest { flag=(r1==r2);
-                                              delayslot(1);
-                                              if flag goto dest; }
-
-

-

-

-This is an example of a conditional branching instruction with a delay -slot. The p-code for the following instruction is inserted before the -final CBRANCH. Notice that -the delayslot directive can appear -anywhere in the semantic section. In this example, the condition -governing the branch is evaluated before the directive because the -following instruction could conceivably affect the registers checked -by the condition. -

-

-Because the delayslot directive -combines two or more instructions into one, the meaning of the -symbols inst_next and inst_next2 -become ambiguous. It is not -clear anymore what exactly the “next instruction” is. SLEIGH uses the -following conventions for interpreting -an inst_next symbol. If it is used in the -semantic section, the symbol refers to the address of the instruction -after any instructions in the delay slot. However, if it is used in a -disassembly action, the inst_next symbol refers -to the address of the instruction immediately after the first -instruction, even if there is a delay slot. The use of the -inst_next2 symbol may be inappropriate in conjunction -with delayslot use. While its use of the -next instruction address is identified by inst_next, -the length of the next instruction ignores any delay slots it may have -when computing the value of inst_next2. -

-
-
-
-
- - - - - - - - - - - -
-Prev   Next -
6. Tokens and Fields Home 8. Using Context
-
- - diff --git a/sources/GhidraDocs/languages/html/sleigh_constructors.md b/sources/GhidraDocs/languages/html/sleigh_constructors.md deleted file mode 100644 index 0c02ad2..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_constructors.md +++ /dev/null @@ -1,2634 +0,0 @@ ---- -status: collected -title: 7. Constructors -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_constructors.html ---- - -::: {.navheader} -7. Constructors -::: - -[Prev](sleigh_tokens.html)  - -  - - [Next](sleigh_context.html) - ------------------------------------------------------------------------- - -::: {.sect1} -::: {.titlepage} -
- -
- -[]{#sleigh_constructors}7. Constructors {#constructors .title style="clear: both"} ---------------------------------------- - -
- -
-::: - -Fields are the basic building block for family symbols. The mechanisms -for building up from fields to the root [*instruction*]{.emphasis} -symbol are the [*constructor*]{.emphasis} and [*table*]{.emphasis}. - -A [*constructor*]{.emphasis} is the unit of syntax for building new -symbols. In essence a constructor describes how to build a new family -symbol, by describing, in turn, how to build a new display meaning, how -to build a new semantic meaning, and how encodings map to these new -meanings. A [*table*]{.emphasis} is a set of one or more constructors -and is the final step in creating a new family symbol identifier -associated with the pieces defined by constructors. The name of the -table is this new identifier, and it is this identifier which can be -used in the syntax for subsequent constructors. - -The difference between a constructor and table is slightly confusing at -first. In short, the syntactical elements described in this chapter, for -combining existing symbols into new symbols, are all used to describe a -single constructor. Specifications for multiple constructors are -combined to describe a single table. Since many tables are built with -only one constructor, it is natural and correct to think of a -constructor as a kind of table in and of itself. But it is only the -table that has an actual family symbol identifier associated with it. -Most of this chapter is devoted to describing how to define a single -constructor. The issues involved in combining multiple constructors into -a single table are addressed in [Section 7.8, -"Tables"](sleigh_constructors.html#sleigh_tables "7.8. Tables"){.xref}. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_sections_constructor}7.1. The Five Sections of a Constructor {#the-five-sections-of-a-constructor .title} - -
- -
-::: - -A single complex statement in the specification file describes a -constructor. This statement is always made up of five distinct sections -that are listed below in the order in which the must occur. - -::: {.informalexample} -::: {.orderedlist} -1. Table Header -2. Display Section -3. Bit Pattern Sections -4. Disassembly Actions Section -5. Semantics Actions Section -::: -::: - -The full set of rules for correctly writing each section is long and -involved, but for any given constructor in a real specification file, -the syntax typically fits on a single line. We describe each section in -turn. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_table_header}7.2. The Table Header {#the-table-header .title} - -
- -
-::: - -Every constructor must be part of a table, which is the element with an -actual family symbol identifier associated with it. So each constructor -starts with the identifier of the table it belongs to followed by a -colon ':'. - -::: {.informalexample} -``` -mode1: ... -``` -::: - -The above line starts the definition of a constructor that is part of -the table identified as [*mode1*]{.emphasis}. If the identifier has not -appeared before, a new table is created. If other constructors have used -the identifier, the new constructor becomes an additional part of that -same table. A constructor in the root [*instruction*]{.emphasis} table -is defined by omitting the identifier. - -::: {.informalexample} -``` -: ... -``` -::: - -The identifier [*instruction*]{.emphasis} is actually reserved for the -root table, but should not be used in the table header as the SLEIGH -parser uses the blank identifier to help distinguish assembly mnemonics -from operands (see [Section 7.3.1, -"Mnemonic"](sleigh_constructors.html#sleigh_mnemonic "7.3.1. Mnemonic"){.xref}). -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_display_section}7.3. The Display Section {#the-display-section .title} - -
- -
-::: - -The [*display section*]{.emphasis} consists of all characters after the -table header ':' up to the SLEIGH keyword [**is**]{.bold}. The section's -primary purpose is to assign disassembly display meaning to the -constructor. The section's secondary purpose is to define local -identifiers for the pieces out of which the constructor is being built. -Characters in the display section are treated as literals with the -following exceptions. - -::: {.informalexample} -::: {.itemizedlist} -- Legal identifiers are not treated literally unless - ::: {.orderedlist} - a. The identifier is surrounded by double quotes. - b. The identifier is considered a mnemonic (see below). - ::: -- The character '\^' has special meaning. -- White space is trimmed from the beginning and end of the section. -- Other sequences of white space characters are condensed into a - single space. -::: -::: - -In particular, all punctuation except '\^' loses its special meaning. -Those identifiers that are not treated as literals are considered to be -new, initially undefined, family symbols. We refer to these new symbols -as the [*operands*]{.emphasis} of the constructor. And for root -constructors, these operands frequently correspond to the natural -assembly operands. Thinking of it as a family symbol, the constructor's -display meaning becomes the string of literals itself, with each -identifier replaced with the display meaning of the symbol corresponding -to that identifier. - -::: {.informalexample} -``` -mode1: ( op1 ),op2 is ... -``` -::: - -In the above example, a constructor for table [*mode1*]{.emphasis} is -being built out of two pieces, symbol [*op1*]{.emphasis} and symbol -[*op2*]{.emphasis}. The characters '(', ')', and ',' become literal -parts of the disassembly display for symbol mode1. After the display -strings for [*op1*]{.emphasis} and [*op2*]{.emphasis} are found, they -are inserted into the string of literals, forming the constructor's -display string. The white space characters surrounding the -[*op1*]{.emphasis} identifier are preserved as part of this string. - -The identifiers [*op1*]{.emphasis} and [*op2*]{.emphasis} are local to -the constructor and can mask global symbols with the same names. The -symbols will (must) be defined in the following sections, but only their -identifiers are established in the display section. - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_mnemonic}7.3.1. Mnemonic {#mnemonic .title} - -
- -
-::: - -If the constructor is part of the root instruction table, the first -string of characters in the display section that does not contain white -space is treated as the [*literal mnemonic*]{.emphasis} of the -instruction and is not considered a local symbol identifier even if it -is legal. - -::: {.informalexample} -``` -:and (var1) is ... -``` -::: - -In the above example, the string "var1" is treated as a symbol -identifier, but the string "and" is considered to be the mnemonic of the -instruction. - -There is nothing that special about the mnemonic. As far as the display -meaning of the constructor is concerned, it is just a sequence of -literal characters. Although the current parser does not concern itself -with this, the mnemonic of any assembly language instruction in general -is used to guarantee the uniqueness of the assembly representation. It -is conceivable that a forward engineering engine built on SLEIGH would -place additional requirements on the mnemonic to assure uniqueness, but -for reverse engineering applications there is no such requirement. -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_caret}7.3.2. The \'\^\' character {#the-character .title} - -
- -
-::: - -The '\^' character in the display section is used to separate -identifiers from other characters where there shouldn't be white space -in the disassembly display. This can be used in any manner but is -usually used to attach display characters from a local symbol to the -literal characters of the mnemonic. - -::: {.informalexample} -``` -:bra^cc op1,op2 is ... -``` -::: - -In the above example, "bra" is treated as literal characters in the -resulting display string followed immediately, with no intervening -spaces, by the display string of the local symbol [*cc*]{.emphasis}. -Thus the whole constructor actually has three operands, denoted by the -three identifiers [*cc*]{.emphasis}, [*op1*]{.emphasis}, and -[*op2*]{.emphasis}. - -If the '\^' is used as the first (non-whitespace) character in the -display section of a base constructor, this inhibits the first -identifier in the display from being considered the mnemonic, as -described in [Section 7.3.1, -"Mnemonic"](sleigh_constructors.html#sleigh_mnemonic "7.3.1. Mnemonic"){.xref}. -This allows specification of less common situations, where the first -part of the mnemonic, rather than perhaps a later part, needs to be -considered as an operand. An initial '\^' character can also facilitate -certain recursive constructions. -::: -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_bit_pattern}7.4. The Bit Pattern Section {#the-bit-pattern-section .title} - -
- -
-::: - -Syntactically, this section comes between the keyword [**is**]{.bold} -and the delimiter for the following section, either an '{' or an '\['. -The [*bit pattern section*]{.emphasis} describes a constructor's -[*pattern*]{.emphasis}, the subset of possible instruction encodings -that the designer wants to [*match*]{.emphasis} the constructor being -defined. - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_constraints}7.4.1. Constraints {#constraints .title} - -
- -
-::: - -The patterns required for processor specifications can almost always be -described as a mask and value pair. Given a specific instruction -encoding, we can decide if the encoding matches our pattern by looking -at just the bits specified by the [*mask*]{.emphasis} and seeing if they -match a specific [*value*]{.emphasis}. The fields, as defined in -[Section 6.1, "Defining Tokens and -Fields"](sleigh_tokens.html#sleigh_defining_tokens "6.1. Defining Tokens and Fields"){.xref}, -typically give us our masks. So to construct a pattern, we can simply -require that the field take on a specific value, as in the example -below. - -::: {.informalexample} -``` -:halt is opcode=0x15 { ... -``` -::: - -Assuming the symbol [*opcode*]{.emphasis} was defined as a field, this -says that a root constructor with mnemonic "halt" matches any -instruction where the bits defining this field have the value 0x15. The -equation "opcode=0x15" is called a [*constraint*]{.emphasis}. - -The standard bit encoding of the integer is used when restricting the -value of a field. This encoding is used even if an [**attach**]{.bold} -statement has assigned a different meaning to the field. The alternate -meaning does not apply within the pattern. This can be slightly -confusing, particularly in the case of an [**attach values**]{.bold} -statement, which provides an alternate integer interpretation of the -field. -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_ampandor}7.4.2. The \'&\' and \'\|\' Operators {#the-and-operators .title} - -
- -
-::: - -More complicated patterns are built out of logical operators. The -meaning of these are fairly straightforward. We can force two or more -constraints to be true at the same time, a [*logical and*]{.emphasis} -'&', or we can require that either one constraint or another must be -true, a [*logical or*]{.emphasis} '\|'. By using these with constraints -and parentheses for grouping, arbitrarily complicated patterns can be -constructed. - -::: {.informalexample} -``` -:nop is (opcode=0 & mode=0) | (opcode=15) { ... -``` -::: - -Of the two operators, the [*logical and*]{.emphasis} is much more -common. The SLEIGH compiler typically can group together several -constraints that are combined with this operator into a single efficient -mask/value check, so this operator is to be preferred if at all -possible. The [*logical or*]{.emphasis} operator usually requires two or -more mask/value style checks to correctly implement. -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_defining_operands}7.4.3. Defining Operands and Invoking Subtables {#defining-operands-and-invoking-subtables .title} - -
- -
-::: - -The principle way of defining a constructor operand, left undefined from -the display section, is done in the bit pattern section. If an operand's -identifier is used by itself, not as part of a constraint, then the -operand takes on both the display and semantic definition of the global -symbol with the same identifier. The syntax is slightly confusing at -first. The identifier must appear in the pattern as if it were a term in -a sequence of constraints but without the operator and right-hand side -of the constraint. - -::: {.informalexample} -``` -define token instr(32) - opcode = (0,5) - r1 = (6,10) - r2 = (11,15); -attach variables [ r1 r2 ] [ reg0 reg1 reg2 reg3 ]; - -:add r1,r2 is opcode=7 & r1 & r2 { ... -``` -::: - -This is a typical example. The [*add*]{.emphasis} instruction must have -the bits in the [*opcode*]{.emphasis} field set specifically. But it -also uses two fields in the instruction which specify registers. The -[*r1*]{.emphasis} and [*r2*]{.emphasis} identifiers are defined to be -local because they appear in the display section, but their use in the -pattern section of the definition links the local symbols with the -global register symbols defined as fields with attached registers. The -constructor is essentially saying that it is building the full -[*add*]{.emphasis} instruction encoding out of the register fields -[*r1*]{.emphasis} and [*r2*]{.emphasis} but is not specifying their -value. - -The syntax makes a little more sense keeping in mind this principle: - -::: {.informalexample} -::: {.itemizedlist} -- The pattern must somehow specify all the bits and symbols being used - by the constructor, even if the bits are not restricted to specific - values. -::: -::: - -The linkage from local symbol to global symbol will happen for any -global identifier which represents a family symbol, including table -symbols. This is in fact the principle mechanism for recursively -building new symbols from old symbols. For those familiar with grammar -parsers, a SLEIGH specification is in part a grammar specification. The -terminal symbols, or tokens, are the bits of an instruction, and the -constructors and tables are the non-terminating symbols. These all build -up to the root instruction table, the grammar's start symbol. So this -link from local to global is simply a statement of the grouping of old -symbols into the new constructor. -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_variable_length}7.4.4. Variable Length Instructions {#variable-length-instructions .title} - -
- -
-::: - -There are some additional complexities to designing a specification for -a processor with variable length instructions. Some initial portion of -an instruction must always be parsed. But depending on the fields in -this first portion, additional portions of varying lengths may need to -be read. The key to incorporating this behavior into a SLEIGH -specification is the token. Recall that all fields are built on top of a -token which is defined to be a specific number of bytes. If a processor -has fixed length instructions, the specification needs to define only a -single token representing the entire instruction, and all fields are -built on top of this one token. For processors with variable length -instructions however, more than one token needs to be defined. Each -token has different fields defined upon it, and the SLEIGH compiler can -distinguish which tokens are involved in a particular constructor by -examining the fields it uses. The tokens that are actually used by any -matching constructors determine the final length of the instruction. -SLEIGH has two operators that are specific to variable length -instruction sets and that give the designer control over how tokens fit -together. - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_semicolon}7.4.4.1. The \';\' Operator {#the-operator .title} - -
- -
-::: - -The most important operator for patterns defining variable length -instructions is the concatenation operator ';'. When building a -constructor with fields from two or more tokens, the pattern must -explicitly define the order of the tokens. In terms of the logic of the -pattern expressions themselves, the ';' operator has the same meaning as -the '&' operator. The combined expression matches only if both -subexpressions are true. However, it also requires that the -subexpressions involve multiple tokens and explicitly indicates an order -for them. - -::: {.informalexample} -``` -define token base(8) - op=(0,3) - mode=(4,4) - reg=(5,7); -define token immtoken(16) - imm16 = (0,15); - -:inc reg is op=2 & reg { ... -:add reg,imm16 is op=3 & reg; imm16 { ... -``` -::: - -In the above example, we see the definitions of two different tokens, -[*base*]{.emphasis} and [*immtoken*]{.emphasis}. For the first -instruction, [*inc*]{.emphasis}, the constructor uses fields -[*op*]{.emphasis} and [*reg*]{.emphasis}, both defined on -[*base*]{.emphasis}. Thus, the pattern applies constraints to just a -single byte, the size of base, in the corresponding encoding. The second -instruction, [*add*]{.emphasis}, uses fields [*op*]{.emphasis} and -[*reg*]{.emphasis}, but it also uses field [*imm16*]{.emphasis} -contained in [*immtoken*]{.emphasis}. The ';' operator indicates that -token [*base*]{.emphasis} (via its fields) comes first in the encoding, -followed by [*immtoken*]{.emphasis}. The constraints on -[*base*]{.emphasis} will therefore correspond to constraints on the -first byte of the encoding, and the constraints on -[*immtoken*]{.emphasis} will apply to the second and third bytes. The -length of the final encoding for [*add*]{.emphasis} will be 3 bytes, the -sum of the lengths of the two tokens. - -If two pattern expressions are combined with the '&' or '\|' operator, -where the concatenation operator ';' is also being used, the designer -must make sure that the tokens underlying each expression are the same -and come in the same order. In the example [*add*]{.emphasis} -instruction for instance, the '&' operator combines the "op=3" and "reg" -expressions. Both of these expressions involve only the token -[*base*]{.emphasis}, so the matching requirement is satisfied. The '&' -and '\|' operators can combine expressions built out of more than one -token, but the tokens must come in the same order. Also these operators -have higher precedence than the ';' operator, so parentheses may be -necessary to get the intended meaning. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_ellipsis}7.4.4.2. The \'\...\' Operator {#the-...-operator .title} - -
- -
-::: - -The ellipsis operator '\...' is used to satisfy the token matching -requirements of the '&' and '\|' operators (described in the previous -section), when the operands are of different lengths. The ellipsis is a -unary operator applied to a pattern expression that extends its token -length before it is combined with another expression. Depending on what -side of the expression the ellipsis is applied, the expression\'s tokens -are either right or left justified within the extension. - -::: {.informalexample} -``` -addrmode: reg is reg & mode=0 { ... -addrmode: #imm16 is mode=1; imm16 { ... - -:xor “A”,addrmode is op=4 ... & addrmode { ... -``` -::: - -Extending the example from the previous section, we add a subtable -[*addrmode*]{.emphasis}, representing an operand that can be encoded -either as a register, if [*mode*]{.emphasis} is set to zero, or as an -immediate value, if the [*mode*]{.emphasis} bit is one. If the immediate -value mode is selected, the operand is built by reading an additional -two bytes directly from the instruction encoding. So the -[*addrmode*]{.emphasis} table can represent a 1 byte or a 3 byte -encoding depending on the mode. In the following [*xor*]{.emphasis} -instruction, [*addrmode*]{.emphasis} is used as an operand. The -particular instruction is selected by encoding a 4 in the -[*op*]{.emphasis} field, so it requires a constraint on that field in -the pattern expression. Since the instruction uses the -[*addrmode*]{.emphasis} operand, it must combine the constraint on -[*op*]{.emphasis} with the pattern for [*addrmode*]{.emphasis}. But -[*op*]{.emphasis} involves only the token [*base*]{.emphasis}, while -[*addrmode*]{.emphasis} may also involve [*immtoken*]{.emphasis}. The -ellipsis operator resolves the conflict by extending the -[*op*]{.emphasis} constraint to be whatever the length of -[*addrmode*]{.emphasis} turns out to be. - -Since the [*op*]{.emphasis} constraint occurs to the left of the -ellipsis, it is considered left justified, and the matching requirement -for '&' will insist that [*base*]{.emphasis} is the first token in all -forms of [*addrmode*]{.emphasis}. This allows the [*xor*]{.emphasis} -instruction\'s constraint on [*op*]{.emphasis} and the -[*addrmode*]{.emphasis} constraint on [*mode*]{.emphasis} to be combined -into constraints on a single byte in the final encoding. -::: -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_invisible_operands}7.4.5. Invisible Operands {#invisible-operands .title} - -
- -
-::: - -It is not necessary for a global symbol, which is needed by a -constructor, to appear in the display section of the definition. If the -global identifier is used in the pattern section as it would be for a -normal operand definition but the identifier was not used in the display -section, then the constructor defines an [*invisible -operand*]{.emphasis}. Such an operand behaves and is parsed exactly like -any other operand but there is absolutely no visible indication of the -operand in the final display of the assembly instruction. The one common -type of instruction that uses this is the relative branch (see -[Section 7.5.1, "Relative -Branches"](sleigh_constructors.html#sleigh_relative_branches "7.5.1. Relative Branches"){.xref}) -but it is otherwise needed only in more esoteric instructions. It is -useful in situations where you need to break up the parsing of an -instruction along lines that don't quite match the assembly. -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_empty_patterns}7.4.6. Empty Patterns {#empty-patterns .title} - -
- -
-::: - -Occasionally there is a need for an empty pattern when building tables. -An empty pattern matches everything. There is a predefined symbol -[*epsilon*]{.emphasis} which has been traditionally used to indicate an -empty pattern. -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_advanced_constraints}7.4.7. Advanced Constraints {#advanced-constraints .title} - -
- -
-::: - -A constraint does not have to be of the form "field = constant", -although this is almost always what is needed. In certain situations, it -may be more convenient to use a different kind of constraint. Special -care should be taken when designing these constraints because they can -substantially deviate from the mask/value model used to implement most -constraints. These more general constraints are implemented by splitting -it up into smaller states which can be modeled as a mask/value pair. -This is all done automatically, and the designer may inadvertently -create huge numbers of parsing states for a single constraint. - -A constraint can actually be built out of arbitrary expressions. These -[*pattern expressions*]{.emphasis} are more commonly used in disassembly -actions and are defined in [Section 7.5.2, "General Actions and Pattern -Expressions"](sleigh_constructors.html#sleigh_general_actions "7.5.2. General Actions and Pattern Expressions"){.xref}, -but they can also be used in constraints. So in general, a constraint is -any equation where the left-hand side is a single family symbol, the -right-hand side is an arbitrary pattern expression, and the constraint -operator is one of the following: - -::: {.informalexample} -::: {.table} -[]{#constraints.htmltable} - -**Table 3. Constraint Operators** - -::: {.table-contents} - ----------------------------------------------------------------------- - [**Operator Name**]{.bold} [**Syntax**]{.bold} - ----------------------------------- ----------------------------------- - Integer equality = - - Integer inequality != - - Integer less-than \< - - Integer greater-than \> - ----------------------------------------------------------------------- -::: -::: - -\ -::: - -For a particular instruction encoding, each variable evaluates to a -specific integer depending on the encoding. A constraint is -[*satisfied*]{.emphasis} if, when all the variables are evaluated, the -equation is true. - -::: {.informalexample} -``` -:xor r1,r2 is opcode=0xcd & r1 & r2 { r1 = r1 ^ r2; } -:clr r1 is opcode=0xcd & r1 & r1=r2 { r1 = 0; } -``` -::: - -The above example illustrates a situation that does come up -occasionally. A processor uses an exclusive-or instruction to clear a -register by setting both operands of the instruction to the same -register. The first line in the example illustrates such an instruction. -However, processor documentation stipulates, and analysts prefer, that, -in this case, the disassembler should print a pseudo-instruction -[*clr*]{.emphasis}. The distinguishing feature of [*clr*]{.emphasis} -from [*xor*]{.emphasis} is that the two fields, specifying the two -register inputs to [*xor*]{.emphasis}, are equal. The easiest way to -specify this special case is with the general constraint, -"[*r1*]{.emphasis} = [*r2*]{.emphasis}", as in the second line of the -example. The SLEIGH compiler will implement this by enumerating all the -cases where [*r1*]{.emphasis} equals [*r2*]{.emphasis}, creating as many -states as there are registers. But the specification itself, at least, -remains compact. -::: -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_disassembly_actions}7.5. Disassembly Actions Section {#disassembly-actions-section .title} - -
- -
-::: - -After the bit pattern section, there can optionally be a section for -doing dynamic calculations, which must be between square brackets. For -certain kinds of instructions, there is a need to calculate values that -depend on the specific bits of the instruction, but which cannot be -obtained as an integer interpretation of a field or by building with an -[**attach values**]{.bold} statement. So SLEIGH provides a mechanism to -build values of arbitrary complexity. This section is not intended to -emulate the execution of the processor (this is the job of the semantic -section) but is intended to produce only those values that are needed at -disassembly time, usually for part of the disassembly display. - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_relative_branches}7.5.1. Relative Branches {#relative-branches .title} - -
- -
-::: - -The canonical example of an action at disassembly time is a branch -relocation. A jump instruction encodes the address of where it jumps to -as a relative offset to the instruction's address, for instance. But -when we display the assembly, we want to show the absolute address of -the jump destination. The correct way to specify this is to reserve an -identifier in the display section which represents the absolute address, -but then, instead of defining it in the pattern section, we define it in -the disassembly action section as a function of the current address and -the relative offset. - -::: {.informalexample} -``` -jmpdest: reloc is simm8 [ reloc=inst_next + simm8*4; ] { ... -``` -::: - -The identifier [*reloc*]{.emphasis} is reserved in the display section -for this constructor, but the identifier is not defined in the pattern -section. Instead, an invisible operand [*simm8*]{.emphasis} is defined -which is attached to a global field definition. The [*reloc*]{.emphasis} -identifier is defined in the action section as the integer obtained by -adding a multiple of [*simm8*]{.emphasis} to [*inst\_next*]{.emphasis}, -a symbol predefined to be equal to the address of the following -instruction (see [Section 5.2, "Predefined -Symbols"](sleigh_symbols.html#sleigh_predefined_symbols "5.2. Predefined Symbols"){.xref}). -Now [*reloc*]{.emphasis} is a specific symbol with both semantic and -display meaning equal to the desired absolute address. This address is -calculated separately, at disassembly time, for every instruction that -this constructor matches. -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_general_actions}7.5.2. General Actions and Pattern Expressions {#general-actions-and-pattern-expressions .title} - -
- -
-::: - -In general, the disassembly actions are encoded as a sequence of -assignments separated by semicolons. The left-hand side of each -statement must be a single operand identifier, and the right-hand side -must be a [*pattern expression*]{.emphasis}. A [*pattern -expression*]{.emphasis} is made up of both integer constants and family -symbols that have retained their semantic meaning as integers, and it is -built up out of the following typical operators: - -::: {.informalexample} -::: {.table} -[]{#patexp.htmltable} - -**Table 4. Pattern Expression Operators** - -::: {.table-contents} -+-----------------------------------+-----------------------------------+ -| [**Operator Name**]{.bold} | [**Syntax**]{.bold} | -+===================================+===================================+ -| Integer addition | \+ | -+-----------------------------------+-----------------------------------+ -| Integer subtraction | \- | -+-----------------------------------+-----------------------------------+ -| Integer multiplication | \* | -+-----------------------------------+-----------------------------------+ -| Integer division | / | -+-----------------------------------+-----------------------------------+ -| Left-shift | \<\< | -+-----------------------------------+-----------------------------------+ -| Arithmetic right-shift | \>\> | -+-----------------------------------+-----------------------------------+ -| Bitwise and | ::: {.informaltable} | -| | []{#bitwiseand.htmltable} | -| | | -| | ---------------------------- | -| | \$and | -| | & (within square brackets) | -| | ---------------------------- | -| | ::: | -+-----------------------------------+-----------------------------------+ -| Bitwise or | ::: {.informaltable} | -| | []{#bitwiseor.htmltable} | -| | | -| | ----------------------------- | -| | \$or | -| | \| (within square brackets) | -| | ----------------------------- | -| | ::: | -+-----------------------------------+-----------------------------------+ -| Bitwise xor | ::: {.informaltable} | -| | []{#bitwisexor.htmltable} | -| | | -| | ------- | -| | \$xor | -| | \^ | -| | ------- | -| | ::: | -+-----------------------------------+-----------------------------------+ -| Bitwise negation | \~ | -+-----------------------------------+-----------------------------------+ -::: -::: - -\ -::: - -For the sake of these expressions, integers are considered signed values -of arbitrary precision. Expressions can also make use of parentheses. A -family symbol can be used in an expression, only if it can be resolved -to a particular specific symbol. This generally means that a global -family symbol, such as a field, must be attached to a local identifier -before it can be used. - -The left-hand side of an assignment statement can be a context variable -(see [Section 6.4, "Context -Variables"](sleigh_tokens.html#sleigh_context_variables "6.4. Context Variables"){.xref}). -An assignment to such a variable changes the context in which the -current instruction is being disassembled and can potentially have a -drastic effect on how the rest of the instruction is disassembled. An -assignment of this form is considered local to the instruction and will -not affect how other instructions are parsed. The context variable is -reset to its original value before parsing other instructions. The -disassembly action may also contain one or more [**globalset**]{.bold} -directives, which cause changes to context variables to become more -permanent. This directive is distinct from the operators in a pattern -expression and must be invoked as a separate statement. See [Section 8, -"Using Context"](sleigh_context.html "8. Using Context"){.xref}, for a -discussion of how to effectively use context variables and [Section 8.3, -"Global Context -Change"](sleigh_context.html#sleigh_global_change "8.3. Global Context Change"){.xref}, -for details of the [**globalset**]{.bold} directive. - -Note that there are two syntax forms for the logical operators in a -pattern expression. When an expression is used as part of a constraint, -the "\$and" and "\$or" forms of the operators must be used in order to -distinguish the bitwise operators from the special pattern combining -operators, '&' and '\|' (as described in [Section 7.4.2, "The \'&\' and -\'\|\' -Operators"](sleigh_constructors.html#sleigh_ampandor "7.4.2. The '&' and '|' Operators"){.xref}). -However inside the square braces of the disassembly action section, '&' -and '\|' are interpreted as the usual logical operators. -::: -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_with_block}7.6. The With Block {#the-with-block .title} - -
- -
-::: - -To avoid tedious repetition and to ease the maintenance of -specifications already having many, many constructors and tables, the -[*with block*]{.emphasis} is provided. It is a syntactic construct that -allows a designer to apply a table header, bit pattern constraints, -and/or disassembly actions to a group of constructors. The block starts -at the [**with**]{.bold} directive and ends with a closing brace. All -constructors within the block are affected: - -::: {.informalexample} -``` -with op1 : mode=1 [ mode=2; ] { - :reg is reg & ind=0 [ mode=1; ] { ... } - :[reg] is reg & ind=1 { ... } -} -``` -::: - -In the example, both constructors are added to the table identified by -[*op1*]{.emphasis}. Both require the context field [*mode*]{.emphasis} -to be equal to 1. The listed constraints take the form described in -[Section 7.4, "The Bit Pattern -Section"](sleigh_constructors.html#sleigh_bit_pattern "7.4. The Bit Pattern Section"){.xref}, -and they are joined to those given in the constructor statement as if -prepended using '&'. Similarly, the actions take the form described in -[Section 7.5, "Disassembly Actions -Section"](sleigh_constructors.html#sleigh_disassembly_actions "7.5. Disassembly Actions Section"){.xref} -and are prepended to the actions given in the constructor statement. -Prepending the actions allows the statement to override actions in the -with block. Both technically occur, but only the last one has a -noticeable effect. The above example could have been equivalently -specified: - -::: {.informalexample} -``` -op1:reg is mode=1 & reg & ind=0 [ mode=2; mode=1; ] { ... } -op1:[ref] is mode=1 & reg & ind=1 [ mode=2; ] { ... } -``` -::: - -The three parts (table header, bit pattern section, and disassembly -actions section) of the with block are all optional. Any of them may be -omitted, though omitting all of them is rather pointless. With blocks -may also be nested. The innermost with block having a table header -specifies the default header of the constructors it contains. The -constraints and actions are combined outermost to innermost, left to -right. Note that when a with block has a table header specifying a table -that does not yet exist, the table is created immediately. Inside a with -block that has a table header, a nested with block may specify the -[*instruction*]{.emphasis} table by name, as in \"with instruction : -{[\...]{.weak}}\". Inside such a block, the rule regarding mnemonic -literals is restored (see [Section 7.3.1, -"Mnemonic"](sleigh_constructors.html#sleigh_mnemonic "7.3.1. Mnemonic"){.xref}). -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_semantic_section}7.7. The Semantic Section {#the-semantic-section .title} - -
- -
-::: - -The final section of a constructor definition is the [*semantic -section*]{.emphasis}. This is a description of how the processor would -manipulate data if it actually executed an instruction that matched the -constructor. From the perspective of a single constructor, the basic -idea is that all the operands for the constructor have been defined in -the bit pattern or disassembly action sections as either specific or -family symbols. In context, all the family symbols map to specific -symbols, and the semantic section uses these and possibly other global -specific symbols in statements that describe the action of the -constructor. All specific symbols have a varnode associated with them, -so within the semantic section, symbols are manipulated as if they were -varnodes. - -The semantic section for one constructor is surrounded by curly braces -'{' and '}' and consists of zero or more statements separated by -semicolons ';'. Most statements are built up out of C-like syntax, where -the variables are the symbols visible to the constructor. There is a -direct correspondence between each type of operator used in the -statements and a p-code operation. The SLEIGH compiler generates p-code -operations and varnodes corresponding to the SLEIGH operators and -symbols by collapsing the syntax trees represented by the statements and -creating temporary storage within the [*unique*]{.emphasis} space when -it needs to. - -::: {.informalexample} -``` -:add r1,r2 is opcode=0x26 & r1 & r2 { r1 = r1 + r2; } -``` -::: - -The above example generates exactly one integer addition operation, -[*INT\_ADD*]{.emphasis}, where the input varnodes are [*r1*]{.emphasis} -and [*r2*]{.emphasis} and the output varnode is [*r1*]{.emphasis}. - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_expressions}7.7.1. Expressions {#expressions .title} - -
- -
-::: - -Expressions are built out of symbols and the binary and unary operators -listed in [Table 5, "Semantic Expression Operators and -Syntax"](sleigh_ref.html#syntaxref.htmltable "Table 5. Semantic Expression Operators and Syntax"){.xref} -in the Appendix. All expressions evaluate to an integer, floating point, -or boolean value, depending on the final operation of the expression. -The value is then used depending on the kind of statement. Most of the -operators require that their input and output varnodes all be the same -size (see [Section 7.7.3, "Varnode -Sizes"](sleigh_constructors.html#sleigh_varnode_sizes "7.7.3. Varnode Sizes"){.xref}). -The operators all have a precedence, which is used by the SLEIGH -compiler to determine the ordering of the final p-code operations. -Parentheses can be used within expressions to affect this order. - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_arithmetic_logical}7.7.1.1. Arithmetic, Logical and Boolean Operators {#arithmetic-logical-and-boolean-operators .title} - -
- -
-::: - -For the most part these operators should be familiar to software -developers. The only real differences arise from the fact that varnodes -are typeless. So for instance, there has to be separate operators to -distinguish between dividing unsigned numbers '/', dividing signed -numbers 's/', and dividing floating point numbers 'f/'. - -Carry, borrow, and overflow calculations are implemented with separate -operations, rather than having indirect effects with the arithmetic -operations. Thus the [*INT\_CARRY*]{.emphasis}, -[*INT\_SCARRY*]{.emphasis}, and [*INT\_SBORROW*]{.emphasis} operations -may be unfamiliar to some people in this form (see the descriptions in -the Appendix). -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_star_operator}7.7.1.2. The \'\*\' Operator {#the-operator-1 .title} - -
- -
-::: - -The dereference operator, which generates [*LOAD*]{.emphasis} operations -(and [*STORE*]{.emphasis} operations), has slightly unfamiliar syntax. -The '\*' operator, as is usual in many programming languages, indicates -that the affected variable is a pointer and that the expression is -[*dereferencing*]{.emphasis} the data being pointed to. Unlike most -languages, in SLEIGH, it is not immediately clear what address space the -variable is pointing into because there may be multiple address spaces -defined. In the absence of any other information, SLEIGH assumes that -the variable points into the [*default*]{.emphasis} space, as labeled in -the definition of one of the address spaces with the -[**default**]{.bold} attribute. If that is not the space desired, the -default can be overridden by putting the identifier for the space in -square brackets immediately after the '\*'. - -It is also frequently not clear what the size of the dereferenced data -is because the pointer variable is typeless. The SLEIGH compiler can -frequently deduce what the size must be by looking at the operation in -the context of the entire statement (see [Section 7.7.3, "Varnode -Sizes"](sleigh_constructors.html#sleigh_varnode_sizes "7.7.3. Varnode Sizes"){.xref}). -But in some situations, this may not be possible, so there is a way to -specify the size explicitly. The operator can be followed by a colon ':' -and an integer indicating the number of bytes being dereferenced. This -can be used with or without the address space override. We give an -example of each kind of override in the example below. - -::: {.informalexample} -``` -:load r1,[r2] is opcode=0x99 & r1 & r2 { r1 = * r2; } -:load2 r1,[r2] is opcode=0x9a & r1 & r2 { r1 = *[other] r2; } -:load3 r1,[r2] is opcode=0x9b & r1 & r2 { r1 = *:2 r2; } -:load4 r1,[r2] is opcode=0x9c & r1 & r2 { r1 = *[other]:2 r2; } -``` -::: - -Keep in mind that the address represented by the pointer is not a byte -address if the [**wordsize**]{.bold} attribute is set to something other -than one. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_extension}7.7.1.3. Extension {#extension .title} - -
- -
-::: - -Most processors have instructions that extend small values into big -values, and many instructions do these minor data manipulations -implicitly. In keeping with the p-code philosophy, these operations must -be specified explicitly with the [*INT\_ZEXT*]{.emphasis} and -[*INT\_SEXT*]{.emphasis} operators in the semantic section. The -[*INT\_ZEXT*]{.emphasis}, does a so-called [*zero -extension*]{.emphasis}. The low-order bits are copied from the input, -and any remaining high-order bits in the result are set to zero. The -[*INT\_SEXT*]{.emphasis}, does a [*signed extension*]{.emphasis}. The -low-order bits are copied from the input, but any remaining high-order -bits in the result are set to the value of the high-order bit of the -input. The [*INT\_ZEXT*]{.emphasis} operation is invoked with the -[**zext**]{.bold} operator, and the [*INT\_SEXT*]{.emphasis} operation -is invoked with the [**sext**]{.bold} operator. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_truncation}7.7.1.4. Truncation {#truncation .title} - -
- -
-::: - -There are two forms of syntax indicating a truncation of the input -varnode. In one the varnode is followed by a colon ':' and an integer -indicating the number of bytes to copy into the output, starting with -the least significant byte. In the second form, the varnode is followed -by an integer, surrounded by parentheses, indicating the number of least -significant bytes to truncate from the input. This second form doesn't -directly specify the size of the output, which must be inferred from -context. - -::: {.informalexample} -``` -:split r1,lo,hi is opcode=0x81 & r1 & lo & hi { - lo = r1:4; - hi = r1(4); -} -``` -::: - -This is an example using both forms of truncation to split a large value -[*r1*]{.emphasis} into two smaller pieces, [*lo*]{.emphasis} and -[*hi*]{.emphasis}. Assuming [*r1*]{.emphasis} is an 8 byte value, -[*lo*]{.emphasis} receives the least significant half and -[*hi*]{.emphasis} receives the most significant half. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_bitrange_operator}7.7.1.5. Bit Range Operator {#bit-range-operator .title} - -
- -
-::: - -A specific subrange of bits within a varnode can be explicitly -referenced. Depending on the range, this may amount to just a variation -on the truncation syntax described earlier. But for this operator, the -size and boundaries of the range do not have to be restricted to byte -alignment. - -::: {.informalexample} -``` -:bit3 r1,r2 is op=0x7e & r1 & r2 { r1 = zext(r2[3,1]); } -``` -::: - -A varnode, [*r2*]{.emphasis} in this example, is immediately followed by -square brackets '\[' and '\]' indicating a bit range, and within the -brackets, there are two parameters separated by a comma. The first -parameter is an integer indicating the least significant bit of the -resulting bit range. The bits of the varnode are labeled in order of -significance, with the least significant bit of the varnode being 0. The -second parameter is an integer indicating the number of bits in the -range. In the example, a single bit is extracted from [*r2*]{.emphasis}, -and its value is extended to fill [*r1*]{.emphasis}. Thus -[*r1*]{.emphasis} takes either the value 0 or 1, depending on bit 3 of -[*r2*]{.emphasis}. - -There are some caveats associated with using this operator. Bit range -extraction is really a pseudo operator, as real p-code can only work -with memory down to byte resolution. The bit range operator will -generate some combination of [*INT\_RIGHT*]{.emphasis}, -[*INT\_AND*]{.emphasis}, and [*SUBPIECE*]{.emphasis} to simulate the -extraction of smaller or unaligned pieces. The "r2\[3,1\]" from the -example generates the following p-code, for instance. - -::: {.informalexample} -``` -u1 = INT_RIGHT r2,#3 -u2 = SUBPIECE u1,0 -u3 = INT_AND u2,#0x1 -``` -::: - -The result of any bit range operator still has a size in bytes. This -size is always the minimum number of bytes needed to contain the -resulting bit range, and if there are any extra bits in the result these -are automatically set to zero. - -This operator can also be used on the left-hand side of assignments with -similar behavior and caveats (see [Section 7.7.2.8, "Bit Range -Assignments"](sleigh_constructors.html#sleigh_bitrange_assign "7.7.2.8. Bit Range Assignments"){.xref}). -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_addressof}7.7.1.6. Address-of Operator {#address-of-operator .title} - -
- -
-::: - -There is an [*address-of*]{.emphasis} operator for generating the -address offset of a selected varnode as an integer value for use in -expressions. Use of this operator is a little subtle because it does -[*not*]{.emphasis} generate a p-code operation that calculates the -desired value. The address is only calculated at disassembly time and -not during execution. The operator can only be used if the symbol -referenced has a static address. - -::: {.warning style="margin-left: 0.5in; margin-right: 0.5in;"} -### Warning {#warning .title} - -The current SLEIGH compiler cannot distinguish when the symbol has an -address that can always be resolved during disassembly. So improper use -may not be flagged as an error, and the specification may produce -unexpected results. -::: - -There '&' operator in front of a symbol invokes this function. The -ampersand can also be followed by a colon ':' and an integer explicitly -indicating the size of the resulting constant as a varnode. - -::: {.informalexample} -``` -:copyr r1 is op=0x3b & r1 { tmp:4 = &r1 + 4; r1 = *[register]tmp;} -``` -::: - -The above is a contrived example of using the address-of operator to -copy from a register that is not explicitly indicated by the -instruction. This example constructs the address of the register -following [*r1*]{.emphasis} within the [*register*]{.emphasis} space, -and then loads [*r1*]{.emphasis} with data from that address. The net -effect of all this is that the register following [*r1*]{.emphasis} is -copied into [*r1*]{.emphasis}, even though it is not mentioned directly -in the instruction. Notice that the address-of operator only produces -the offset portion of the address, and to copy the desired value, the -'\*' operator must have a [*register*]{.emphasis} space override. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_managed_code}7.7.1.7. Managed Code Operations {#managed-code-operations .title} - -
- -
-::: - -SLEIGH provides basic support for instructions where encoding and -context don\'t provide a complete description of the semantics. This is -the case typically for [*managed code*]{.emphasis} instruction sets -where generation of the semantic details of an instruction may be -deferred until run-time. Support for these operators is architecture -dependent, otherwise they just act as black-box functions. - -The constant pool operator, [**cpool**]{.bold}, returns sizes, offsets, -addresses, and other structural constants. It behaves like a -[*query*]{.emphasis} to the architecture about these constants. The -first parameter is generally an [*object reference*]{.emphasis}, and -additional parameters are constants describing the particular query. The -operator returns the requested value. In the following example, an -object reference [*regParamC*]{.emphasis} and the encoded constant -[*METHOD\_INDEX*]{.emphasis} are sent as part of a query to obtain the -final destination address of an object method. - -::: {.informalexample} -``` -:invoke_direct METHOD_INDEX,regParamC - is inst0=0x70 ; N_PARAMS=1 & METHOD_INDEX & regParamC -{ - iv0 = regParamC; - destination:4 = cpool( regParamC, METHOD_INDEX, $(CPOOL_METHOD)); - call [ destination ]; -} -``` -::: - -If object memory allocation is an atomic feature of the instruction set, -the specification designer can use the [**newobject**]{.bold} functional -operator to implement it in SLEIGH. It takes one or two parameters. The -first parameter is a [*class reference*]{.emphasis} or other value -describing the object to be allocated, and the second parameter is an -optional count of the number of objects to allocate. It returns a -pointer to the allocated object. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_userdef_op}7.7.1.8. User-Defined Operations {#user-defined-operations .title} - -
- -
-::: - -Any identifier that has been defined as a new p-code operation, using -the [**define pcodeop**]{.bold} statement, can be invoked as an operator -using functional syntax. The SLEIGH compiler assumes that the operator -can take an arbitrary number of inputs, and if used in an expression, -the compiler assumes the operation returns an output. Using this syntax -of course generates the particular p-code operation reserved for the -identifier. - -::: {.informalexample} -``` -define pcodeop arctan; - ... -:atan r1,r2 is opcode=0xa3 & r1 & r2 { r1 = arctan(r2); } -``` -::: -::: -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_statements}7.7.2. Statements {#statements .title} - -
- -
-::: - -We describe the types of semantic statements that are allowed in SLEIGH. - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_assign_statements}7.7.2.1. Assignment Statements and Temporary Variables {#assignment-statements-and-temporary-variables .title} - -
- -
-::: - -Of course SLEIGH allows assignment statements with the '=' operator, -where the right-hand side is an arbitrary expression and the left-hand -side is the varnode being assigned. The assigned varnode can be any -specific symbol in the scope of the constructor, either a global symbol -or a local operand. - -In SLEIGH, the keyword [**local**]{.bold} is used to allocate temporary -variables. If an assignment statement is prepended with -[**local**]{.bold}, and the identifier on the left-hand side of an -assignment does not match any symbol in the scope of the constructor, a -named temporary varnode is created in the [*unique*]{.emphasis} address -space to hold the result of the expression. The new symbol becomes part -of the local scope of the constructor, and can be referred to in the -following semantic statements. The size of the new varnode is calculated -by examining the statement in context (see [Section 7.7.3, "Varnode -Sizes"](sleigh_constructors.html#sleigh_varnode_sizes "7.7.3. Varnode Sizes"){.xref}). -It is also possible to explicitly indicate the size by using the colon -':' operator followed by an integer size in bytes. The following -examples demonstrate the temporary variable [*tmp*]{.emphasis} being -defined using both forms. - -::: {.informalexample} -``` -:swap r1,r2 is opcode=0x41 & r1 & r2 { - local tmp = r1; - r1 = r2; - r2 = tmp; -} -:store r1,imm is opcode=0x42 & r1 & imm { - local tmp:4 = imm+0x20; - *r1 = tmp; -} -``` -::: - -The [**local**]{.bold} keyword can also be used to declare a named -temporary varnode, without an assignment statement. This is useful for -temporaries that are immediately passed into a macro. - -::: {.informalexample} -``` -:pushflags r1 is opcode=0x43 & r1 { - local tmp:4; - packflags(tmp); - * r1 = tmp; - r1 = r1 - 4; -} -``` -::: - -::: {.warning style="margin-left: 0.5in; margin-right: 0.5in;"} -### Warning {#warning-1 .title} - -Currently, the SLEIGH compiler does not need the [**local**]{.bold} -keyword to create a temporary variable. For any assignment statement, if -the left-hand side has a new identifier, a new temporary symbol will be -created using this identifier. Unfortunately, this can cause SLEIGH to -blindly accept assignment statements where the left-hand side identifier -is a misspelling of an existing symbol. Use of the [**local**]{.bold} -keyword is preferred and may be enforced in future compiler versions. -::: -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_storage_statements}7.7.2.2. Storage Statements {#storage-statements .title} - -
- -
-::: - -SLEIGH supports fairly standard [*storage statement*]{.emphasis} syntax -to complement the load operator. The left-hand side of an assignment -statement uses the '\*' operator to indicate a dynamic storage location, -followed by an arbitrary expression to calculate the location. This -syntax of course generates the p-code [*STORE*]{.emphasis} operator as -the final step of the statement. - -::: {.informalexample} -``` -:sta [r1],r2 is opcode=0x20 & r1 & r2 { *r1 = r2; } -:stx [r1],r2 is opcode=0x21 & r1 & r2 { *[other] r1 = r2; } -:sti [r1],imm is opcode=0x22 & r1 & imm { *:4 r1 = imm; } -``` -::: - -The same size and address space considerations that apply to the '\*' -operator when it is used as a load operator also apply when it is used -as a store operator, see [Section 7.7.1.2, "The \'\*\' -Operator"](sleigh_constructors.html#sleigh_star_operator "7.7.1.2. The '*' Operator"){.xref}. -Unless explicit modifiers are given, the default address space is -assumed as the storage destination, and the size of the data being -stored is calculated from context. Keep in mind that the address -represented by the pointer is not a byte address if the -[**wordsize**]{.bold} attribute is set to something other than one. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_exports}7.7.2.3. Exports {#exports .title} - -
- -
-::: - -The semantic section doesn't just specify how to generate p-code for a -constructor. Except for those constructors in the root table, this -section also associates a semantic meaning to the table symbol the -constructor is part of, allowing the table to be used as an operand in -other tables. The mechanism for making this association is the -[*export*]{.emphasis} statement. This must be the last statement in the -section and consists of the [**export**]{.bold} keyword followed by the -specific symbol to be associated with the constructor. In general, the -constructor will have a sequence of assignment statements building a -final value, and then the varnode containing the value will be exported. -However, anything can be exported. - -::: {.informalexample} -``` -mode: reg++ is addrmode=0x2 & reg { tmp=reg; reg=reg+1; export tmp; } -``` -::: - -This is an example of a post-increment addressing mode that would be -used to build more complicated instructions. The constructor increments -a register [*reg*]{.emphasis} but stores a copy of its original value in -[*tmp*]{.emphasis}. The varnode [*tmp*]{.emphasis} is then exported, -associating it with the table symbol [*mode*]{.emphasis}. When this -constructor is matched, as part of a more complicated instruction, the -symbol [*mode*]{.emphasis} will represent the original semantic value of -[*reg*]{.emphasis} but with the standard post-increment side-effect. - -The table symbol associated with the constructor becomes a -[*reference*]{.emphasis} to the varnode being exported, not a copy of -the value. If the table symbol is written to, as the left-hand side of -an assignment statement, in some other constructor, the exported varnode -is affected. A constant can be exported if its size as a varnode is -given explicitly with the ':' operator. - -It is not legal to put a full expression in an [**export**]{.bold} -statement, any expression must appear in an earlier statement. However, -a single '&' operator is allowed as part of the statement and it behaves -as it would in a normal expression (see [Section 7.7.1.6, "Address-of -Operator"](sleigh_constructors.html#sleigh_addressof "7.7.1.6. Address-of Operator"){.xref}). -It causes the address of the varnode being modified to be exported as an -integer constant. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_dynamic_references}7.7.2.4. Dynamic References {#dynamic-references .title} - -
- -
-::: - -The only other operator allowed as part of an [**export**]{.bold} -statement, is the '\*' operator. The semantic meaning of this operator -is the same as if it were used in an expression (see [Section 7.7.1.2, -"The \'\*\' -Operator"](sleigh_constructors.html#sleigh_star_operator "7.7.1.2. The '*' Operator"){.xref}), -but it is worth examining the effects of this form of export in detail. -Bearing in mind that an [**export**]{.bold} statement exports a -[*reference*]{.emphasis}, using the '\*' operator in the statement -exports a [*dynamic reference*]{.emphasis}. The varnode being modified -by the '\*' is interpreted as a pointer to another varnode. It is this -varnode being pointed to which is exported, even though the address may -be dynamic and cannot be determined at disassembly time. This is not the -same as dereferencing the pointer into a temporary variable that is then -exported. The dynamic reference can be both read and -[*written*]{.emphasis}. Internally, the SLEIGH compiler keeps track of -the pointer and inserts a [*LOAD*]{.emphasis} or [*STORE*]{.emphasis} -operation when the symbol associated with the dynamic reference is -referred to in other constructors. - -::: {.informalexample} -``` -mode: reg[off] is addr=1 & reg & off { - ea = reg + off; - export *:4 ea; -} -dest: reloc is abs [ reloc = abs * 4; ] { - export *[ram]:4 reloc; -} -``` -::: - -In the first example, the effective address of an operand is calculated -from a register [*reg*]{.emphasis} and a field of the instruction -[*off*]{.emphasis}. The constructor does not export the resulting -pointer [*ea*]{.emphasis}, it exports the location being pointed to by -[*ea*]{.emphasis}. Notice the size of this location (4) is given -explicitly with the ':' modifier. The '\*' operator can also be used on -constant pointers. In the second example, the constant operand -[*reloc*]{.emphasis} is used as the offset portion of an address into -the [*ram*]{.emphasis} address space. The constant [*reloc*]{.emphasis} -is calculated at disassembly time from the instruction field -[*abs*]{.emphasis}. This is a very common construction for jump -destinations (see [Section 7.5.1, "Relative -Branches"](sleigh_constructors.html#sleigh_relative_branches "7.5.1. Relative Branches"){.xref}) -but can be used in general. This particular combination of a disassembly -time action and a dynamic export is a very general way to construct a -family of varnodes. - -Dynamic references are a key construction for effectively separating -addressing mode implementations from instruction semantics at higher -levels. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_branching_statements}7.7.2.5. Branching Statements {#branching-statements .title} - -
- -
-::: - -This section discusses statements that generate p-code branching -operations. These are listed in [Table 7, "Branching -Statements"](sleigh_ref.html#branchref.htmltable "Table 7. Branching Statements"){.xref}, -in the Appendix. - -There are six forms covering the gamut of typical assembly language -branches, but in terms of actual semantics there are really only three. -With p-code, - -::: {.informalexample} -::: {.itemizedlist} -- [*CALL*]{.emphasis} is semantically equivalent to - [*BRANCH*]{.emphasis}, -- [*CALLIND*]{.emphasis} is semantically equivalent to - [*BRANCHIND*]{.emphasis}, and -- [*RETURN*]{.emphasis} is semantically equivalent to - [*BRANCHIND*]{.emphasis}. -::: -::: - -The reason for this is that calls and returns imply the presence of some -sort of a stack. Typically an assembly language call instruction does -several separate actions, manipulating a stack pointer, storing a return -value, and so on. When translating the call instruction into p-code, -these actions must be implemented with explicit operations. The final -step of the instruction, the actual jump to the destination of the call -is now just a branch, stripped of its implied meaning. The -[*CALL*]{.emphasis}, [*CALLIND*]{.emphasis}, and [*RETURN*]{.emphasis} -operations, are kept as distinct from their [*BRANCH*]{.emphasis} -counterparts in order to provide analysis software a hint as to the -higher level meaning of the branch. - -There are actually two fundamentally different ways of indicating a -destination for these branch operations. By far the most common way to -specify a destination is to give the [*address*]{.emphasis} of a machine -instruction. It bears repeating here that there is typically more than -one p-code operation per machine instruction. So specifying a -[*destination address*]{.emphasis} really means that the destination is -the first p-code operation for the (translated) machine instruction at -that address. For most cases, this is the only kind of branching needed. -The rarer case of [*p-code relative*]{.emphasis} branching is discussed -in the following section ([Section 7.7.2.6, "P-code Relative -Branching"](sleigh_constructors.html#sleigh_pcode_relative "7.7.2.6. P-code Relative Branching"){.xref}), -but for the remainder of this section, we assume the destination is -ultimately given as an address. - -There are two ways to specify a branching operation's destination -address; directly and indirectly. Where a direct address is needed, as -for the [*BRANCH*]{.emphasis}, [*CBRANCH*]{.emphasis}, and -[*CALL*]{.emphasis} instructions, The specification can give the integer -offset of the jump destination within the address space of the current -instruction. Optionally, the offset can be followed by the name of -another address space in square brackets, if the destination is in -another address space. - -::: {.informalexample} -``` -:reset is opcode=0x0 { goto 0x1000; } -:modeshift is opcode=0x1 { goto 0x0[codespace]; } -``` -::: - -Of course, most branching instructions encode the destination of the -jump within the instruction somehow. So the jump destination is almost -always represented by an operand symbol and its associated varnode. For -a direct branch, the destination is given by the address space and the -offset defining the varnode. In this case, the varnode itself is really -just an annotation of the jump destination and not used as a variable. -The best way to define varnodes which annotate jump destinations in this -way is with a dynamic export. - -::: {.informalexample} -``` -dest: rel is simm8 [ rel = inst_next + simm8*4; ] { - export *[ram]:4 rel; -} -``` -::: - -In this example, the operand [*rel*]{.emphasis} is defined with a -disassembly action in terms of the address of the following instruction, -[*inst\_next*]{.emphasis}, and a field specifying a relative relocation, -[*simm8*]{.emphasis}. The resulting exported varnode has -[*rel*]{.emphasis} as its offset and [*ram*]{.emphasis} as its address -space, by virtue of the dynamic form of the export. The symbol -associated with this varnode, [*dest*]{.emphasis}, can now be used in -branch operations. - -::: {.informalexample} -``` -:jmp dest is opcode=3 & dest { - goto dest; -} -:call dest is opcode=4 & dest { - *:4 sp = inst_next; - sp=sp-4; - call dest; -} -``` -::: - -The above examples illustrate the direct forms of the [**goto**]{.bold} -and [**call**]{.bold} operators, which generate the p- code -[*BRANCH*]{.emphasis} and [*CALL*]{.emphasis} operations respectively. -Both these operations take a single annotation varnode as input, -indicating the destination address of the jump. Notice the explicit -manipulation of a stack pointer [*sp*]{.emphasis}, for the call -instruction. The [*CBRANCH*]{.emphasis} operation takes two inputs, a -boolean value indicating whether or not the branch should be taken, and -a destination annotation. - -::: {.informalexample} -``` -:bcc dest is opcode=5 & dest { if (carryflag==0) goto dest; } -``` -::: - -As in the above example, the [*CBRANCH*]{.emphasis} operation takes two -inputs, a boolean value indicating whether or operation is invoked with -the [**if goto**]{.bold} operation takes two inputs, a boolean value -indicating whether or syntax. The condition of the [**if**]{.bold} -operation takes two inputs, a boolean value indicating whether or can be -any semantic expression that results in a boolean value. The destination -must be an annotation varnode. - -The operators [*BRANCHIND*]{.emphasis}, [*CALLIND*]{.emphasis}, and -[*RETURN*]{.emphasis} all have the same semantic meaning and all use the -same syntax to specify an indirect address. - -::: {.informalexample} -``` -:b [reg] is opcode=6 & reg { - goto [reg]; -} -:call (reg) is opcode=7 & reg { - *:4 sp = inst_next; - sp=sp-4; - call [reg]; -} -:ret is opcode=8 { - sp=sp+4; - tmp:4 = * sp; - return [tmp]; -} -``` -::: - -Square brackets surround the varnode containing the address. Currently, -any indirect address must be in the address space containing the branch -instruction. The offset of the destination address is taken dynamically -from the varnode. The size of the varnode must match the size of the -destination space. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_pcode_relative}7.7.2.6. P-code Relative Branching {#p-code-relative-branching .title} - -
- -
-::: - -In some cases, the semantics of an instruction may require branching -[*within*]{.emphasis} the semantics of a single instruction, so -specifying a destination address is too coarse. In this case, SLEIGH is -capable of [*p-code relative*]{.emphasis} branching. Individual p-code -operations can be identified by a [*label*]{.emphasis}, and this label -can be used as the destination specifier, after the [**goto**]{.bold} -keyword. A [*label*]{.emphasis}, within the semantic section, is any -identifier surrounded by the '\<' and '\>' characters. If this -construction occurs at the beginning of a statement, we say the label is -[*defined*]{.emphasis}, and that identifier is now associated with the -first p-code operation corresponding to the following statement. Any -label must be defined exactly once in this way. When the construction is -used as a destination, immediately after a [**goto**]{.bold} or -[**call**]{.bold}, this is referred to as a label reference. Of course -the p-code destination meant by a label reference is the operation at -the point where the label was defined. Multiple references to the same -label are allowed. - -::: {.informalexample} -``` -:sum r1,r2,r3 is opcode=7 & r1 & r2 & r3 { - tmp:4 = 0; - r1 = 0; - - r1 = r1 + *r2; - r2 = r2 + 4; - tmp = tmp + 1; - if (tmp < r3) goto ; -} -``` -::: - -In the example above, the string "loopstart" is the label identifier -which appears twice; once at the point where the label is defined at the -top of the loop, after the initialization, and once as a reference where -the conditional branch is made for the loop. - -References to labels can refer to p-code that occurs either before or -after the branching statement. But label references can only be used in -a branching statement, they cannot be used as a varnode in other -expressions. The label identifiers are local symbols and can only be -referred to within the semantic section of the constructor that defines -them. Branching into the middle of some completely different instruction -is not possible. - -Internally, branches to labels are encoded as a relative index. Each -p-code operation is assigned an index corresponding to the operation's -position within the entire translation of the instruction. Then the -branch can be expressed as a relative offset between the branch -operation's index and the destination operation's index. The SLEIGH -compiler encodes this offset as a constant varnode that is used as input -to the [*BRANCH*]{.emphasis}, [*CBRANCH*]{.emphasis}, or -[*CALL*]{.emphasis} operation. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_skip_instruction_branching}7.7.2.7. Skip Instruction Branching {#skip-instruction-branching .title} - -
- -
-::: - -Many processors have a conditional-skip-instruction which must branch -over the next instruction based upon some condition. The -[*inst\_next2*]{.emphasis} symbol has been provided for this purpose. - -::: {.informalexample} -``` -:skip.eq is opcode=10 { - if (zeroflag!=0) goto inst_next2; -} -``` -::: - -In the example above, the branch address will be determined by adding -the parsed-length of the next instruction to the value of -[*inst\_next*]{.emphasis} causing a branch over the next instruction -when the condition is satisfied. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_bitrange_assign}7.7.2.8. Bit Range Assignments {#bit-range-assignments .title} - -
- -
-::: - -The bit range operator can appear on the left-hand side of an -assignment. But as with the '\*' operator, its meaning is slightly -different when used on this side. The bit range is specified in square -brackets, as before, by giving the integer specifying the least -significant bit of the range, followed by the number of bits in the -range. In contrast with its use on the right however (see -[Section 7.7.1.5, "Bit Range -Operator"](sleigh_constructors.html#sleigh_bitrange_operator "7.7.1.5. Bit Range Operator"){.xref}), -the indicated bit range is filled rather than extracted. Bits obtained -from evaluating the expression on the right are extracted and spliced -into the result at the indicated bit offset. - -::: {.informalexample} -``` -:bitset3 r1 is op=0x7d & r1 { r1[3,1] = 1; } -``` -::: - -In this example, bit 3 of varnode [*r1*]{.emphasis} is set to 1, leaving -all other bits unaffected. - -As in the right-hand case, the desired insertion is achieved by piecing -together some combination of the p-code operations -[*INT\_LEFT*]{.emphasis}, [*INT\_ZEXT*]{.emphasis}, -[*INT\_AND*]{.emphasis}, and [*INT\_OR*]{.emphasis}. - -In terms of the rest of the assignment expression, the bit range -operator is again assumed to have a size equal to the minimum number of -bytes needed to hold the bit range. In particular, in order to satisfy -size restrictions (see [Section 7.7.3, "Varnode -Sizes"](sleigh_constructors.html#sleigh_varnode_sizes "7.7.3. Varnode Sizes"){.xref}), -the right-hand side must match this size. Furthermore, it is assumed -that any extra bits in the right-hand side expression are already set to -zero. -::: -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_varnode_sizes}7.7.3. Varnode Sizes {#varnode-sizes .title} - -
- -
-::: - -All statements within the semantic section must be specified up to the -point where the sizes of all varnodes are unambiguously determined. Most -specific symbols, like registers, must have their size defined by -definition, but there are two sources of size ambiguity. - -::: {.informalexample} -::: {.itemizedlist} -- Constants -- Temporary Variables -::: -::: - -The SLEIGH compiler does not make assumptions about the size of a -constant variable based on the constant value itself. This is true of -values occurring explicitly in the specification and of values that are -calculated dynamically in a disassembly action. As described in -[Section 7.7.2.1, "Assignment Statements and Temporary -Variables"](sleigh_constructors.html#sleigh_assign_statements "7.7.2.1. Assignment Statements and Temporary Variables"){.xref}, -temporary variables do not need to have their size given explicitly. - -The SLEIGH compiler can usually fill in the required size by examining -these situations in the context of the entire semantic section. Most -p-code operations have size restrictions on their inputs and outputs, -which when put together can uniquely determine the unspecified sizes. -Referring to [Table 5, "Semantic Expression Operators and -Syntax"](sleigh_ref.html#syntaxref.htmltable "Table 5. Semantic Expression Operators and Syntax"){.xref} -in the Appendix, all arithmetic and logical operations, both integer and -floating point, must have inputs and outputs all of the same size. The -only exceptions are as follows. The overflow operators, -[*INT\_CARRY*]{.emphasis}, [*INT\_SCARRY*]{.emphasis}, -[*INT\_SBORROW*]{.emphasis}, and [*FLOAT\_NAN*]{.emphasis} have a -boolean output. The shift operators, [*INT\_LEFT*]{.emphasis}, -[*INT\_RIGHT*]{.emphasis}, and [*INT\_SRIGHT*]{.emphasis}, currently -place no restrictions on the [*shift amount*]{.emphasis} operand. All -the comparison operators, both integer and floating point, insist that -their inputs are all the same size, and the output must be a boolean -variable, with a size of 1 byte. - -The operators without a size constraint are the load and store -operators, the extension and truncation operators, and the conversion -operators. As discussed in [Section 7.7.1.2, "The \'\*\' -Operator"](sleigh_constructors.html#sleigh_star_operator "7.7.1.2. The '*' Operator"){.xref}, -the '\*' operator cannot get size information for the dynamic -(pointed-to) object from the pointer itself. The other operators by -definition involve a change of size from input to output. - -If the SLEIGH compiler cannot discover the sizes of constants and -temporaries, it will report an error stating that it could not resolve -variable sizes for that constructor. This can usually be fixed rapidly -by appending the size ':' modifier to either the '\*' operator, the -temporary variable definition, or to an explicit integer. Here are three -examples of statements that generate a size resolution error, each -followed by a variation which corrects the error. - -::: {.informalexample} -``` -:sta [r1],imm is opcode=0x3a & r1 & imm { - *r1 = imm; #Error -} -:sta [r1],imm is opcode=0x3a & r1 & imm { - *:4 r1 = imm; #Correct -} -:inc [r1] is opcode=0x3b & r1 { - tmp = *r1 + 1; *r1 = tmp; # Error -} -:inc [r1] is opcode=0x3b & r1 { - tmp:4 = *r1 + 1; *r1 = tmp; # Correct -} -:clr [r1] is opcode=0x3c & r1 { - * r1 = 0; # Error -} -:clr [r1] is opcode=0x3c & r1 { - * r1 = 0:4; # Correct -} -``` -::: -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_unimplemented_semantics}7.7.4. Unimplemented Semantics {#unimplemented-semantics .title} - -
- -
-::: - -The semantic section must be present for every constructor in the -specification. But the designer can leave the semantics explicitly -unimplemented if the keyword [**unimpl**]{.bold} is put in the -constructor definition in place of the curly braces. This serves as a -placeholder if a specification is still in development or if the -designer does not intend to model data flow for portions of the -instruction set. Any instruction involving a constructor that is -unimplemented in this way will still be disassembled properly, but the -basic data flow routines will report an error when analyzing the -instruction. Analysis routines then can choose whether or not to -intentionally ignore the error, effectively treating the unimplemented -portion of the instruction as if it does nothing. - -::: {.informalexample} -``` -:cache r1 is opcode=0x45 & r1 unimpl -:nop is opcode=0x0 { } -``` -::: -::: -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_tables}7.8. Tables {#tables .title} - -
- -
-::: - -A single constructor does not form a new specific symbol. The -[*table*]{.emphasis} that the constructor is associated with via its -table header is the actual symbol that can be reused to build up more -complicated elements. With all the basic building blocks now in place, -we outline the final elements for building symbols that represent larger -and larger portions of the disassembly and p- code translation process. - -The best analogy here is with grammar specifications and Regular -Language parsers. Those who have used [*yacc*]{.emphasis}, -[*bison*]{.emphasis}, or otherwise looked at BNF grammars should find -the concepts here familiar. - -With SLEIGH, there are in some sense two separate grammars being parsed -at the same time. A display grammar and a semantic grammar. To the -extent that the two grammars breakdown in the same way, SLEIGH can -exploit the similarity to produce an extremely concise description. - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_matching}7.8.1. Matching {#matching .title} - -
- -
-::: - -If a table contains exactly one constructor, the meaning of the table as -a specific symbol is straightforward. The display meaning of the symbol -comes from the [*display section*]{.emphasis} of the constructor, and -the symbol's semantic meaning comes from the constructor's [*semantic -section*]{.emphasis}. - -::: {.informalexample} -``` -mode1: (r1) is addrmode=1 & r1 { export r1; } -``` -::: - -The table symbol in this example is [*mode1*]{.emphasis}. Assuming this -is the only constructor, the display meaning of the symbol are the -literal characters '(', and ')' concatenated with the display meaning of -[*r1*]{.emphasis}, presumably a register name that has been attached. -The semantic meaning of [*mode1*]{.emphasis}, because of the export -statement, becomes whatever register is matched by the -[*r1*]{.emphasis}. - -::: {.informalexample} -``` -mode1: (r1) is addrmode=1 & r1 { export r1; } -mode1: [r2] is addrmode=2 & r2 { export r2; } -``` -::: - -If there are two or more constructors defined for the same table, the -[*bit pattern section*]{.emphasis} is used to select between the -constructors in context. In the above example, the [*mode1*]{.emphasis} -table is now defined with two constructors and the distinguishing -feature of their bit patterns is that in one the [*addrmode*]{.emphasis} -field must be 1 and in the other it must be 2. In the context of a -particular instruction, the matching constructor can be determined -uniquely based on this field, and the [*mode1*]{.emphasis} symbol takes -on the display and semantic characteristics of the matching constructor. - -The bit patterns for constructors under a single table must be built so -that a constructor can be uniquely determined in context. The above -example shows the easiest way to accomplish this. The two sets of -instruction encodings, which match one or the other of the two -[*addrmode*]{.emphasis} constraints, are disjoint. In general, if each -constructor has a set of instruction encodings associated with it, and -if the sets for any two constructors are disjoint, then no two -constructors can match at the same time. - -It is possible for two sets to intersect, if one of the two sets -properly contains the other. In this situation, the constructor -corresponding to the smaller (contained) set is considered a [*special -case*]{.emphasis} of the other constructor. If an instruction encoding -matches the special case, that constructor is used to define the symbol, -even though the other constructor will also match. If the special case -does not match but the other more general constructor does, then the -general constructor is used to define the symbol. - -::: {.informalexample} -``` -zA: r1 is addrmode=3 & r1 { export r1; } -zA: “0” is addrmode=3 & r1=0 { export 0:4; } # Special case -``` -::: - -In this example, the symbol [*zA*]{.emphasis} takes on the same display -and semantic meaning as [*r1*]{.emphasis}, except in the special case -when the field [*r1*]{.emphasis} equals 0. In this case, -[*zA*]{.emphasis} takes on the display and semantic meaning of the -constant zero. Notice that the first constructor has only the one -constraint on [*addrmode*]{.emphasis}, which is also a constraint for -the second constructor. So any instruction that matches the second must -also match the first. - -The same exact rules apply when there are more than two constructors. -Any two sets defined by the bit patterns must be either disjoint or one -contained in the other. It is entirely possible to have one general case -with many special cases, or a special case of a special case, and so on. - -If the patterns for two constructors intersect, but one pattern does not -properly contain the other, this is generally an error in the -specification. Depending on the flags given to the SLEIGH compiler, it -may be more or less lenient with this kind of situation however. In the -case where an intersection is not flagged as an error, the -[*first*]{.emphasis} constructor that matches, in the order that the -constructors appear in the specification, is used. - -If two constructors intersect, but there is a third constructor whose -pattern is exactly equal to the intersection, then the third pattern is -said to [*resolve*]{.emphasis} the conflict produced by the first two -constructors. An instruction in the intersection will match the third -constructor, as a specialization, and the remaining pieces in the -patterns of the first two constructors are disjoint. A resolved conflict -like this is not flagged as an error even with the strictest checking. -Other types of intersections, in combination with lenient checking, can -be used for various tricks in the specification but should generally be -avoided. -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_specific_symbol_trees}7.8.2. Specific Symbol Trees {#specific-symbol-trees .title} - -
- -
-::: - -When the SLEIGH parser analyzes an instruction, it starts with the root -symbol [*instruction*]{.emphasis}, and decides which of the constructors -defined under it match. This particular constructor is likely to be -defined in terms of one or more other family symbols. The parsing -process recurses at this point. Each of the unresolved family symbols is -analyzed in the same way to find the matching specific symbol. The -matching is accomplished either with a table lookup, as with a field -with attached registers, or with the matching algorithm described in -[Section 7.8.1, -"Matching"](sleigh_constructors.html#sleigh_matching "7.8.1. Matching"){.xref}. -By the end of the parsing process, we have a tree of specific symbols -representing the parsed instruction. We present a small but complete -SLEIGH specification to illustrate this hierarchy. - -::: {.informalexample} -``` -define endian=big; -define space ram type=ram_space size=4 default; -define space register type=register_space size=4; -define register offset=0 size=4 [ r0 r1 r2 r3 r4 r5 r6 r7 ]; - -define token instr(16) - op=(10,15) mode=(6,9) reg1=(3,5) reg2=(0,2) imm=(0,2) -; -attach variables [ reg1 reg2 ] [ r0 r1 r2 r3 r4 r5 r6 r7 ]; - -op2: reg2 is mode=0 & reg2 { export reg2; } -op2: imm is mode=1 & imm { export *[const]:4 imm; } -op2: [reg2] is mode=2 & reg2 { tmp = *:4 reg2; export tmp;} - -:and reg1,op2 is op=0x10 & reg1 & op2 { reg1 = reg1 & op2; } -:xor reg1,op2 is op=0x11 & reg1 & op2 { reg1 = reg1 ^ op2; } -:or reg1,op2 is op=0x12 & reg1 & op2 { reg1 = reg1 | op2; } -``` -::: - -This processor has 16 bit instructions. The high order 6 bits are the -main [*opcode*]{.emphasis} field, selecting between logical operations, -[*and*]{.emphasis}, [*or*]{.emphasis}, and [*xor*]{.emphasis}. The -logical operations each take two operands, [*reg1*]{.emphasis} and -[*op2*]{.emphasis}. The operand [*reg1*]{.emphasis} selects between the -8 registers of the processor, [*r0*]{.emphasis} through -[*r7*]{.emphasis}. The operand [*op2*]{.emphasis} is a table built out -of more complicated addressing modes, determined by the field -[*mode*]{.emphasis}. The addressing mode can either be direct, in which -[*op2*]{.emphasis} is really just the register selected by -[*reg2*]{.emphasis}, it can be immediate, in which case the same bits -are interpreted as a constant value [*imm*]{.emphasis}, or it can be an -indirect mode, where the register [*reg2*]{.emphasis} is interpreted as -a pointer to the actual operand. In any case, the two operands are -combined by the logical operation and the result is stored back in -[*reg1*]{.emphasis}. - -The parsing proceeds from the root symbol down. Once a particular -matching constructor is found, any disassembly action associated with -that constructor is executed. After that, each operand of the -constructor is resolved in turn. - -::: {.figure} -[]{#sleigh_encoding_image} - -::: {.figure-contents} -::: {.mediaobject align="center"} - -------------------------------------------------------------------------------------------------- - ![Two Encodings and the Resulting Specific Symbol Trees](Diagram1.png){width="540" height="225"} - -------------------------------------------------------------------------------------------------- -::: -::: - -**Figure 1. Two Encodings and the Resulting Specific Symbol Trees** -::: - -\ - -In [Figure 1, "Two Encodings and the Resulting Specific Symbol -Trees"](sleigh_constructors.html#sleigh_encoding_image "Figure 1. Two Encodings and the Resulting Specific Symbol Trees"){.xref}, -we can see the break down of two typical instructions in the example -instruction set. For each instruction, we see the how the encodings -split into the relevant fields and the resulting tree of specific -symbols. Each node in the trees are labeled with the base family symbol, -the portion of the bit pattern that matches, and then the resulting -specific symbol or constructor. Notice that the use of the overlapping -fields, [*reg2*]{.emphasis} and [*imm*]{.emphasis}, is determined by the -matching constructor for the [*op2*]{.emphasis} table. SLEIGH generates -the disassembly and p-code for these encodings by walking the trees. - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_disassembly_trees}7.8.2.1. Disassembly Trees {#disassembly-trees .title} - -
- -
-::: - -If the nodes of each tree are replaced with the display information of -the corresponding specific symbol, we see how the disassembly statement -is built. - -::: {.figure} -[]{#sleigh_disassembly_image} - -::: {.figure-contents} -::: {.mediaobject align="center"} - ------------------------------------------------------------------ - ![Two Disassembly Trees](Diagram2.png){width="310" height="151"} - ------------------------------------------------------------------ -::: -::: - -**Figure 2. Two Disassembly Trees** -::: - -\ - -[Figure 2, "Two Disassembly -Trees"](sleigh_constructors.html#sleigh_disassembly_image "Figure 2. Two Disassembly Trees"){.xref}, -shows the resulting disassembly trees corresponding to the specific -symbol trees in [Figure 1, "Two Encodings and the Resulting Specific -Symbol -Trees"](sleigh_constructors.html#sleigh_encoding_image "Figure 1. Two Encodings and the Resulting Specific Symbol Trees"){.xref}. -The display information comes from constructor display sections, the -names of attached registers, or the integer interpretation of fields. -The identifiers in a constructor display section serves as placeholders -for the subtrees below them. By walking the tree, SLEIGH obtains the -final illustrated assembly statements corresponding to the original -instruction encodings. -::: - -::: {.sect4} -::: {.titlepage} -
- -
- -##### []{#sleigh_pcode_trees}7.8.2.2. P-code Trees {#p-code-trees .title} - -
- -
-::: - -A similar procedure produces the resulting p-code translation of the -instruction. If each node in the specific symbol tree is replaced with -the corresponding p-code, we see how the final translation is built. - -::: {.figure} -[]{#sleigh_pcode_image} - -::: {.figure-contents} -::: {.mediaobject align="center"} - ------------------------------------------------------------- - ![Two P-code Trees](Diagram3.png){width="405" height="149"} - ------------------------------------------------------------- -::: -::: - -**Figure 3. Two P-code Trees** -::: - -\ - -[Figure 3, "Two P-code -Trees"](sleigh_constructors.html#sleigh_pcode_image "Figure 3. Two P-code Trees"){.xref} -lists the final p-code translation for our example instructions and -shows the trees from which the translation is derived. Symbol names -within the p-code for a particular node, as with the disassembly tree, -are placeholders for the subtree below them. The final translation is -put together by concatenating the p-code from each node, traversing the -nodes in a depth-first order. Thus the p-code of a child tends to come -before the p-code of the parent node (but see [Section 7.9, "P-code -Macros"](sleigh_constructors.html#sleigh_macros "7.9. P-code Macros"){.xref}). -Placeholders are filled in with the appropriate varnode, as determined -by the export statement of the root of the corresponding subtree. -::: -::: -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_macros}7.9. P-code Macros {#p-code-macros .title} - -
- -
-::: - -SLEIGH supports a macro facility for encapsulating semantic actions. The -syntax, in effect, allows the designer to define p-code subroutines -which can be invoked as part of a constructor's semantic action. The -subroutine is expanded automatically at compile time. - -A macro definition is started with the [**macro**]{.bold} keyword, which -can occur anywhere in the file before its first use. This is followed by -the global identifier for the new macro and a parameter list, comma -separated and in parentheses. The body of the definition comes next, -surrounded by curly braces. The body is a sequence of semantic -statements with the same syntax as a constructor's semantic section. The -identifiers in the macro's parameter list are local in scope. The macro -can refer to these and any global specific symbol. - -::: {.informalexample} -``` -macro resultflags(op) { - zeroflag = (op == 0); - signflag = (op1 s< 0); -} - -:add r1,r2 is opcode=0xba & r1 & r2 { r1 = r1 + r2; resultflags(r1); } -``` -::: - -The macro is invoked in the semantic section of a constructor by using -the identifier with a functional syntax, listing the varnodes which are -to be passed into the macro. In the example above, the macro -[*resultflags*]{.emphasis} calculates the value of two global flags by -comparing its parameter to zero. The [*add*]{.emphasis} constructor -invokes the macro so that the [*r1*]{.emphasis} is used in the -comparisons. Parameters are passed by [*reference*]{.emphasis}, so the -value of varnodes passed into the macro can be changed. Currently, there -is no syntax for returning a value from the macro, except by writing to -a parameter or global symbol. - -Almost any statement that can be used in a constructor can also be used -in a macro. This includes assignment statements, branching statements, -[**delayslot**]{.bold} directives, and calls to other macros. A -[**build**]{.bold} directive however should not be used in a macro. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_build_directives}7.10. Build Directives {#build-directives .title} - -
- -
-::: - -Because the nodes of a specific symbol tree are traversed in a -depth-first order, the p-code for a child node in general comes before -the p-code of the parent. Furthermore, without special intervention, the -specification designer has no control over the order in which the -children of a particular node are traversed. The [**build**]{.bold} -directive is used to affect these issues in the rare cases where it is -necessary. The [**build**]{.bold} directive occurs as another form of -statement in the semantic section of a constructor. The keyword -[**build**]{.bold} is followed by one of the constructor's operand -identifiers. Then, instead of filling in the operand's associated p-code -based on an arbitrary traversal of the symbol tree, the directive -specifies that the operand's p-code must occur at that point in the -p-code for the parent constructor. - -This directive is useful in situations where an instruction supports -prefixes or addressing modes with side-effects that must occur in a -particular order. Suppose for example that many instructions support a -condition bit in their encoding. If the bit is set, then the instruction -is executed only if a status flag is set. Otherwise, the instruction -always executes. This situation can be implemented by treating the -instruction variations as distinct constructors. However, if many -instructions support the same variation, it is probably more efficient -to treat the condition bit which distinguishes the variants as a special -operand. - -::: {.informalexample} -``` -cc: “c” is condition=1 { if (flag==1) goto inst_next; } -cc: is condition=0 { } - -:and^cc r1,r2 is opcode=0x67 & cc & r1 & r2 { - build cc; - r1 = r1 & r2; -} -``` -::: - -In this example, the conditional variant is distinguished by a 'c' -appended to the assembly mnemonic. The [*cc*]{.emphasis} operand -performs the conditional side-effect, checking a flag in one case, or -doing nothing in the other. The two forms of the instruction can now be -implemented with a single constructor. To make sure that the flag is -checked first, before the action of the instruction, the -[*cc*]{.emphasis} operand is forced to evaluate first with a -[**build**]{.bold} directive, followed by the normal action of the -instruction. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_delayslot_directives}7.11. Delay Slot Directives {#delay-slot-directives .title} - -
- -
-::: - -For processors with a pipe-lined architecture, multiple instructions are -typically executing simultaneously. This can lead to processor -conventions where certain pairs of instructions do not seem to execute -sequentially. The standard examples are branching instructions that -execute the instruction in the [*delay slot*]{.emphasis}. Despite the -fact that execution of the branch instruction does not fall through, the -following instruction is executed anyway. Such semantics can be -implemented in SLEIGH with the [**delayslot**]{.bold} directive. - -This directive appears as a standalone statement in the semantic section -of a constructor. When p- code is generated for a matching instruction, -at the point where the directive occurs, p-code for the following -instruction(s) will be generated and inserted. The directive takes a -single integer argument, indicating the minimum number of bytes in the -delay slot. Additional machine instructions will be parsed and p-code -generated, until at least that many bytes have been disassembled. -Typically the value of 1 is used to indicate that there is exactly one -more instruction in the delay slot. - -::: {.informalexample} -``` -:beq r1,r2,dest is op=0xbc & r1 & r2 & dest { flag=(r1==r2); - delayslot(1); - if flag goto dest; } -``` -::: - -This is an example of a conditional branching instruction with a delay -slot. The p-code for the following instruction is inserted before the -final [*CBRANCH*]{.emphasis}. Notice that the [**delayslot**]{.bold} -directive can appear anywhere in the semantic section. In this example, -the condition governing the branch is evaluated before the directive -because the following instruction could conceivably affect the registers -checked by the condition. - -Because the [**delayslot**]{.bold} directive combines two or more -instructions into one, the meaning of the symbols -[*inst\_next*]{.emphasis} and [*inst\_next2*]{.emphasis} become -ambiguous. It is not clear anymore what exactly the "next instruction" -is. SLEIGH uses the following conventions for interpreting an -[*inst\_next*]{.emphasis} symbol. If it is used in the semantic section, -the symbol refers to the address of the instruction after any -instructions in the delay slot. However, if it is used in a disassembly -action, the [*inst\_next*]{.emphasis} symbol refers to the address of -the instruction immediately after the first instruction, even if there -is a delay slot. The use of the [*inst\_next2*]{.emphasis} symbol may be -inappropriate in conjunction with [**delayslot**]{.bold} use. While its -use of the next instruction address is identified by -[*inst\_next*]{.emphasis}, the length of the next instruction ignores -any delay slots it may have when computing the value of -[*inst\_next2*]{.emphasis}. -::: -::: - -::: {.navfooter} - ------------------------------------------------------------------------- - - ----------------------------- --------------------- ------------------------------ - [Prev](sleigh_tokens.html)     [Next](sleigh_context.html) - 6. Tokens and Fields  [Home](sleigh.html)  8. Using Context - ----------------------------- --------------------- ------------------------------ -::: diff --git a/sources/GhidraDocs/languages/html/sleigh_context.html b/sources/GhidraDocs/languages/html/sleigh_context.html deleted file mode 100644 index 0239994..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_context.html +++ /dev/null @@ -1,364 +0,0 @@ - - - -8. Using Context - - - - - - - - - -
- - - - - - - -
8. Using Context
-Prev   Next -
-
-
-
-

-8. Using Context

-

-For most practical specifications, the disassembly and semantic -meaning of an instruction can be determined by looking only at the -bits in the encoding of that instruction. SLEIGH syntax reflects this -fact as every constructor or attached register is ultimately decided -by examining fields, the syntactic representation -of these instruction bits. In some cases however, the instruction -encoding itself may not be enough. Additional information, which we -refer to as context, may be necessary to fully -resolve the meaning of the instruction. -

-

-In truth, almost every modern processor has multiple modes of -operation, where the exact interpretation of instructions may depend -on that mode. Typical examples include distinguishing between a 16-bit -mode and a 32-bit mode, or between a big endian mode or a little -endian mode. But for the specification designer, these are of little -consequence because most software for such a processor will run in -only one mode without ever changing it. The designer need only pick -the most popular or most important mode for his projects and design to -that. If there is in fact software that runs under a different mode, -the other mode can be described in a separate specification. -

-

-However, for certain processors or software, the need to distinguish -between different interpretations of the same instruction encoding, -based on context, may be a crucial part of the disassembly and -analysis process. There are two typical situations where this becomes -necessary. -

-
    -
  • - The processor supports two (or more) separate instruction - sets. The set to use is usually determined by special bits in a status - register, and a single piece of software frequently switches between - these modes. -
    • -
  • - The processor supports instructions that temporarily affect - the execution of the immediately following instruction(s). For - example, many processors support hardware loop instructions that - automatically cause the following instructions to repeat without an - explicit instruction causing the branching and loop counting. -
    • -
-

-

-

-SLEIGH solves these problems by introducing context -variables. The syntax for defining these symbols was -described in Section 6.4, “Context Variables”. As mentioned -there, the easiest and most common way to use a context variable is as -just another field to use in our bit patterns. It gives us the extra -information we need to distinguish between different instructions -whose encodings are otherwise the same. -

-
-

-8.1. Basic Use of Context Variables

-

-Suppose a processor supports the use of two different sets of -registers in its main addressing mode, based on the setting of a -status bit which can be changed dynamically. If an instruction is -executed with this bit cleared, then one set of registers is used, and -if the bit is set, the other registers are used. The instructions -otherwise behave identically. -

-
-define endian=big;
-define space ram type=ram_space size=4 default;
-define space register type=register_space size=4;
-define register offset=0 size=4 [ r0 r1 r2 r3 r4 r5 r6 r7 ];
-define register offset=0x100 size=4 [ s0 s1 s2 s3 s4 s5 s6 s7 ];
-define register offset=0x200 size=4 [ statusreg ]; # define context bits (if defined, size must be multiple of 4-bytes)
-
-define token instr(16)
-  op=(10,15) rreg1=(7,9) sreg1=(7,9) imm=(0,6)
-;
-define context statusreg
-  mode=(3,3)
-;
-attach variables [ rreg1 ] [ r0 r1 r2 r3 r4 r5 r6 r7 ];
-attach variables [ sreg1 ] [ s0 s1 s2 s3 s4 s5 s6 s7 ];
-
-Reg1: rreg1 is mode=0 & rreg1 { export rreg1; }
-Reg1: sreg1 is mode=1 & sreg1 { export sreg1; }
-
-:addi Reg1,#imm  is op=1 & Reg1 & imm { Reg1 = Reg1 + imm; }
-
-

-

-

-In this example the symbol Reg1 uses the 3 bits -(7,9) to select one of eight registers. If the context -variable mode is set to 0, it selects -an r register, through -the rreg1 field. If mode is -set to 1 on the other hand, an s register is -selected instead -via sreg1. The addi -instruction (encoded as 0x0590 for example) can disassemble in one of -two ways. -

-
-addi r3,#0x10    OR
-addi s3,#0x10
-
-

-

-

-This is the same behavior as if mode were defined -as a field instead of a context variable, except that there is nothing -in the instruction encoding itself which indicates which of the two -forms will be chosen. An engine doing the disassembly will have global -state associated with the mode variable that will -make the final decision about which form to generate. The setting of -this state is (at least partially) out of the control of SLEIGH, -although see the following sections. -

-
-
-

-8.2. Local Context Change

-

-SLEIGH can make direct modifications to context variables through -statements in the disassembly action section of a constructor. The -left-hand side of an assignment statement in this section can be a context variable, -see Section 7.5.2, “General Actions and Pattern Expressions”. Because the result of this -assignment is calculated in the middle of the instruction disassembly, -the change in value of the context variable can potentially affect any -remaining parsing for that instruction. A modal variable is being -added to what was otherwise a stateless grammar, a common technique in -many practical parsing engines. -

-

-Any assignment statement changing a context variable is immediately -executed upon the successful match of the constructor containing the -statement and can be used to guide the parsing of the constructor's -operands. We introduce two more instructions to the example -specification from the previous section. -

-
-:raddi Reg1,#imm is op=2 & Reg1 & imm [ mode=0; ] {
-    Reg1 = Reg1 + imm;
-}
-:saddi Reg1,#imm is op=3 & Reg1 & imm [ mode=1; ] {
-    Reg1 = Reg1 + imm;
-}
-
-

-

-

-Notice that both new constructors modify the context -variable mode. The raddi instruction sets mode to -0 and effectively guarantees that an r register -will be produced by the disassembly. Similarly, -the saddi instruction can force -an s register. Both are in contrast to -the addi instruction, which depends on a global -state. The changes to mode made by these -instructions only persist for parsing of that single instruction. For -any following instructions, if the matching constructors -use mode, its value will have reverted to its -original global state. The same holds for any context variable -modified with this syntax. If an instruction needs to permanently -modify the state of a context variable, the designer must use -constructions described in Section 8.3, “Global Context Change”. -

-

-Clearly, the behavior of the above example could be easily replicated -without using context variables at all and having the selection of a -register set simply depend directly on the op -field. But, with more complicated addressing modes, local modification -of context variables can drastically reduce the complexity and size of -a specification. -

-

-At the point where a modification is made to a context variable, the -specification designer has the guarantee that none of the operands of -the constructor have been evaluated yet, so if their matching depends -on this context variable, they will be affected by the change. In -contrast, the matching of any ancestor constructor cannot be -affected. Other constructors, which are not direct ancestors or -descendants, may or may not be affected by the change, depending on -the order of evaluation. It is usually best not to depend on this -ordering when designing the specification, with the possible exception -of orderings which are guaranteed -by build directives. -

-
-
-

-8.3. Global Context Change

-

-It is possible for an instruction to attempt a permanent change to a -context variable, which would then affect the parsing of other -instructions, by using the globalset -directive in a disassembly action. As mentioned in the previous -section, context variables have an associated global state, which can -be used during constructor matching. A complete model for this state -is, unfortunately, outside the scope of SLEIGH. The disassembly engine -has to make too many decisions about what is getting disassembled and -what assumptions are being made to give complete control of the -context to SLEIGH. Because of this caveat, SLEIGH syntax for making -permanent context changes should be viewed as a suggestion to the -disassembly engine. -

-

-For processors that support multiple modes, there are typically -specific instructions that switch between these modes. Extending the -example from the previous sections, we add two instructions to the -specification for permanently switching which register set is being -used. -

-
-:rmode is op=32 & rreg1=0 & imm=0
-       [ mode=0; globalset(inst_next,mode); ]
-{}
-:smode is op=33 & rreg1=0 & imm=0
-       [ mode=1; globalset(inst_next,mode); ]
-{}
-
-

-

-

-The register set is, as before, controlled by -the mode variable, and as with a local change to -context, the variable is assigned to inside the square -brackets. The rmode instruction -sets mode to 0, in order to -select r registers -via rreg1, and smode -sets mode to 1 in order to -select s registers. As is described in -Section 8.2, “Local Context Change”, these assignments by themselves -cause only a local context change. However, the -subsequent globalset directives make -the change persist outside of the the instructions -themselves. The globalset directive -takes two parameters, the second being the particular context variable -being changed. The first parameter indicates the first address where -the new context takes effect. In the example, the expectation is that -a mode change affects any subsequent instructions. So the first -parameter to globalset here -is inst_next, indicating that the new value -of mode begins at the next address. -

-
-

-8.3.1. Context Flow

-

-A global change to context that affects instruction decoding is typically -open-ended. I.e. once the mode switching instruction is executed, a permanent change -is made to the run-time processor state, and all future instruction decoding is -affected, until another mode switch is encountered. In terms of SLEIGH by default, -the effect of a globalset directive -follows flow. Starting from the address specified in the directive, -the change in context follows the control-flow of the instructions, through -branches and calls, until an execution path terminates or another context change -is encountered. -

-

-Flow following behavior can be overridden by adding the noflow -attribute to the definition of the context field. (See Section 6.4, “Context Variables”) -In this case, a globalset directive only affects the context -of a single instruction at the specified address. Subsequent instructions -retain their original context. This can be useful in a variety of situations but is typically -used to let one instruction alter the behavior, not necessarily the decoding, -of the following instruction. In the example below, -an indirect branch instruction jumps through a link register lr. If the previous -instruction moves the program counter in to lr, it communicates this to the -branch instruction through the LRset context variable so that the branch can -be interpreted as a return, rather than a generic indirect branch. -

-
-define context contextreg
-  LRset = (1,1) noflow  # 1 if the instruction before was a mov lr,pc
-;
-  ...
-mov lr,pc  is opcode=34 & lr & pc
-           [ LRset=1; globalset(inst_next,LRset); ] { lr = pc; }
-  ...
-blr        is opcode=35 & reg=15 & LRset=0 { goto [lr]; }
-blr        is opcode=35 & reg=15 & LRset=1 { return [lr]; }
-
-

-

-

-An alternative to the noflow attribute is to simply issue -multiple directives within a single constructor, so an explicit end to a context change -can be given. The value of the variable exported to the global state -is the one in effect at the point where the directive is issued. Thus, -after one globalset, the same context -variable can be assigned a different value, followed by -another globalset for a different -address. -

-

-Because context in SLEIGH is controlled by a disassembly process, -there are some basic caveats to the use of -the globalset directive. With -flowing context changes, -there is no guarantee of what global state will be in effect at a -particular address. During disassembly, at any given -point, the process may not have uncovered all the relevant directives, -and the known directives may not necessarily be consistent. In -general, for most processors, the disassembly at a particular address -is intended to be absolute. So given enough information, it should be -possible to make a definitive determination of what the context is at -a certain address, but there is no guarantee. It is up to the -disassembly process to fully determine where context changes begin and -end and what to do if there are conflicts. -

-
-
-
-
-
- - - - - - - - - - - -
-Prev   Next -
7. Constructors Home 9. P-code Tables
-
- - diff --git a/sources/GhidraDocs/languages/html/sleigh_context.md b/sources/GhidraDocs/languages/html/sleigh_context.md deleted file mode 100644 index 5bc68fb..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_context.md +++ /dev/null @@ -1,379 +0,0 @@ ---- -status: collected -title: 8. Using Context -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_context.html ---- - -::: {.navheader} -8. Using Context -::: - -[Prev](sleigh_constructors.html)  - -  - - [Next](sleigh_ref.html) - ------------------------------------------------------------------------- - -::: {.sect1} -::: {.titlepage} -
- -
- -[]{#sleigh_context}8. Using Context {#using-context .title style="clear: both"} ------------------------------------ - -
- -
-::: - -For most practical specifications, the disassembly and semantic meaning -of an instruction can be determined by looking only at the bits in the -encoding of that instruction. SLEIGH syntax reflects this fact as every -constructor or attached register is ultimately decided by examining -[*fields*]{.emphasis}, the syntactic representation of these instruction -bits. In some cases however, the instruction encoding itself may not be -enough. Additional information, which we refer to as -[*context*]{.emphasis}, may be necessary to fully resolve the meaning of -the instruction. - -In truth, almost every modern processor has multiple modes of operation, -where the exact interpretation of instructions may depend on that mode. -Typical examples include distinguishing between a 16-bit mode and a -32-bit mode, or between a big endian mode or a little endian mode. But -for the specification designer, these are of little consequence because -most software for such a processor will run in only one mode without -ever changing it. The designer need only pick the most popular or most -important mode for his projects and design to that. If there is in fact -software that runs under a different mode, the other mode can be -described in a separate specification. - -However, for certain processors or software, the need to distinguish -between different interpretations of the same instruction encoding, -based on context, may be a crucial part of the disassembly and analysis -process. There are two typical situations where this becomes necessary. - -::: {.informalexample} -::: {.itemizedlist} -- The processor supports two (or more) separate instruction sets. The - set to use is usually determined by special bits in a status - register, and a single piece of software frequently switches between - these modes. -- The processor supports instructions that temporarily affect the - execution of the immediately following instruction(s). For example, - many processors support hardware [*loop*]{.emphasis} instructions - that automatically cause the following instructions to repeat - without an explicit instruction causing the branching and loop - counting. -::: -::: - -SLEIGH solves these problems by introducing [*context -variables*]{.emphasis}. The syntax for defining these symbols was -described in [Section 6.4, "Context -Variables"](sleigh_tokens.html#sleigh_context_variables "6.4. Context Variables"){.xref}. -As mentioned there, the easiest and most common way to use a context -variable is as just another field to use in our bit patterns. It gives -us the extra information we need to distinguish between different -instructions whose encodings are otherwise the same. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_context_basic}8.1. Basic Use of Context Variables {#basic-use-of-context-variables .title} - -
- -
-::: - -Suppose a processor supports the use of two different sets of registers -in its main addressing mode, based on the setting of a status bit which -can be changed dynamically. If an instruction is executed with this bit -cleared, then one set of registers is used, and if the bit is set, the -other registers are used. The instructions otherwise behave identically. - -::: {.informalexample} -``` -define endian=big; -define space ram type=ram_space size=4 default; -define space register type=register_space size=4; -define register offset=0 size=4 [ r0 r1 r2 r3 r4 r5 r6 r7 ]; -define register offset=0x100 size=4 [ s0 s1 s2 s3 s4 s5 s6 s7 ]; -define register offset=0x200 size=4 [ statusreg ]; # define context bits (if defined, size must be multiple of 4-bytes) - -define token instr(16) - op=(10,15) rreg1=(7,9) sreg1=(7,9) imm=(0,6) -; -define context statusreg - mode=(3,3) -; -attach variables [ rreg1 ] [ r0 r1 r2 r3 r4 r5 r6 r7 ]; -attach variables [ sreg1 ] [ s0 s1 s2 s3 s4 s5 s6 s7 ]; - -Reg1: rreg1 is mode=0 & rreg1 { export rreg1; } -Reg1: sreg1 is mode=1 & sreg1 { export sreg1; } - -:addi Reg1,#imm is op=1 & Reg1 & imm { Reg1 = Reg1 + imm; } -``` -::: - -In this example the symbol [*Reg1*]{.emphasis} uses the 3 bits (7,9) to -select one of eight registers. If the context variable -[*mode*]{.emphasis} is set to 0, it selects an [*r*]{.emphasis} -register, through the [*rreg1*]{.emphasis} field. If [*mode*]{.emphasis} -is set to 1 on the other hand, an [*s*]{.emphasis} register is selected -instead via [*sreg1*]{.emphasis}. The [*addi*]{.emphasis} instruction -(encoded as 0x0590 for example) can disassemble in one of two ways. - -::: {.informalexample} -``` -addi r3,#0x10 OR -addi s3,#0x10 -``` -::: - -This is the same behavior as if [*mode*]{.emphasis} were defined as a -field instead of a context variable, except that there is nothing in the -instruction encoding itself which indicates which of the two forms will -be chosen. An engine doing the disassembly will have global state -associated with the [*mode*]{.emphasis} variable that will make the -final decision about which form to generate. The setting of this state -is (at least partially) out of the control of SLEIGH, although see the -following sections. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_local_change}8.2. Local Context Change {#local-context-change .title} - -
- -
-::: - -SLEIGH can make direct modifications to context variables through -statements in the disassembly action section of a constructor. The -left-hand side of an assignment statement in this section can be a -context variable, see [Section 7.5.2, "General Actions and Pattern -Expressions"](sleigh_constructors.html#sleigh_general_actions "7.5.2. General Actions and Pattern Expressions"){.xref}. -Because the result of this assignment is calculated in the middle of the -instruction disassembly, the change in value of the context variable can -potentially affect any remaining parsing for that instruction. A modal -variable is being added to what was otherwise a stateless grammar, a -common technique in many practical parsing engines. - -Any assignment statement changing a context variable is immediately -executed upon the successful match of the constructor containing the -statement and can be used to guide the parsing of the constructor\'s -operands. We introduce two more instructions to the example -specification from the previous section. - -::: {.informalexample} -``` -:raddi Reg1,#imm is op=2 & Reg1 & imm [ mode=0; ] { - Reg1 = Reg1 + imm; -} -:saddi Reg1,#imm is op=3 & Reg1 & imm [ mode=1; ] { - Reg1 = Reg1 + imm; -} -``` -::: - -Notice that both new constructors modify the context variable -[*mode*]{.emphasis}. The raddi instruction sets mode to 0 and -effectively guarantees that an [*r*]{.emphasis} register will be -produced by the disassembly. Similarly, the [*saddi*]{.emphasis} -instruction can force an [*s*]{.emphasis} register. Both are in contrast -to the [*addi*]{.emphasis} instruction, which depends on a global state. -The changes to [*mode*]{.emphasis} made by these instructions only -persist for parsing of that single instruction. For any following -instructions, if the matching constructors use [*mode*]{.emphasis}, its -value will have reverted to its original global state. The same holds -for any context variable modified with this syntax. If an instruction -needs to permanently modify the state of a context variable, the -designer must use constructions described in [Section 8.3, "Global -Context -Change"](sleigh_context.html#sleigh_global_change "8.3. Global Context Change"){.xref}. - -Clearly, the behavior of the above example could be easily replicated -without using context variables at all and having the selection of a -register set simply depend directly on the [*op*]{.emphasis} field. But, -with more complicated addressing modes, local modification of context -variables can drastically reduce the complexity and size of a -specification. - -At the point where a modification is made to a context variable, the -specification designer has the guarantee that none of the operands of -the constructor have been evaluated yet, so if their matching depends on -this context variable, they will be affected by the change. In contrast, -the matching of any ancestor constructor cannot be affected. Other -constructors, which are not direct ancestors or descendants, may or may -not be affected by the change, depending on the order of evaluation. It -is usually best not to depend on this ordering when designing the -specification, with the possible exception of orderings which are -guaranteed by [**build**]{.bold} directives. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_global_change}8.3. Global Context Change {#global-context-change .title} - -
- -
-::: - -It is possible for an instruction to attempt a permanent change to a -context variable, which would then affect the parsing of other -instructions, by using the [**globalset**]{.bold} directive in a -disassembly action. As mentioned in the previous section, context -variables have an associated global state, which can be used during -constructor matching. A complete model for this state is, unfortunately, -outside the scope of SLEIGH. The disassembly engine has to make too many -decisions about what is getting disassembled and what assumptions are -being made to give complete control of the context to SLEIGH. Because of -this caveat, SLEIGH syntax for making permanent context changes should -be viewed as a suggestion to the disassembly engine. - -For processors that support multiple modes, there are typically specific -instructions that switch between these modes. Extending the example from -the previous sections, we add two instructions to the specification for -permanently switching which register set is being used. - -::: {.informalexample} -``` -:rmode is op=32 & rreg1=0 & imm=0 - [ mode=0; globalset(inst_next,mode); ] -{} -:smode is op=33 & rreg1=0 & imm=0 - [ mode=1; globalset(inst_next,mode); ] -{} -``` -::: - -The register set is, as before, controlled by the [*mode*]{.emphasis} -variable, and as with a local change to context, the variable is -assigned to inside the square brackets. The [*rmode*]{.emphasis} -instruction sets [*mode*]{.emphasis} to 0, in order to select -[*r*]{.emphasis} registers via [*rreg1*]{.emphasis}, and -[*smode*]{.emphasis} sets [*mode*]{.emphasis} to 1 in order to select -[*s*]{.emphasis} registers. As is described in [Section 8.2, "Local -Context -Change"](sleigh_context.html#sleigh_local_change "8.2. Local Context Change"){.xref}, -these assignments by themselves cause only a local context change. -However, the subsequent [**globalset**]{.bold} directives make the -change persist outside of the the instructions themselves. The -[**globalset**]{.bold} directive takes two parameters, the second being -the particular context variable being changed. The first parameter -indicates the first address where the new context takes effect. In the -example, the expectation is that a mode change affects any subsequent -instructions. So the first parameter to [**globalset**]{.bold} here is -[*inst\_next*]{.emphasis}, indicating that the new value of -[*mode*]{.emphasis} begins at the next address. - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_contextflow}8.3.1. Context Flow {#context-flow .title} - -
- -
-::: - -A global change to context that affects instruction decoding is -typically open-ended. I.e. once the mode switching instruction is -executed, a permanent change is made to the run-time processor state, -and all future instruction decoding is affected, until another mode -switch is encountered. In terms of SLEIGH by default, the effect of a -[**globalset**]{.bold} directive follows [*flow*]{.emphasis}. Starting -from the address specified in the directive, the change in context -follows the control-flow of the instructions, through branches and -calls, until an execution path terminates or another context change is -encountered. - -Flow following behavior can be overridden by adding the -[**noflow**]{.bold} attribute to the definition of the context field. -(See [Section 6.4, "Context -Variables"](sleigh_tokens.html#sleigh_context_variables "6.4. Context Variables"){.xref}) -In this case, a [**globalset**]{.bold} directive only affects the -context of a single instruction at the specified address. Subsequent -instructions retain their original context. This can be useful in a -variety of situations but is typically used to let one instruction alter -the behavior, not necessarily the decoding, of the following -instruction. In the example below, an indirect branch instruction jumps -through a link register [*lr*]{.emphasis}. If the previous instruction -moves the program counter in to [*lr*]{.emphasis}, it communicates this -to the branch instruction through the [*LRset*]{.emphasis} context -variable so that the branch can be interpreted as a return, rather than -a generic indirect branch. - -::: {.informalexample} -``` -define context contextreg - LRset = (1,1) noflow # 1 if the instruction before was a mov lr,pc -; - ... -mov lr,pc is opcode=34 & lr & pc - [ LRset=1; globalset(inst_next,LRset); ] { lr = pc; } - ... -blr is opcode=35 & reg=15 & LRset=0 { goto [lr]; } -blr is opcode=35 & reg=15 & LRset=1 { return [lr]; } -``` -::: - -An alternative to the [**noflow**]{.bold} attribute is to simply issue -multiple directives within a single constructor, so an explicit end to a -context change can be given. The value of the variable exported to the -global state is the one in effect at the point where the directive is -issued. Thus, after one [**globalset**]{.bold}, the same context -variable can be assigned a different value, followed by another -[**globalset**]{.bold} for a different address. - -Because context in SLEIGH is controlled by a disassembly process, there -are some basic caveats to the use of the [**globalset**]{.bold} -directive. With [*flowing*]{.emphasis} context changes, there is no -guarantee of what global state will be in effect at a particular -address. During disassembly, at any given point, the process may not -have uncovered all the relevant directives, and the known directives may -not necessarily be consistent. In general, for most processors, the -disassembly at a particular address is intended to be absolute. So given -enough information, it should be possible to make a definitive -determination of what the context is at a certain address, but there is -no guarantee. It is up to the disassembly process to fully determine -where context changes begin and end and what to do if there are -conflicts. -::: -::: -::: - -::: {.navfooter} - ------------------------------------------------------------------------- - - ----------------------------------- --------------------- -------------------------- - [Prev](sleigh_constructors.html)     [Next](sleigh_ref.html) - 7. Constructors  [Home](sleigh.html)  9. P-code Tables - ----------------------------------- --------------------- -------------------------- -::: diff --git a/sources/GhidraDocs/languages/html/sleigh_definitions.html b/sources/GhidraDocs/languages/html/sleigh_definitions.html deleted file mode 100644 index 1b615ac..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_definitions.html +++ /dev/null @@ -1,354 +0,0 @@ - - - -4. Basic Definitions - - - - - - - - - -
- - - - - - - -
4. Basic Definitions
-Prev   Next -
-
-
-
-

-4. Basic Definitions

-

-SLEIGH files must start with all the definitions needed by the rest of -the specification. All definition statements start with the keyword -define and end with a semicolon ‘;’. -

-
-

-4.1. Endianness Definition

-

-The first definition in any SLEIGH specification must be for endianness. Either -

-
-define endian=big;            OR
-define endian=little;
-
-

-This defines how the processor interprets contiguous sequences of -bytes as integers or other values and globally affects values across -all address spaces. It also affects how integer fields -within an instruction are interpreted, (see Section 6.1, “Defining Tokens and Fields”), -although it is possible to override this setting in the rare case that endianness is -different for data versus instruction encoding. -The specification designer generally only needs to worry about -endianness when labeling instruction fields and when defining overlapping registers, -otherwise the specification language hides endianness issues. -

-
-
-

-4.2. Alignment Definition

-

-An alignment definition looks like -

-
-define alignment=integer;
-
-

-This specifies the byte alignment of instructions within their address -space. It defaults to 1 or no alignment. When disassembling an -instruction at a particular, the disassembler checks the alignment of -the address against this value and can opt to flag an unaligned -instruction as an error. -

-
-
-

-4.3. Space Definitions

-

-The definition of an address space looks like -

-
-define space spacename attributes ;
-
-

-The spacename is the name of the new space, -and attributes looks like zero or more of the -following lines: -

-
-type=(ram_space|rom_space|register_space)
-size=integer
-default
-wordsize=integer
-
-

-The only required attribute is size -which specifies the number of bytes needed to address any byte within -the space, for example a 32-bit address space has size 4. -

-

-A space of type ram_space is defined as follows: -

-
    -
  • - It is read/write. -
    • -
  • - It is part of the standard memory map of the processor. -
    • -
  • - It is addressable in the sense that the processor may load -and store from dynamic pointers into the space. -
    • -
-

-

-

-A space of type register_space is -intended to model the processor’s general-purpose registers. In terms -of accessing and manipulating data within the space, SLEIGH and p-code -make no distinction between the -type ram_space or the -type register_space. But there are -still some distinguishing properties of a space labeled -with register_space. -

-
    -
  • - It is read/write. -
    • -
  • - It is not part of the standard memory map of the processor. -
    • -
  • - In terms of GHIDRA, there will not be separate windows for - the space and references into the space will not be stored. -
    • -
  • - Named symbols within the space will have Register objects - associated with them in GHIDRA. -
    • -
  • - It is not addressable. Data-flow - analysis will assume that data within the space cannot be - manipulated indirectly via pointer, so there is no pointer - aliasing. Make sure this is true! -
    • -
-

-

-

-A space of type rom_space has seen -little use so far but is intended to be the same as -a ram_space that is not writable. -

-

-At least one space needs to be labeled with -the default attribute. This should be -the space that the processor accesses with its main address bus. In -terms of the rest of the specification file, this sets the default -space referred to by the ‘*’ operator (see -Section 7.7.1.2, “The '*' Operator”). It also has meaning to -GHIDRA. -

-

-The average 32-bit processor requires only the following two space definitions. -

-
-define space ram type=ram_space size=4 default;
-define space register type=register_space size=4;
-
-

-The wordsize attribute can be used to -specify the size of the memory location referred to with a single -address. If a space has wordsize two, -then each address of the space refers to 16 bits of data, rather than -8 bits. If the space has size two, -then there are still 216 different -addresses, but since each address accesses two bytes, there are twice -as many bytes, 217, in the space. If -the wordsize attribute is not -specified, the size of a memory location defaults to one byte (8 -bits). -

-
-
-

-4.4. Naming Registers

-

-The general purpose registers of the processors can be named with the -following define syntax: -

-
-define spacename offset=integer size=integer stringlist ;
-
-

-A stringlist is either a single string or a white -space separated list of strings in square brackets ‘[’ and ‘]’. A -string of just “_” indicates a skip in the sequence for that -definition. The offset corresponding to that position in the list of -names will not have a varnode defined at it. -

-

-This defines specific varnodes within the indicated address -space. Each name in the list is assigned to a varnode in turn starting -at the indicated offset within the space. Each varnode occupies the -indicated number of bytes in size. There is no restriction on size, -and by reusing the same offset in -different define statements, -overlapping varnodes are allowed. This is most often used to give -registers their standard names but could be used to label any semantic -variable that might need to be accessed globally by the -processor. Overlapping register sequences like the x86 EAX/AX/AL can -be easily modeled with overlapping varnode definitions. -

-

-Here is a typical example of register definition: -

-
-define register offset=0 size=4
-    [EAX ECX EDX EBX ESP EBP ESI EDI ];
-define register offset=0 size=2
-    [AX _ CX _ DX _ BX _ SP _ BP _ SI _ DI];
-define register offset=0 size=1
-    [AL AH _ _ CL CH _ _ DL DH _ _ BL BH ];
-
-

-

-
-
-

-4.5. Bit Range Registers

-

-Many processors define registers that either consist of a single bit -or otherwise don't use an integral number of bytes. A recurring -example in many processors is the status register which is further -subdivided into the overflow and result flags for the arithmetic -instructions. These flags are typically have labels like ZF for the -zero flag or CF for the carry flag and can be considered logical -registers contained within the status register. SLEIGH allows -registers to be defined like this using -the define bitrange statement, but -there are some important caveats with its use. A bit register like -this is problematic for the underlying p-code instructions that SLEIGH -models because the smallest object they can manipulate directly is a -byte. In order to manipulate single bits, p-code must use a -combination of bitwise logical, extension, and truncation -operations. So a register defined as a bit range is not really a -varnode as described in Section 1.2, “Varnodes”, but is -really just a signal to the SLEIGH compiler to fill in the proper -operators to simulate the bit manipulation. Using this feature may -greatly increase the complexity of the compiled specification with -little indication within the specification file itself. -

-
-define register offset=0x180 size=4 [ statusreg ];
-define bitrange zf=statusreg[10,1]
-                cf=statusreg[11,1]
-                sf=statusreg[12,1];
-
-

-

-

-A bit range register must be defined on top of another normal -register. In this example, statusreg is defined -first as a 4 byte register, and the bit registers themselves are built -by the following define bitrange -statement. A single bit register definition consists of an identifier -for the register, followed by ‘=’, then the name of the register -containing the bits, and finally a pair of numbers in square -brackets. The first number indicates the lowest significant bit in the -containing register of the bit range, where bit 0 is the least -significant bit. The second number indicates the number of bits in the -new register. Multiple definitions can be included in a -single define bitrange statement, and -the command is finally terminated with a semicolon. In the example, -three new registers are defined on top -of statusreg, each made up of 1 bit. The new -registers zf, cf, -and sf represent the tenth, eleventh, and twelfth -bit of statusreg respectively. -

-

-The syntax for defining a new bit register is consistent with the -pseudo bit range operator, described in -Section 7.7.1.5, “Bit Range Operator”, and the resulting symbol -is really just a placeholder for this operator. Whenever SLEIGH sees -this symbol it generates p-code precisely as if the designer had used -the bit range operator -instead. Section 7.7.1.5, “Bit Range Operator”, provides some -additional details about how p-code is generated, which apply to the -use of bit range registers. -

-

-If a defined bit range happens to fall on byte boundaries, the new -symbol will in fact be a normal varnode, so -the define bitrange statement can be -used as an alternate syntax for defining overlapping registers. -

-
-
-

-4.6. User-Defined Operations

-

-The specification designer can define new p-code operations using -a define pcodeop statement. This -statement automatically reserves an internal form for the new p-code -operation and associates an identifier with it. This identifier can -then be used in semantic expressions (see -Section 7.7.1.8, “User-Defined Operations”). The following example defines a -new p-code operation arctan. -

-
-define pcodeop arctan;
-
-

-

-

-This construction should be used sparingly. The definition does not -specify how the new operation is supposed to actually manipulate data, -and any analysis routines cannot know what the specification designer -intended. The operation will be treated as a black box. It will hold -its place in syntax trees, and the routines will understand how data -flows into and out of it. But, no other analysis will be possible. -

-

-New operations should be defined only after considering the above -points and the general philosophy of p-code. The designer should have -a detailed description of the new operation in mind, even though this -cannot be put in the specification. If it all possible, the operation -should be atomic, with specific inputs and outputs, and with no -side-effects. The most common use of a new operation is to encapsulate -actions that are too esoteric or too complicated to implement. -

-
-
-
-
- - - - - - - - - - - -
-Prev   Next -
3. Preprocessing Home 5. Introduction to Symbols
-
- - diff --git a/sources/GhidraDocs/languages/html/sleigh_definitions.md b/sources/GhidraDocs/languages/html/sleigh_definitions.md deleted file mode 100644 index 811fe16..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_definitions.md +++ /dev/null @@ -1,388 +0,0 @@ ---- -status: collected -title: 4. Basic Definitions -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_definitions.html ---- - -::: {.navheader} -4. Basic Definitions -::: - -[Prev](sleigh_preprocessing.html)  - -  - - [Next](sleigh_symbols.html) - ------------------------------------------------------------------------- - -::: {.sect1} -::: {.titlepage} -
- -
- -[]{#sleigh_definitions}4. Basic Definitions {#basic-definitions .title style="clear: both"} -------------------------------------------- - -
- -
-::: - -SLEIGH files must start with all the definitions needed by the rest of -the specification. All definition statements start with the keyword -[**define**]{.bold} and end with a semicolon ';'. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_endianness_definition}4.1. Endianness Definition {#endianness-definition .title} - -
- -
-::: - -The first definition in any SLEIGH specification must be for endianness. -Either - -::: {.informalexample} -``` -define endian=big; OR -define endian=little; -``` -::: - -This defines how the processor interprets contiguous sequences of bytes -as integers or other values and globally affects values across all -address spaces. It also affects how integer fields within an instruction -are interpreted, (see [Section 6.1, "Defining Tokens and -Fields"](sleigh_tokens.html#sleigh_defining_tokens "6.1. Defining Tokens and Fields"){.xref}), -although it is possible to override this setting in the rare case that -endianness is different for data versus instruction encoding. The -specification designer generally only needs to worry about endianness -when labeling instruction fields and when defining overlapping -registers, otherwise the specification language hides endianness issues. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_alignment_definition}4.2. Alignment Definition {#alignment-definition .title} - -
- -
-::: - -An alignment definition looks like - -::: {.informalexample} -``` -define alignment=integer; -``` -::: - -This specifies the byte alignment of instructions within their address -space. It defaults to 1 or no alignment. When disassembling an -instruction at a particular, the disassembler checks the alignment of -the address against this value and can opt to flag an unaligned -instruction as an error. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_space_definitions}4.3. Space Definitions {#space-definitions .title} - -
- -
-::: - -The definition of an address space looks like - -::: {.informalexample} -``` -define space spacename attributes ; -``` -::: - -The [*spacename*]{.emphasis} is the name of the new space, and -[*attributes*]{.emphasis} looks like zero or more of the following -lines: - -::: {.informalexample} -``` -type=(ram_space|rom_space|register_space) -size=integer -default -wordsize=integer -``` -::: - -The only required attribute is [**size**]{.bold} which specifies the -number of bytes needed to address any byte within the space, for example -a 32-bit address space has size 4. - -A space of type [**ram\_space**]{.bold} is defined as follows: - -::: {.informalexample} -::: {.itemizedlist} -- It is read/write. -- It is part of the standard memory map of the processor. -- It is addressable in the sense that the processor may load and store - from dynamic pointers into the space. -::: -::: - -A space of type [**register\_space**]{.bold} is intended to model the -processor's general-purpose registers. In terms of accessing and -manipulating data within the space, SLEIGH and p-code make no -distinction between the type [**ram\_space**]{.bold} or the type -[**register\_space**]{.bold}. But there are still some distinguishing -properties of a space labeled with [**register\_space**]{.bold}. - -::: {.informalexample} -::: {.itemizedlist} -- It is read/write. -- It is [*not*]{.emphasis} part of the standard memory map of the - processor. -- In terms of GHIDRA, there will not be separate windows for the space - and references into the space will not be stored. -- Named symbols within the space will have Register objects associated - with them in GHIDRA. -- It is [*not*]{.emphasis} addressable. Data-flow analysis will assume - that data within the space cannot be manipulated indirectly via - pointer, so there is no pointer aliasing. Make sure this is true! -::: -::: - -A space of type [**rom\_space**]{.bold} has seen little use so far but -is intended to be the same as a [**ram\_space**]{.bold} that is not -writable. - -At least one space needs to be labeled with the [**default**]{.bold} -attribute. This should be the space that the processor accesses with its -main address bus. In terms of the rest of the specification file, this -sets the default space referred to by the '\*' operator (see -[Section 7.7.1.2, "The \'\*\' -Operator"](sleigh_constructors.html#sleigh_star_operator "7.7.1.2. The '*' Operator"){.xref}). -It also has meaning to GHIDRA. - -The average 32-bit processor requires only the following two space -definitions. - -::: {.informalexample} -``` -define space ram type=ram_space size=4 default; -define space register type=register_space size=4; -``` -::: - -The [**wordsize**]{.bold} attribute can be used to specify the size of -the memory location referred to with a single address. If a space has -[**wordsize**]{.bold} two, then each address of the space refers to 16 -bits of data, rather than 8 bits. If the space has [**size**]{.bold} -two, then there are still 2^16^ different addresses, but since each -address accesses two bytes, there are twice as many bytes, 2^17^, in the -space. If the [**wordsize**]{.bold} attribute is not specified, the size -of a memory location defaults to one byte (8 bits). -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_naming_registers}4.4. Naming Registers {#naming-registers .title} - -
- -
-::: - -The general purpose registers of the processors can be named with the -following define syntax: - -::: {.informalexample} -``` -define spacename offset=integer size=integer stringlist ; -``` -::: - -A [*stringlist*]{.emphasis} is either a single string or a white space -separated list of strings in square brackets '\[' and '\]'. A string of -just "\_" indicates a skip in the sequence for that definition. The -offset corresponding to that position in the list of names will not have -a varnode defined at it. - -This defines specific varnodes within the indicated address space. Each -name in the list is assigned to a varnode in turn starting at the -indicated offset within the space. Each varnode occupies the indicated -number of bytes in size. There is no restriction on size, and by reusing -the same offset in different [**define**]{.bold} statements, overlapping -varnodes are allowed. This is most often used to give registers their -standard names but could be used to label any semantic variable that -might need to be accessed globally by the processor. Overlapping -register sequences like the x86 EAX/AX/AL can be easily modeled with -overlapping varnode definitions. - -Here is a typical example of register definition: - -::: {.informalexample} -``` -define register offset=0 size=4 - [EAX ECX EDX EBX ESP EBP ESI EDI ]; -define register offset=0 size=2 - [AX _ CX _ DX _ BX _ SP _ BP _ SI _ DI]; -define register offset=0 size=1 - [AL AH _ _ CL CH _ _ DL DH _ _ BL BH ]; -``` -::: -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_bitrange_registers}4.5. Bit Range Registers {#bit-range-registers .title} - -
- -
-::: - -Many processors define registers that either consist of a single bit or -otherwise don\'t use an integral number of bytes. A recurring example in -many processors is the status register which is further subdivided into -the overflow and result flags for the arithmetic instructions. These -flags are typically have labels like ZF for the zero flag or CF for the -carry flag and can be considered logical registers contained within the -status register. SLEIGH allows registers to be defined like this using -the [**define bitrange**]{.bold} statement, but there are some important -caveats with its use. A bit register like this is problematic for the -underlying p-code instructions that SLEIGH models because the smallest -object they can manipulate directly is a byte. In order to manipulate -single bits, p-code must use a combination of bitwise logical, -extension, and truncation operations. So a register defined as a bit -range is not really a varnode as described in [Section 1.2, -"Varnodes"](sleigh.html#sleigh_varnodes "1.2. Varnodes"){.xref}, but is -really just a signal to the SLEIGH compiler to fill in the proper -operators to simulate the bit manipulation. Using this feature may -greatly increase the complexity of the compiled specification with -little indication within the specification file itself. - -::: {.informalexample} -``` -define register offset=0x180 size=4 [ statusreg ]; -define bitrange zf=statusreg[10,1] - cf=statusreg[11,1] - sf=statusreg[12,1]; -``` -::: - -A bit range register must be defined on top of another normal register. -In this example, [*statusreg*]{.emphasis} is defined first as a 4 byte -register, and the bit registers themselves are built by the following -[**define bitrange**]{.bold} statement. A single bit register definition -consists of an identifier for the register, followed by '=', then the -name of the register containing the bits, and finally a pair of numbers -in square brackets. The first number indicates the lowest significant -bit in the containing register of the bit range, where bit 0 is the -least significant bit. The second number indicates the number of bits in -the new register. Multiple definitions can be included in a single -[**define bitrange**]{.bold} statement, and the command is finally -terminated with a semicolon. In the example, three new registers are -defined on top of [*statusreg*]{.emphasis}, each made up of 1 bit. The -new registers [*zf*]{.emphasis}, [*cf*]{.emphasis}, and -[*sf*]{.emphasis} represent the tenth, eleventh, and twelfth bit of -[*statusreg*]{.emphasis} respectively. - -The syntax for defining a new bit register is consistent with the pseudo -bit range operator, described in [Section 7.7.1.5, "Bit Range -Operator"](sleigh_constructors.html#sleigh_bitrange_operator "7.7.1.5. Bit Range Operator"){.xref}, -and the resulting symbol is really just a placeholder for this operator. -Whenever SLEIGH sees this symbol it generates p-code precisely as if the -designer had used the bit range operator instead. [Section 7.7.1.5, "Bit -Range -Operator"](sleigh_constructors.html#sleigh_bitrange_operator "7.7.1.5. Bit Range Operator"){.xref}, -provides some additional details about how p-code is generated, which -apply to the use of bit range registers. - -If a defined bit range happens to fall on byte boundaries, the new -symbol will in fact be a normal varnode, so the [**define -bitrange**]{.bold} statement can be used as an alternate syntax for -defining overlapping registers. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_userdefined_operations}4.6. User-Defined Operations {#user-defined-operations .title} - -
- -
-::: - -The specification designer can define new p-code operations using a -[**define pcodeop**]{.bold} statement. This statement automatically -reserves an internal form for the new p-code operation and associates an -identifier with it. This identifier can then be used in semantic -expressions (see [Section 7.7.1.8, "User-Defined -Operations"](sleigh_constructors.html#sleigh_userdef_op "7.7.1.8. User-Defined Operations"){.xref}). -The following example defines a new p-code operation -[*arctan*]{.emphasis}. - -::: {.informalexample} -``` -define pcodeop arctan; -``` -::: - -This construction should be used sparingly. The definition does not -specify how the new operation is supposed to actually manipulate data, -and any analysis routines cannot know what the specification designer -intended. The operation will be treated as a black box. It will hold its -place in syntax trees, and the routines will understand how data flows -into and out of it. But, no other analysis will be possible. - -New operations should be defined only after considering the above points -and the general philosophy of p-code. The designer should have a -detailed description of the new operation in mind, even though this -cannot be put in the specification. If it all possible, the operation -should be atomic, with specific inputs and outputs, and with no -side-effects. The most common use of a new operation is to encapsulate -actions that are too esoteric or too complicated to implement. -::: -::: - -::: {.navfooter} - ------------------------------------------------------------------------- - - ------------------------------------ --------------------- ------------------------------ - [Prev](sleigh_preprocessing.html)     [Next](sleigh_symbols.html) - 3. Preprocessing  [Home](sleigh.html)  5. Introduction to Symbols - ------------------------------------ --------------------- ------------------------------ -::: diff --git a/sources/GhidraDocs/languages/html/sleigh_layout.html b/sources/GhidraDocs/languages/html/sleigh_layout.html deleted file mode 100644 index 2a1497c..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_layout.html +++ /dev/null @@ -1,122 +0,0 @@ - - - -2. Basic Specification Layout - - - - - - - - - -
- - - - - - - -
2. Basic Specification Layout
-Prev   Next -
-
-
-
-

-2. Basic Specification Layout

-

-A SLEIGH specification is typically contained in a single file, -although see Section 3.1, “Including Files”. The file must -follow a specific format as parsed by the SLEIGH compiler. In this -section, we list the basic formatting rules for this file as enforced -by the compiler. -

-
-

-2.1. Comments

-

-Comments start with the ‘#’ character and continue to the end of the -line. Comments can appear anywhere except the display section of a -constructor (see Section 7.3, “The Display Section”) where the ‘#’ character will be -interpreted as something that should be printed in disassembly. -

-
-
-

-2.2. Identifiers

-

-Identifiers are made up of letters a-z, capitals A-Z, digits 0-9 and -the characters ‘.’ and ‘_’. An identifier can use these characters in -any order and for any length, but it must not start with a digit. -

-
-
-

-2.3. Strings

-

-String literals can be used, when specifying names and when specifying -how disassembly should be printed, so that special characters are -treated as literals. Strings are surrounded by the double quote -character ‘”’ and all characters in between lose their special -meaning. -

-
-
-

-2.4. Integers

-

-Integers are specified either in a decimal format or in a standard -C-style hexadecimal format by prepending the -number with “0x”. Alternately, a binary representation of an integer -can be given by prepending the string of '0' and '1' characters with "0b". -

-
-1006789
-0xF5CC5
-0xf5cc5
-0b11110101110011000101
-
-

-Numbers are treated as unsigned -except when used in patterns where they are treated as signed (see -Section 7.4, “The Bit Pattern Section”). The number of bytes used to -encode the integer when specifying the semantics of an instruction is -inferred from other parts of the syntax (see -Section 7.3, “The Display Section”). Otherwise, integers should -be thought of as having arbitrary precision. Currently, SLEIGH stores -integers internally with 64 bits of precision. -

-
-
-

-2.5. White Space

-

-White space characters include space, tab, line-feed, vertical -line-feed, and carriage-return (‘ ‘, ‘\t’, ‘\r’, ‘\v’, -‘\n’). Variations in spacing have no effect on the parsing of the file -except in string literals. -

-
-
-
-
- - - - - - - - - - - -
-Prev   Next -
SLEIGH Home 3. Preprocessing
-
- - diff --git a/sources/GhidraDocs/languages/html/sleigh_layout.md b/sources/GhidraDocs/languages/html/sleigh_layout.md deleted file mode 100644 index 0f4a51d..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_layout.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -status: collected -title: 2. Basic Specification Layout -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_layout.html ---- - -::: {.navheader} -2. Basic Specification Layout -::: - -[Prev](sleigh.html)  - -  - - [Next](sleigh_preprocessing.html) - ------------------------------------------------------------------------- - -::: {.sect1} -::: {.titlepage} -
- -
- -[]{#sleigh_layout}2. Basic Specification Layout {#basic-specification-layout .title style="clear: both"} ------------------------------------------------ - -
- -
-::: - -A SLEIGH specification is typically contained in a single file, although -see [Section 3.1, "Including -Files"](sleigh_preprocessing.html#sleigh_including_files "3.1. Including Files"){.xref}. -The file must follow a specific format as parsed by the SLEIGH compiler. -In this section, we list the basic formatting rules for this file as -enforced by the compiler. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_comments}2.1. Comments {#comments .title} - -
- -
-::: - -Comments start with the '\#' character and continue to the end of the -line. Comments can appear anywhere except the [*display -section*]{.emphasis} of a constructor (see [Section 7.3, "The Display -Section"](sleigh_constructors.html#sleigh_display_section "7.3. The Display Section"){.xref}) -where the '\#' character will be interpreted as something that should be -printed in disassembly. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_identifiers}2.2. Identifiers {#identifiers .title} - -
- -
-::: - -Identifiers are made up of letters a-z, capitals A-Z, digits 0-9 and the -characters '.' and '\_'. An identifier can use these characters in any -order and for any length, but it must not start with a digit. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_strings}2.3. Strings {#strings .title} - -
- -
-::: - -String literals can be used, when specifying names and when specifying -how disassembly should be printed, so that special characters are -treated as literals. Strings are surrounded by the double quote -character '"' and all characters in between lose their special meaning. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_integers}2.4. Integers {#integers .title} - -
- -
-::: - -Integers are specified either in a decimal format or in a standard -[*C-style*]{.emphasis} hexadecimal format by prepending the number with -"0x". Alternately, a binary representation of an integer can be given by -prepending the string of \'0\' and \'1\' characters with \"0b\". - -::: {.informalexample} -``` -1006789 -0xF5CC5 -0xf5cc5 -0b11110101110011000101 -``` -::: - -Numbers are treated as unsigned except when used in patterns where they -are treated as signed (see [Section 7.4, "The Bit Pattern -Section"](sleigh_constructors.html#sleigh_bit_pattern "7.4. The Bit Pattern Section"){.xref}). -The number of bytes used to encode the integer when specifying the -semantics of an instruction is inferred from other parts of the syntax -(see [Section 7.3, "The Display -Section"](sleigh_constructors.html#sleigh_display_section "7.3. The Display Section"){.xref}). -Otherwise, integers should be thought of as having arbitrary precision. -Currently, SLEIGH stores integers internally with 64 bits of precision. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_white_space}2.5. White Space {#white-space .title} - -
- -
-::: - -White space characters include space, tab, line-feed, vertical -line-feed, and carriage-return (' ', '\\t', '\\r', '\\v', '\\n'). -Variations in spacing have no effect on the parsing of the file except -in string literals. -::: -::: - -::: {.navfooter} - ------------------------------------------------------------------------- - - ---------------------- --------------------- ------------------------------------ - [Prev](sleigh.html)     [Next](sleigh_preprocessing.html) - SLEIGH  [Home](sleigh.html)  3. Preprocessing - ---------------------- --------------------- ------------------------------------ -::: diff --git a/sources/GhidraDocs/languages/html/sleigh_preprocessing.html b/sources/GhidraDocs/languages/html/sleigh_preprocessing.html deleted file mode 100644 index 3006f08..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_preprocessing.html +++ /dev/null @@ -1,214 +0,0 @@ - - - -3. Preprocessing - - - - - - - - - -
- - - - - - - -
3. Preprocessing
-Prev   Next -
-
-
-
-

-3. Preprocessing

-

-SLEIGH provides support for simple file inclusion, macros, and other -basic preprocessing functions. These are all invoked with directives -that start with the ‘@’ character, which must be the first character -in the line. -

-
-

-3.1. Including Files

-

-In general a single SLEIGH specification is contained in a single -file, and the compiler is invoked on one file at a time. Multiple -files can be put together for one specification by using -the @include directive. This must -appear at the beginning of the line and is followed by the path name -of the file to be included, enclosed in double quotes. -

-
@include "example.slaspec"
-

-Parsing proceeds as if the entire line is replaced with the contents -of the indicated file. Multiple inclusions are possible, and the -included files can have their -own @include directives. -

-
-
-

-3.2. Preprocessor Macros

-

-SLEIGH allows simple (unparameterized) macro definitions and -expansions. A macro definition occurs on one line and starts with -the @define directive. This is -followed by an identifier for the macro and then a string to which the -macro should expand. The string must either be a proper identifier -itself or surrounded with double quotes. The macro can then be -expanded with typical “$(identifier)” syntax at any other point in the -specification following the definition. -

-
-@define ENDIAN "big"
-  ...
-define endian=$(ENDIAN);
-
-

-This example defines a macro identified as ENDIAN -with the string “big”, and then expands the macro in a later SLEIGH -statement. Macro definitions can also be made from the command line -and in the “.spec” file, allowing multiple specification variations to -be derived from one file. SLEIGH also has -an @undef directive which removes the -definition of a macro from that point on in the file. -

-
@undef ENDIAN
-

-

-
-
-

-3.3. Conditional Compilation

-

-SLEIGH supports several directives that allow conditional inclusion of -parts of a specification, based on the existence of a macro, or its -value. The lines of the specification to be conditionally included are -bounded by one of the @if... -directives described below and at the bottom by -the @endif directive. If the -condition described by the @if... -directive is true, the bounded lines are evaluated as part of the -specification, otherwise they are skipped. Nesting of these directives -is allowed: a -second @if... @endif -pair can occur inside an initial @if -and @endif. -

-
-

-3.3.1. @ifdef and @ifndef

-

-The @ifdef directive is followed by a -macro identifier and evaluates to true if the macro is defined. -The @ifndef directive is similar -except it evaluates to true if the macro identifier -is not defined. -

-
-@ifdef ENDIAN
-define endian=$(ENDIAN);
-@else
-define endian=little;
-@endif
-
-

-This directive can only take a single identifier as an argument, any -other form is flagged as an error. For logically combining a test of -whether a macro is defined with other tests, use -the defined operator in -an @if -or @elif directive (See below). -

-
-
-

-3.3.2. @if

-

-The @if directive is followed by a -boolean expression with macros as the variables and strings as the -constants. Comparisons between macros and strings are currently -limited to string equality or inequality. But individual comparisons -can be combined arbitrarily using parentheses and the boolean -operators ‘&&’, ‘||’, and ‘^^’. These represent a logical -and, a logical or, and -a logical exclusive-or operation respectively. It -is possible to test whether a particular macro is defined within the -boolean expression for an @if -directive, by using the defined -operator. This exists as a keyword and a functional operator only -within a preprocessor boolean -expression. The defined keyword takes -as argument a macro identifier, and it evaluates to true if the macro -is defined. -

-
-@if defined(X_EXTENSION) || (VERSION == "5")
-  ...
-@endif
-
-

-

-
-
-

-3.3.3. @else and @elif

-

-An @else directive splits the lines -bounded by an @if directive and -an @endif directive into two -parts. The first part is included in the processing if the -initial @if directive evaluates to -true, otherwise the second part is included. -

-

-The @elif directive splits the -bounded lines up as with @else, but -the second part is included only if the -previous @if was false and the -condition specified in the @elif -itself is true. Between one @if -and @endif pair, there can be -multiple @elif directives, but only -one @else, which must occur after all -the @elif directives. -

-
-@if PROCESSOR == “mips”
-@ define ENDIAN “big”
-@elif ((PROCESSOR==”x86”)&&(OS!=”win”))
-@ define ENDIAN “little”
-@else
-@ define ENDIAN “unknown”
-@endif
-
-

-

-
-
-
-
-
- - - - - - - - - - - -
-Prev   Next -
2. Basic Specification Layout Home 4. Basic Definitions
-
- - diff --git a/sources/GhidraDocs/languages/html/sleigh_preprocessing.md b/sources/GhidraDocs/languages/html/sleigh_preprocessing.md deleted file mode 100644 index 6354e03..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_preprocessing.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -status: collected -title: 3. Preprocessing -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_preprocessing.html ---- - -::: {.navheader} -3. Preprocessing -::: - -[Prev](sleigh_layout.html)  - -  - - [Next](sleigh_definitions.html) - ------------------------------------------------------------------------- - -::: {.sect1} -::: {.titlepage} -
- -
- -[]{#sleigh_preprocessing}3. Preprocessing {#preprocessing .title style="clear: both"} ------------------------------------------ - -
- -
-::: - -SLEIGH provides support for simple file inclusion, macros, and other -basic preprocessing functions. These are all invoked with directives -that start with the '@' character, which must be the first character in -the line. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_including_files}3.1. Including Files {#including-files .title} - -
- -
-::: - -In general a single SLEIGH specification is contained in a single file, -and the compiler is invoked on one file at a time. Multiple files can be -put together for one specification by using the [**\@include**]{.bold} -directive. This must appear at the beginning of the line and is followed -by the path name of the file to be included, enclosed in double quotes. - -::: {.informalexample} -`@include "example.slaspec"`{.code} -::: - -Parsing proceeds as if the entire line is replaced with the contents of -the indicated file. Multiple inclusions are possible, and the included -files can have their own [**\@include**]{.bold} directives. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_preprocessor_macros}3.2. Preprocessor Macros {#preprocessor-macros .title} - -
- -
-::: - -SLEIGH allows simple (unparameterized) macro definitions and expansions. -A macro definition occurs on one line and starts with the -[**\@define**]{.bold} directive. This is followed by an identifier for -the macro and then a string to which the macro should expand. The string -must either be a proper identifier itself or surrounded with double -quotes. The macro can then be expanded with typical "\$(identifier)" -syntax at any other point in the specification following the definition. - -::: {.informalexample} -``` -@define ENDIAN "big" - ... -define endian=$(ENDIAN); -``` -::: - -This example defines a macro identified as [*ENDIAN*]{.emphasis} with -the string "big", and then expands the macro in a later SLEIGH -statement. Macro definitions can also be made from the command line and -in the ".spec" file, allowing multiple specification variations to be -derived from one file. SLEIGH also has an [**\@undef**]{.bold} directive -which removes the definition of a macro from that point on in the file. - -::: {.informalexample} -`@undef ENDIAN`{.code} -::: -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_conditional_compilation}3.3. Conditional Compilation {#conditional-compilation .title} - -
- -
-::: - -SLEIGH supports several directives that allow conditional inclusion of -parts of a specification, based on the existence of a macro, or its -value. The lines of the specification to be conditionally included are -bounded by one of the [**\@if\...**]{.bold} directives described below -and at the bottom by the [**\@endif**]{.bold} directive. If the -condition described by the [**\@if\...**]{.bold} directive is true, the -bounded lines are evaluated as part of the specification, otherwise they -are skipped. Nesting of these directives is allowed: a second -[**\@if\...**]{.bold} [**\@endif**]{.bold} pair can occur inside an -initial [**\@if**]{.bold} and [**\@endif**]{.bold}. - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_ifdef}3.3.1. \@ifdef and \@ifndef {#ifdef-and-ifndef .title} - -
- -
-::: - -The [**\@ifdef**]{.bold} directive is followed by a macro identifier and -evaluates to true if the macro is defined. The [**\@ifndef**]{.bold} -directive is similar except it evaluates to true if the macro identifier -is [*not*]{.emphasis} defined. - -::: {.informalexample} -``` -@ifdef ENDIAN -define endian=$(ENDIAN); -@else -define endian=little; -@endif -``` -::: - -This directive can only take a single identifier as an argument, any -other form is flagged as an error. For logically combining a test of -whether a macro is defined with other tests, use the -[**defined**]{.bold} operator in an [**\@if**]{.bold} or -[**\@elif**]{.bold} directive (See below). -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_if}3.3.2. \@if {#if .title} - -
- -
-::: - -The [**\@if**]{.bold} directive is followed by a boolean expression with -macros as the variables and strings as the constants. Comparisons -between macros and strings are currently limited to string equality or -inequality. But individual comparisons can be combined arbitrarily using -parentheses and the boolean operators '&&', '\|\|', and '\^\^'. These -represent a [*logical and*]{.emphasis}, a [*logical or*]{.emphasis}, and -a [*logical exclusive-or*]{.emphasis} operation respectively. It is -possible to test whether a particular macro is defined within the -boolean expression for an [**\@if**]{.bold} directive, by using the -[**defined**]{.bold} operator. This exists as a keyword and a functional -operator only within a preprocessor boolean expression. The -[**defined**]{.bold} keyword takes as argument a macro identifier, and -it evaluates to true if the macro is defined. - -::: {.informalexample} -``` -@if defined(X_EXTENSION) || (VERSION == "5") - ... -@endif -``` -::: -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_else}3.3.3. \@else and \@elif {#else-and-elif .title} - -
- -
-::: - -An [**\@else**]{.bold} directive splits the lines bounded by an -[**\@if**]{.bold} directive and an [**\@endif**]{.bold} directive into -two parts. The first part is included in the processing if the initial -[**\@if**]{.bold} directive evaluates to true, otherwise the second part -is included. - -The [**\@elif**]{.bold} directive splits the bounded lines up as with -[**\@else**]{.bold}, but the second part is included only if the -previous [**\@if**]{.bold} was false and the condition specified in the -[**\@elif**]{.bold} itself is true. Between one [**\@if**]{.bold} and -[**\@endif**]{.bold} pair, there can be multiple [**\@elif**]{.bold} -directives, but only one [**\@else**]{.bold}, which must occur after all -the [**\@elif**]{.bold} directives. - -::: {.informalexample} -``` -@if PROCESSOR == “mips” -@ define ENDIAN “big” -@elif ((PROCESSOR==”x86”)&&(OS!=”win”)) -@ define ENDIAN “little” -@else -@ define ENDIAN “unknown” -@endif -``` -::: -::: -::: -::: - -::: {.navfooter} - ------------------------------------------------------------------------- - - -------------------------------- --------------------- ---------------------------------- - [Prev](sleigh_layout.html)     [Next](sleigh_definitions.html) - 2. Basic Specification Layout  [Home](sleigh.html)  4. Basic Definitions - -------------------------------- --------------------- ---------------------------------- -::: diff --git a/sources/GhidraDocs/languages/html/sleigh_ref.html b/sources/GhidraDocs/languages/html/sleigh_ref.html deleted file mode 100644 index b21fc5f..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_ref.html +++ /dev/null @@ -1,607 +0,0 @@ - - - -9. P-code Tables - - - - - - - - -
- - - - - - - -
9. P-code Tables
-Prev   
-
-
-
-

-9. P-code Tables

-

-We list all the p-code operations by name along with the syntax for -invoking them within the semantic section of a constructor definition -(see Section 7.7, “The Semantic Section”), and with a -description of the operator. The terms v0 -and v1 represent identifiers of individual input -varnodes to the operation. In terms of syntax, v0 -and v1 can be replaced with any semantic -expression, in which case the final output varnode of the expression -becomes the input to the operator. The term spc -represents the identifier of an address space, which is a special -input to the LOAD and STORE -operations. The identifier of any address space can be used. -

-

-This table lists all the operators for building semantic -expressions. The operators are listed in order of precedence, highest -to lowest. -

-
-
-

Table 5. Semantic Expression Operators and Syntax

-
---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
P-code NameSLEIGH SyntaxDescription
SUBPIECE -
- - - - - - - -
v0:2
v0(2)
-
- 		The least significant n bytes of v0. - Truncate least significant n bytes of - v0. Most significant bytes may be - truncated depending on result size. -
POPCOUNTpopcount(v0)Count the number of 1 bits in v0. -
LZCOUNTlzcount(v0)Count the number of leading 0 bits in v0. -
(simulated)v0[6,1]Extract a range of bits from v0, - putting result in a minimum number of - bytes. The bracketed numbers give - respectively, the least significant - bit and the number of bits in the - range. -
LOAD -
- - - - - - - - - - - - - -
* v1
*[spc]v1
*:2 v1
*[spc]:2 v1
-
- 		Dereference v1 as pointer into - default space. Optionally specify - space to load from and size of data - in bytes. -
BOOL_NEGATE!v0Negation of boolean value v0.
INT_NEGATE~v0Bitwise negation of v0.
INT_2COMP-v0Twos complement of v0.
FLOAT_NEGf- v0Additive inverse of v0 as a floating-point number.
INT_MULTv0 * v1Integer multiplication of v0 and v1.
INT_DIVv0 / v1Unsigned division of v0 by v1.
INT_SDIVv0 s/ v1Signed division of v0 by v1.
INT_REMv0 % v1Unsigned remainder of v0 modulo v1.
INT_SREMv0 s% v1Signed remainder of v0 modulo v1.
FLOAT_DIVv0 f/ v1Division of v0 by v1 as floating-point numbers.
FLOAT_MULTv0 f* v1Multiplication of v0 and v1 as floating-point numbers.
INT_ADDv0 + v1Addition of v0 and v1 as integers.
INT_SUBv0 - v1Subtraction of v1 from v0 as integers.
FLOAT_ADDv0 f+ v1Addition of v0 and v1 as floating-point numbers.
FLOAT_SUBv0 f- v1Subtraction of v1 from v0 as floating-point numbers.
INT_LEFTv0 << v1Left shift of v0 by v1 bits.
INT_RIGHTv0 >> v1Unsigned (logical) right shift of v0 by v1 bits.
INT_SRIGHTv0 s>> v1Signed (arithmetic) right shift of v0 by b1 bits.
INT_SLESS -
- - - - - - - -
v0 s< v1
v1 s> v0
-
- 		True if v0 is less than v1 as a signed integer.
INT_SLESSEQUAL -
- - - - - - - -
v0 s<= v1
v1 s>= v0
-
- 		True if v0 is less than or equal to v1 as a signed integer.
INT_LESS -
- - - - - - - -
v0 < v1
v1 > v0
-
- 		True if v0 is less than v1 as an unsigned integer.
INT_LESSEQUAL -
- - - - - - - -
v0 <= v1
v1 >= v0
-
- 		True if v0 is less than or equal to v1 as an unsigned integer.
FLOAT_LESS -
- - - - - - - -
v0 f< v1
v1 f> v0
-
- 		True if v0 is less than v1 viewed as floating-point numbers.
FLOAT_LESSEQUAL -
- - - - - - - -
v0 f<= v1
v1 f>= v0
-
- 		True if v0 is less than or equal to v1 as floating-point.
INT_EQUALv0 == v1True if v0 equals v1.
INT_NOTEQUALv0 != v1True if v0 does not equal v1.
FLOAT_EQUALv0 f== v1True if v0 equals v1 viewed as floating-point numbers.
FLOAT_NOTEQUALv0 f!= v1True if v0 does not equal v1 viewed as floating-point numbers.
INT_ANDv0 & v1Bitwise Logical And of v0 with v1.
INT_XORv0 ^ v1Bitwise Exclusive Or of v0 with v1.
INT_ORv0 | v1Bitwise Logical Or of v0 with v1.
BOOL_XORv0 ^^ v1Exclusive-Or of booleans v0 and v1.
BOOL_ANDv0 && v1Logical-And of booleans v0 and v1.
BOOL_ORv0 || v1Logical-Or of booleans v0 and v1.
INT_ZEXTzext(v0)Zero extension of v0.
INT_SEXTsext(v0)Sign extension of v0.
INT_CARRYcarry(v0,v1)True if adding v0 and v1 would produce an unsigned carry.
INT_SCARRYscarry(v0,v1)True if adding v0 and v1 would produce a signed carry.
INT_SBORROWsborrow(v0,v1)True if subtracting v1 from v0 would produce a signed borrow.
FLOAT_NANnan(v0)True if v0 is not a valid floating-point number (NaN).
FLOAT_ABSabs(v0)Absolute value of v0 as floating point number.
FLOAT_SQRTsqrt(v0)Square root of v0 as floating-point number.
INT2FLOATint2float(v0)Floating-point representation of v0 viewed as an integer.
FLOAT2FLOATfloat2float(v0)Copy of floating-point number v0 with more or less precision.
TRUNCtrunc(v0)Signed integer obtained by truncating v0.
FLOAT_CEILceil(v0)Nearest integer greater than v0.
FLOAT_FLOORfloor(v0)Nearest integer less than v0.
FLOAT_ROUNDround(v0)Nearest integer to v0.
CPOOLREFcpool(v0,...)Access value from the constant pool.
NEWnewobject(v0)Allocate object of type described by v0.
USER_DEFINEDident(v0,...)User defined operator ident, with functional syntax.
-
-
-
-

-

-

-The following table lists the basic forms of a semantic statement. -

-
-
-

Table 6. Basic Statements and Associated Operators

-
---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
P-code NameSLEIGH SyntaxDescription
COPY, otherv0 = v1;Assignment of v1 to v0.
STORE -
- - - - - - - - - - - - - -
*v0 = v1
*[spc]v0 = v1;
*:4 v0 = v1;
*[spc]:4 v0 = v1;
-
- 		Store v1 in default space using v0 - As pointer. Optionally specify space - to store in and size of data in - bytes. -
USER_DEFINEDident(v0,...);Invoke user-defined operation ident as a standalone statement, with no output.
v0[8,1] = v1;Fill a bit range within v0 using v1, leaving the rest of v0 unchanged.
ident(v0,...);Invoke the macro named ident.
build ident;Execute the p-code to build operand ident.
delayslot(1);Execute the p-code for the following instruction.
-
-
-
-

-

-

-The following table lists the branching operations and the statements which invoke them. -

-
-
-

Table 7. Branching Statements

-
---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
P-code NameSLEIGH SyntaxDescription
BRANCHgoto v0;Branch execution to address of v0.
CBRANCHif (v0) goto v1;Branch execution to address of v1 if v0 equals 1 (true).
BRANCHINDgoto [v0];Branch execution to v0 viewed as an offset in current space.
CALLcall v0;Branch execution to address of v0. Hint that branch is subroutine call.
CALLINDcall [v0];Branch execution to v0 viewed as an offset in current space. Hint that branch is subroutine call.
RETURNreturn [v0];Branch execution to v0 viewed as an offset in current space. Hint that branch is a subroutine return.
-
-
-
-

-

-
-
-
- - - - - - - - - - - -
-Prev   
8. Using Context Home 
-
- - diff --git a/sources/GhidraDocs/languages/html/sleigh_ref.md b/sources/GhidraDocs/languages/html/sleigh_ref.md deleted file mode 100644 index 1ccac10..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_ref.md +++ /dev/null @@ -1,450 +0,0 @@ ---- -status: collected -title: 9. P-code Tables -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_ref.html ---- - -::: {.navheader} -9. P-code Tables -::: - -[Prev](sleigh_context.html)  - -  - -  - ------------------------------------------------------------------------- - -::: {.sect1} -::: {.titlepage} -
- -
- -[]{#sleigh_ref}9. P-code Tables {#p-code-tables .title style="clear: both"} -------------------------------- - -
- -
-::: - -We list all the p-code operations by name along with the syntax for -invoking them within the semantic section of a constructor definition -(see [Section 7.7, "The Semantic -Section"](sleigh_constructors.html#sleigh_semantic_section "7.7. The Semantic Section"){.xref}), -and with a description of the operator. The terms [*v0*]{.emphasis} and -[*v1*]{.emphasis} represent identifiers of individual input varnodes to -the operation. In terms of syntax, [*v0*]{.emphasis} and -[*v1*]{.emphasis} can be replaced with any semantic expression, in which -case the final output varnode of the expression becomes the input to the -operator. The term [*spc*]{.emphasis} represents the identifier of an -address space, which is a special input to the [*LOAD*]{.emphasis} and -[*STORE*]{.emphasis} operations. The identifier of any address space can -be used. - -This table lists all the operators for building semantic expressions. -The operators are listed in order of precedence, highest to lowest. - -::: {.informalexample} -::: {.table} -[]{#syntaxref.htmltable} - -**Table 5. Semantic Expression Operators and Syntax** - -::: {.table-contents} -+-----------------+-----------------+-----------------------------------+ -| [**P-code | [**SLEIGH | [**Description**]{.bold} | -| Name**]{.bold} | S | | -| | yntax**]{.bold} | | -+=================+=================+===================================+ -| `S | ::: { | The least significant n bytes of | -| UBPIECE`{.code} | .informaltable} | v0. Truncate least significant n | -| | []{#subpiec | bytes of v0. Most significant | -| | eref.htmltable} | bytes may be truncated depending | -| | | on result size. | -| | - | | -| | --------------- | | -| | `v0:2`{.code} | | -| | | | -| | `v0(2)`{.code} | | -| | - | | -| | --------------- | | -| | ::: | | -+-----------------+-----------------+-----------------------------------+ -| `P | `popco | Count the number of 1 bits in v0. | -| OPCOUNT`{.code} | unt(v0)`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| ` | `lzco | Count the number of leading 0 | -| LZCOUNT`{.code} | unt(v0)`{.code} | bits in v0. | -+-----------------+-----------------+-----------------------------------+ -| `(sim | ` | Extract a range of bits from v0, | -| ulated)`{.code} | v0[6,1]`{.code} | putting result in a minimum | -| | | number of bytes. The bracketed | -| | | numbers give respectively, the | -| | | least significant bit and the | -| | | number of bits in the range. | -+-----------------+-----------------+-----------------------------------+ -| `LOAD`{.code} | ::: { | Dereference v1 as pointer into | -| | .informaltable} | default space. Optionally specify | -| | []{#loa | space to load from and size of | -| | dref.htmltable} | data in bytes. | -| | | | -| | ------- | | -| | --------------- | | -| | `* v1`{.code} | | -| | `* | | -| | [spc]v1`{.code} | | -| | | | -| | `*:2 v1`{.code} | | -| | `*[sp | | -| | c]:2 v1`{.code} | | -| | ------- | | -| | --------------- | | -| | ::: | | -+-----------------+-----------------+-----------------------------------+ -| `BOOL | `!v0`{.code} | Negation of boolean value v0. | -| _NEGATE`{.code} | | | -+-----------------+-----------------+-----------------------------------+ -| `INT | `~v0`{.code} | Bitwise negation of v0. | -| _NEGATE`{.code} | | | -+-----------------+-----------------+-----------------------------------+ -| `IN | `-v0`{.code} | Twos complement of v0. | -| T_2COMP`{.code} | | | -+-----------------+-----------------+-----------------------------------+ -| `FL | `f- v0`{.code} | Additive inverse of v0 as a | -| OAT_NEG`{.code} | | floating-point number. | -+-----------------+-----------------+-----------------------------------+ -| `I | ` | Integer multiplication of v0 and | -| NT_MULT`{.code} | v0 * v1`{.code} | v1. | -+-----------------+-----------------+-----------------------------------+ -| ` | ` | Unsigned division of v0 by v1. | -| INT_DIV`{.code} | v0 / v1`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `I | `v | Signed division of v0 by v1. | -| NT_SDIV`{.code} | 0 s/ v1`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| ` | ` | Unsigned remainder of v0 modulo | -| INT_REM`{.code} | v0 % v1`{.code} | v1. | -+-----------------+-----------------+-----------------------------------+ -| `I | `v | Signed remainder of v0 modulo v1. | -| NT_SREM`{.code} | 0 s% v1`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `FL | `v | Division of v0 by v1 as | -| OAT_DIV`{.code} | 0 f/ v1`{.code} | floating-point numbers. | -+-----------------+-----------------+-----------------------------------+ -| `FLO | `v | Multiplication of v0 and v1 as | -| AT_MULT`{.code} | 0 f* v1`{.code} | floating-point numbers. | -+-----------------+-----------------+-----------------------------------+ -| ` | ` | Addition of v0 and v1 as | -| INT_ADD`{.code} | v0 + v1`{.code} | integers. | -+-----------------+-----------------+-----------------------------------+ -| ` | ` | Subtraction of v1 from v0 as | -| INT_SUB`{.code} | v0 - v1`{.code} | integers. | -+-----------------+-----------------+-----------------------------------+ -| `FL | `v | Addition of v0 and v1 as | -| OAT_ADD`{.code} | 0 f+ v1`{.code} | floating-point numbers. | -+-----------------+-----------------+-----------------------------------+ -| `FL | `v | Subtraction of v1 from v0 as | -| OAT_SUB`{.code} | 0 f- v1`{.code} | floating-point numbers. | -+-----------------+-----------------+-----------------------------------+ -| `I | `v | Left shift of v0 by v1 bits. | -| NT_LEFT`{.code} | 0 << v1`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `IN | `v | Unsigned (logical) right shift of | -| T_RIGHT`{.code} | 0 >> v1`{.code} | v0 by v1 bits. | -+-----------------+-----------------+-----------------------------------+ -| `INT | `v0 | Signed (arithmetic) right shift | -| _SRIGHT`{.code} | s>> v1`{.code} | of v0 by b1 bits. | -+-----------------+-----------------+-----------------------------------+ -| `IN | ::: { | True if v0 is less than v1 as a | -| T_SLESS`{.code} | .informaltable} | signed integer. | -| | []{#sles | | -| | sref.htmltable} | | -| | | | -| | ---- | | -| | --------------- | | -| | `v | | -| | 0 s< v1`{.code} | | -| | `v | | -| | 1 s> v0`{.code} | | -| | ---- | | -| | --------------- | | -| | ::: | | -+-----------------+-----------------+-----------------------------------+ -| `INT_SLE | ::: { | True if v0 is less than or equal | -| SSEQUAL`{.code} | .informaltable} | to v1 as a signed integer. | -| | []{#slessequa | | -| | lref.htmltable} | | -| | | | -| | ----- | | -| | --------------- | | -| | `v0 | | -| | s<= v1`{.code} | | -| | `v1 | | -| | s>= v0`{.code} | | -| | ----- | | -| | --------------- | | -| | ::: | | -+-----------------+-----------------+-----------------------------------+ -| `I | ::: { | True if v0 is less than v1 as an | -| NT_LESS`{.code} | .informaltable} | unsigned integer. | -| | []{#les | | -| | sref.htmltable} | | -| | | | -| | --- | | -| | --------------- | | -| | ` | | -| | v0 < v1`{.code} | | -| | ` | | -| | v1 > v0`{.code} | | -| | --- | | -| | --------------- | | -| | ::: | | -+-----------------+-----------------+-----------------------------------+ -| `INT_LE | ::: { | True if v0 is less than or equal | -| SSEQUAL`{.code} | .informaltable} | to v1 as an unsigned integer. | -| | []{#lessequa | | -| | lref.htmltable} | | -| | | | -| | ---- | | -| | --------------- | | -| | `v | | -| | 0 <= v1`{.code} | | -| | `v | | -| | 1 >= v0`{.code} | | -| | ---- | | -| | --------------- | | -| | ::: | | -+-----------------+-----------------+-----------------------------------+ -| `FLO | ::: { | True if v0 is less than v1 viewed | -| AT_LESS`{.code} | .informaltable} | as floating-point numbers. | -| | []{#fles | | -| | sref.htmltable} | | -| | | | -| | ---- | | -| | --------------- | | -| | `v | | -| | 0 f< v1`{.code} | | -| | `v | | -| | 1 f> v0`{.code} | | -| | ---- | | -| | --------------- | | -| | ::: | | -+-----------------+-----------------+-----------------------------------+ -| `FLOAT_LE | ::: { | True if v0 is less than or equal | -| SSEQUAL`{.code} | .informaltable} | to v1 as floating-point. | -| | []{#flessequa | | -| | lref.htmltable} | | -| | | | -| | ----- | | -| | --------------- | | -| | `v0 | | -| | f<= v1`{.code} | | -| | `v1 | | -| | f>= v0`{.code} | | -| | ----- | | -| | --------------- | | -| | ::: | | -+-----------------+-----------------+-----------------------------------+ -| `IN | `v | True if v0 equals v1. | -| T_EQUAL`{.code} | 0 == v1`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `INT_N | `v | True if v0 does not equal v1. | -| OTEQUAL`{.code} | 0 != v1`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `FLOA | `v0 | True if v0 equals v1 viewed as | -| T_EQUAL`{.code} | f== v1`{.code} | floating-point numbers. | -+-----------------+-----------------+-----------------------------------+ -| `FLOAT_N | `v0 | True if v0 does not equal v1 | -| OTEQUAL`{.code} | f!= v1`{.code} | viewed as floating-point numbers. | -+-----------------+-----------------+-----------------------------------+ -| ` | ` | Bitwise Logical And of v0 with | -| INT_AND`{.code} | v0 & v1`{.code} | v1. | -+-----------------+-----------------+-----------------------------------+ -| ` | ` | Bitwise Exclusive Or of v0 with | -| INT_XOR`{.code} | v0 ^ v1`{.code} | v1. | -+-----------------+-----------------+-----------------------------------+ -| `INT_OR`{.code} | ` | Bitwise Logical Or of v0 with v1. | -| | v0 | v1`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `B | `v | Exclusive-Or of booleans v0 and | -| OOL_XOR`{.code} | 0 ^^ v1`{.code} | v1. | -+-----------------+-----------------+-----------------------------------+ -| `B | `v | Logical-And of booleans v0 and | -| OOL_AND`{.code} | 0 && v1`{.code} | v1. | -+-----------------+-----------------+-----------------------------------+ -| ` | `v | Logical-Or of booleans v0 and v1. | -| BOOL_OR`{.code} | 0 || v1`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `I | `z | Zero extension of v0. | -| NT_ZEXT`{.code} | ext(v0)`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `I | `s | Sign extension of v0. | -| NT_SEXT`{.code} | ext(v0)`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `IN | `carry | True if adding v0 and v1 would | -| T_CARRY`{.code} | (v0,v1)`{.code} | produce an unsigned carry. | -+-----------------+-----------------+-----------------------------------+ -| `INT | `scarry | True if adding v0 and v1 would | -| _SCARRY`{.code} | (v0,v1)`{.code} | produce a signed carry. | -+-----------------+-----------------+-----------------------------------+ -| `INT_ | `sborrow | True if subtracting v1 from v0 | -| SBORROW`{.code} | (v0,v1)`{.code} | would produce a signed borrow. | -+-----------------+-----------------+-----------------------------------+ -| `FL | ` | True if v0 is not a valid | -| OAT_NAN`{.code} | nan(v0)`{.code} | floating-point number (NaN). | -+-----------------+-----------------+-----------------------------------+ -| `FL | ` | Absolute value of v0 as floating | -| OAT_ABS`{.code} | abs(v0)`{.code} | point number. | -+-----------------+-----------------+-----------------------------------+ -| `FLO | `s | Square root of v0 as | -| AT_SQRT`{.code} | qrt(v0)`{.code} | floating-point number. | -+-----------------+-----------------+-----------------------------------+ -| `IN | `int2fl | Floating-point representation of | -| T2FLOAT`{.code} | oat(v0)`{.code} | v0 viewed as an integer. | -+-----------------+-----------------+-----------------------------------+ -| `FLOA | `float2fl | Copy of floating-point number v0 | -| T2FLOAT`{.code} | oat(v0)`{.code} | with more or less precision. | -+-----------------+-----------------+-----------------------------------+ -| `TRUNC`{.code} | `tr | Signed integer obtained by | -| | unc(v0)`{.code} | truncating v0. | -+-----------------+-----------------+-----------------------------------+ -| `FLO | `c | Nearest integer greater than v0. | -| AT_CEIL`{.code} | eil(v0)`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `FLOA | `fl | Nearest integer less than v0. | -| T_FLOOR`{.code} | oor(v0)`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `FLOA | `ro | Nearest integer to v0. | -| T_ROUND`{.code} | und(v0)`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `C | `cpool( | Access value from the constant | -| POOLREF`{.code} | v0,...)`{.code} | pool. | -+-----------------+-----------------+-----------------------------------+ -| `NEW`{.code} | `newobj | Allocate object of type described | -| | ect(v0)`{.code} | by v0. | -+-----------------+-----------------+-----------------------------------+ -| `USER_ | `ident( | User defined operator | -| DEFINED`{.code} | v0,...)`{.code} | [*ident*]{.emphasis}, with | -| | | functional syntax. | -+-----------------+-----------------+-----------------------------------+ -::: -::: - -\ -::: - -The following table lists the basic forms of a semantic statement. - -::: {.informalexample} -::: {.table} -[]{#statementref.htmltable} - -**Table 6. Basic Statements and Associated Operators** - -::: {.table-contents} -+-----------------+-----------------+-----------------------------------+ -| [**P-code | [**SLEIGH | [**Description**]{.bold} | -| Name**]{.bold} | S | | -| | yntax**]{.bold} | | -+=================+=================+===================================+ -| `COPY | `v | Assignment of v1 to v0. | -| , other`{.code} | 0 = v1;`{.code} | | -+-----------------+-----------------+-----------------------------------+ -| `STORE`{.code} | ::: { | Store v1 in default space using | -| | .informaltable} | v0 As pointer. Optionally specify | -| | []{#stor | space to store in and size of | -| | eref.htmltable} | data in bytes. | -| | | | -| | ------------- | | -| | --------------- | | -| | `* | | -| | v0 = v1`{.code} | | -| | `*[spc]v | | -| | 0 = v1;`{.code} | | -| | `*:4 v | | -| | 0 = v1;`{.code} | | -| | `*[spc]:4 v | | -| | 0 = v1;`{.code} | | -| | ------------- | | -| | --------------- | | -| | ::: | | -+-----------------+-----------------+-----------------------------------+ -| `USER_ | `ident(v | Invoke user-defined operation | -| DEFINED`{.code} | 0,...);`{.code} | ident as a standalone statement, | -| | | with no output. | -+-----------------+-----------------+-----------------------------------+ -| | `v0[8,1 | Fill a bit range within v0 using | -| | ] = v1;`{.code} | v1, leaving the rest of v0 | -| | | unchanged. | -+-----------------+-----------------+-----------------------------------+ -| | `ident(v | Invoke the macro named | -| | 0,...);`{.code} | [*ident*]{.emphasis}. | -+-----------------+-----------------+-----------------------------------+ -| | `build | Execute the p-code to build | -| | ident;`{.code} | operand [*ident*]{.emphasis}. | -+-----------------+-----------------+-----------------------------------+ -| | `delays | Execute the p-code for the | -| | lot(1);`{.code} | following instruction. | -+-----------------+-----------------+-----------------------------------+ -::: -::: - -\ -::: - -The following table lists the branching operations and the statements -which invoke them. - -::: {.informalexample} -::: {.table} -[]{#branchref.htmltable} - -**Table 7. Branching Statements** - -::: {.table-contents} - ------------------------------------------------------------------------------------ - [**P-code [**SLEIGH Syntax**]{.bold} [**Description**]{.bold} - Name**]{.bold} - -------------------- --------------------------- ----------------------------------- - `BRANCH`{.code} `goto v0;`{.code} Branch execution to address of v0. - - `CBRANCH`{.code} `if (v0) goto v1;`{.code} Branch execution to address of v1 - if v0 equals 1 (true). - - `BRANCHIND`{.code} `goto [v0];`{.code} Branch execution to v0 viewed as an - offset in current space. - - `CALL`{.code} `call v0;`{.code} Branch execution to address of v0. - Hint that branch is subroutine - call. - - `CALLIND`{.code} `call [v0];`{.code} Branch execution to v0 viewed as an - offset in current space. Hint that - branch is subroutine call. - - `RETURN`{.code} `return [v0];`{.code} Branch execution to v0 viewed as an - offset in current space. Hint that - branch is a subroutine return. - ------------------------------------------------------------------------------------ -::: -::: - -\ -::: -::: - -::: {.navfooter} - ------------------------------------------------------------------------- - - ------------------------------ --------------------- --- - [Prev](sleigh_context.html)      - 8. Using Context  [Home](sleigh.html)   - ------------------------------ --------------------- --- -::: diff --git a/sources/GhidraDocs/languages/html/sleigh_symbols.html b/sources/GhidraDocs/languages/html/sleigh_symbols.html deleted file mode 100644 index 2022555..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_symbols.html +++ /dev/null @@ -1,229 +0,0 @@ - - - -5. Introduction to Symbols - - - - - - - - - -
- - - - - - - -
5. Introduction to Symbols
-Prev   Next -
-
-
-
-

-5. Introduction to Symbols

-

-After the definition section, we are prepared to start writing the -body of the specification. This part of the specification shows how -the bits in an instruction break down into opcodes, operands, -immediate values, and the other pieces of an instruction. Then once -this is figured out, the specification must also describe exactly how -the processor would manipulate the data and operands if this -particular instruction were executed. All of SLEIGH revolves around -these two major tasks of disassembling and following semantics. It -should come as no surprise then that the primary symbols defined and -manipulated in the specification all have two key properties. -

-
    -
  1. - How does the symbol get displayed as part of the disassembly? -
    2. -
  2. - What semantic variable is associated with the symbol, and how is it constructed? -
    3. -
-

-Formally a Specific Symbol is defined as an identifier associated with -

-
    -
  1. - A string displayed in disassembly. -
    2. -
  2. - varnode used in semantic actions, and any p-code used to construct that varnode. -
    3. -
-

-The named registers that we defined earlier are the simplest examples -of specific symbols (see -Section 4.4, “Naming Registers”). The symbol identifier -itself is the string that will get printed in disassembly and the -varnode associated with the symbol is the one constructed by the -define statement. -

-

-The other crucial part of the specification is how to map from the -bits of a particular instruction to the specific symbols that -apply. To this end we have the Family Symbol, -which is defined as an identifier associated with a map from machine -instructions to specific symbols. -

-
-Family Symbol: Instruction Encodings => Specific Symbols -
-

-The set of instruction encodings that map to a single specific symbol -is called an instruction pattern and is described -more fully in Section 7.4, “The Bit Pattern Section”. In most cases, this -can be thought of as a mask on the bits of the instruction and a value -that the remaining unmasked bits must match. At any rate, the family -symbol identifier, when taken out of context, represents the entire -collection of specific symbols involved in this map. But in the -context of a specific instruction, the identifier represents the one -specific symbol associated with the encoding of that instruction by -the family symbol map. -

-

-Given these maps, the idea of the specification is to build up more -and more complicated family symbols until we have a single root -symbol. This gives us a single map from the bits of an instruction to -the full disassembly of it and to the sequence of p-code instructions -that simulate the instruction. -

-

-The symbol responsible for combining smaller family symbols is called -a table, which is fully described in -Section 7.8, “Tables”. Any table symbol -can be used in the definition of other table -symbols until the root symbol is fully described. The root symbol has -the predefined identifier instruction. -

-
-

-5.1. Notes on Namespaces

-

-Almost all identifiers live in the same global "scope". The global scope includes -

-
-

-All of the names in this scope must be unique. Each -individual constructor (defined in Section 7, “Constructors”) -defines a local scope for operand names. As with most languages, a -local symbol with the same name as a global -symbol hides the global symbol while that scope -is in effect. -

-
-
-

-5.2. Predefined Symbols

-

-We list all of the symbols that are predefined by SLEIGH. -

-
-
-

Table 2. Predefined Symbols

-
--- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IdentifierMeaning
instructionThe root instruction table.
constSpecial address space for building constant varnodes.
uniqueAddress space for allocating temporary registers.
inst_startOffset of the address of the current instruction.
inst_nextOffset of the address of the next instruction.
inst_next2Offset of the address of the instruction after the next instruction.
epsilonA special identifier indicating an empty bit pattern.
-
-
-
-

-The most important of these to be aware of -are inst_start -and inst_next. These are family symbols which map -in the context of particular instruction to the integer offset of -either the address of the instruction or the address of the next -instruction respectively. These are used in any relative branching -situation. The inst_next2 is intended for conditional -skip instruction situations. The remaining symbols are rarely -used. The const and unique -identifiers are address spaces. The epsilon -identifier is inherited from SLED and is a specific symbol equivalent -to the constant zero. The instruction identifier -is the root instruction table. -

-
-
-
-
- - - - - - - - - - - -
-Prev   Next -
4. Basic Definitions Home 6. Tokens and Fields
-
- - diff --git a/sources/GhidraDocs/languages/html/sleigh_symbols.md b/sources/GhidraDocs/languages/html/sleigh_symbols.md deleted file mode 100644 index 09f2634..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_symbols.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -status: collected -title: 5. Introduction to Symbols -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_symbols.html ---- - -::: {.navheader} -5. Introduction to Symbols -::: - -[Prev](sleigh_definitions.html)  - -  - - [Next](sleigh_tokens.html) - ------------------------------------------------------------------------- - -::: {.sect1} -::: {.titlepage} -
- -
- -[]{#sleigh_symbols}5. Introduction to Symbols {#introduction-to-symbols .title style="clear: both"} ---------------------------------------------- - -
- -
-::: - -After the definition section, we are prepared to start writing the body -of the specification. This part of the specification shows how the bits -in an instruction break down into opcodes, operands, immediate values, -and the other pieces of an instruction. Then once this is figured out, -the specification must also describe exactly how the processor would -manipulate the data and operands if this particular instruction were -executed. All of SLEIGH revolves around these two major tasks of -disassembling and following semantics. It should come as no surprise -then that the primary symbols defined and manipulated in the -specification all have two key properties. - -::: {.informalexample} -::: {.orderedlist} -1. How does the symbol get displayed as part of the disassembly? -2. What semantic variable is associated with the symbol, and how is it - constructed? -::: -::: - -Formally a [*Specific Symbol*]{.emphasis} is defined as an identifier -associated with - -::: {.informalexample} -::: {.orderedlist} -1. A string displayed in disassembly. -2. varnode used in semantic actions, and any p-code used to construct - that varnode. -::: -::: - -The named registers that we defined earlier are the simplest examples of -specific symbols (see [Section 4.4, "Naming -Registers"](sleigh_definitions.html#sleigh_naming_registers "4.4. Naming Registers"){.xref}). -The symbol identifier itself is the string that will get printed in -disassembly and the varnode associated with the symbol is the one -constructed by the define statement. - -The other crucial part of the specification is how to map from the bits -of a particular instruction to the specific symbols that apply. To this -end we have the [*Family Symbol*]{.emphasis}, which is defined as an -identifier associated with a map from machine instructions to specific -symbols. - -::: {.informalexample} -[**Family Symbol:**]{.bold} Instruction Encodings =\> Specific Symbols -::: - -The set of instruction encodings that map to a single specific symbol is -called an [*instruction pattern*]{.emphasis} and is described more fully -in [Section 7.4, "The Bit Pattern -Section"](sleigh_constructors.html#sleigh_bit_pattern "7.4. The Bit Pattern Section"){.xref}. -In most cases, this can be thought of as a mask on the bits of the -instruction and a value that the remaining unmasked bits must match. At -any rate, the family symbol identifier, when taken out of context, -represents the entire collection of specific symbols involved in this -map. But in the context of a specific instruction, the identifier -represents the one specific symbol associated with the encoding of that -instruction by the family symbol map. - -Given these maps, the idea of the specification is to build up more and -more complicated family symbols until we have a single root symbol. This -gives us a single map from the bits of an instruction to the full -disassembly of it and to the sequence of p-code instructions that -simulate the instruction. - -The symbol responsible for combining smaller family symbols is called a -[*table*]{.emphasis}, which is fully described in [Section 7.8, -"Tables"](sleigh_constructors.html#sleigh_tables "7.8. Tables"){.xref}. -Any [*table*]{.emphasis} symbol can be used in the definition of other -[*table*]{.emphasis} symbols until the root symbol is fully described. -The root symbol has the predefined identifier -[*instruction*]{.emphasis}. - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_notes_namespaces}5.1. Notes on Namespaces {#notes-on-namespaces .title} - -
- -
-::: - -Almost all identifiers live in the same global \"scope\". The global -scope includes - -::: {.informalexample} -::: {.itemizedlist} -- Names of address spaces -- Names of tokens -- Names of fields -- Names of user-defined p-code ops -- Names of registers -- Names of macros (see [Section 7.9, "P-code - Macros"](sleigh_constructors.html#sleigh_macros "7.9. P-code Macros"){.xref}) -- Names of tables (see [Section 7.8, - "Tables"](sleigh_constructors.html#sleigh_tables "7.8. Tables"){.xref}) -::: -::: - -All of the names in this scope must be unique. Each individual -[*constructor*]{.emphasis} (defined in [Section 7, -"Constructors"](sleigh_constructors.html "7. Constructors"){.xref}) -defines a local scope for operand names. As with most languages, a local -symbol with the same name as a global symbol [*hides*]{.emphasis} the -global symbol while that scope is in effect. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_predefined_symbols}5.2. Predefined Symbols {#predefined-symbols .title} - -
- -
-::: - -We list all of the symbols that are predefined by SLEIGH. - -::: {.informalexample} -::: {.table} -[]{#predefine.htmltable} - -**Table 2. Predefined Symbols** - -::: {.table-contents} - --------------------------------------------------------------------------- - [**Identifier**]{.bold} [**Meaning**]{.bold} - ------------------------- ------------------------------------------------- - `instruction`{.code} The root instruction table. - - `const`{.code} Special address space for building constant - varnodes. - - `unique`{.code} Address space for allocating temporary registers. - - `inst_start`{.code} Offset of the address of the current instruction. - - `inst_next`{.code} Offset of the address of the next instruction. - - `inst_next2`{.code} Offset of the address of the instruction after - the next instruction. - - `epsilon`{.code} A special identifier indicating an empty bit - pattern. - --------------------------------------------------------------------------- -::: -::: - -\ -::: - -The most important of these to be aware of are -[*inst\_start*]{.emphasis} and [*inst\_next*]{.emphasis}. These are -family symbols which map in the context of particular instruction to the -integer offset of either the address of the instruction or the address -of the next instruction respectively. These are used in any relative -branching situation. The [*inst\_next2*]{.emphasis} is intended for -conditional skip instruction situations. The remaining symbols are -rarely used. The [*const*]{.emphasis} and [*unique*]{.emphasis} -identifiers are address spaces. The [*epsilon*]{.emphasis} identifier is -inherited from SLED and is a specific symbol equivalent to the constant -zero. The [*instruction*]{.emphasis} identifier is the root instruction -table. -::: -::: - -::: {.navfooter} - ------------------------------------------------------------------------- - - ---------------------------------- --------------------- ----------------------------- - [Prev](sleigh_definitions.html)     [Next](sleigh_tokens.html) - 4. Basic Definitions  [Home](sleigh.html)  6. Tokens and Fields - ---------------------------------- --------------------- ----------------------------- -::: diff --git a/sources/GhidraDocs/languages/html/sleigh_tokens.html b/sources/GhidraDocs/languages/html/sleigh_tokens.html deleted file mode 100644 index 2ba08cd..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_tokens.html +++ /dev/null @@ -1,285 +0,0 @@ - - - -6. Tokens and Fields - - - - - - - - - -
- - - - - - - -
6. Tokens and Fields
-Prev   Next -
-
-
-
-

-6. Tokens and Fields

-
-

-6.1. Defining Tokens and Fields

-

-A token is one of the byte-sized pieces that make -up the machine code instructions being modeled. -Instruction fields must be defined on top of -them. A field is a logical range of bits within -an instruction that can specify an opcode, or an operand etc. Together -tokens and fields determine the basic interpretation of bits and how -many bytes the instruction takes up. To define a token and the fields -associated with it, we use the define -token statement. -

-
-define token tokenname ( integer )
-  fieldname=(integer,integer) attributelist
-  ...
-;
-
-

-

-

-The first part of the definition defines the name of a token and the -number of bits it uses (this must be a multiple of 8). Following this -there are one or more field declarations specifying the name of the -field and the range of bits within the token making up the field. The -size of a field does not need to be a multiple of -8. The range is inclusive where the least significant bit in the token -is labeled 0. When defining tokens that are bigger than 1 byte, the -global endianness setting (See Section 4.1, “Endianness Definition”) -will affect this labeling. Although it is rarely required, it is possible to override -the global endianness setting for a specific token by appending either the qualifier -endian=little or endian=big -immediately after the token name and size. For instance: -

-
-  define token instr ( 32 ) endian=little op0=(0,15) ...
-
-

-The token instr is overridden to be little endian. -This override applies to all fields defined for the token but affects no other tokens. -

-

-After each field -declaration, there can be zero or more of the following attribute -keywords: -

-
-signed
-hex
-dec
-
-

-These attributes are defined in the next section. There can be any -manner of repeats and overlaps in the fields so long as they all have -different names. -

-
-
-

-6.2. Fields as Family Symbols

-

-Fields are the most basic form of family symbol; they define a natural -map from instruction bits to a specific symbol as follows. We take the -set of bits within the instruction as given by the field’s defining -range and treat them as an integer encoding. The resulting integer is -both the display portion and the semantic meaning of the specific -symbol. The display string is obtained by converting the integer into -either a decimal or hexadecimal representation (see below), and the -integer is treated as a constant varnode in any semantic action. -

-

-The attributes of the field affect the resulting specific symbol in -obvious ways. The signed attribute -determines whether the integer encoding should be treated as just an -unsigned encoding or if a twos-complement encoding should be used to -obtain a signed integer. The hex -or dec attributes describe whether -the integer should be displayed with a hexadecimal or decimal -representation. The default is hexadecimal. [Currently -the dec attribute is not supported] -

-
-
-

-6.3. Attaching Alternate Meanings to Fields

-

-The default interpretation of a field is probably the most natural but -of course processors interpret fields within an instruction in a wide -variety of ways. The attach keyword -is used to alter either the display or semantic meaning of fields into -the most common (and basic) interpretations. More complex -interpretations must be built up out of tables. -

-
-

-6.3.1. Attaching Registers

-

-Probably the most common processor interpretation -of a field is as an encoding of a particular register. In SLEIGH this -can be done with the attach variables -statement: -

-
-attach variables fieldlist registerlist;
-
-

-A fieldlist can be a single field identifier or a -space separated list of field identifiers surrounded by square -brackets. A registerlist must be a square bracket -surrounded and space separated list of register identifiers as created -with define statements (see Section -Section 4.4, “Naming Registers”). For each field in -the fieldlist, instead of having the display and -semantic meaning of an integer, the field becomes a look-up table for -the given list of registers. The original integer interpretation is -used as the index into the list starting at zero, so a specific -instruction that has all the bits in the field equal to zero yields -the first register (a specific varnode) from the list as the meaning -of the field in the context of that instruction. Note that both the -display and semantic meaning of the field are now taken from the new -register. -

-

-A particular integer can remain unspecified by putting a ‘_’ character -in the appropriate position of the register list or also if the length -of the register list is less than the integer. A specific integer -encoding of the field that is unspecified like this -does not revert to the original semantic and -display meaning. Instead this encoding is flagged as an invalid form -of the instruction. -

-
-
-

-6.3.2. Attaching Other Integers

-

-Sometimes a processor interprets a field as an integer but not the -integer given by the default interpretation. A different integer -interpretation of the field can be specified with -an attach values statement. -

-
-attach values fieldlist integerlist;
-
-

-The integerlist is surrounded by square brackets -and is a space separated list of integers. In the same way that a new -register interpretation is assigned to fields with -an attach variables statement, the -integers in the list are assigned to each field specified in -the fieldlist. [Currently SLEIGH does not support -unspecified positions in the list using a ‘_’] -

-
-
-

-6.3.3. Attaching Names

-

-It is possible to just modify the display characteristics of a field -without changing the semantic meaning. The need for this is rare, but -it is possible to treat a field as having influence on the display of -the disassembly but having no influence on the semantics. Even if the -bits of the field do have some semantic meaning, sometimes it is -appropriate to define overlapping fields, one of which is defined to -have no semantic meaning. The most convenient way to break down the -required disassembly may not be the most convenient way to break down -the semantics. It is also possible to have symbols with semantic -meaning but no display meaning (see Section 7.4.5, “Invisible Operands”). -

-

-At any rate we can list the display interpretation of a field directly -with an attach names statement. -

-
-attach names fieldlist stringlist;
-
-

-The stringlist is assigned to each of the fields -in the same manner as the attach -variables and attach -values statements. A specific encoding of the field now -displays as the string in the list at that integer position. Field -values greater than the size of the list are interpreted as invalid -encodings. -

-
-
-
-

-6.4. Context Variables

-

-SLEIGH supports the concept of context -variables. For the most part processor instructions can be -unambiguously decoded by examining only the bits of the instruction -encoding. But in some cases, decoding may depend on the state of -processor. Typically, the processor will have some set of status flags -that indicate what mode is being used to process instructions. In -terms of SLEIGH, a context variable is a field -which is defined on top of a register rather than the instruction -encoding (token). -

-
-define context contextreg
-  fieldname=(integer,integer) attributelist
-  ...
-;
-
-

-

-

-Context variables are defined with a define -context statement. The keywords must be followed by the -name of a defined register. The remaining part of the definition is -nearly identical to the normal definition of fields. Each context -variable defined on this register is listed in turn, specifying the -name, the bit range, and any attributes. All the normal field attributes, -signed, dec, and -hex, can also be used for context variables. -

-

-Context variables introduce a new, dedicated, attribute: noflow. -By default, globally setting a context variable affects instruction decoding -from the point of the change, forward, -following the flow of the instructions, but if the variable is labeled as -noflow, any change is limited to a -single instruction. (See Section 8.3.1, “Context Flow”) -

-

-Once the context variable is defined, in terms of the specification -syntax, it can be treated as if it were just another field. See -Section 8, “Using Context”, for a complete discussion of how to -use context variables. -

-
-
-
-
- - - - - - - - - - - -
-Prev   Next -
5. Introduction to Symbols Home 7. Constructors
-
- - diff --git a/sources/GhidraDocs/languages/html/sleigh_tokens.md b/sources/GhidraDocs/languages/html/sleigh_tokens.md deleted file mode 100644 index 45ecc8b..0000000 --- a/sources/GhidraDocs/languages/html/sleigh_tokens.md +++ /dev/null @@ -1,346 +0,0 @@ ---- -status: collected -title: 6. Tokens and Fields -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/html/sleigh_tokens.html ---- - -::: {.navheader} -6. Tokens and Fields -::: - -[Prev](sleigh_symbols.html)  - -  - - [Next](sleigh_constructors.html) - ------------------------------------------------------------------------- - -::: {.sect1} -::: {.titlepage} -
- -
- -[]{#sleigh_tokens}6. Tokens and Fields {#tokens-and-fields .title style="clear: both"} --------------------------------------- - -
- -
-::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_defining_tokens}6.1. Defining Tokens and Fields {#defining-tokens-and-fields .title} - -
- -
-::: - -A [*token*]{.emphasis} is one of the byte-sized pieces that make up the -machine code instructions being modeled. Instruction -[*fields*]{.emphasis} must be defined on top of them. A -[*field*]{.emphasis} is a logical range of bits within an instruction -that can specify an opcode, or an operand etc. Together tokens and -fields determine the basic interpretation of bits and how many bytes the -instruction takes up. To define a token and the fields associated with -it, we use the [**define token**]{.bold} statement. - -::: {.informalexample} -``` -define token tokenname ( integer ) - fieldname=(integer,integer) attributelist - ... -; -``` -::: - -The first part of the definition defines the name of a token and the -number of bits it uses (this must be a multiple of 8). Following this -there are one or more field declarations specifying the name of the -field and the range of bits within the token making up the field. The -size of a field does [*not*]{.emphasis} need to be a multiple of 8. The -range is inclusive where the least significant bit in the token is -labeled 0. When defining tokens that are bigger than 1 byte, the global -endianness setting (See [Section 4.1, "Endianness -Definition"](sleigh_definitions.html#sleigh_endianness_definition "4.1. Endianness Definition"){.xref}) -will affect this labeling. Although it is rarely required, it is -possible to override the global endianness setting for a specific token -by appending either the qualifier [**endian=little**]{.bold} or -[**endian=big**]{.bold} immediately after the token name and size. For -instance: - -::: {.informalexample} -``` - define token instr ( 32 ) endian=little op0=(0,15) ... -``` -::: - -The token [*instr*]{.emphasis} is overridden to be little endian. This -override applies to all fields defined for the token but affects no -other tokens. - -After each field declaration, there can be zero or more of the following -attribute keywords: - -::: {.informalexample} -``` -signed -hex -dec -``` -::: - -These attributes are defined in the next section. There can be any -manner of repeats and overlaps in the fields so long as they all have -different names. -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_fields_family}6.2. Fields as Family Symbols {#fields-as-family-symbols .title} - -
- -
-::: - -Fields are the most basic form of family symbol; they define a natural -map from instruction bits to a specific symbol as follows. We take the -set of bits within the instruction as given by the field's defining -range and treat them as an integer encoding. The resulting integer is -both the display portion and the semantic meaning of the specific -symbol. The display string is obtained by converting the integer into -either a decimal or hexadecimal representation (see below), and the -integer is treated as a constant varnode in any semantic action. - -The attributes of the field affect the resulting specific symbol in -obvious ways. The [**signed**]{.bold} attribute determines whether the -integer encoding should be treated as just an unsigned encoding or if a -twos-complement encoding should be used to obtain a signed integer. The -[**hex**]{.bold} or [**dec**]{.bold} attributes describe whether the -integer should be displayed with a hexadecimal or decimal -representation. The default is hexadecimal. \[Currently the -[**dec**]{.bold} attribute is not supported\] -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_alternate_meanings}6.3. Attaching Alternate Meanings to Fields {#attaching-alternate-meanings-to-fields .title} - -
- -
-::: - -The default interpretation of a field is probably the most natural but -of course processors interpret fields within an instruction in a wide -variety of ways. The [**attach**]{.bold} keyword is used to alter either -the display or semantic meaning of fields into the most common (and -basic) interpretations. More complex interpretations must be built up -out of tables. - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_attaching_registers}6.3.1. Attaching Registers {#attaching-registers .title} - -
- -
-::: - -Probably [*the*]{.emphasis} most common processor interpretation of a -field is as an encoding of a particular register. In SLEIGH this can be -done with the [**attach variables**]{.bold} statement: - -::: {.informalexample} -``` -attach variables fieldlist registerlist; -``` -::: - -A [*fieldlist*]{.emphasis} can be a single field identifier or a space -separated list of field identifiers surrounded by square brackets. A -[*registerlist*]{.emphasis} must be a square bracket surrounded and -space separated list of register identifiers as created with -[**define**]{.bold} statements (see Section [Section 4.4, "Naming -Registers"](sleigh_definitions.html#sleigh_naming_registers "4.4. Naming Registers"){.xref}). -For each field in the [*fieldlist*]{.emphasis}, instead of having the -display and semantic meaning of an integer, the field becomes a look-up -table for the given list of registers. The original integer -interpretation is used as the index into the list starting at zero, so a -specific instruction that has all the bits in the field equal to zero -yields the first register (a specific varnode) from the list as the -meaning of the field in the context of that instruction. Note that both -the display and semantic meaning of the field are now taken from the new -register. - -A particular integer can remain unspecified by putting a '\_' character -in the appropriate position of the register list or also if the length -of the register list is less than the integer. A specific integer -encoding of the field that is unspecified like this does -[*not*]{.emphasis} revert to the original semantic and display meaning. -Instead this encoding is flagged as an invalid form of the instruction. -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_attaching_integers}6.3.2. Attaching Other Integers {#attaching-other-integers .title} - -
- -
-::: - -Sometimes a processor interprets a field as an integer but not the -integer given by the default interpretation. A different integer -interpretation of the field can be specified with an [**attach -values**]{.bold} statement. - -::: {.informalexample} -``` -attach values fieldlist integerlist; -``` -::: - -The [*integerlist*]{.emphasis} is surrounded by square brackets and is a -space separated list of integers. In the same way that a new register -interpretation is assigned to fields with an [**attach -variables**]{.bold} statement, the integers in the list are assigned to -each field specified in the [*fieldlist*]{.emphasis}. \[Currently SLEIGH -does not support unspecified positions in the list using a '\_'\] -::: - -::: {.sect3} -::: {.titlepage} -
- -
- -#### []{#sleigh_attaching_names}6.3.3. Attaching Names {#attaching-names .title} - -
- -
-::: - -It is possible to just modify the display characteristics of a field -without changing the semantic meaning. The need for this is rare, but it -is possible to treat a field as having influence on the display of the -disassembly but having no influence on the semantics. Even if the bits -of the field do have some semantic meaning, sometimes it is appropriate -to define overlapping fields, one of which is defined to have no -semantic meaning. The most convenient way to break down the required -disassembly may not be the most convenient way to break down the -semantics. It is also possible to have symbols with semantic meaning but -no display meaning (see [Section 7.4.5, "Invisible -Operands"](sleigh_constructors.html#sleigh_invisible_operands "7.4.5. Invisible Operands"){.xref}). - -At any rate we can list the display interpretation of a field directly -with an [**attach names**]{.bold} statement. - -::: {.informalexample} -``` -attach names fieldlist stringlist; -``` -::: - -The [*stringlist*]{.emphasis} is assigned to each of the fields in the -same manner as the [**attach variables**]{.bold} and [**attach -values**]{.bold} statements. A specific encoding of the field now -displays as the string in the list at that integer position. Field -values greater than the size of the list are interpreted as invalid -encodings. -::: -::: - -::: {.sect2} -::: {.titlepage} -
- -
- -### []{#sleigh_context_variables}6.4. Context Variables {#context-variables .title} - -
- -
-::: - -SLEIGH supports the concept of [*context variables*]{.emphasis}. For the -most part processor instructions can be unambiguously decoded by -examining only the bits of the instruction encoding. But in some cases, -decoding may depend on the state of processor. Typically, the processor -will have some set of status flags that indicate what mode is being used -to process instructions. In terms of SLEIGH, a context variable is a -[*field*]{.emphasis} which is defined on top of a register rather than -the instruction encoding (token). - -::: {.informalexample} -``` -define context contextreg - fieldname=(integer,integer) attributelist - ... -; -``` -::: - -Context variables are defined with a [**define context**]{.bold} -statement. The keywords must be followed by the name of a defined -register. The remaining part of the definition is nearly identical to -the normal definition of fields. Each context variable defined on this -register is listed in turn, specifying the name, the bit range, and any -attributes. All the normal field attributes, [**signed**]{.bold}, -[**dec**]{.bold}, and [**hex**]{.bold}, can also be used for context -variables. - -Context variables introduce a new, dedicated, attribute: -[**noflow**]{.bold}. By default, globally setting a context variable -affects instruction decoding from the point of the change, forward, -following the flow of the instructions, but if the variable is labeled -as [**noflow**]{.bold}, any change is limited to a single instruction. -(See [Section 8.3.1, "Context -Flow"](sleigh_context.html#sleigh_contextflow "8.3.1. Context Flow"){.xref}) - -Once the context variable is defined, in terms of the specification -syntax, it can be treated as if it were just another field. See -[Section 8, "Using -Context"](sleigh_context.html "8. Using Context"){.xref}, for a complete -discussion of how to use context variables. -::: -::: - -::: {.navfooter} - ------------------------------------------------------------------------- - - ------------------------------ --------------------- ----------------------------------- - [Prev](sleigh_symbols.html)     [Next](sleigh_constructors.html) - 5. Introduction to Symbols  [Home](sleigh.html)  7. Constructors - ------------------------------ --------------------- ----------------------------------- -::: diff --git a/sources/GhidraDocs/languages/manual_index.txt b/sources/GhidraDocs/languages/manual_index.txt deleted file mode 100644 index 60149bf..0000000 --- a/sources/GhidraDocs/languages/manual_index.txt +++ /dev/null @@ -1,54 +0,0 @@ - -How to Create a Processor Language Manual Index File ----------------------------------------------------- - -The processor manual index file (*.idx) contains list of instructions mnemonic and page -numbers into an identified PDF manual. These files along with the corresponding PDF files -are generally located within the data/manuals directory of a Ghidra module -(e.g., Ghidra/Processors/x86/data/manuals/x86.idx). - -The first line of the .idx file must be a PDF manual selector preceeded by the @ character. - -Example: - -@68000.pdf [M68000 FAMILY Programmer's Reference Manual, 1992 (M68000PM/AD REV.1)] - -The manual selector specifies the PDF file name followed by the manual description within -brackets [ ]. The ".pdf" file extension is assumed if not specified, and the file path is -relative to the directory containing the index file. If the manual is omitted from the -distribution due to copyright or other restrictions, the bracketed text will be helpful -in allowing the user to obtain the manual on there own. - -The PDF manual selector is immediately followed by lines containing instruction -mnemonic, page number pairs which are contained within the specified PDF manual. -Additional PDF manuals may be referenced by repeating this pattern starting with -the @ character on a new line. - -Example: - -@Intel64_IA32_vol2a.pdf [Intel 64 and IA-32 Vol 2A: Instruction Set Reference, A-M, Nov 2008 (253666-029US)] -AAA, 74 -AAD, 76 -@Intel64_IA32_vol2b.pdf [Intel 64 and IA-32 Vol 2B: Instruction Set Reference, N-Z, Nov 2008 (253667-029US)] -NEG, 4 -NOP, 7 -NOT, 9 - -The AAA and AAD instructions will be found in Intel64_IA32_vol2a.pdf manual on -on page 74 and 76, respectively. Moreover, the NEG and NOP instructions -will be found in Intel64_IA32_vol2b.pdf on page 4 and 7 respectively. Also, the -remainder of the instructions will be found under Intel64_IA32_vol2b.pdf unless -another section is defined with the "@" symbol. - -Note: All files are expected to be stored relative to the directory -where the index file is located. The index file should be in the module's -data/manuals directory. - -The index file contains one line per instruction mnemonic or section header. -Each line of the index file for instruction mnemonics contains two strings: -the mnemonic and the corresponding instruction info page number in the PDF file in -its respective section. The instruction mnemonic may only specify the start of a -mnemonic if appropriate. For example a conditional branch instruction may include -a condition suffix on the mnemonic, but for simplification the suffix may be omitted -within the index file if all condition cases are handled together (e.g., index could -a mnemonic 'B' instead of listing all the condition cases BLT, BGT, BEQ, etc.). diff --git a/sources/GhidraDocs/languages/versioning.html b/sources/GhidraDocs/languages/versioning.html deleted file mode 100644 index eef8ceb..0000000 --- a/sources/GhidraDocs/languages/versioning.html +++ /dev/null @@ -1,237 +0,0 @@ - - - - - Language Versioning and Migration - - - -

Language Versioning and -Migration

-

This document discusses the mechanisms within Ghidra which mitigate -the impact of language modifications to existing user program -files.  There are two general classes of language modifications -which can be supported by the language translation capabilities within -Ghidra :
-

-
    -
  1. Version -Change - caused by modifications to a specific -language implementation which necessitates a re-disassembly of a programs -instructions.
    2. -
  2. Forced -Language Migration - caused when an existing language -implementation is completely replaced by a new implementation (language -name must be different).  It is important that an "old" language -file (*.lang) be generated for -a language before it is eliminated.   A simple or custom -language translator is required to facilitate the forced migration.
    -
    3. -
-

Any program opened within Ghidra whose language has had a version -change or has been replaced by a new implementation will be forced to -upgrade.  This will prevent such a program file from being opened -as immutable and will impose a delay due to the necessary -re-disassembly of all instructions.

-

In addition to a forced upgrade, Ghidra's Set Language capability will allow -a user to make certain transitions between similar language -implementations.  Such transitions are generally facilitated via a -default translator, although certain limitations are imposed based upon -address space sizes and register mappings.

-

Any changes made to a Data Organization could impact the packing of -components within a structure or union. While such changes should be avoided -due to the possible fallout, any such change to a -*.cspec should be made -in conjunction with a version change to all affected languages within -the relevant *.ldefs files. The -resulting program upgrade will allow affected data types to be updated. -
-

-

Language Versioning

-

A language's version is specified as a <major>.<minor> number pair (e.g., -1.0).  The decision to advance the major or minor version number -should be based upon the following criteria:
-

-
    -
  1. Major Version Change - -caused by modifications to a specific -language implementation which changes register addressing or context -register schema.  Addition of registers alone does not constitute -a major or minor change.
    -
    2. -
  2. Minor Version Change - -caused by modifications to a specific -language implementation which changes existing instruction or -subconstructor pattern matching.  Pcode changes and addition of -new instructions alone does not constitute a major or minor change.
    3. -
-

Anytime the major version number is advanced, the minor version -number should be reset to zero.
-

-

Only major version changes utilize a Language -Translator to facilitate the language transition.
-

-

Forced Language Migration
-

-

When eliminating an old language the following must be accomplished:
-

-
    -
  1. Establish a replacement language
    2. -
  2. Generate old-language specification file (*.lang)
    -
    3. -
  3. Establish one and only one Language -Translator from the final version of the eliminated language to -its replacement language.
    -
    4. -
-

Before eliminating a language a corresponding "old" language file -must be generated and stored somewhere within Ghidra's languages -directory (core/languages/old -directory has been established for this purpose).   In -addition, a simple or custom Language Translator -must be established to facilitate the language migration to the -replacement language. 
-

-

An old-language file may be generated automatically while the -language still exists using the GenerateOldLanguagePlugin -configured into Ghidra's project window.  In addition, if -appropriate, a draft simple Language Translator specification can -generated provided the replacement language is also available.
-

-

To generate an old-language file and optionally a draft simple -translator specification:
-

-
    -
  • Choose the menu item File>Generate Old Language File...
    • -
  • Select the language to be eliminated from the languages list and -click Generate...
    • -
  • From the file chooser select the output directory, enter a -suitable name for the file and click Create
    • -
  • Once the old-language file is generated you will be asked if you -would like to Create -a Simple Translator?  If the replacement language is -complete and available you can click Yes - and specify an output file with the file chooser.
    • -
-

Old Language Specification (*.lang)

-

An old-language specification file is used to describe the essential -elements of a language needed to instantiate an old program using that -language and to facilitate translation to a replacement language.
-

-

The specification file is an XML file which identifies a language's -description, address spaces and named registers.   Since it -should be generated using the GenerateOldLanguagePlugin, -its syntax is not defined here. -

-

Sample -Old-Language Specification File:
-

-
<?xml version="1.0" encoding="UTF-8"?>
<language version="1" endian="big">
    <description>
        <name>MyOldProcessorLanguage</name>
        <processor>MyOldProcessor</processor>
        <family>Motorola</family>
        <alias>MyOldProcessorLanguageAlias1</alias>
	<alias>MyOldProcessorLanguageAlias2</alias>
    </description>
    <spaces>
        <space name="ram" type="ram" size="4" default="yes" />
        <space name="register" type="register" size="4" />
        <space name="data" type="code" size="4" />
    </spaces>
    <registers>
	<context_register name="contextreg" offset="0x40" bitsize="8">
            <field name="ctxbit1" range="1,1" />
            <field name="ctxbit0" range="0,0" />
        </context_register>
        <register name="r0" offset="0x0" bitsize="32" />
        <register name="r1" offset="0x4" bitsize="32" />
        <register name="r2" offset="0x8" bitsize="32" />
        <register name="r3" offset="0xc" bitsize="32" />
        <register name="r4" offset="0x10" bitsize="32" />
    </registers>
</language>

-

Language Translators

-

A language translator facilitates the renaming of address spaces, -and relocation/renaming of registers.  In addition, stored -register values can be transformed - although limited knowledge is -available for decision making.  Through the process of -re-disassembly, language changes in instruction and subconstructor -pattern matching is handled.  Three forms of  translators are -supported:
-

-
    -
  1. Default Translator - in -the absence of a simple or custom translator, an attempt will be made -to map all address spaces and registers.  Stored register values -for unmapped registers will be discarded.  Forced language -migration can not use a default translator since it is the presence of -a translator with an old-language which specifies the migration path.
    -
    2. -
  2. Simple Translator - -extends the behavior of the default translator allowing specific -address space and register mappings to be specified via an XML file (*.trans).  See sample Simple Translator Specification.
    -
    3. -
  3. Custom Translator - -custom translators can be written as a Java class which extends LanguageTranslatorAdapter -or implements LanguageTranslator.  -This should generally be unnecessary but can provided additional -flexibility.  The default constructor must be public and will be used -for instantiation.  Extending LanguageTranslatorAdapter - will allow the default translator capabilities to be -leveraged with minimal coding.
    4. -
- -

Sample -Simple Translator Specification File:

-
<?xml version="1.0" encoding="UTF-8"?>
-<language_translation>
-
-    <from_language version="1">MyOldProcessorLanguage</from_language>  
-    <to_language version="1">MyNewProcessorLanguage</to_language>
-
-    <!--
-        Obsolete space will be deleted with all code units in that space.
-    -->
-    <delete_space name="data" />
-
-    <!--
-        Spaces whose name has changed can be mapped over
-    -->
-    <map_space from="ram" to="ram" />
-
-    <!--
-        Registers whose name has changed can be mapped (size and offset changes are allowed)
-        The map_register may include a size attribute although it is ignored. 
-    --> 
-    <map_register from="r0" to="cr0" />
-    <map_register from="r1" to="cr1" />
-
-    <!--
-        All existing processor context can be cleared
-    -->
-    <clear_all_context/>
-
-    <!--
-        A specific context value can be painted across all of program memory
-        NOTE: sets occur after clear_all_context
-    -->
-    <set_context name="ctxbit0" value="1"/>
-    
-    <!--
-        Force a specific Java class which extends
-          ghidra.program.util.LanguagePostUpgradeInstructionHandler
-        to be invoked following translation and re-disassembly to allow for more
-        complex instruction context transformations/repair.
-    -->
-    <post_upgrade_handler class="ghidra.program.language.MyOldNewProcessorInstructionRepair" />
-
-</language_translation>
-
-
-

Translator Limitations
-

-

The current translation mechanism does not handle the potential need -for complete re-disassembly and associated auto-analysis.
-

- - diff --git a/sources/GhidraDocs/languages/versioning.md b/sources/GhidraDocs/languages/versioning.md deleted file mode 100644 index d692fd0..0000000 --- a/sources/GhidraDocs/languages/versioning.md +++ /dev/null @@ -1,242 +0,0 @@ ---- -status: collected -title: Language Versioning and Migration -author: Ghidra Developers Team -collector: Hornos3 -collected_date: 20240826 -link: https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs/languages/versioning.html ---- - -Language Versioning and Migration -================================= - -This document discusses the mechanisms within Ghidra which mitigate the -impact of language modifications to existing user program files.  There -are two general classes of language modifications which can be supported -by the language translation capabilities within Ghidra :\ - -1. [[Version Change]{style="font-weight: bold;"}](#versioning) - caused - by modifications to a specific language implementation which - necessitates a re-disassembly of a programs instructions. -2. [[Forced Language - Migration]{style="font-weight: bold;"}](#forcedMigration) - caused - when an existing language implementation is completely replaced by a - new implementation (language name must be different).  It is - important that an \"old\" language file - ([\*.lang]{style="font-style: italic;"}) be generated for a language - before it is eliminated.   A simple or custom language translator is - required to facilitate the forced migration.\ - -Any program opened within Ghidra whose language has had a version change -or has been replaced by a new implementation will be forced to upgrade.  -This will prevent such a program file from being opened as immutable and -will impose a delay due to the necessary re-disassembly of all -instructions. - -In addition to a forced upgrade, Ghidra\'s [Set -Language]{style="font-style: italic;"} capability will allow a user to -make certain transitions between similar language implementations.  Such -transitions are generally facilitated via a default translator, although -certain limitations are imposed based upon address space sizes and -register mappings. - -Any changes made to a Data Organization could impact the packing of -components within a structure or union. While such changes should be -avoided due to the possible fallout, any such change to a -[\*.cspec]{style="font-style: italic;"} should be made in conjunction -with a version change to all affected languages within the relevant -[\*.ldefs]{style="font-style: italic;"} files. The resulting program -upgrade will allow affected data types to be updated.\ - -[]{#versioning}Language Versioning ----------------------------------- - -A language\'s version is specified as a[ -\]{style="font-style: italic;"}[.]{style="font-weight: bold; font-style: italic;"}[\]{style="font-style: italic;"} -number pair (e.g., 1.0).  The decision to advance the major or minor -version number should be based upon the following criteria:\ - -1. [Major Version Change]{style="font-weight: bold;"} - caused by - modifications to a specific language implementation which changes - register addressing or context register schema.  Addition of - registers alone does not constitute a major or minor change.\ -2. [Minor Version Change]{style="font-weight: bold;"} - caused by - modifications to a specific language implementation which changes - existing instruction or subconstructor pattern matching.  Pcode - changes and addition of new instructions alone does not constitute a - major or minor change. - -Anytime the major version number is advanced, the minor version number -should be reset to zero.\ - -Only major version changes utilize a [Language Translator](#translators) -to facilitate the language transition.\ - -[]{#forcedMigration}Forced Language Migration ---------------------------------------------- - -When eliminating an old language the following must be accomplished:\ - -1. Establish a replacement language -2. Generate [old-language specification](#oldlang) file - ([\*.lang]{style="font-style: italic;"})\ -3. Establish one and only one [Language Translator](#translators) from - the final version of the eliminated language to its replacement - language.\ - -Before eliminating a language a corresponding \"old\" language file must -be generated and stored somewhere within Ghidra\'s languages directory -([core/languages/old]{style="font-style: italic;"} directory has been -established for this purpose).   In addition, a simple or custom -[Language Translator](#translators) must be established to facilitate -the language migration to the replacement language. \ - -An old-language file may be generated automatically while the language -still exists using the [GenerateOldLanguagePlugin -]{style="font-style: italic; font-weight: bold;"}configured into -Ghidra\'s project window.  In addition, if appropriate, a draft simple -Language Translator specification can generated provided the replacement -language is also available.\ - -To generate an old-language file and optionally a draft simple -translator specification:\ - -- Choose the menu item File\>Generate Old Language File\... -- Select the language to be eliminated from the languages list and - click [Generate\...]{style="font-weight: bold;"} -- From the file chooser select the output directory, enter a suitable - name for the file and click [Create]{style="font-weight: bold;"} -- Once the old-language file is generated you will be asked if you - would like to [Create a Simple - Translator?]{style="font-weight: bold; font-style: italic;"}  If the - replacement language is complete and available you can click [Yes - ]{style="font-weight: bold;"}and specify an output file with the - file chooser. - -[]{#oldlang}Old Language Specification ([\*.lang]{style="font-style: italic;"}) -------------------------------------------------------------------------------- - -An old-language specification file is used to describe the essential -elements of a language needed to instantiate an old program using that -language and to facilitate translation to a replacement language.\ - -The specification file is an XML file which identifies a language\'s -description, address spaces and named registers.   Since it should be -generated using the -[GenerateOldLanguagePlugin]{style="font-style: italic; font-weight: bold;"}, -its syntax is not defined here. - -[Sample Old-Language Specification -File:]{style="font-style: italic; font-weight: bold;"}\ - - - - - MyOldProcessorLanguage - MyOldProcessor - Motorola - MyOldProcessorLanguageAlias1 - MyOldProcessorLanguageAlias2 - - - - - - - - - - - - - - - - - - - -[]{#translators}Language Translators ------------------------------------- - -A language translator facilitates the renaming of address spaces, and -relocation/renaming of registers.  In addition, stored register values -can be transformed - although limited knowledge is available for -decision making.  Through the process of re-disassembly, language -changes in instruction and subconstructor pattern matching is handled.  -Three forms of  translators are supported:\ - -1. [Default Translator]{style="font-weight: bold;"} - in the absence of - a simple or custom translator, an attempt will be made to map all - address spaces and registers.  Stored register values for unmapped - registers will be discarded.  Forced language migration can not use - a default translator since it is the presence of a translator with - an old-language which specifies the migration path.\ -2. [Simple Translator]{style="font-weight: bold;"} - extends the - behavior of the default translator allowing specific address space - and register mappings to be specified via an XML file - ([\*.trans]{style="font-style: italic;"}).  See sample [Simple - Translator Specification](#transfile).\ -3. [Custom Translator]{style="font-weight: bold;"} - custom translators - can be written as a Java class which extends - [LanguageTranslatorAdapter]{style="font-weight: bold; font-style: italic;"} - or implements - [LanguageTranslator]{style="font-weight: bold; font-style: italic;"}.  - This should generally be unnecessary but can provided additional - flexibility.  The default constructor must be public and will be - used for instantiation.  Extending [LanguageTranslatorAdapter - ]{style="font-weight: bold; font-style: italic;"}will allow the - default translator capabilities to be leveraged with minimal coding. - -[[]{style="font-weight: bold;"}]{style="font-family: times new roman;"} - -[]{#transfile}Sample Simple Translator Specification File: - - - - - MyOldProcessorLanguage - MyNewProcessorLanguage - - - - - - - - - - - - - - - - - - - - - - -Translator Limitations\ - -The current translation mechanism does not handle the potential need for -complete re-disassembly and associated auto-analysis.\