0.1HEADmaster

1 files changed, 83 insertions, 0 deletions

diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..d8d410a
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,83 @@
+asm.sh
+======
+
+asm.sh is an assembler embedded into POSIX shell. It defines functions for
+all (supported) i386 instructions.
+
+It generally follows AT&T syntax, modified in many places to avoid characters
+reserved by the shell. Arguments are separated by spaces, no comma allowed
+(as usual in shell). Width suffixes are generally mandatory.
+
+Labels
+------
+
+There are two kinds of label: Global and local labels.
+
+Global labels are defined with the `label' function, e.g.:
+
+label _start
+
+They must be globally unique. Global labels are referred to by their name,
+e.g. `_start'.
+
+They can also be relative; the following defines a label `offset' whose value
+is the difference between the current location and the value of the label
+`base':
+
+label offset base
+
+Local labels are defined with the `L' function, e.g.:
+
+L loop
+
+There can be several definitions of a local label. There are two ways to
+refer to a local label:
+
+- `loop^' refers to the previous declaration of the label
+- `loop.' refers to the next declaration of the label
+
+Operands
+--------
+
+Immediates: Either a label, or an integer literal in decimal, octal
+(preceded by 0) or hexadecimal (preceded by 0x).
+
+Registers: Preceded by `%' as in AT&T, e.g. `%eax'.
+
+Memory operands: Start with `@', followed by a sum expression. Examples:
+
+                  AT&T | asm.sh
+    -------------------|-------------------
+                 0x100 | @0x100
+                 label | @label
+               4(%eax) | @%eax+4
+              4(,%eax) | @1%eax+4
+           14(,%eax,2) | @14+2%eax
+           (%eax,%ebx) | @%eax+%ebx
+           (%ebx,%eax) | @%ebx+%eax
+           (%ebx,%eax) | @1%eax+%ebx
+       12(%ebx,%eax,8) | @%ebx+8%eax+12
+
+  The order of the summands is generally irrelevant, except that if there are
+  two unscaled registers, the first is taken to be the base and the second
+  the index. Displacement can be a label, scale must be one of the literal
+  characters 1, 2, 4, or 8 (or omitted, implicitly 1).
+
+Calling convention
+==================
+
+The first three arguments are passed in %eax, %ecx and %edx. Remaining
+arguments are passed on the stack in right-to-left order (last argument is
+pushed first), and cleaned up by the callee.
+
+The return value currently always fits in three registers; it is placed in
+%eax, %ecx, and %edx. Some functions also modify EFLAGS, e.g. streq sets
+ZF iff the strings are equal.
+
+Functions may clobber %eax, %ecx and %edx. Stack must be 4-byte aligned.
+
+Porting
+=======
+
+To port to other operating systems, it should be sufficient to modify asm.sh
+(for the ELF header) and start.asm (for system calls etc).