Started to document instructions and updated encoding formats (colors + added conditions)

src/execution-engine-spec/glossary.adoc

@@ -4,7 +4,7 @@
 [glossary]
 [horizontal]
 Processing Complex::
-    Composed of a _Processing Unit_, memory modules and subsystems that are not located inside of the _Processing Unit_ (e.g. Channel I/O Subsytem, Hardware Management Subsystem).
+    Composed of a _Processing Unit_, memory modules and subsystems that are not located inside of the _Processing Unit_ (e.g. Channel I/O Subsystem, Hardware Management Subsystem).
     The name applies both to the hardware enclosure and the hardware inside said enclosure.
 
 Processing Unit::

src/execution-engine-spec/images/instruction-formats.adoc

@@ -1,48 +1,60 @@
 [wavedrom, ,svg]
 ....
 {reg: [
-  {bits: 7,  name: 'opcode'},
+  {bits: 7,  name: 'opcode', type: 8},
-  {bits: 5,  name: 'rd'},
+  {bits: 4, name: 'cond', type: 6},
-  {bits: 5,  name: 'rs1'},
+  {bits: 5,  name: 'rd', type: 2},
-  {bits: 5,  name: 'rs2'},
+  {bits: 5,  name: 'rs1', type: 4},
-  {bits: 10,  name: 'imm'}
+  {bits: 5,  name: 'rs2', type: 4},
+  {bits: 6,  name: 'imm', type: 5}
 ], config: {label: {right: 'A-Type'}}}
 ....
 
 [wavedrom, ,svg]
 ....
 {reg: [
-  {bits: 7,  name: 'opcode'},
+  {bits: 7,  name: 'opcode', type: 8},
-  {bits: 5,  name: 'rd'},
+  {bits: 4, name: 'cond', type: 6},
-  {bits: 5,  name: 'rs1'},
+  {bits: 5,  name: 'rd', type: 2},
-  {bits: 15,  name: 'imm'}
+  {bits: 5,  name: 'rs1', type: 4},
+  {bits: 11,  name: 'imm', type: 5}
 ], config: {label: {right: 'B-Type'}}}
 ....
 
 [wavedrom, ,svg]
 ....
 {reg: [
-  {bits: 7,  name: 'opcode'},
+  {bits: 7,  name: 'opcode', type: 8},
-  {bits: 5,  name: 'rd'},
+  {bits: 4, name: 'cond', type: 6},
-  {bits: 20,  name: 'imm'}
+  {bits: 5,  name: 'rd', type: 2},
+  {bits: 16,  name: 'imm', type: 5}
 ], config: {label: {right: 'C-Type'}}}
 ....
 
 [wavedrom, ,svg]
 ....
 {reg: [
-  {bits: 7,  name: 'opcode'},
+  {bits: 7,  name: 'opcode', type: 8},
-  {bits: 25,  name: 'imm'}
+  {bits: 4, name: 'cond', type: 6},
-], config: {label: {right: 'D-Type'}}}
+  {bits: 21,  name: 'imm', type: 5}
+], config: {label: {right: 'D1-Type'}}}
 ....
 
 [wavedrom, ,svg]
 ....
 {reg: [
-  {bits: 7,  name: 'opcode'},
+  {bits: 7,  name: 'opcode', type: 8},
-  {bits: 5,  name: 'reg'},
+  {bits: 25,  name: 'imm', type: 5}
-  {bits: 4,  name: 'sid'},
+], config: {label: {right: 'D2-Type'}}}
-  {bits: 8,  name: 'sre'},
+....
-  {bits: 8,  name: 'cmd'}
+
+[wavedrom, ,svg]
+....
+{reg: [
+  {bits: 7,  name: 'opcode', type: 8},
+  {bits: 5,  name: 'reg', type: 2},
+  {bits: 4,  name: 'sid', type: 7},
+  {bits: 8,  name: 'sre', type: 2},
+  {bits: 8,  name: 'cmd', type: 8}
 ], config: {label: {right: 'E-Type'}}}
 ....

src/execution-engine-spec/instructions.adoc

@@ -7,17 +7,23 @@ For instruction encoding formats that contain an immediate value, not all immedi
 
 include::images/instruction-formats.adoc[]
 
-.Bit ranges legend
+.Format fields
+[horizontal]
 opcode::
     The operation to carry on.
+cond::
+    Condition code. +
+    #TODO: Define conditions encoding.#
 rd::
