asmsh/README.md

amsh : a shell that runs assembly

Description

A shell designed to run assembly (for the moment only x86_64 is supported).

A simple program is spawned by the shell, and each instructions are runned in the subprocess environment.

Instructions

The shell uses the GNU assembler as (GAS) from GNU Binutils, consequently instructions syntax follows GAS syntax.

For the moment the shell can only be used in AT&T syntax.

Assembly syntax

Informations on x86 syntax can be found in GAS documentation

x86_64 assembly documentation

The list and names of the registers can be found in GAS documentation too.

The instructions list and documentation can be found in the 1st volume of AMD64 Architecture Programmer’s Manual, in section 3.3 Instruction summary or in the Intel’s equivalent document, Intel® 64 and IA-32 Architectures Software Developer’s Manual.

Relative jumps

For the moment there is no way to define symbols, so jumps can only be relative to the current address. The current address is expressed with the "." character in an expression.

Relative jumps can be expressed using the syntax :

jmp . - 8
jnz . + 32
loop . - 4

Commands

Shell commands starts with the “.” symbol. You can list all commands using .help or quit the shell using .quit.

Dependencies

• Linux
• GNU Binutils (GNU as)
• libreadline

Compilation

Dependencies

• GCC
• GNU “Autotools”
  • make
  • autoconf
  • automake
• GNU Binutils (GNU as)
• libreadline headers
  

Optionals dependencies :

• check
• lcov
• Doxygen

From a release tarball

tar -xvf asmsh*.tar.gz
cd asmsh*
./configure
make  -j6
./src/asmsh

From the git repository

git clone https://git.yannweb.net/yannweb/asmsh.git
cd asmsh
./regen.sh
./configure
make -j6
./src/asmsh

Examples

Exit with a specific status

asmsh@0x7f55d2433000 > mov $60, %rax
asmsh@0x7f55d2433005 > mov $0x2a, %rdi
asmsh@0x7f55d243300a > syscall
Child exited with status 42
Exit with status 42

Print a message to stdout

asmsh@0x7f6e312e5000 > mov $0x0a6f6c6c, %rax
asmsh@0x7f6e312e5005 > shl $(8*2), %rax
asmsh@0x7f6e312e5009 > or $0x6548, %rax
asmsh@0x7f6e312e500f > push %rax
asmsh@0x7f6e312e5010 > mov $1, %rax
asmsh@0x7f6e312e5015 > mov %rax, %rdi
asmsh@0x7f6e312e5018 > mov %rsp, %rsi
asmsh@0x7f6e312e501b > mov $6, %rdx
asmsh@0x7f6e312e5020 > syscall
Hello
asmsh@0x7f6e312e5022 > 

Make a loop and use commands

asmsh@0x7f3020bec000 > .regs %rbx
rbx: 0000000000000000
asmsh@0x7f3020bec000 > mov $6, %rcx
asmsh@0x7f3020bec005 > add $0xb, %rbx
asmsh@0x7f3020bec009 > .breakpoint after loop . -4
INFO: Set breakpoint @ 00007F3020BEC00B
asmsh@0x7f3020bec005 > .run
INFO: Breakpoint 00007f3020bec00b reached
asmsh@0x7f3020bec00b > .regs %rbx
rbx: 0000000000000042

Tests & docs

Run tests and coverage

Needs check

make -j8 checks

If lcov is installed unit-tests will generate a coverage report in lcov_html/index.html

Generate the documentation only

Needs Doxygen

make doxygen