Custom ISA extension

ZStudio has integrated-in instruction customization tool --- ZIGen, which helps you add custom instructions and generate shared library. With ZIGen as well as other tools in ZStudio, you can explore architecture rapidly. About the Demo of working with custom extension, please refer to add.

Create custom extension

ZStudio has built-in instructions and extensions, that is RISC-V base integer instruction set and standard extension, listed in side bar of ZIGen view. You can extend the RISC-V base ISA architecture with new instruction extensions to meet wide-ranged requirement.

On the main menu, select View > ZIGen to invoke the instruction customization tool and start creating your custom instructions:

1. Create a new extension

   Click (New Extension) to create a new extension. The name of your extension is limited to uppercase and lowercase English letters.

2. Create new instruction

   Right-click extension node and select New Instruction and specify the instruction name to create a new instruction. You can also focus on one of the extension and click (New Instruction) in the up-right corner. The name of your instruction is limited to number, underline as well as uppercase and lowercase English letters.

3. Specify custom instruction configuration

   In instruction edit page, you need to specify all the configurable options to your custom instruction.

   • Function Unit: Select the dedicated hardware resources (VPU, IntAlu, etc) that your custom instruction required from the drop-down box. Specify the function unit to EXU component in CPU layer of your virtual board model to use your custom instruction. Refer to Microarchitecture of CPU component and the below table.

   Available Function Units

   Function Unit	Description
   IntAlu	Integer Arithmetic Logic Unit
   IntBru	Integer Branch Unit
   IntMult	Integer Multiplication Unit
   IntDiv	Integer Division Unit
   FloatAdd	Floating Point Addition Unit
   FloatCmp	Floating Point Comparison Unit
   FloatCvt	Floating Point Conversion Unit
   FloatMult	Floating Point Multiplication Unit
   FloatMultAcc	Floating Point Multiply-Accumulate Unit
   FloatDiv	Floating Point Division Unit
   FloatMisc	Floating Point Miscellaneous Unit
   FloatSqrt	Floating Point Square Root Unit
   MemRead	Memory Read Unit
   MemWrite	Memory Write Unit
   FloatMemRead	Floating Point Memory Read Unit
   FloatMemWrite	Floating Point Memory Write Unit
   VPU	Vector Processing Unit
   SIMD	Single Instruction, Multiple Data
   Builtin	Include all function unit types except Cus
   Cus0/Cus1/Cus2/Cus3/Cus4	Reserved for user customization

   • Length: Select the length (16/32bits) of your custom instruction required from the drop-down box.
   • Architecture: Select the processor architecture (RV32/RV64) of your custom instruction from the drop-down box.
   • ASM: The assembly language (ASM) representation of your custom instruction, also known as instruction mnemonic, will be generated after defining custom instruction format automatically.

4. Define the format of your custom instruction

   Click (Add) to invoke the encoding field dialog and specify available encoding space in Encoding Field. You can add "imm" type encoding field and control the base and width of different positions in the same dialog.

   There are some built-in templates in ZStudio. You can click (Import Template) to select a template to apply in current encoding field or click (Export as Template) to save your format as template to reuse next time. All the templates are listed in Template Manage.

   • Base & Width: Control the encoding length and bit position.
   • Type & Value: Refer the table below, select the encoding type and enter its value.

   The Types of Encoding Field

   Type	Description
   opcode	Opcode determines the basic type of the instruction. There will be a default opcode when you create new instruction. You can only set its Value without change its Base, Width and Type.
   function	Funct fields are used to further distinguish different instructions. The specific number of bits and their position in the funct field depend on the type and length of the instruction.
   reg	Registers have subtype of GPR, GPRC, FRR, FRRC and VR. You need to determine their direction of in, out or in/out. Each instruction allows one destination register.
   imm	Immediates are constant values. They can be either signed or unsigned and can have varying lengths. You need to allocate specific bits for immediates and specify the offset.
   customFlag	The custom flag allows you rename, allocate specific bits and set a constant value for a new flag.

5. check your custom instruction format

   You can check your custom instruction format in Encoding Preview Table and right-click the rows in Encoding Field to edit or delete them until you are happy with the corrections.

6. Define instruction behavior

   Describe the execution flow and exception handling logic as well as additional details or constraints of your custom instruction in C Code editor.

7. Preview your custom instruction

   Right-click the extension and select Preview to check all instructions in the extension. You can use the search box to perform a straightforward search. The gear icon gives you the option to open instruction edit page and change the format (only custom instructions can be edited).

8. Generate shared library

   Right-click the extension and select Generate Shared Library. Check the status in Run Console and wait for the <extension_name> has generate shared library successfully message on bottom-right corner. You can find it under Include navigator.

   tip

   You can control the default visibility of Extensions and Include navigator with (More Actions...) button in the up-right corner of side bar.

Each custom extension will generate a dynamic library and a header file, which includes all the instructions within.

The macro that needed be included as header file of your programme will be saved under Home/{user_name}/ZStudio_Workspace/include in your file system.

The shared library that be used by compiler and simulator will be saved under Home/{user_name}/ZStudio_Workspace/lib in your file system.

Work with your custom extension

Select ZSolution from the drop-down menu to enter into ZSolution, then create a new project for using custom extension.

To use your custom extension in your programming, please refer to add.

1. Use your custom extension in your solution and project.

   • Include header file of custom extension in your coding.
   • Use the custom instructions you want in your coding.
   tip

   Coding in assembly does't need include header file of custom extension.

2. Set build configuration

   Click the (Build Configuration) button and specify the Arch {standard_feature}_x{custom_extension} and ABI in build configuration. The prefix "x" is needed for custom extensions. You can check the supported arch/abi option combinations for the RISC-V architecture in ZCC User Manual.

   When you specify Arch in build configuration, the header file will be included in your code and the shared library of custom extension will be linked in your ELF.

3. Build your project and check the build result.

   Click the button in Project Controller view and check the build result in the Build Console view.

4. Run your project and check the run result.

   Click the button in Project Controller view and check the result in the Run Console view.

Import and export extension

ZStudio supports importing local custom extension or export the current extension to an .zsext file, which helps you design custom extensions with your team across different platforms.

Import extension

To import extension, click (Import Extension) to evoke a dialog box to browse for the path of the .zsext file. The imported extension will displayed in side bar and you can add or edit instructions in the imported extension.

Export extension

To export extension, right-click and select Export Extension to specify the destination and name of the exported file in the evoked dialog. ZStudio will create a {file_name}.zsext file and save in the specified directory.

The exported .zsext file can be shared with other team members or used as input for ZStudio in other machines or cloud platform.

Export extension encoding

ZIGen also allows you to export the list of custom ISA extension for further design, verification, and produce ISA doc.

You may right-click extension node and select Export Extension Encoding in the pull-down menu. In the evoked dialog, specify the destination and name of the exported .txt file.

You can check the export process in the message view on bottom-right corner. The exported file will open in editor and save in the directory of Home/ZStudio (Linux) or C:\Users\{User_name}\ZStudio (Windows).

Template management

ZExplorer provide the Template Manage tool to check, edit and manage all built-in and custom instruction templates. On the main menu, select View > Template Manage to invoke the mange tab.

The built-in and custom instruction templates are categorized by instruction lengths listed in this tab. You can unfold 16bits or 32bits to search and quickly locate the instruction format you want.

The gear icon (Menu) opens a context menu with options to duplicate, rename and delete the instruction format templates. To edit the template format, right-click the field cell and select Edit Field. On the encoding dialog, you can change its type, value and width. Those built-in templates with lock icon can not be edited. But you can duplicate and edi its copy.