# Introduction
-This tutorial intends to sched some light at the first steps for a newcomer.
+This tutorial intends to shed some light at the first steps for a newcomer.
Note that this tutorial is a work in progress; feel free to update it.
This tutorial assumes that the environment and and repositories are set.
The information on environment can be found at
-[HDL workflow](https://libre-soc.org/HDL_workflow/) page.
+[[HDL workflow]] page, and
+an easy set of commands is at the [[HDL_workflow/devscripts]] page
In this tutorial, we will perform these steps:
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.
projects / libreriscv.git / blobdiff