{"id":15060284,"url":"https://github.com/0xade1a1de/assemblyline","last_synced_at":"2025-04-04T07:04:07.663Z","repository":{"id":38595722,"uuid":"399327719","full_name":"0xADE1A1DE/AssemblyLine","owner":"0xADE1A1DE","description":"A C library and binary for generating machine code of x86_64 assembly language and executing on the fly without invoking another compiler, assembler or linker.","archived":false,"fork":false,"pushed_at":"2025-02-10T03:28:23.000Z","size":519,"stargazers_count":190,"open_issues_count":2,"forks_count":27,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-04T06:39:54.170Z","etag":null,"topics":["assembler","assembly","c","x86","x86-64"],"latest_commit_sha":null,"homepage":"https://0xade1a1de.github.io/AssemblyLine","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xADE1A1DE.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-08-24T03:52:58.000Z","updated_at":"2025-03-17T07:53:22.000Z","dependencies_parsed_at":"2023-01-31T07:45:45.457Z","dependency_job_id":null,"html_url":"https://github.com/0xADE1A1DE/AssemblyLine","commit_stats":{"total_commits":189,"total_committers":8,"mean_commits":23.625,"dds":0.6190476190476191,"last_synced_commit":"9fb095da7b5be01a121be9262e476f7a5cf71697"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xADE1A1DE%2FAssemblyLine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xADE1A1DE%2FAssemblyLine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xADE1A1DE%2FAssemblyLine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xADE1A1DE%2FAssemblyLine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xADE1A1DE","download_url":"https://codeload.github.com/0xADE1A1DE/AssemblyLine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247135139,"owners_count":20889420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembler","assembly","c","x86","x86-64"],"created_at":"2024-09-24T22:55:57.515Z","updated_at":"2025-04-04T07:04:07.638Z","avatar_url":"https://github.com/0xADE1A1DE.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AssemblyLine\n![Unit Tests](https://github.com/0xADE1A1DE/AssemblyLine/actions/workflows/c-check.yml/badge.svg)\n![Code Style](https://github.com/0xADE1A1DE/AssemblyLine/actions/workflows/clang-format-check.yml/badge.svg)\n![Version](https://img.shields.io/github/v/release/0xADE1A1DE/AssemblyLine?logo=github\u0026style=flat)\n![AUR Version](https://img.shields.io/aur/version/assemblyline-bin?logo=github\u0026style=flat)\n\n\n\nAn ultra-lightweight C library and binary for generating machine code of x86\\_64 assembly language and executing on the fly without invoking another compiler, assembler or linker.\n\n* Easy to use C library `libassemblyline`.\n* Print or run assembly code with our cli tool `asmline` (see [tools/README.md](/tools/README.md)) \n* Support for MMX, SSE2, AVX, and AVX2 instruction sets.\n* Supports Scaled Index addressing mode (SIB) with the following syntax:  \n`[base + index*scale +\\- offset]`, `[base + scale*index +\\- offset]`  \n`[scale*index +\\- offset]`, `[constant]`\n* Supports pointer: byte, word, dword, and qword\n* Supports multi-length nop instructions (by using `nop{2..11}` as the instruction)  \n  see [test/nop.asm](test/nop.asm) for more information\n* Supports jump instructions without labels: short, long, and far\n* Memory chunk alignment by using nop-padding.\n* Command line completion (zsh, bash) for `asmline`\n* Different modes for assembling instructions.  \n`NASM`: binary output will match that of nasm as closely as possible (default for SIB).  \n`STRICT`: binary output will be in an 'as is' state in respect to the instruction.  \n`SMART`: instructions could be manipulated to ensure binary output matches nasm (default).  \n  See [tools/README.md](/tools/README.md) **Different Modes of Assembly** section for more information\n* `man`-pages for `asmline` and `libassemblyline`\n* High instruction compatibility and easy to add new instructions (see [src/README.md](src/README.md), and [/src/instructions.c](src/instructions.c) for a list of supported instructions.   \n\n## How to Install\n\nWe have packages in the [AUR](https://aur.archlinux.org/packages/assemblyline-bin).\u003cbr\u003e\nOtherwise clone this repo or get a [stable release tarball](https://github.com/0xADE1A1DE/AssemblyLine/releases). \u003cbr\u003e \n\n```bash\n$ ./autogen.sh # when `git clone`d\n$ ./configure \u0026\u0026 \\\nmake  \u0026\u0026 \\\nsudo make install\n```\n## Usage\n\n1. `$ cc your_program.c -lassemblyline` to use the library and compile a C program using assemblyline\u003cbr\u003e\u003cbr\u003e   \n1. `$ echo -e \"mov rax, 0xADE1A1DE\\nret\" | asmline -r` to use our asmline-cli tool\u003cbr\u003e (Will print 'the value is 0xade1a1de')\u003cbr\u003e\n\n\n## Jumpstart library\n  \nFull code example:\u003cbr\u003e\n```c\n#include \u003cassemblyline.h\u003e // all assemblyline functions\n#include \u003cstdint.h\u003e       // uint8_t\n#include \u003cstdio.h\u003e        // printf\n#include \u003csys/mman.h\u003e     // mmap\n\nint main() {\n  const int buffer_size = 300; // bytes\n  uint8_t *mybuffer = mmap(NULL, sizeof(uint8_t) * buffer_size,\n                           PROT_READ | PROT_WRITE | PROT_EXEC,\n                           MAP_ANONYMOUS | MAP_PRIVATE, -1, 0);\n\n  assemblyline_t al = asm_create_instance(mybuffer, buffer_size);\n\n  asm_assemble_str(al, \"mov rax, 0x0\\nadd rax, 0x2; adds two\");\n  asm_assemble_str(al, \"sub rax, 0x1; subs one\\nret\");\n\n  int (*func)() = asm_get_code(al);\n\n  int result = func();\n  printf(\"The result is: %d\\n\", result);\n  // prints \"The result is: 1\\n\"\n\n  asm_destroy_instance(al);\n  munmap(mybuffer, buffer_size);\n}\n```\n\nLets dissect the example (and give alternatives):\n\n1. Include the required header files and preprocessors\n    ```c\n    #include \u003cassemblyline.h\u003e // all assemblyline functions\n    #include \u003cstdint.h\u003e       // uint8_t\n    #include \u003cstdio.h\u003e        // printf\n    #include \u003csys/mman.h\u003e     // mmap\n    ```\n1. Allocate an executable buffer of sufficient size (\u003e 20 bytes) using mmap\n    ```c\n    // the machine code will be written to this location\n   const int buffer_size = 300; // bytes\n   uint8_t *mybuffer = mmap(NULL, sizeof(uint8_t) * buffer_size,\n                            PROT_READ | PROT_WRITE | PROT_EXEC,\n                            MAP_ANONYMOUS | MAP_PRIVATE, -1, 0);\n    ```\n1. Create an instance of assemblyline\\_t and attach `mybuffer` (or `NULL, 0` for internal memory allocation)\n    ```c\n    // manual memory allocation\n    assemblyline_t al = asm_create_instance(mybuffer, buffer_size);\n\n    // assemblyline-managed memory allocation\n    assemblyline_t al = asm_create_instance(NULL, 0);\n    ```\n\n1. Assemble a file or string containing. The machine code will be written to `mybuffer` (or the internal buffer).\n   Call those functions sequentially; subsequent new machine code will be appended at the end of the last instruction.\n   Separate instructions with `\\n`.\n    ```c\n    asm_assemble_file(al, \"./path/to/x64_file.asm\");\n    asm_assemble_str(al, \"mov rax, 0x0\\nadd rax, 0x2; adds two\");\n    asm_assemble_str(al, \"sub rax, 0x1; subs one\\nret\");\n    ```\n1. Get the start address of the buffer containing the start of the assembly program\n    ```c\n    void (*func)() = asm_get_code(al);\n\n    // call the function\n    int result = func();\n    ```\n1. Free all memory associated with assembyline (an external buffer is not freed)\n    ```c\n    asm_destroy_instance(al);\n    munmap(mybuffer, buffer_size);\n    ```\n    \u003cbr\u003e\n\n**Note: for more information see [/src/assemblyline.h](/src/assemblyline.h) or run `$ man libassemblyline` for more information**\n\n## Jumpstart Cli-tool: asmline\n\nThe general usage is `asmline [OPTIONS]... FILE`. `asmline --help` for all options.\n\n```asm\n; jump.asm\nmov rcx, 0x123\njmp 0x4\nadd rcx, 1\nmov rax, rcx\nret\n```\nUse `-p` for printing ASCII-hex to `stdout`\n\n```bash\n$ asmline -p jump.asm\nb9 23 01 00 00 \neb 04 \n48 83 c1 01 \n48 89 c8 \nc3 \n```\nOr pipe directly into it, use `-r` to run the code:\n```bash\n$ echo -n 'mov rax, 0xC0FFEE\\nret' | asmline -pr\nb8 ee ff c0 00 \nc3 \n\n# the value is 0xc0ffee\n```\n\nSee [tools/README.md](/tools/README.md) for more info.\u003cbr\u003e\u003cbr\u003e     \n\n## Adding new instructions\n\nTo add support for new instructions see [src/README.md](/src/README.md) for more info.\u003cbr\u003e\u003cbr\u003e  \n\n## Test files\n\n`$ make check` to run all test suites (repo must be cloned for this to work)\n\n* To run only one test suite `TESTS=seto.asm make -e check`, then check `./test/seto.log`\n* Or run the `./al_nasm_compare.sh seto.asm` in the `test` directory\n* Adding a new test: add the test file e.g. `sub.asm` to the directory and add `sub.asm` to the `TESTS`-variable in `./Makefile.am`\nthen run `$ make clean check`. Finally, add `Makefile.am` and `sub.asm` to git.\u003cbr\u003e\u003cbr\u003e \n\n  \n## Contributing\n\nWe welcome any kind of contribution. Feel free to open issues if something is broken or you'd need feature. Or open up a PR if you've enhanced AssemblyLine already and want to see it here.\n\n## Acknowledgements\n#### Authors:\n* Chitchanok Chuengsatiansup (University of Adelaide)\n* Daniel Genkin (Georgia Tech)\n* Joel Kuepper (University of Adelaide)\n* Markus Wagner (University of Adelaide)\n* David Wu (University of Adelaide)  \n* Yuval Yarom (University of Adelaide)\n\n\n#### This project was supported by:  \n* The Air Force Office of Scientific Research (AFOSR) under award number FA9550-20-1-0425\n* An ARC Discovery Early Career Researcher Award (project number DE200101577) \n* An ARC Discovery Project (project number DP210102670)  \n* The Blavatnik ICRC at Tel-Aviv University  \n* Data61, CSIRO\n* the Defense Advanced Research Projects Agency (DARPA) and Air Force Research Laboratory (AFRL) under contracts FA8750-19-C-0531 and HR001120C0087\n* the National Science Foundation under grant CNS-1954712\n* Gifts from AMD, Google, and Intel  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xade1a1de%2Fassemblyline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xade1a1de%2Fassemblyline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xade1a1de%2Fassemblyline/lists"}