Enhancement in documentation

Makefile.am

@@ -75,3 +75,5 @@ checks: $(ALL_CHECKS)
 
 lint: $(LINT)
 
+doxygen:
+	$(MAKE) -C docs

asm_env.h

@@ -96,8 +96,10 @@ int asmsh_env_write_code(asmsh_env_t *env, asmsh_bytecode_t *bcode);
 
 /** Run the next instruction
  * @param asmsh_env_t* The run environment
- * @param int* If not null will be set to the status of the child PID (error cases)
- * @return 0 if no error from the child pid else -1 and wstatus is set to the child status
+ * @param int* If not null will be set to the status of the child PID (error
+ * cases)
+ * @return 0 if no error else -1, if the child is not trapped as expected, 1 is
+ * returned and wstatus is set to the child status (see man 2 waitpid)
  */
 int asmsh_env_step(asmsh_env_t *env, int *status);
 

asmsh.h

@@ -3,11 +3,101 @@
 @section SYNOPSIS
 asmsh [OPTIONS]...
 @section DESCRIPTION
-A shell designed to run assembly.
+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>
+
+@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 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;