-    Destination register.
+    Destination register. +
+    #TODO: Define registers encoding.#
 rs1::
     Source register 1.
 rs2::
     Source register 2.
 imm::
     Immediate value.
+    Can be interpreted as signed or unsigned depending on the instruction.
 reg::
     Source/destination register on the _Execution Engine_ side.
 sid::
@@ -30,3 +36,135 @@ cmd::
 === Instruction list
 #TODO: List instructions#
 
+* NOP instruction
+* memory load/store instructions
+* register move instructions
+* arithmetic instructions
+* bitwise operations instructions (w/ bit shifts)
+* comparison instructions
+* jump instructions
+* system mode instructions (svc, uret, sret, ...)
+* subsystems instructions (ssr & ssw)
+
+==== The NOP instruction
+[wavedrom, ,svg]
+....
+{reg: [
+  {bits: 7,  name: 0x0, type: 8, attr: '0x0'},
+  {bits: 25, name: 'unused'}
+], config: {label: {right: 'NOP'}}}
+....
+
+Description::
+    Does nothing. Can be used to align a block of instructions.
+Encoding:: D2-Type
+Assembler syntax::
+[source]
+----
+nop
+----
+Privileged instruction:: No.
+Updates program state flags:: No.
+Exceptions:: None.
+
+==== Memory-related instructions
+===== LDR: Load Register
+[wavedrom, ,svg]
+....
+{reg: [
+  {bits: 7,  name: 0x1, type: 8, attr: '0x1'},
+  {bits: 4, name: 'cond', type: 6},
+  {bits: 5,  name: 'dst', type: 2},
+  {bits: 5,  name: 'src', type: 4},
+  {bits: 11,  name: 'off', type: 5}
+], config: {label: {right: 'LDRIR'}}}
+....
+
+[wavedrom, ,svg]
+....
+{reg: [
+  {bits: 7,  name: 0x2, type: 8, attr: '0x2'},
+  {bits: 4, name: 'cond', type: 6},
+  {bits: 5,  name: 'dst', type: 2},
+  {bits: 5,  name: 'src', type: 4},
+  {bits: 11,  name: 'off', type: 5}
+], config: {label: {right: 'LDRIRW'}}}
+....
+
+[wavedrom, ,svg]
+....
+{reg: [
+  {bits: 7,  name: 0x3, type: 8, attr: '0x3'},
+  {bits: 4, name: 'cond', type: 6},
+  {bits: 5,  name: 'dst', type: 2},
+  {bits: 5,  name: 'src', type: 4},
+  {bits: 11,  name: 'off', type: 5}
+], config: {label: {right: 'LDRIOW'}}}
+....
+
+[wavedrom, ,svg]
+....
+{reg: [
+  {bits: 7,  name: 0x4, type: 8, attr: '0x4'},
+  {bits: 4, name: 'cond', type: 6},
+  {bits: 5,  name: 'dst', type: 2},
+  {bits: 5,  name: 'src', type: 4},
+  {bits: 5,  name: 'off', type: 4},
+  {bits: 6,  name: 'unused'}
+], config: {label: {right: 'LDRR'}}}
+....
+
+[wavedrom, ,svg]
+....
+{reg: [
+  {bits: 7,  name: 0x5, type: 8, attr: '0x5'},
+  {bits: 4, name: 'cond', type: 6},
+  {bits: 5,  name: 'dst', type: 2},
+  {bits: 5,  name: 'src', type: 4},
+  {bits: 5,  name: 'off', type: 4},
+  {bits: 6,  name: 'unused'}
+], config: {label: {right: 'LDRRW'}}}
+....
+
+[wavedrom, ,svg]
+....
+{reg: [
+  {bits: 7,  name: 0x6, type: 8, attr: '0x6'},
+  {bits: 4, name: 'cond', type: 6},
+  {bits: 5,  name: 'dst', type: 2},
+  {bits: 5,  name: 'src', type: 4},
+  {bits: 5,  name: 'off', type: 4},
+  {bits: 6,  name: 'unused'}
+], config: {label: {right: 'LDROW'}}}
+....
+
+====== LDRIR: Load Register Immediate Pre-indexed
+Description::
+    Loads a word from memory into a register.
+    The immediate offset `off` is added to the address in the `src` register before reading memory.
+Encoding:: A-Type
+Assembler syntax::
++
+[source]
+----
+ldr{cond} dst, [src, off]
+----
+Examples::
++
+[source]
+----
+ldr    r1, [r0]    ; Reads a word from the memory address in r0 into r1.
+ldr    r3, [r2, 8] ; Reads a word from the memory address in r2, with a 8 bytes
+                   ; offset, into r3.
+ldr.eq r5, [r4]    ; If the last comparison resulted in an 'eq' condition status,
+                   ; then reads a word from the memory address in r4 into r5.
+                   ; Else, does nothing.
+----
+Privileged instruction:: No.
+Updates program state flags:: No.
+Exceptions::
+[horizontal]
+    MemFault:::
+        If the memory address being accessed is invalid, non readable or not paged in.
+        The kernel may update the page table entries and re-execute the instruction without the user application being aware that it failed in the first place.
+

