asmsh/src/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
loop . - 4
</pre>

@par Labels
Labels can be defined to ease relative jumps using the ".label" command.
Labels are used using "@NAME" notation, they are substituted with
". SIGN OFFSET" with SIGN and OFFSET calculated from RIP value.

@par Example
The instruction "loop @lbl" could be transformed in "loop . - 8"

@section shell_cmds COMMANDS

@par .breakpoint [CMD] [OPTS...]
Handle breakpoint with different subcommands :
- add (implicit) add a breakpoint at given address (or RIP value if no address given)
- del remove a breakpoint at given address (or RIP)
- list list all breakpoints
@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 .label [NAME] [ADDR]
Handle labels :
- if no name given all labels are displayed.
- if a name is given without address, a label is set at RIP value
- if address is 0, the label is deleted
@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 Files

@par ~/.local/share/asmsh/asmsh.history
The command history file

@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 > .breakpoint after loop . -4
INFO: Set breakpoint @ 00007F3020BEC00B
asmsh@0x7f3020bec005 > .run
INFO: Breakpoint 00007f3020bec00b reached
asmsh@0x7f3020bec00b > .regs \%rbx
rbx: 0000000000000042
</pre>

@subsection label_loop Make a loop using a label

<pre>
asmsh@0x7f0fadb73000 > mov $27, \%rcx
asmsh@0x7f0fadb73005 > .label print
INFO: Label '@print' 00007f0fadb73005 added
asmsh@0x7f0fadb73005 > push \%rcx
asmsh@0x7f0fadb73006 > mov $27,\%rbx
asmsh@0x7f0fadb7300b > sub \%rcx, \%rbx
asmsh@0x7f0fadb7300e > add $0x0a40, \%rbx
asmsh@0x7f0fadb73015 > push \%rbx
asmsh@0x7f0fadb73016 > mov $1, \%rax
asmsh@0x7f0fadb7301b > mov \%rax, \%rdi
asmsh@0x7f0fadb7301e > mov \%rsp, \%rsi
asmsh@0x7f0fadb73021 > mov $2, \%rdx
asmsh@0x7f0fadb73026 > syscall
@
asmsh@0x7f0fadb73028 > pop \%rbx
asmsh@0x7f0fadb73029 > pop \%rcx
asmsh@0x7f0fadb7302a > .breakpoint after loop @print
INFO: Set breakpoint @ 00007F0FADB7302C
asmsh@0x7f0fadb73005 > .run
[...]
</pre>

@section TODO TODOLIST

@todo Implement command for memory read/dump
@todo Implement write without exec
@todo Implement function declaration
@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 :/)
@todo Enhance support for labels & far/abs jump
@todo Implement a script run mode without the prompt & without readline

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