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 UI

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.

@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>

@section TODO TODOLIST

@todo Implement breakpoints
@todo Implement symbols for jumps
@todo Implement write without exec
@todo Implement function declaration
@todo Implement command for memory read/dump
@todo Add switch between intel's & AT&T's syntaxes.
@todo Add support for label declarations & references

@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.
 */