From 64c0f7b1da2cb238a385454bcfc19da872df1ccb Mon Sep 17 00:00:00 2001
From: Kevin Ramharak <kevin@ramharak.nl>
Date: Sat, 12 Jan 2019 23:06:35 +0100
Subject: [PATCH] add `PUSHF` and `POPF` documentation

---
 Instruction-Set.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/Instruction-Set.md b/Instruction-Set.md
index b180d88..600d46c 100644
--- a/Instruction-Set.md
+++ b/Instruction-Set.md
@@ -917,8 +917,49 @@ destination = destination - 1
 ```
 
 ### POPF
+#### Details
+| mnemonic | opcode | operands | carry | zero | sign | overflow | break |
+| -------- | ------ | -------- | ----- | ---- | ---- | -------- | ----- |
+| `POPF`    | `0x2C` |   |  `X`  |  `X` |  `X` |    `X`   |  `-`  |
+
+#### Description
+Pops a word of the top of the stack and uses the 4 lowest bits of the result to set the CPU flags. In the order *sign*, *zero*, *carry* and *overflow* also represented by the following bit pattern `xxxx xxxx xxxx SZCO`.
+
+All flags will be according to the corresponding bit values of given word. To only set on flag a `PUSHF` to query the flags and a bitmask with the desired flag to manipulate should be used.
+
+#### Pseudo code
+```py
+flags = memory[SP]
+
+SIGN_FLAG = flags & (1 << 3)
+ZERO_FLAG = flags & (1 << 2)
+CARRY_FLAG = flags & (1 << 1)
+OVERFLOW_FLAG = flags & 1
+
+SP = SP + 1
+```
 
 ### PUSHF
+#### Details
+| mnemonic | opcode | operands | carry | zero | sign | overflow | break |
+| -------- | ------ | -------- | ----- | ---- | ---- | -------- | ----- |
+| `PUSHF`    | `0x2D` |   |  `-`  |  `-` |  `-` |    `-`   |  `-`  |
+
+#### Description
+Pushes the current flags on top of the stack. The flags are present in the 4 lowest bits of the result on the stack. In the order *sign*, *zero*, *carry* and *overflow* also represented by the following bit pattern `xxxx xxxx xxxx SZCO`.
+
+To get the state of a single flag you can use a bit mask.
+
+example: the operation `flags & 0100` will give a result of 1 if the zero flag was set and a result of 0 if it was unset
+
+#### Pseudo code
+```py
+# 0000 0000 0000 SZCO
+flags = (SIGN_FLAG << 3) | (ZERO_FLAG << 2) | (CARRY_FLAG << 1) | (OVERFLOW_FLAG)
+
+SP = SP - 1
+memory[SP] = flags
+```
 
 ### JA