src/execution-engine-spec/intro.adoc

@@ -7,14 +7,14 @@ The {central-arch-name} uses byte-addressable memory.
 While an _Execution engine_ handles data 32-bits wide, memory addresses are only 24-bits wide.
 An _Execution Engine_ can thus address up to 16MB of main memory.
 
-NOTE: We use the terms "`memory`" and "`main memory`" interchangably. Main memory refers to the RAM while we use the term "`secondary memory`" to refer to HDD or SSD storage.
+NOTE: We use the terms "`memory`" and "`main memory`" interchangeably. Main memory refers to the RAM while we use the term "`secondary memory`" to refer to HDD or SSD storage.
 
 At the hardware level, memory accesses are done on a memory-word boundary.
 A memory-word is 32-bits wide and memory accesses should be done at a 32-bits alignment to avoid wasting cycles doing double the amount of memory operations.
 
 NOTE: The term "`memory accesses`" encompasses both read and write operations.
 
-Data is encoded in memory with the little endian scheme.
+Data is encoded in memory in little endian.
 For a given value, the least significant byte (LSB) is stored in the lowest address and the most significant byte (MSB) in the highest.
 
 === System Modes and Privilege Levels
@@ -48,7 +48,7 @@ Supervisor-mode::
     Software executing in this mode provides context switching, I/O, process management and inter-process communications.
 
 Fault-mode::
-    Code executes in this mode when a double fault occurs, i.e. when an exception is generated in system-mode code.
+    Code executes in this mode when a double fault occurs, i.e. when an exception is generated in supervisor-mode code.
     Code executing under this mode can be used to log/report double faults and then reset/halt the system.
     Debug exceptions generated in supervisor-mode code are also handled in this mode, in which case control is passed back to supervisor-mode after handling.
 
@@ -62,7 +62,7 @@ Exceptions thus always suspend user code for the duration of their handling.
 Exceptions can be of two types: *synchronous* and *asynchronous*.
 
 ==== Synchronous Exceptions
-Synchronous exceptions are generated from events originating from inside of the _Execution engine_.
+Synchronous exceptions are generated from events originating from inside of the _Execution Engine_.
 They are a conditional or unconditional response to the execution of an instruction.
 
 SVC::
@@ -84,11 +84,18 @@ Debug::
     * Fetching an instruction located at an address matching a configured _Hardware Breakpoint_,
     * Accessing a memory address matching a configured _Hardware Watchpoint_
 
+SvcDebug::
+    This exception is the same as the *Debug* exception, except it is generated when debug events are encountered while in supervisor-mode.
+
+UnknownInstr::
+    This exception is generated when an unknown instruction failed to be executed.
+    It is important not to ignore this exception as it can be the symptom of a memory corruption bug.
+
 ==== Asynchronous Exceptions
 Asynchronous exceptions are generated from events originating from outside of the _Execution engine_.
 These exceptions enable the system to react to its environment.
 
-HardMgmt::
+HdwrMgmt::
     This exception is generated when the _Hardware Management Console_ communicates with the _Processing Unit_ and that the _Processing Unit_ relays the event to the _Execution Engine_.
     Data can be passed alongside the exception and would be stored in main memory by the _Processing Unit_ communications controller.
 

src/execution-engine-spec/registers.adoc

@@ -1,7 +1,7 @@
 === Registers
 ==== General Purpose Registers
 General purpose registers (GPRs) are used to perform calculations and store intermediate values.
-There are 8 GPRs in an Execution Engine. These registers are named *_r0_* through *_r7_*.
+There are 8 GPRs in an _Execution Engine_. These registers are named *_r0_* through *_r7_*.
 
 ==== Special Purpose Registers
 

src/global-config.adoc

@@ -3,6 +3,6 @@
 :icons: font
 :lang: en
 :toc: left
-:toclevels: 5
+:toclevels: 4
 :sectnums:
 :sectnumlevels: 5