{"id":20713241,"url":"https://github.com/linaro/vixl","last_synced_at":"2025-04-13T07:49:03.504Z","repository":{"id":39752033,"uuid":"334964073","full_name":"Linaro/vixl","owner":"Linaro","description":"AArch32 and AArch64 Runtime Code Generation Library","archived":false,"fork":false,"pushed_at":"2025-03-13T15:17:24.000Z","size":76007,"stargazers_count":145,"open_issues_count":9,"forks_count":51,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-13T07:48:35.815Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Linaro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-01T13:47:48.000Z","updated_at":"2025-04-03T12:58:53.000Z","dependencies_parsed_at":"2023-02-17T06:15:22.886Z","dependency_job_id":"d2390c85-b550-46a7-9cb7-8fd6686fe64e","html_url":"https://github.com/Linaro/vixl","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Linaro%2Fvixl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Linaro%2Fvixl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Linaro%2Fvixl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Linaro%2Fvixl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Linaro","download_url":"https://codeload.github.com/Linaro/vixl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681494,"owners_count":21144700,"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":[],"created_at":"2024-11-17T02:24:04.624Z","updated_at":"2025-04-13T07:49:03.479Z","avatar_url":"https://github.com/Linaro.png","language":"C","readme":"VIXL: ARMv8 Runtime Code Generation Library\n===========================================\n\nContents:\n\n * Overview\n * Licence\n * Requirements\n * Known limitations\n * Bug reports\n * Usage\n\n\nOverview\n========\n\nVIXL contains three components.\n\n 1. Programmatic **assemblers** to generate A64, A32 or T32 code at runtime. The\n    assemblers abstract some of the constraints of each ISA; for example, most\n    instructions support any immediate.\n 2. **Disassemblers** that can print any instruction emitted by the assemblers.\n 3. A **simulator** that can simulate any instruction emitted by the A64\n    assembler. The simulator allows generated code to be run on another\n    architecture without the need for a full ISA model.\n\nThe VIXL git repository can be found [on GitHub][vixl].\n\nBuild and Test Status\n---------------------\n\n  * [![Build Status](https://ci.linaro.org/buildStatus/icon?job=linaro-art-vixlpresubmit)](https://ci.linaro.org/job/linaro-art-vixlpresubmit/) Simulator\n  * [![Build Status](https://ci.linaro.org/buildStatus/icon?job=linaro-art-vixlpresubmit-native-armv8)](https://ci.linaro.org/job/linaro-art-vixlpresubmit-native-armv8/) Native\n  * [![Build Status](https://ci.linaro.org/buildStatus/icon?job=linaro-art-vixlpresubmit-macos)](https://ci.linaro.org/job/linaro-art-vixlpresubmit-macos/) MacOS\n\n\nLicence\n=======\n\nThis software is covered by the licence described in the [LICENCE](LICENCE)\nfile.\n\nContributions, as pull requests or via other means, are accepted under the terms\nof the same [LICENCE](LICENCE).\n\nRequirements\n============\n\nTo build VIXL the following software is required:\n\n 1. Python 3.5+\n 2. SCons 2.0\n 3. GCC 4.8+ or Clang 4.0+\n\nA 64-bit host machine is required, implementing an LP64 data model. VIXL has\nbeen tested using GCC on AArch64 Debian, GCC and Clang on amd64 Ubuntu\nsystems.\n\nTo run the linter and code formatting stages of the tests, the following\nsoftware is also required:\n\n 1. Git\n 2. [Google's `cpplint.py`][cpplint]\n 3. clang-format 11+\n 4. clang-tidy 11+\n\nRefer to the 'Usage' section for details.\n\nNote that in Ubuntu 18.04, clang-tidy-4.0 will only work if the clang-4.0\npackage is also installed.\n\nSupported Arm Architecture Features\n===================================\n\n| Feature    | VIXL CPUFeatures Flag | Notes                           |\n|------------|-----------------------|---------------------------------|\n| BTI        | kBTI                  | Per-page enabling not supported |\n| DotProd    | kDotProduct           |                                 |\n| FCMA       | kFcma                 |                                 |\n| FHM        | kFHM                  |                                 |\n| FP16       | kFPHalf, kNEONHalf    |                                 |\n| FRINTTS    | kFrintToFixedSizedInt |                                 |\n| FlagM      | kFlagM                |                                 |\n| FlagM2     | kAXFlag               |                                 |\n| I8MM       | kI8MM                 |                                 |\n| JSCVT      | kJSCVT                |                                 |\n| LOR        | kLORegions            |                                 |\n| LRCPC      | kRCpc                 |                                 |\n| LRCPC2     | kRCpcImm              |                                 |\n| LSE        | kAtomics              |                                 |\n| PAuth      | kPAuth, kPAuthGeneric | Not ERETAA, ERETAB              |\n| RAS        | kRAS                  |                                 |\n| RDM        | kRDM                  |                                 |\n| SVE        | kSVE                  |                                 |\n| SVE2       | kSVE2                 |                                 |\n| SVEBitPerm | kSVEBitPerm           |                                 |\n| SVEF32MM   | kSVEF32MM             |                                 |\n| SVEF64MM   | kSVEF64MM             |                                 |\n| SVEI8MM    | kSVEI8MM              |                                 |\n\nEnable generating code for an architecture feature by combining a flag with\nthe MacroAssembler's defaults. For example, to generate code for SVE, use\n`masm.GetCPUFeatures()-\u003eCombine(CPUFeatures::kSVE);`.\n\nSee [the cpu features header file](src/cpu-features.h) for more information.\n\n\nKnown Limitations\n=================\n\nVIXL was developed for JavaScript engines so a number of features from A64 were\ndeemed unnecessary:\n\n * Limited rounding mode support for floating point.\n * Limited support for synchronisation instructions.\n * Limited support for system instructions.\n * A few miscellaneous integer and floating point instructions are missing.\n\nThe VIXL simulator supports only those instructions that the VIXL assembler can\ngenerate. The `doc` directory contains a\n[list of supported A64 instructions](doc/aarch64/supported-instructions-aarch64.md).\n\nThe VIXL simulator was developed to run on 64-bit amd64 platforms. Whilst it\nbuilds and mostly works for 32-bit x86 platforms, there are a number of\nfloating-point operations which do not work correctly, and a number of tests\nfail as a result.\n\nDebug Builds\n------------\n\nYour project's build system must define `VIXL_DEBUG` (eg. `-DVIXL_DEBUG`)\nwhen using a VIXL library that has been built with debug enabled.\n\nSome classes defined in VIXL header files contain fields that are only present\nin debug builds, so if `VIXL_DEBUG` is defined when the library is built, but\nnot defined for the header files included in your project, you will see runtime\nfailures.\n\nExclusive-Access Instructions\n-----------------------------\n\nAll exclusive-access instructions are supported, but the simulator cannot\naccurately simulate their behaviour as described in the ARMv8 Architecture\nReference Manual.\n\n * A local monitor is simulated, so simulated exclusive loads and stores execute\n   as expected in a single-threaded environment.\n * The global monitor is simulated by occasionally causing exclusive-access\n   instructions to fail regardless of the local monitor state.\n * Load-acquire, store-release semantics are approximated by issuing a host\n   memory barrier after loads or before stores. The built-in\n   `__sync_synchronize()` is used for this purpose.\n\nThe simulator tries to be strict, and implements the following restrictions that\nthe ARMv8 ARM allows:\n\n * A pair of load-/store-exclusive instructions will only succeed if they have\n   the same address and access size.\n * Most of the time, cache-maintenance operations or explicit memory accesses\n   will clear the exclusive monitor.\n    * To ensure that simulated code does not depend on this behaviour, the\n      exclusive monitor will sometimes be left intact after these instructions.\n\nInstructions affected by these limitations:\n  `stxrb`, `stxrh`, `stxr`, `ldxrb`, `ldxrh`, `ldxr`, `stxp`, `ldxp`, `stlxrb`,\n  `stlxrh`, `stlxr`, `ldaxrb`, `ldaxrh`, `ldaxr`, `stlxp`, `ldaxp`, `stlrb`,\n  `stlrh`, `stlr`, `ldarb`, `ldarh`, `ldar`, `clrex`.\n\nSecurity Considerations\n-----------------------\n\nVIXL allows callers to generate any code they want. The generated code is\narbitrary, and can therefore call back into any other component in the process.\nAs with any self-modifying code, vulnerabilities in the client or in VIXL itself\ncould lead to arbitrary code generation.\n\nFor performance reasons, VIXL's Assembler only performs debug-mode checking of\ninstruction operands (such as immediate field encodability). This can minimise\ncode-generation overheads for advanced compilers that already model instructions\naccurately, and might consider the Assembler's checks to be redundant. The\nAssembler should only be used directly where encodability is independently\nchecked, and where fine control over all generated code is required.\n\nThe MacroAssembler synthesises multiple-instruction sequences to support _some_\nunencodable operand combinations. The MacroAssembler can provide a useful safety\ncheck in cases where the Assembler's precision is not required; an unexpected\nunencodable operand should result in a macro with the correct behaviour, rather\nthan an invalid instruction.\n\nIn general, the MacroAssembler handles operands which are likely to vary with\nuser-supplied data, but does not usually handle inputs which are likely to be\neasily covered by tests. For example, move-immediate arguments are likely to be\ndata-dependent, but register types (e.g. `x` vs `w`) are not.\n\nWe recommend that _all_ users use the MacroAssembler, using `ExactAssemblyScope`\nto invoke the Assembler when specific instruction sequences are required. This\napproach is recommended even in cases where a compiler can model the\ninstructions precisely, because, subject to the limitations described above, it\noffers an additional layer of protection against logic bugs in instruction\nselection.\n\nBug reports\n===========\n\nBug reports may be made in the Issues section of GitHub, or sent to\nvixl@arm.com. Please provide any steps required to recreate a bug, along with\nbuild environment and host system information.\n\nUsage\n=====\n\nRunning all Tests\n-----------------\n\nThe helper script `tools/test.py` will build and run every test that is provided\nwith VIXL, in both release and debug mode. It is a useful script for verifying\nthat all of VIXL's dependencies are in place and that VIXL is working as it\nshould.\n\nBy default, the `tools/test.py` script runs a linter to check that the source\ncode conforms with the code style guide, and to detect several common errors\nthat the compiler may not warn about. This is most useful for VIXL developers.\nThe linter has the following dependencies:\n\n 1. Git must be installed, and the VIXL project must be in a valid Git\n    repository, such as one produced using `git clone`.\n 2. `cpplint.py`, [as provided by Google][cpplint], must be available (and\n    executable) on the `PATH`.\n\nIt is possible to tell `tools/test.py` to skip the linter stage by passing\n`--nolint`. This removes the dependency on `cpplint.py` and Git. The `--nolint`\noption is implied if the VIXL project is a snapshot (with no `.git` directory).\n\nAdditionally, `tools/test.py` tests code formatting using `clang-format-4.0`,\nand performs static analysis using `clang-tidy-4.0`. If you don't have these\ntools, disable the test using `--noclang-format` or `--noclang-tidy`,\nrespectively.\n\nAlso note that the tests for the tracing features depend upon external `diff`\nand `sed` tools. If these tools are not available in `PATH`, these tests will\nfail.\n\nGetting Started\n---------------\n\nWe have separate guides for introducing VIXL, depending on what architecture you\nare targeting. A guide for working with AArch32 can be found\n[here][getting-started-aarch32], while the AArch64 guide is\n[here][getting-started-aarch64]. Example source code is provided in the\n[examples](examples) directory. You can build examples with either `scons\naarch32_examples` or `scons aarch64_examples` from the root directory, or use\n`scons --help` to get a detailed list of available build targets.\n\n\n\n\n[cpplint]: https://github.com/google/styleguide/tree/gh-pages/cpplint\n           \"Google's cpplint.py script.\"\n\n[vixl]: https://github.com/Linaro/vixl\n        \"The VIXL repository on GitHub.\"\n\n[getting-started-aarch32]: doc/aarch32/getting-started-aarch32.md\n                           \"Introduction to VIXL for AArch32.\"\n\n[getting-started-aarch64]: doc/aarch64/getting-started-aarch64.md\n                           \"Introduction to VIXL for AArch64.\"\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinaro%2Fvixl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinaro%2Fvixl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinaro%2Fvixl/lists"}