Merge pull request #1 from ArmDeveloperEcosystem/temp-BIOERMJNLG

First version of the Arm Disassembly Library

.gitignore

@@ -0,0 +1,11 @@
+/venv
+__pycache__
+*.bak
+*.o
+build
+llvmlib
+.vscode
+*.so
+llvm-temp
+.cache
+.idea

CMakeLists.txt

@@ -0,0 +1,24 @@
+#
+# SPDX-FileCopyrightText: Copyright (C) 2024 Arm Limited and/or its affiliates
+# SPDX-FileCopyrightText: <[email protected]>
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+
+cmake_minimum_required(VERSION 3.20)
+
+project(armdisasm-root)
+
+add_subdirectory(src)
+add_subdirectory(examples)
+add_subdirectory(test)

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+Arm Disassembly Library is licensed under the [Apache-2.0 License](LICENSE). By contributing to this project, you agree to the license and copyright terms.
+
+All contributions will be released under these terms, as per the [Developer Certificate of Origin](DCO.md).
+
+# Getting Started
+
+* Make sure you have a [GitHub account](https://github.com/login).
+* Clone the repo to your own machine.
+* Create a local branch based on the [Arm Disassembly Library](https://github.com/ArmDeveloperEcosystem/disassembly-library) `main` branch.
+
+# Making Changes
+
+* Make commits of logical units. See these general [Git guidelines](http://git-scm.com/book/ch5-2.html) for contributing to a project.
+* Follow the [style guidelines](#style-guidelines) section below.
+* Keep commits focused on their main purpose. If you need to fix another bug or make another enhancement, please address it using a separate pull request.
+* Avoid using a long series of commits. Consider whether some commits should be squashed together or addressed in a separate pull request.
+* Make sure your commit messages are in the proper format.
+* Where appropriate, please update the documentation.
+* Ensure that each changed file has the correct copyright and license information:
+ * Files that entirely consist of contributions to this project should have a copyright notice and Apache-2.0 SPDX license identifier.
+ * Files that contain changes to imported Third Party IP files should retain their original copyright and license notices.
+* For pull requests with multiple commits, it is recommended that you make all the documentation changes (and nothing else) in the last commit of the series.
+* Please test your changes.
+
+# Style Guidelines
+
+The source code must use the UTF-8 encoding. Comments, documentation and strings may use non-ASCII characters when required.
+
+## C/C++
+* Follow the style in existing source files.
+
+## Python
+* For Python, follow the style in existing source files and the PEP8 specification.
+* Code should be linted using `pylint` and the provided [.pylintrc file](python/.pylintrc).
+
+# Submitting Changes
+
+* Ensure that each commit in the series has at least one `Signed-off-by:` line, using your real name and email address. The names in the `Signed-off-by:` and `Author:` lines must match. If anyone else contributes to the commit, they must also add their own `Signed-off-by:` line. By adding this line the contributor certifies the contribution is made under the terms of the [Developer Certificate of Origin (DCO)](DCO.md).
+* Push your local changes to a new branch (this may require [adding a new SSH key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).
+* [Create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) from your branch to the [Arm Disassembly Library](https://github.com/ArmDeveloperEcosystem/disassembly-library) `main` branch.
+* The changes will then undergo further review and testing by the maintainers. Any review comments will be made as comments on the PR. This may require you to make further changes.
+* When the changes are accepted, the maintainers will integrate them.
+* If the MR is not based on a recent commit, the maintainers may rebase it onto the `main` branch first, or ask you to do this.
+* If the MR cannot be automatically merged, the maintainers will ask you to rebase it onto the `main` branch.
+* If the maintainers find any issues after merging, they may remove the commits and ask you to create a new pull request to resolve the problem(s).
+
+> [!TIP]
+> Consider setting your user.name and user.email in your git config; then you can sign your commit automatically with git commit -s

DCO.md

@@ -0,0 +1,37 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/

README.md

@@ -0,0 +1,100 @@
+# Arm Disassembly Library
+
+Arm Disassembly Library is a software library and API for decoding and disassembling AArch64 instructions.
+
+The instruction decoder takes 32-bit instruction encodings as input and generates a data structure containing information about the decoded instruction, such as register usage and operand details.
+
+The disassembly library API provides a way to produce text disassembly and query additional information about decoded instructions. The API aims to be as stable as possible.
+
+The library source code is written in C/C++ and is built on the [LLVM project](https://github.com/llvm/llvm-project)'s MC (Machine Code) component. The API is available in C, C++, and Python. An installable Python package is built to provide the Python bindings.
+
+The library has a small memory footprint and only temporarily allocates small amounts of memory in order to decode instructions. The library does not make system calls or perform I/O.
+
+The library is designed to have minimal dependencies on the run-time environment, only requiring simple linking with common libraries such as libstdc++.
+
+## Dependencies
+
+The following packages and versions are required in order to build the library:
+* CMake >= 3.20 (must be built from source if not available in OS' package repository)
+* C++ compiler that supports C++11
+* Python >= 3.7
+* pip >= 21.0
+* python3-build
+* python3-setuptools >= 59.0
+* virtualenv (installed using 'pip install')
+* bc (basic calculator)
+
+## Building
+
+### Overview
+
+Before using the Arm Disassembly Library, it must be built from source using the `build.sh` script provided.
+
+Internally, the Arm Disassembly Library leverages the LLVM project. The library is built in two main stages:
+* Build LLVM
+* Build the Arm Disassembly Library (including example programs, tests, and Python bindings)
+
+Firstly, the build script will first perform a shallow clone of LLVM and apply any required modifications/patches before building. Cloning and building LLVM is resource-heavy and requires ~5GB of disk space. This produces a static library build of LLVM with some minor changes that exposes methods within the MC component.
+
+Secondly, libarmdisasm.so is created by combining the LLVM build and armdisasm code into a shared object library.
+
+ ___________________           __________________
+|                   |         |                  |
+|  Python bindings  |         |   C application  |
+|___________________|         |__________________|
+         / \                           / \
+          |                             |
+          |                             |
+          |                             |
+          |_____________________________|
+            |                         |
+            |     libarmdisasm.so     |
+            |_________________________|
+            |             |           |
+            | armdisasm.c |  LLVM MC  |
+            |_____________|___________|
+
+Once built, the resulting shared object library `libarmdisasm.so` can be linked and used as a component in your own C/C++ applications. The Python package can be installed to provide bindings for your Python applications.
+
+### Instructions
+
+Follow the steps below to build the library. Before starting, ensure all dependencies above have been installed.
+
+Clone this git repository:
+```sh
+git clone https://github.com/ArmDeveloperEcosystem/disassembly-library.git
+```
+
+Run the `build.sh` script from the project root directory to build the Arm Disassembly Library, examples, tests, and installable Python package.
+
+To view script usage and options:
+```sh
+./build.sh --help
+```
+
+## Learning Path
+
+For more information and examples on how to use this tool, check out the [Arm Learning Path](https://learn.arm.com/learning-paths/servers-and-cloud-computing/arm-disassembly-library).
+
+## Compatibility
+
+This library can be built for any platform, however it has only been tested on AArch64 Linux and x86-64 Linux. Currently, only AArch64 instructions are supported.
+
+Please consider raising a [GitHub issue](https://github.com/ArmDeveloperEcosystem/disassembly-library/issues/new) if this tool does not work as expected on your system.
+
+## Contributing
+
+Contributions are welcome. In order to contribute, follow these steps:
+* Read the [contribution agreement](CONTRIBUTING.md)
+* Sign the commit message to indicate that you agree to the contribution agreement
+# Submit a [pull request](https://github.com/ArmDeveloperEcosystem/disassembly-library/pulls) on GitHub
+
+## Security
+
+To report security vulnerabilities in this project, follow the guidance in the [security policy](SECURITY.md).
+
+## License
+
+This project is licensed under the [Apache-2.0 License](LICENSE).
+
+The only exceptions to this are files stored under the `src/llvm-project/` subdirectory, which are licensed under the [Apache-2.0 License with LLVM Exceptions](src/llvm-project/LICENSE-Apache-2.0-with-LLVM-Exceptions).

SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+Arm takes security vulnerabilities seriously and aims to quickly address any issues reported.
+
+Arm is committed to security and welcomes feedback from researchers and the security community to improve its products and services.
+
+### Arm Disassembly Library
+
+For issues found in the Arm Disassembly Library project, follow Arm's policy on [reporting a product security vulnerability](https://developer.arm.com/documentation/102850/latest/).
+
+### LLVM Project
+
+For issues found in the LLVM project (i.e. source files in `src/llvm-project/`), the [LLVM security guidelines](https://llvm.org/docs/Security.html#what-is-considered-a-security-issue) will be followed.