From 423d736aec5d5102c4ef0ce78e8b71a70ccbfdb4 Mon Sep 17 00:00:00 2001
From: Andrey Miroshnikov <andrey@technepisteme.xyz>
Date: Fri, 24 Jun 2022 17:28:12 +0100
Subject: [PATCH] New page describing how to add new cpu instructions

---
 docs/adding_instr.mdwn | 98 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 docs/adding_instr.mdwn

diff --git a/docs/adding_instr.mdwn b/docs/adding_instr.mdwn
new file mode 100644
index 000000000..4d39ddc2d
--- /dev/null
+++ b/docs/adding_instr.mdwn
@@ -0,0 +1,98 @@
+Links:
+
+* <https://git.libre-soc.org/?p=openpower-isa.git;a=summary>
+* <>
+
+# Adding a New Instruction
+
+For this guide, an example instruction Bitmanip Mask (bmask) will be used.
+
+## Determine the pseudo-code
+
+The nomenclature for pseudo-code is in the PowerISA spec, sections 1.3.2
+onwards.
+This code is useful to determine the inputs, outputs, flags to include
+in the instruction bitfields etc. This pseudo-code then needs to be
+added to one of the markdown files in the openpower-isa repo
+(openpower/isa/).
+
+The [PyWriter](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=src/openpower/decoder/pseudo/pywriter.py;hb=HEAD) script converts the
+pseudo-code to a Python function, which is used for testing.
+
+## Determine the instruction form
+
+This step varies from simple-to-challenging, and depends on your
+familiarity with the PowerISA spec. Section 1.6.1 Word Instruction
+Formats in the spec shows all the available opcode formats, however
+you likely won't need to look there at first.
+
+Instead, first check "fields.txt" (openpower/isatables/fields.text)
+
+This instruction required adding the BM2-FORM to fields.txt, see the
+[commit](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=0ca15640ad0151cc099e699712e3c67fe9c365f4)
+
+## Add the markdown template with the pseudo-code
+
+The template needs to go into one of the markdown files
+(openpower/isa/), in this case av.mdwn (**THIS NEEDS TO BE CLARIFIED!**).
+
+* [Adding the template](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=5f982fc17f531d9703ea94c38f8376df9afd693f)
+
+* [Missed Special Register section](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=e2cfdcaab120eb8370d94d411a29d45f60fc2d91]
+
+The template requires:
+
+* Title: DRAFT Bitmanip Masked
+* Instruction form: BM2-Form
+* (**Probably need re-wording**)name, dest,arg1,arg2,flag: bmask  RT,RA,RB,bm
+* Pseudo-code: [see](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=openpower/isa/av.mdwn;)
+* Special Registers Altered: None
+
+It's essential to have the "Special Registers Altered" section (even if
+no special registers are used), otherwise the PyWriter script will fail.
+
+## Adding opcode entry to CSV file
+
+The csv files contain the bitfields for every instruction, and even if the pseudo-code has been added, the opcode bitfield breakdowns *must* exist!
+
+(**There are MANY csv files, which one should be used and when?**)
+
+[Bitfield breakdown for bmask](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=57d74f69d825b116257dbf721465034de2924e18)
+
+TODO
+
+## Add opcode to power_enums.py
+
+The file power_enums.py (src/openpower/decoder/power_enums.py) contains the opcode enums (**are they arbitrary?**) and instruction string name in "_insns" list. Each new instruction must have an enum assigned and string added to the list.
+
+[Adding enum](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=5f982fc17f531d9703ea94c38f8376df9afd693f)
+
+[Adding string to "_insns"](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=0bd52beedc217ce882dc7ae176ff05d93c6d4715)
+
+## Adding code to caller.py
+
+(**What is this for?**)
+
+The following code must be added to the caller.py file (src/openpower/decoder/isa/caller.py):
+    # and anything bmask
+    if asmop.startswith('bmask'):
+        illegal = False
+        ins_name = asmop
+
+Make sure to replace "bmask" with your new instruction name.
+
+## Add bitfield decoding to svp64.py
+
+For the testing code to know *how* to decode your new instruction, you must add some code to svp64.py (src/openpower/sv/trans/svp64.py).
+
+[Commit with correct decoding]
+
+TODO
+
+## Run PyWriter to generate Python function
+
+TODO
+
+## Create new test cases
+
+TODO
-- 
2.30.2