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 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

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

  • [Missed Special Register section](;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
  • 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


Add opcode to

The file (src/openpower/decoder/ 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

Adding string to "_insns"

Adding code to

(What is this for?)

The following code must be added to the file (src/openpower/decoder/isa/ # 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

For the testing code to know how to decode your new instruction, you must add some code to (src/openpower/sv/trans/

[Commit with correct decoding]


Run PyWriter to generate Python function


Create new test cases