From ed3bab7a26c86841171006ce9ef96a87fdfb415b Mon Sep 17 00:00:00 2001 From: wargio Date: Thu, 17 Aug 2023 21:04:12 +0800 Subject: [PATCH] Fix readme --- DEVELOPERS.md | 91 +++++++++++++++++----------------- README.md | 135 ++++++++------------------------------------------ 2 files changed, 68 insertions(+), 158 deletions(-) diff --git a/DEVELOPERS.md b/DEVELOPERS.md index 962e9b7..9cf4a0b 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -4,49 +4,47 @@ ## Extending jsdec arch -First of all when you need to add a new architecture, you need to create a new `.js` file inside `libdec/arch/`. +First of all when you need to add a new architecture, you need to create a new `.js` file inside `js/libdec/arch/`. -For example `libdec/arch/arch9999.js` and it needs to follow the minimal base javascript template: +For example `js/libdec/arch/arch9999.js` and it needs to follow the minimal base javascript template: ```js -(function() { // lgtm [js/useless-expression] - const Base = require('libdec/core/base'); - const Variable = require('libdec/core/variable'); - const Extra = require('libdec/core/extra'); - return { - instructions: { - add: function(instr, context, instructions) { - return Base.add(instr.parsed.opd[0], instr.parsed.opd[1], instr.parsed.opd[2]); - }, - nop: function() { - return Base.nop(); - }, - invalid: function(instr, context, instructions) { - return Base.nop(); - } +import Base from '../core/base.js'; +import Variable from '../core/variable.js'; +import Extra from '../core/extra.js'; +return { + instructions: { + add: function(instr, context, instructions) { + return Base.add(instr.parsed.opd[0], instr.parsed.opd[1], instr.parsed.opd[2]); }, - parse: function(assembly) { - var tokens = assembly.trim().split(' '); - return { mnem: tokens.shift(), opd: tokens }; + nop: function() { + return Base.nop(); }, - context: function() { - return { cond: { a: '?', b: '?' } }; - }, - preanalisys: function(instructions, context) {}, - postanalisys: function(instructions, context) {}, - localvars: function(context) { - return []; - }, - globalvars: function(context) { - return []; - }, - arguments: function(context) { - return []; - }, - returns: function(context) { - return 'void'; + invalid: function(instr, context, instructions) { + return Base.nop(); } - }; -}); + }, + parse: function(assembly) { + var tokens = assembly.trim().split(' '); + return { mnem: tokens.shift(), opd: tokens }; + }, + context: function() { + return { cond: { a: '?', b: '?' } }; + }, + preanalisys: function(instructions, context) {}, + postanalisys: function(instructions, context) {}, + localvars: function(context) { + return []; + }, + globalvars: function(context) { + return []; + }, + arguments: function(context) { + return []; + }, + returns: function(context) { + return 'void'; + } +}; ``` After saving the new arch (`arch9999.js` in the example), you need to add this arch to the file `libdec/Archs.js`. @@ -54,13 +52,16 @@ The new architecture needs to have the same name as the cmd `e asm.arch`, becaus For example: ```js -(function() { - return { - arm: require('libdec/arch/arm'), - arch9999: require('libdec/arch/arch9999'), - x86: require('libdec/arch/x86') - }; -}); + +import arm from './arch/arm.js'; +import x86 from './arch/x86.js'; +import arch9999 from './arch/arch9999.js'; + +export default { + arm: arm, + arch9999: arch9999, + x86: x86 +}; ``` ## Codebase: diff --git a/README.md b/README.md index ad21dbb..318f7e5 100644 --- a/README.md +++ b/README.md @@ -11,23 +11,22 @@ Converts asm to pseudo-C code. Requires [rizin](https://github.com/rizinorg/rizin). -# Install system wide - -Follow the following steps to install jsdec - - clone this repository - - Run `cd p` - - Run `meson -Djsc_folder=".." --prefix=/usr build` to create the build folder - - Run `ninja -C build install` to build the shared library and to install it - - # Install in home folder (or in other paths) If you want to install in the HOME folder or in other non standard paths, just set the `prefix` to a different value - Run `cd p` - - Run ``meson -Djsc_folder=".." --prefix=~/.local build`` + - Run ``meson --prefix=~/.local build`` - Run `ninja -C build install` +# Install system wide + +Follow the following steps to install jsdec + - clone this repository + - Run `cd p` + - Run `meson --prefix=/usr build` to create the build folder + - Run `ninja -C build install` to build the shared library and to install it + # Usage * Open your file with rizin @@ -37,34 +36,18 @@ set the `prefix` to a different value # Arguments ``` -[0x00000000]> pdd?Usage: pdd [args] - core plugin for jsdec - pdd - decompile current function - pdd? - show this help - pdd* - the decompiled code is returned to rizin as comment (via CCu) - pdda - decompile current function side by side with assembly - pddb - decompile current function but shows only scopes - pddo - decompile current function side by side with offsets - pddi - generates the issue data - -Environment - JSDEC_HOME defaults to the root directory of the jsdec repo - -[0x00000000]> pdd --help - -jsdec [options] - --help | this help message - --assembly | shows pseudo next to the assembly - --blocks | shows only scopes blocks - --casts | shows all casts in the pseudo code - --colors | enables syntax colors - --debug | do not catch exceptions - --html | outputs html data instead of text - --issue | generates the json used for the test suite - --offsets | shows pseudo next to the assembly offset - --paddr | all xrefs uses physical addresses instead of virtual addresses - --xrefs | shows also instruction xrefs in the pseudo code - --as-comment | the decompiled code is returned to rizin as comment (via CCu) - --as-opcode | the decompiled code is returned to rizin as opcode (via aho) +[0x00000000]> pdd? +Usage: pdd[?] # Core plugin for jsdec +| pdd # decompile current function +| pddt # lists the supported architectures +| pdda # decompile current function with side assembly +| pddA # decompile current function with annotation output +| pddb # decompile current function but show only scopes +| pddc # decompiled code is returned to rizin as 'file:line code' (via CL) +| pddf # decompile all functions +| pddi # generate issue data +| pddj # decompile current function as json +| pddo # decompile current function side by side with offsets ``` # Evaluable vars @@ -102,7 +85,7 @@ e scr.color | enables syntax colors. PowerPC 32/64 bit (VLE included) RISC-V Sparc - superh (experimental) + SuperH (experimental) v850 WebAssembly (experimental) x86/x64 @@ -111,77 +94,3 @@ e scr.color | enables syntax colors. [Read DEVELOPERS.md](https://github.com/rizinorg/jsdec/blob/master/DEVELOPERS.md) -## Example - -This example shows a possible dump of the plugin. - -### Source Code - -```c -#include - -int main(int argc, char const *argv[]) { - int var = 0; - while(var < 0x90) { - if(var < 0x10) { - var += 0x50; - } - var += 0x10; - } - return 0; -} -``` - -### rizin view - - -``` -╭ (fcn) main 50 -│ main (int arg1, int arg2); -│ ; var int local_20h @ rbp-0x20 -│ ; var int local_14h @ rbp-0x14 -│ ; var signed int local_4h @ rbp-0x4 -│ ; DATA XREF from entry0 (0x1041) -│ 0x00001119 55 push rbp -│ 0x0000111a 4889e5 mov rbp, rsp -│ 0x0000111d 897dec mov dword [local_14h], edi ; arg1 -│ 0x00001120 488975e0 mov qword [local_20h], rsi ; arg2 -│ 0x00001124 c745fc000000. mov dword [local_4h], 0 -│ ╭─< 0x0000112b eb0e jmp 0x113b -│ │ ; CODE XREF from main (0x1142) -│ ╭──> 0x0000112d 837dfc0f cmp dword [local_4h], 0xf ; [0xf:4]=0x3e000300 -│ ╭───< 0x00001131 7f04 jg 0x1137 -│ │⋮│ 0x00001133 8345fc50 add dword [local_4h], 0x50 ; 'P' -│ │⋮│ ; CODE XREF from main (0x1131) -│ ╰───> 0x00001137 8345fc10 add dword [local_4h], 0x10 -│ ⋮│ ; CODE XREF from main (0x112b) -│ ⋮╰─> 0x0000113b 817dfc8f0000. cmp dword [local_4h], 0x8f ; [0x8f:4]=0x2a800 -│ ╰──< 0x00001142 7ee9 jle 0x112d -│ 0x00001144 b800000000 mov eax, 0 -│ 0x00001149 5d pop rbp -╰ 0x0000114a c3 ret -``` - -### jsdec pseudo-C code - -```c -/* jsdec pseudo C output */ -#include - -int32_t main (int32_t argc, char ** argv) { - char ** local_20h; - int32_t local_14h; - int32_t local_4h; - local_14h = edi; - local_20h = rsi; - local_4h = 0; - while (local_4h <= 0x8f) { - if (local_4h <= 0xf) { - local_4h += 0x50; - } - local_4h += 0x10; - } - eax = 0; - return eax; -} -```