diff options
Diffstat (limited to '')
| -rw-r--r-- | README.md | 30 | ||||
| -rw-r--r-- | test/autowasm.c | 10 |
2 files changed, 32 insertions, 8 deletions
@@ -7,11 +7,21 @@ The generated source code does not include a main.<br/> The root node should have two childs, named exactly `READ` and `DEFINITION`(order not important).<br/> The `READ` node will include the actual structures that the parser will read and can return.<br/> The `DEFINITION` node includes the definitions for the structures that are aggregate.<br/> -For an explanation of the format for the XML file, let's look at the example XML file under `resources`. The XML file describes the format of a WASM object file:<br/> -Any child node of either `DEFINITION` or `READ` will have to at least have the attributes `name` and `type` defined. The presence of the attribute `count` is optional but if it's not present faultreiber will assume that the count is one. The presence of the attribute `isaggregate` signifies the fact that the data structure is composed of other smaller parts. faultreiber will only read the children of a node that is the child of either the `DEFINITION` or `READ` node(unless a child node has the attribute `conditional` set). If a data structure requires more children then you should add a new node under `DEFINITION` and reference that node from it's parent.<br/> + +## Demo +For a practical example, look at the example XML file under `resources`. The XML file describes the format of a WASM object file:<br/> +To run the demo, run `run.sh`, go to the `test` direcotory and run `make`. Then run the executable.<br/> + +### Rules: + +Any child node of either `DEFINITION` or `READ` will have to at least have the attributes `name` and `type` defined. The presence of the attribute `count` is optional but if it's not present faultreiber will assume that the count is one.<br/> +The presence of the attribute `isaggregate` signifies the fact that the data structure is composed of other smaller parts. faultreiber will only read the children of a node that is the child of either the `DEFINITION` or `READ` node(unless a child node has the attribute `conditional` set). If a data structure requires more children then you should add a new node under `DEFINITION` and reference that node from it's parent. In other words, an aggregate node can't itself have child nodes that are aggregate.<br/> + `count`, `size`, `type` and `condition` attributes can reference a child node of the `DEFINITION` node. To do that, you should use `self::TAG`.<br/> the tag names of the nodes that are on the same level should be unique. The `name` attribute of the nodes on the same level need to be unique as well.<br/> -tags, needless to say, should follow the naming convention for naming XML nodes. The `name` attributes should follow the C identifier naming convention(if the value of the `name` attribute is invalid in C as as identifier you're going to end up with code that won't even build).<br/> +The order of the nodes that appear as children of the `DEFINITION` node, even when the child nodes are referencing each other, is unimportant to faultreiber.<br/> + +Tags should follow the naming convention for naming XML nodes. The `name` attributes should follow the C identifier naming convention(if the value of the `name` attribute is invalid in C as as identifier you're going to end up with code that won't even build).<br/> The following values are valid values for the `type` attribute:<br/> * int8 * uint8 @@ -29,9 +39,15 @@ The following values are valid values for the `type` attribute:<br/> * FT::conditional * self::TAG +For string nodes, the node should either have a non-empty `size` attribute or have a `delimiter` attribute. In case a `delimiter` attribute is selected the value of the delimiter should be provided as the value of the `delimiter` attribute to the node.<br/> +Strings read through a `delimiter` node will have their delimiter attached to the end of the string(null-terminated or otherwise). String reads that have a `size` attribute will be forcefully null-terminated even if the original string was not null-terminated.<br/> + +Child nodes of `READ` node that have the `unordered` attribute set, will be regarded as such, meaning they can appear in the file sporaically. Such nodes will have to have a child node with attriute `sign`.The value of the sign attribute is used to check for the presence of the parent node in the file.<br/> +`unorderedbegin` and `unorderedend` attributes denote the begenning and end of an unordered section in the `READ` node. For every unordered section, only one node needs to define the begin and end attributes. All the other nodes, including the nodes that define the `unorderedbegin` and `unorderedend` attributes, shall have the `unordered` attribute defined.<br/> +Any child of the `READ` node that is not inside an unordered block or doesnt have the `unordered` attribute set, will be regarded as ordered.<br/> + Whether `int128` or `uint128` are defined depends on your the C implementation you are using on your host. If 128-bit integers are not supported or you need to read in bigger integers, you can simply use a smaller int type and increase the `count` attribute accordingly.<br/> The `FT::conditional` tag for a type means that the actual content of the node will depend on a value. The attribute `condition` will provide what that condition is. The value for the condition should be provided as text for the different nodes that define what the actual contents should be.<br/> -A node referencing another node as the value of its `type` attribute is insensitive to the order in which the nodes appear under their parent node, `DEFINITION`.<br/> `size` attribute is currently only meaningful when the `type` attribute is set as `string` in which case it denotes the size of the string.<br/> ## Options @@ -69,9 +85,7 @@ A node referencing another node as the value of its `type` attribute is insensit ## limitations Big-Endian reads are not supported.<br/> -Only files that are instantly-decodable(need a single pass) are supported.<br/> -None byte sized raw reads are not supported.<br/> -String reads need to have a size. Currently null-terminated string reads without the size of the string are not supported.<br/> +None-byte-sized raw reads are not supported.<br/> ## makefile To get a list of the targets the makfile supports you can run its `help` target.<br/> @@ -85,4 +99,4 @@ The list of the projects that use faulreiber:<br/> * [bruiser](https://github.com/bloodstalker/mutator/tree/master/bruiser)<br/> ## License -`faultreiber` along with the makefile are provided under MIT. I don't know if I have the legal right to license the generated files, but if I do, they are also under MIT as far as I'm concerned.<br/> +`faultreiber` along with the makefile, are provided under MIT. I'm not sure whether the generated code is considered "derived work", but if it is, then the generated code will also fall under MIT<br/> diff --git a/test/autowasm.c b/test/autowasm.c index 4054f48..0f81225 100644 --- a/test/autowasm.c +++ b/test/autowasm.c @@ -125,6 +125,16 @@ int main (int argc, char** argv) { printf("%c ", W_Data_Section_container->entries[i]->data[j]); } printf("\n"); + int j = 0; + printf("offset:\n"); + while(1) { + printf("%02x ", W_Data_Section_container->entries[i]->offset->code[j]); + if (W_Data_Section_container->entries[i]->offset->code[j] == 11) { + break; + } + j++; + } + printf("\n"); } release_all(); |