Note that the initial values for registers `3` and `2` are `0x1234` and `0x4321`
respectively, and this matches to the input parameters in the logs:
+
```
inputs [SelectableInt(value=0x1234, bits=64), SelectableInt(value=0x4321, bits=64)]
```
The simulator performs the actual computation, obtaining the result, and then
updates the general-purpose register we used as an output parameter:
+
```
results (SelectableInt(value=0x5555, bits=64),)
writing gpr 1 SelectableInt(value=0x5555, bits=64) 0
```
In the end, we see that our assertion indeed passes:
+
```
__eq__ SelectableInt(value=0x5555, bits=64) SelectableInt(value=0x5555, bits=64)
```
and this is the place where the magic happens. In `process` nested function,
we actually simulate that our instructions are executed one-by-one, literally
calling `yield from simulator.execute_one()`. And this method inside the
-simulator instance belongs to `src/openpower/decoder/isa/caller.py` script.
+simulator instance belongs to
+[`src/openpower/decoder/isa/caller.py`](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/isa/caller.py;hb=HEAD)
+script.
Inside `execute_one` method, the most crucial part is
`yield from self.call(opname)` call; and, if we take a look inside of the
`call` method, we will see that, aside of the aforementioned log
(`log("call", ins_name, asmop)`), this function also takes care of the rest
of the magic. This includes a lot of manipulations before and after executing
instruction, but the crucial part is quite simple:
+
```
# execute actual instruction here (finally)
log("inputs", inputs)
The part of the most interest is `info.func` call; we'll take a look at it
in the next chapter.
+
+# Markdown enters the scene
+
+If we investigate the `info.func` object, we'll discover that, in case of our
+`add` instruction, it is actually `fixedarith.op_add` function. Where does it
+come from?
+
+This function is defined inside `fixedarith.py`, which is generated from the
+corresponding Markdown file, `fixedarith.mdwn`. On the first glance, one can
+find an idea to generate the code from the documentation somewhat surprising;
+however, this is perfectly reasonable, since we try to stay as close to the
+documentation as possible. Some Markdown files, like `fixedarith.mdwn`,
+contain the pseudocode in exactly the same form as it is present in the ISA
+docs. Let's take a look at `fixedarith.mdwn` and find our instruction.
+
+As we can see in `# Add` section, there are four `add` variants:
+
+* add RT,RA,RB (OE=0 Rc=0)
+* add. RT,RA,RB (OE=0 Rc=1)
+* addo RT,RA,RB (OE=1 Rc=0)
+* addo. RT,RA,RB (OE=1 Rc=1)
+
+All variants are covered in the relevant OpenPOWER ISA. As of time of writing,
+the most recent edition is 3.0C, and it is available here:
+
+https://ftp.libre-soc.org/PowerISA_public.v3.0C.pdf
+
+The instructions of our interest can be found exactly where we'd expect them
+to be found, at chapter `3.3: Fixed-Point Facility Instructions`. We can see
+here the instruction encoding, as well as its form (XO) and all information
+we already found in `fixedarith.mdwn` file.
+
+All these details are available in some form as part of `info` variable we
+observed before (at `caller.py` file). The `info` variable is, actually,
+a simple instance of named tuple; the overall structure of this named tuple
+is left as an exercise for the reader.
+
+# Modifying the pseudocode
+
+We won't dive into all gory details of the decoder, at least for now. What
+is important for us at this stage is, how can we affect the generated code?
+As we saw recently, the markdown file is somehow converted into the Python
+code; but how is the conversion done?
+
+This is done by the script called pywriter. Again, we omit the exact details,
+since this script clearly deserves its own documentation; the only crucial
+information that pywriter script uses PLY (hint: Python-Lex-Yacc) in order
+to get the work done, and, thanks to PLY magic, it is able to convert ISA
+pseudocode into something more Pythonic.
+
+For illustrative purposes, let's modify the pseudocode so that, instead of
+addition, it performs a subtraction. Let's find the pseudocode for `add`
+instructions inside `fixedarith.mdwn`...
+
+```
+Pseudo-code:
+
+ RT <- (RA) + (RB)
+```
+
+and modify it to:
+
+
+```
+Pseudo-code:
+
+ RT <- (RA) - (RB)
+```
+
+OK, we changed the pseudocode inside the Markdown, but it hasn't yet changed
+a word inside the corresponding Python file (`fixedarith.py`). If we attempt
+to re-run the unit test, nothing happens, since Python code is kept intact.
+
+In order to force the source code re-generation, `pywriter noall fixedarith`
+command is used. Once `pywriter` completes its task, we can re-run the test,
+and it should **fail**. The logs show a different result.
+
+Work out by hand what 0x1234 - 0x4321 in 64-bit unsigned arithmetic is, and
+change the assert in the unit test to match. Re-run: the test should now
+**pass**. These manipulations, again, are left as an exercise for the reader.
+
+This chapter concludes the First Steps tutorial. We'll take a deeper look
+at pseudocode generation when we will dive into an example of modifying
+BCD instructions.