docs/adding_instr.mdwn

   1 Links:
   2
   3 * <https://git.libre-soc.org/?p=openpower-isa.git;a=summary>
   4 * <>
   5
   6 # Adding a New Instruction
   7
   8 For this guide, an example instruction Bitmanip Mask (bmask) will be used.
   9
  10 ## Determine the pseudo-code
  11
  12 The nomenclature for pseudo-code is in the PowerISA spec, sections 1.3.2
  13 onwards.
  14 This code is useful to determine the inputs, outputs, flags to include
  15 in the instruction bitfields etc. This pseudo-code then needs to be
  16 added to one of the markdown files in the openpower-isa repo
  17 (openpower/isa/).
  18
  19 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
  20 pseudo-code to a Python function, which is used for testing.
  21
  22 ## Determine the instruction form
  23
  24 This step varies from simple-to-challenging, and depends on your
  25 familiarity with the PowerISA spec. Section 1.6.1 Word Instruction
  26 Formats in the spec shows all the available opcode formats, however
  27 you likely won't need to look there at first.
  28
  29 Instead, first check "fields.txt" (openpower/isatables/fields.text)
  30
  31 This instruction required adding the BM2-FORM to fields.txt, see the
  32 [commit](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=0ca15640ad0151cc099e699712e3c67fe9c365f4)
  33
  34 ## Add the markdown template with the pseudo-code
  35
  36 The template needs to go into one of the markdown files
  37 (openpower/isa/), in this case av.mdwn (**THIS NEEDS TO BE CLARIFIED!**).
  38
  39 * [Adding the template](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=5f982fc17f531d9703ea94c38f8376df9afd693f)
  40
  41 * [Missed Special Register section](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=e2cfdcaab120eb8370d94d411a29d45f60fc2d91]
  42
  43 The template requires:
  44
  45 * Title: DRAFT Bitmanip Masked
  46 * Instruction form: BM2-Form
  47 * (**Probably need re-wording**)name, dest,arg1,arg2,flag: bmask  RT,RA,RB,bm
  48 * Pseudo-code: [see](https://git.libre-soc.org/?p=openpower-isa.git;a=blob;f=openpower/isa/av.mdwn;)
  49 * Special Registers Altered: None
  50
  51 It's essential to have the "Special Registers Altered" section (even if
  52 no special registers are used), otherwise the PyWriter script will fail.
  53
  54 ## Adding opcode entry to CSV file
  55
  56 The csv files contain the bitfields for every instruction, and even if the pseudo-code has been added, the opcode bitfield breakdowns *must* exist!
  57
  58 (**There are MANY csv files, which one should be used and when?**)
  59
  60 [Bitfield breakdown for bmask](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=57d74f69d825b116257dbf721465034de2924e18)
  61
  62 TODO
  63
  64 ## Add opcode to power_enums.py
  65
  66 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.
  67
  68 [Adding enum](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=5f982fc17f531d9703ea94c38f8376df9afd693f)
  69
  70 [Adding string to "_insns"](https://git.libre-soc.org/?p=openpower-isa.git;a=commitdiff;h=0bd52beedc217ce882dc7ae176ff05d93c6d4715)
  71
  72 ## Adding code to caller.py
  73
  74 (**What is this for?**)
  75
  76 The following code must be added to the caller.py file (src/openpower/decoder/isa/caller.py):
  77     # and anything bmask
  78     if asmop.startswith('bmask'):
  79         illegal = False
  80         ins_name = asmop
  81
  82 Make sure to replace "bmask" with your new instruction name.
  83
  84 ## Add bitfield decoding to svp64.py
  85
  86 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).
  87
  88 [Commit with correct decoding]
  89
  90 TODO
  91
  92 ## Run PyWriter to generate Python function
  93
  94 TODO
  95
  96 ## Create new test cases
  97
  98 TODO