From 3a148be8d8201f9e5b5a60c7ae702c550cc86742 Mon Sep 17 00:00:00 2001 From: huku Date: Mon, 1 Jul 2024 19:02:03 +0300 Subject: [PATCH] Update documentation --- Makefile.nmake | 3 +- NOTES.md | 20 ++++----- README.md | 112 +++++++++++++++++++------------------------------ TODO | 1 - 4 files changed, 54 insertions(+), 82 deletions(-) diff --git a/Makefile.nmake b/Makefile.nmake index 4595b49..607d66a 100644 --- a/Makefile.nmake +++ b/Makefile.nmake @@ -1,4 +1,5 @@ -PYTHON27_PREFIX=C:\Python27 +PYTHON27_PREFIX= +# PYTHON27_PREFIX=C:\Python27 PYTHON27_HEADERS=$(PYTHON27_PREFIX)\include PYTHON27_LIBS=$(PYTHON27_PREFIX)\libs diff --git a/NOTES.md b/NOTES.md index 707439d..6fd00f1 100644 --- a/NOTES.md +++ b/NOTES.md @@ -7,18 +7,18 @@ huku <[huku@grhack.net](mailto:huku@grhack.net)> ## Converting C datatypes to Python PyObjects -Most functions exported to Python are simple wrappers around the low level C API +Most functions exported to Python are simple wrappers around the low level C API offered by XED2. To be properly returned to the user, the return values of those -C functions must be converted to one of the datatypes recognized by the Python -runtime (i.e. **PyObject** pointers). For the sake of developing **pyxed**, I +C functions must be converted to one of the datatypes recognized by the Python +runtime (i.e. `PyObject` pointers). For the sake of developing **pyxed**, I settled down to the following set of simple guidelines: - * When a XED2 function returns **xed_uint_t** to indicate a true/false result, - or **xed_bool_t** (also **typedef**'ed to **unsigned int**), use - **PyBool_FromLong()** to retrieve the corresponding Python object. + * When a XED2 function returns `xed_uint_t` to indicate a true/false result, + or `xed_bool_t` (also `typedef`'ed to `unsigned int`), use `PyBool_FromLong()` + to retrieve the corresponding Python object. - * When functions return arbitrary values of type **xed_uint_t**, use - **PyLong_FromUnsignedLong()**. + * When functions return arbitrary values of type `xed_uint_t`, use + `PyLong_FromUnsignedLong()`. - * For return values of type **xed_*_enum_t**, use **PyInt_FromLong()** - (according to the C standard, enumerations are treated as **int** values). + * For return values of type `xed_*_enum_t`, use `PyInt_FromLong()` + (according to the C standard, enumerations are treated as `int` values). diff --git a/README.md b/README.md index dfb1865..db41f33 100644 --- a/README.md +++ b/README.md @@ -12,88 +12,72 @@ it doesn't provide any high level abstractions. ## Compiling pyxed -**pyxed** comes with Makefiles for the most widely used platforms, namely -Microsoft Windows, MacOS X and Linux. All Makefiles require that you edit them -and set **XED_PREFIX** appropriately. In order to compile the Python 3 -module, you will need to initialize the sub-modules: +### Linux & MacOS X -```shell script -$ git submodule update --init --recursive -```` +The **pyxed** build process is based on `setuptools` and should work on both +Python 3.x and Python 2.x, even though the latter is obsolete. -### Linux +Begin by cloning **pyxed** and its dependencies: -There are two methods for compiling **pyxed**: Using the make file (Python 2 only) -or using the Python distools. + $ git submodule update --init --recursive -#### Makefile (Python 2) +Create a new virtual environment for installing and testing: -Compiling on Linux requires GCC to be installed (chances are it is). Just open a -terminal, enter **pyxed**'s top-level directory and run **make**. + $ python -m venv /tmp/pyxed-venv # Python 3.x + $ virtualenv --python=python2 /tmp/pyxed-venv # Python 2.x -#### Python Distools (Python 2 and 3) +Build and install **pyxed**: -Simply build the module: + $ . /tmp/pyxed-venv/bin/activate + $ python setup.py build + $ python setup.py install -```shell script -$ python3 setup.py build -```` +And, last but not least, make sure everything works as expected: + $ pip install pytest + $ pytest tests/ -### MacOS X -Compiling on MacOS X requires the XCode command line utilities to be installed. -Just open a terminal, enter **pyxed**'s top-level directory and run **make**. - -To test that everything works as expected, use the following command: +### Notes on MacOS X -```sh -$ PYTHONPATH=. python examples/dump_asm.py 41414141 -``` +Compiling on MacOS X requires the XCode command line utilities to be installed. Depending on the XED version, you might get the following error when trying to import **pyxed** in your project. -``` -Traceback (most recent call last): - File "", line 1, in -ImportError: dlopen(pyxed.so, 2): Library not loaded: obj/libxed.dylib - Referenced from: pyxed.so - Reason: unsafe use of relative rpath obj/libxed.dylib in pyxed.so with restricted binary -``` + Traceback (most recent call last): + File "", line 1, in + ImportError: dlopen(pyxed.so, 2): Library not loaded: obj/libxed.dylib + Referenced from: pyxed.so + Reason: unsafe use of relative rpath obj/libxed.dylib in pyxed.so with restricted binary This is a problem related to hardcoded **rpath** values in Intel's **libxed.dylib**. To fix it, run the following command after substituting **/path/to/libxed.dylib** with the actual path of **libxed.dylib** in your filesystem. -```sh -$ otool -L pyxed.so | grep libxed.dylib - obj/libxed.dylib -$ install_name_tool -change obj/libxed.dylib /path/to/libxed.dylib pyxed.so -``` + $ otool -L pyxed.so | grep libxed.dylib + obj/libxed.dylib + $ install_name_tool -change obj/libxed.dylib /path/to/libxed.dylib pyxed.so ### Microsoft Windows -Compiling on Microsoft Windows requires Visual Studio to be installed. Just open -a console, enter **pyxed**'s top-level directory and set **PYTHON27_PREFIX** in -**Makefile** to the location where Python is installed on your system. Then, run -the following commands to build a 32-bit binary: +Compiling on Microsoft Windows requires Visual Studio to be installed. -``` -C:\pyxed> "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\vcvarsall.bat" -C:\pyxed> nmake /F Makefile.nmake -``` +First set `PYTHON27_PREFIX` and `XED_PREFIX` in **Makefile.nmake** to the location +of Python and XED on your system accordingly. Then, run the following commands +to build a 32-bit binary: + + C:\pyxed> "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\vcvarsall.bat" + C:\pyxed> nmake /F Makefile.nmake Or the following to build a 64-bit binary: -``` -C:\pyxed> "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\vcvarsall.bat" amd64 -C:\pyxed> nmake /F Makefile.nmake -``` + C:\pyxed> "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\vcvarsall.bat" amd64 + C:\pyxed> nmake /F Makefile.nmake -In newer versions of Visual Studio you might need to replace the **amd64** -argument with **x86\_amd64**. +In newer versions of Visual Studio you might need to replace the `amd64` argument +with `x86_amd64`. ### Compiling for use with IDAPython @@ -103,25 +87,14 @@ appropriate Python version. For example, on my MacOS X system, **IDAPython** runs on Python 2.6.x: -``` -Python>sys.version -2.6.7 (r267:88850, Oct 11 2012, 20:15:00) -[GCC 4.2.1 Compatible Apple Clang 4.0 (tags/Apple/clang-418.0.60)] -``` + Python>sys.version + 2.6.7 (r267:88850, Oct 11 2012, 20:15:00) + [GCC 4.2.1 Compatible Apple Clang 4.0 (tags/Apple/clang-418.0.60)] To make **pyxed** work correctly I had to replace **python2.7-config** with **python2.6-config** in **Makefile**. -### Precompiled binaries - -Experimental precompiled binaries for Microsoft Windows can be downloaded from -[here](https://www.grhack.net/pyxed-vs2012-xed_2016_02_02.tgz). The tarball -includes both a 32-bit and a 64-bit release of **pyxed**. - -Debian packages are also planned for the near future. - - ## Using pyxed For information on how to use **pyxed**, have a look at **examples/**. @@ -130,8 +103,7 @@ If your compiler throws a warning, if you happen to hit a bug, or if you have any comments or suggestions please let me know. -## References - - * XED [downloads](https://software.intel.com/en-us/articles/xed-x86-encoder-decoder-software-library) - * XED [documentation](https://software.intel.com/sites/landingpage/xed/ref-manual/html/index.html) +# Links + * XED [source code](https://github.com/intelxed) + * XED [documentation](https://intelxed.github.io/) diff --git a/TODO b/TODO index a4e772f..d0f7bf8 100644 --- a/TODO +++ b/TODO @@ -1,4 +1,3 @@ 2014-12-23 huku * Add new class `pyxed.Encoder'. -