# 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)](https://sourceware.org/binutils/docs-2.40/as/index.html)
from
[GNU Binutils](https://www.gnu.org/software/binutils/), consequently
 instructions syntax follows GAS syntax.
 
For the moment the shell can only be used in
[AT&T syntax](https://sourceware.org/binutils/docs-2.40/as/i386_002dVariations.html).

#### Assembly syntax

Informations on x86 syntax can be found in
[GAS documentation](https://sourceware.org/binutils/docs-2.40/as.html#i386_002dSyntax)

#### x86_64 assembly documentation

The list and names of the registers can be found in
[GAS documentation](https://sourceware.org/binutils/docs-2.40/as.html#i386_002dRegs) too.

The instructions list and documentation can be found in the *1st volume* of
[AMD64 Architecture Programmer’s Manual](https://www.amd.com/en/support/tech-docs/amd64-architecture-programmers-manual-volumes-1-5), in *section 3.3 Instruction summary* or in the Intel's
equivalent document,
[Intel® 64 and IA-32 Architectures Software Developer’s Manual](https://cdrdv2-public.intel.com/774494/325462-sdm-vol-1-2abcd-3abcd.pdf).

#### 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 :

```asm
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](https://www.kernel.org/)
* [GNU Binutils](https://www.gnu.org/software/binutils/) (GNU `as`)
* [libreadline](https://tiswww.case.edu/php/chet/readline/rltop.html)

## Compilation

### Dependencies

* [GCC](https://www.gnu.org/software/gcc/)
* GNU "Autotools"
  * [make](https://www.gnu.org/software/make/)
  * [autoconf](https://www.gnu.org/software/autoconf/)
  * [automake](https://www.gnu.org/software/automake/)
* [GNU Binutils](https://www.gnu.org/software/binutils/) (GNU `as`)
* [libreadline](https://tiswww.case.edu/php/chet/readline/rltop.html) headers
  
*Optionals dependencies* :
* [check](https://libcheck.github.io/check/)
* [lcov](https://github.com/linux-test-project/lcov.git)
* [Doxygen](http://www.doxygen.nl/)

### From a release tarball

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

### From the git repository

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


## Examples

**Exit with a specific status**

```text
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**

```text
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**

```text
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`](https://libcheck.github.io/check/)*

```
make -j8 checks
```

If [`lcov`](https://github.com/linux-test-project/lcov.git) is installed unit-tests
will generate a coverage report in `lcov_html/index.html`

**Generate the documentation only**

*Needs [Doxygen](http://www.doxygen.nl/)*
```
make doxygen
```