asmsh/asmsh.h

/**@page asmsh
@brief A shell that runs assembly
@section SYNOPSIS
asmsh [OPTIONS]...
@section DESCRIPTION
A shell designed to run assembly (for the moment only x86_64 is supported).

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

@section man_ui USER INTERFACE

For the moment, the UI is implemented using GNU readline with basic support for
completion (using tab).

The prompt is composed like "asmsh@RIPVAL > " where RIPVAL is the RIP register (
Instruction Pointer ) value in hexadecimal.

Other readline(3) features are available like up arrow to display previous commands,
C^R for history search, etc.

@section INSTRUCTIONS

The shell uses the GNU as compiler from binutils, the instructions syntax
follows GAS syntax.

For the moment GAS can only be used with the AT&T syntax.

Details on x86 syntax can be found in GAS documentation at
<pre>
[https://sourceware.org/binutils/docs-2.40/as.html#i386_002dSyntax]
</pre>

The list & names of the registers can be found at the same place
<pre>
[https://sourceware.org/binutils/docs-2.40/as.html#i386_002dRegs]
</pre>

The list & documentation of the instructions for the x86_64 platform can be
found in the 1st volume of "AMD64 Architecture Programmer’s Manual", in section
3.3 Instruction summary
<pre>
[https://www.amd.com/en/support/tech-docs/amd64-architecture-programmers-manual-volumes-1-5]
</pre>

Or in the Intel's equivalent document, namely the 
"Intel® 64 and IA-32 Architectures Software Developer’s Manual"
<pre>
[https://cdrdv2-public.intel.com/774494/325462-sdm-vol-1-2abcd-3abcd.pdf]
</pre>

@subsection man_reljmp 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 :

<pre>
jmp . - 8
jnz . + 32
</pre>

@section shell_cmds COMMANDS

@par .bytecode
Compile an instruction and display it's bytecode
@par .flags
Display the CPU flags
@par .help [COMMAND]
Display the builtin help or the help of the command gioven as argument
@par .maps
Display process memory maps
@par .quit
Exit the shell
@par .regs
Display the CPU registers values
@par .syscalls
Print syscalls names and numbers
@par .reset
Reset the shell (spawn a new process)

@section EXAMPLES

@subsection example_exit Exit with a specific status

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

@subsection example_hello Print a message to stdout

<pre>
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 > 
</pre>

@subsection example_loop Make a loop and use commands

<pre>
asmsh@0x7f3020bec000 > .regs \%rbx
rbx: 0000000000000000
asmsh@0x7f3020bec000 > mov $6, \%rcx
asmsh@0x7f3020bec005 > add $0xb, \%rbx
asmsh@0x7f3020bec009 > loop . -4
asmsh@0x7f3020bec005 > .bytecode loop . -4
loop . -4 = ( 2 Bytes) e2fa.... ........  ........ ......
asmsh@0x7f3020bec005 > .breakpoint . + 6
INFO: Set breakpoint @ 00007F3020BEC00B
asmsh@0x7f3020bec005 > .run
INFO: Breakpoint 00007f3020bec00b reached
asmsh@0x7f3020bec00b > .regs \%rbx
rbx: 0000000000000042
</pre>

@section TODO TODOLIST

@todo Implement command for memory read/dump
@todo Implement symbols for jumps
@todo Add support for label declarations & references
@todo Implement write without exec
@todo Implement function declaration
@todo Add switch between intel's & AT&T's syntaxes.
@todo Implement a command to run until syscall only (and another for run until
		breakpoint or syscall ?)
@todo Rationalise commands argument parsing (at the moment .breakpoints allready uses special stuff :/)

@section AUTHOR
Written by Yann Weber &lt;yann.weber@members.fsf.org&gt;

@section COPYRIGHT
Copyright  ©  2023  Weber Yann  License GPLv3+: GNU GPL version 3 or later 
&lt;http://gnu.org/licenses/gpl.html>.

This is free software: you are free  to  change  and  redistribute  it.
There is NO WARRANTY, to the extent permitted by law.

*/

/**@mainpage
 * @brief Asmsh a shell that runs assembly
 *
 * @section Description
 *
 * A simple programm is spawned by the shell, and each instructions are runned in the
 * subprocess environment.
 */