Update

assembly.md

@@ -8,11 +8,13 @@ The most common assembly languages you'll encounter nowadays are **[x86](x86.md)
 
 To be precise, a typical assembly language is actually more than a set of nicknames for machine code instructions, it may offer helpers such as [macros](macro.md) (something aking the C preprocessor), pseudoinstructions (commands that look like instructions but actually translate to e.g. multiple instructions), [comments](comment.md), directives, named labels for jumps (as writing literal jump addresses would be extremely tedious) etc.
 
+Assembly is extremely low level, so you get no handholding or much programming "safety" (apart from e.g. CPU operation modes), you have to do everything yourself -- you'll be dealing with things such as function [call conventions](call_convention.md), [interrupts](interrupt.md), [syscalls](syscall.md) and their conventions, memory segments, [endianness](endianness.md), raw addresses/[goto](goto.md) jumps, call frames etc.
+
 ## Typical Assembly Language
 
 Assembly languages are usually unstructured, i.e. there are no control structures such as `if` or `while` statements: these have to be manually implemented using labels and jump ([goto](goto.md)) instructions. There may exist macros that mimic control structures. The typical look of an assembly program is however still a single column of instructions with arguments, one per line.
 
-The working of the language reflects the actual [hardware](hardware.md) architecture -- usually there is a small number (something like 16) of [registers](register.md) which may be called something like R0 to R15, or A, B, C etc. Sometimes registers may even be subdivided (e.g. in x86 there is an *eax* 32bit register and half of it can be used as the *ax* 16bit register). These registers are the fastest available memory (faster than the main RAM memory) and are used to perform calculations. Some registers are general purpose and some are special: typically there will be e.g. the FLAGS register which holds various 1bit results of performed operations (e.g. [overflow](overflow.md), zero result etc.). Some instructions may only work with some registers (e.g. there may be kind of a "[pointer](pointer.md)" register used to hold addresses along with instructions that work with this register, which is meant to implement [arrays](array.md)). Values can be moved between registers and the main memory.
+The working of the language reflects the actual [hardware](hardware.md) architecture -- most architectures are based on [registers](register.md) so usually there is a small number (something like 16) of registers which may be called something like R0 to R15, or A, B, C etc. Sometimes registers may even be subdivided (e.g. in x86 there is an *eax* 32bit register and half of it can be used as the *ax* 16bit register). These registers are the fastest available memory (faster than the main RAM memory) and are used to perform calculations. Some registers are general purpose and some are special: typically there will be e.g. the FLAGS register which holds various 1bit results of performed operations (e.g. [overflow](overflow.md), zero result etc.). Some instructions may only work with some registers (e.g. there may be kind of a "[pointer](pointer.md)" register used to hold addresses along with instructions that work with this register, which is meant to implement [arrays](array.md)). Values can be moved between registers and the main memory.
 
 Instructions are typically written as three-letter abbreviations and follow some unwritten naming conventions so that different assembly languages at least look similar. Common instructions found in most assembly languages are for example:
 
@@ -23,4 +25,27 @@ Instructions are typically written as three-letter abbreviations and follow some
 - NOP (no operation): do nothing (used e.g. for delays).
 - CMP (compare): compare two numbers and set relevant flags (typically for a subsequent conditional jump).
 
-Assembly languages may offer simple helpers such as macros.
+Assembly languages may offer simple helpers such as macros.
+
+## Example
+
+TODO: some C code and how it translates to different assembly langs
+
+```
+#include <stdio.h>
+
+char incrementDigit(char d)
+{
+  return
+    d >= '0' && d < '9' ?
+    d + 1 :
+    '?';
+}
+
+int main(void)
+{
+  char c = getchar();
+  putchar(incrementDigit(c));
+  return 0;
+}
+```