Intel Nios II User Manual

Nios II Custom Instruction User Guide

Send Feedback

UG-20286 | 2020.04.27

Latest document on the web: PDF | HTML

Contents

1. Nios II Custom Instruction Overview..............................................................................4

1.1. Custom Instruction Implementation......................................................................... 4

1.1.1. Custom Instruction Hardware Implementation............................................... 5

1.1.2. Custom Instruction Software Implementation................................................ 6

2. Custom Instruction Hardware Interface......................................................................... 7

2.1. Custom Instruction Types....................................................................................... 7

2.1.1. Combinational Custom Instructions.............................................................. 8

2.1.2. Multicycle Custom Instructions...................................................................10

2.1.3. Extended Custom Instructions................................................................... 11

2.1.4. Internal Register File Custom Instructions................................................... 13

2.1.5. External Interface Custom Instructions....................................................... 15

3. Custom Instruction Software Interface.........................................................................16

3.1. Custom Instruction Software Examples................................................................... 16

3.2. Built-in Functions and User-defined Macros..............................................................17

3.2.1. Built-in Functions with No Return Value.......................................................18

3.2.2. Built-in Functions that Return a Value of Type Int......................................... 18

3.2.3. Built-in Functions that Return a Value of Type Float...................................... 19

3.2.4. Built-in Functions that Return a Pointer Value...............................................19

3.3. Custom Instruction Assembly Language Interface.................................................... 20

3.3.1. Custom Instruction Assembly Language Syntax........................................... 20

3.3.2. Custom Instruction Assembly Language Examples........................................20

3.3.3. Custom Instruction Word Format................................................................21

4. Design Example: Cyclic Redundancy Check................................................................... 23

4.1. Building the CRC Example Hardware.......................................................................23

4.1.1. Setting up the Environment for the CRC Example Design...............................24

4.1.2. Opening the Component Editor.................................................................. 24

4.1.3. Specifying the Custom Instruction Component Type......................................25

4.1.4. Displaying the Custom Instruction Block Symbol.......................................... 26

4.1.5. Adding the CRC Custom Instruction HDL Files.............................................. 26

4.1.6. Configuring the Custom Instruction Parameter Type......................................28

4.1.7. Setting Up the CRC Custom Instruction Interfaces........................................ 29

4.1.8. Configuring the Custom Instruction Signal Type........................................... 31

4.1.9. Saving and Adding the CRC Custom Instruction........................................... 32

4.1.10. Generating and Compiling the CRC Example System................................... 33

4.2. Building the CRC Example Software........................................................................33

4.2.1. Running and Analyzing the CRC Example Software....................................... 34

4.2.2. Using the User-defined Custom Instruction Macro.........................................35

5. Introduction to Nios® II Floating Point Custom Instructions........................................ 37

5.1. Floating Point Background.....................................................................................39

5.2. IEEE 754 Format..................................................................................................39

5.2.1. Unit in the Last Place................................................................................39

5.2.2. Floating Point Value Encoding.................................................................... 40

5.3. Rounding Schemes...............................................................................................41

5.3.1. Nearest Rounding.................................................................................... 41

Nios II Custom Instruction User Guide

Send Feedback

Contents

5.3.2. Truncation Rounding.................................................................................41

5.3.3. Faithful Rounding..................................................................................... 41

5.3.4. Rounding Examples..................................................................................42

5.4. Special Floating Point Cases.................................................................................. 42

6. Nios II Floating Point Hardware 2 Component.............................................................. 44

6.1. Overview of the Floating Point Hardware 2 Component..............................................44

6.2. Floating Point Hardware 2 IEEE 754 Compliance.......................................................46

6.3. IEEE 754 Exception Conditions with FPH2................................................................47

6.4. Floating Point Hardware 2 Operations..................................................................... 47

6.5. Building the FPH2 Example Hardware..................................................................... 49

6.6. Building the FPH2 Example Software...................................................................... 51

6.6.1. FPH2 and Nios II GCC...............................................................................52

6.6.2. Floating Point Hardware 2 Conversions........................................................52

6.6.3. Nios II FPH2 Software Options................................................................... 53

6.7. FPH2 Implementation of GCC Options.....................................................................55

6.7.1. -fno-math-errno...................................................................................... 55

6.7.2. -fsingle-precision-constant........................................................................ 55

6.7.3. -funsafe-math-optimizations......................................................................56

6.7.4. -ffinite-math-only.................................................................................... 56

6.7.5. -fno-trapping-math.................................................................................. 56

6.7.6. -frounding-math...................................................................................... 57

6.8. Nios II FPH2 and the Newlib Library........................................................................57

6.9. C Macros for round(), fmins(), and fmaxs()............................................................. 58

7. Nios II Floating Point Hardware (FPH1) Component.....................................................59

7.1. Creating the FPH1 Example Hardware ...................................................................59

7.2. Adding FPH1 to the Design and Configuring the Device............................................. 60

7.3. Building the FPH1 Example Software...................................................................... 61

7.3.1. Creating the FPH1 Software Project............................................................ 61

7.3.2. Running and Analyzing the FPH1 Example Software......................................61

7.3.3. Software Implementation for FPH1............................................................. 63

7.4. Nios II FPH1 and the Newlib Library........................................................................63

7.5. Assessing Your Floating Point Optimization Needs.....................................................63

7.6. Hardware Divide Considerations with FPH1..............................................................64

8. Document Revision History for Nios II Custom Instruction User Guide......................... 66

Send Feedback

Nios II Custom Instruction User Guide

Nios II Embedded Processor

+ –

<< >>

Result

Nios II

ALU

Custom

Logic

UG-20286 | 2020.04.27

Send Feedback

1. Nios II Custom Instruction Overview

Custom instructions give you the ability to tailor the Nios II processor to meet the needs of a particular application. You can accelerate time critical software algorithms by converting them to custom hardware logic blocks. Because it is easy to alter the design of the FPGA-based Nios II processor, custom instructions provide an easy way to experiment with hardware-software tradeoffs at any point in the design process.

The custom instruction logic connects directly to the Nios II arithmetic logic unit (ALU) as shown in the following figure.

Figure 1. Custom Instruction Logic Connects to the Nios II ALU

Related Information

• Custom Instruction Software Interface on page 16

• Building the CRC Example Hardware on page 23

1.1. Custom Instruction Implementation

Nios II custom instructions are custom logic blocks adjacent to the arithmetic logic

Intel Corporation. All rights reserved. Agilex, Altera, Arria, Cyclone, Enpirion, Intel, the Intel logo, MAX, Nios, Quartus and Stratix words and logos are trademarks of Intel Corporation or its subsidiaries in the U.S. and/or other countries. Intel warrants performance of its FPGA and semiconductor products to current specifications in accordance with Intel's standard warranty, but reserves the right to make changes to any products and services at any time without notice. Intel assumes no responsibility or liability arising out of the application or use of any information, product, or service described herein except as expressly agreed to in writing by Intel. Intel customers are advised to obtain the latest version of device specifications before relying on any published information and before placing orders for products or services. *Other names and brands may be claimed as the property of others.

unit (ALU) in the processor’s datapath.

ISO 9001:2015 Registered

Combinatorial

Conduit interface to external memory, FIFO, or other logic

Multi-cycle

result [31..0]

Extended

Internal

done

dataa[31..0]

datab[31..0]

clk

clk_en

reset

start

n[7..0]

a[4..0]

readra

b[4..0]

readrb

c[4..0]

writerc

Combinational

Custom

Logic

1. Nios II Custom Instruction Overview

UG-20286 | 2020.04.27

When custom instructions are implemented in a Nios II system, each custom operation is assigned a unique selector index. The selector index allows software to specify the desired operation from among up to 256 custom operations. The selector index is determined at the time the hardware is instantiated with the Platform Designer or Platform Designer (Standard) software. Platform Designer exports the selection index value to system.h for use by the Nios II software build tools.

1.1.1. Custom Instruction Hardware Implementation

Figure 2. Hardware Block Diagram of a Nios II Custom Instruction

A Nios II custom instruction logic block interfaces with the Nios II processor through three ports: dataa, datab, and result.

The custom instruction logic provides a result based on the inputs provided by the Nios II processor. The Nios II custom instruction logic receives input on its dataa port, or on its dataa and datab ports, and drives the result to its result port.

The Nios II processor supports several types of custom instructions. The figure above shows all the ports required to accommodate all custom instruction types. Any particular custom instruction implementation requires only the ports specific to its custom instruction type.

The figure above also shows a conduit interface to external logic. The interface to external logic allows you to include a custom interface to system resources outside of the Nios II processor datapath.

Send Feedback

Nios II Custom Instruction User Guide

1. Nios II Custom Instruction Overview

1.1.2. Custom Instruction Software Implementation

The Nios II custom instruction software interface is simple and abstracts the details of the custom instruction from the software developer.

For each custom instruction, the Nios II Embedded Design Suite (EDS) generates a macro in the system header file, system.h. You can use the macro directly in your C or C++ application code, and you do not need to program assembly code to access custom instructions. Software can also invoke custom instructions in Nios II processor assembly language.

Related Information

Custom Instruction Software Interface on page 16

UG-20286 | 2020.04.27

Nios II Custom Instruction User Guide

Send Feedback

UG-20286 | 2020.04.27

Send Feedback

2. Custom Instruction Hardware Interface

2.1. Custom Instruction Types

Different types of custom instructions are available to meet the requirements of your application. The type you choose determines the hardware interface for your custom instruction.

Table 1. Custom Instruction Types, Applications, and Hardware Ports

Instruction Type Application Hardware Ports

Combinational Single clock cycle custom logic blocks. •

Multicycle Multi-clock cycle custom logic blocks of fixed or

variable durations.

dataa[31:0]

•

datab[31:0]

•

result[31:0]

•

dataa[31:0]

•

datab[31:0]

•

result[31:0]

•

clk

•

clk_en

•

start

•

reset

•

done

(1)

continued...

(1)

The clk_en input signal must be connected to the clk_en signals of all the registers in the custom instruction, in case the Nios II processor needs to stall the custom instruction during execution.

ISO 9001:2015 Registered

2. Custom Instruction Hardware Interface

UG-20286 | 2020.04.27

Instruction Type Application Hardware Ports

Extended Custom logic blocks that are capable of

Internal register file

External interface Custom logic blocks that interface to logic

performing multiple operations

Custom logic blocks that access internal register files for input or output or both.

outside of the Nios II processor’s datapath

•

dataa[31:0]

•

datab[31:0]

•

result[31:0]

•

clk

•

clk_en

•

start

•

reset

•

done

•

n[7:0]

•

dataa[31:0]

•

datab[31:0]

•

result[31:0]

•

clk

•

clk_en

•

start

•

reset

•

done

•

n[7:0]

•

a[4:0]

•

readra

•

b[4:0]

•

readrb

•

c[4:0]

•

writerc

Standard custom instruction ports, plus userdefined interface to external logic.

(1)

2.1.1. Combinational Custom Instructions

A combinational custom instruction is a logic block that completes its logic function in a single clock cycle.

A combinational custom instruction must not have side effects. In particular, a combinational custom instruction cannot have an external interface. This restriction exists because the Nios II processor issues combinational custom instructions speculatively, to optimize execution. It issues the instruction before knowing whether it is necessary, and ignores the result if it is not required.

A basic combinational custom instruction block, with the required ports shown in "Custom Instruction Types", implements a single custom operation. This operation has a selection index determined when the instruction is instantiated in the system using Platform Designer.

You can further optimize combinational custom instructions by implementing the extended custom instruction. Refer to “Extended Custom Instructions”.

Related Information

• Extended Custom Instructions on page 11

• Custom Instruction Types on page 7 List of standard custom instruction hardware ports, to be used as signal types

Nios II Custom Instruction User Guide

Send Feedback

dataa[31..0]

datab[31..0]

Combinational result[31..0]

clk

T1 T3T2 T4

dataa[ ]

datab[ ]

result[ ]

dataa[ ] valid

datab[ ] valid

result valid

2. Custom Instruction Hardware Interface

UG-20286 | 2020.04.27

2.1.1.1. Combinational Custom Instruction Ports

A combinational custom instruction must have a result port, and may have optional

dataa and datab ports.

Figure 3. Combinational Custom Instruction Block Diagram

In the figure above, the dataa and datab ports are inputs to the logic block, which drives the results on the result port. Because the logic function completes in a single clock cycle, a combinational custom instruction does not require control ports.

Table 2. Combinational Custom Instruction Ports

Port Name Direction Required Description

dataa[31:0]

datab[31:0]

result[31:0]

Input No Input operand to custom instruction

Output Yes Result of custom instruction

The only required port for combinational custom instructions is the result port. The

dataa and datab ports are optional. Include them only if the custom instruction

requires input operands. If the custom instruction requires only a single input port, use dataa.

2.1.1.2. Combinational Custom Instruction Timing

The processor presents the input data on the dataa and datab ports on the rising edge of the processor clock. The processor reads the result port on the rising edge of the following processor clock cycle.

Figure 4. Combinational Custom Instruction Timing Diagram

Related Information

Combinational Custom Instruction Ports on page 9

Block diagram showing the dataa, datab, and result ports

Send Feedback

Nios II Custom Instruction User Guide

2.1.2. Multicycle Custom Instructions

dataa[31..0] datab[31..0] clk

clk_en reset start

Multi-cycle

done

result[31..0]

Multicycle (sequential) custom instructions consist of a logic block that requires two or more clock cycles to complete an operation.

Figure 5. Multicycle Custom Instruction Block Diagram

Multicycle custom instructions complete in either a fixed or variable number of clock cycles. For a custom instruction that completes in a fixed number of clock cycles, you specify the required number of clock cycles at system generation. For a custom instruction that requires a variable number of clock cycles, you instantiate the start

and done ports. These ports participate in a handshaking scheme to determine when the custom instruction execution is complete.

2. Custom Instruction Hardware Interface

UG-20286 | 2020.04.27

A basic multicycle custom instruction block, with the required ports shown in "Custom Instruction Types", implements a single custom operation. This operation has a selection index determined when the instruction is instantiated in the system using Platform Designer.

You can further optimize multicycle custom instructions by implementing the extended internal register file, or by creating external interface custom instructions.

Related Information

• Extended Custom Instructions on page 11

• Internal Register File Custom Instructions on page 13

• External Interface Custom Instructions on page 15

• Custom Instruction Types on page 7 List of standard custom instruction hardware ports, to be used as signal types

2.1.2.1. Multicycle Custom Instruction Ports

Table 3. Multicycle Custom Instruction Ports

Port Name Direction Required Description

clk

clk_en

reset

start

done

Input Yes System clock

Input Yes Clock enable

Input Yes Synchronous reset

Input No Commands custom instruction logic to start execution

Output No Custom instruction logic indicates to the processor that execution is

complete

continued...

Nios II Custom Instruction User Guide

Send Feedback

clk

dataa[]

datab[]

result[]

valid

T0 T1 T3T2 T4 T5

valid

done

clk_en

start

reset

2. Custom Instruction Hardware Interface

UG-20286 | 2020.04.27

Port Name Direction Required Description

dataa[31:0]

datab[31:0]

result[31:0]

The clk, clk_en, and reset ports are required for multicycle custom instructions. The start, done, dataa, datab, and result ports are optional. Implement them only if the custom instruction requires them.

The Nios II system clock feeds the custom logic block’s clk port, and the Nios II system’s master reset feeds the active high reset port. The reset port is asserted only when the whole Nios II system is reset.

The custom logic block must treat the active high clk_en port as a conventional clock qualifier signal, ignoring clk while clk_en is deasserted.

Input No Input operand to custom instruction

Output No Result of custom instruction

2.1.2.2. Multicycle Custom Instruction Timing

Figure 6. Multicycle Custom Instruction Timing Diagram

The processor asserts the active high start port on the first clock cycle of the custom instruction execution. At this time, the dataa and datab ports have valid values and remain valid throughout the duration of the custom instruction execution. The start signal is asserted for a single clock cycle.

For a fixed length multicycle custom instruction, after the instruction starts, the processor waits the specified number of clock cycles, and then reads the value on the

result signal. For an n-cycle operation, the custom logic block must present valid

data on the nth rising edge after the custom instruction begins execution.

For a variable length multicycle custom instruction, the processor waits until the active high done signal is asserted. The processor reads the result port on the same clock edge on which done is asserted. The custom logic block must present data on the

result port on the same clock cycle on which it asserts the done signal.

2.1.3. Extended Custom Instructions

Send Feedback

An extended custom instruction allows a single custom logic block to implement several different operations.

Nios II Custom Instruction User Guide

dataa[31..0]

n[1..0]

result[31..0]

bit-swap

operation

byte-swap

operation

Custom

Instruction

half-word-swap

operation

2. Custom Instruction Hardware Interface

Extended custom instruction components occupy multiple select indices. The selection indices are determined when the custom instruction hardware block is instantiated in the system using Platform Designer.

Extended custom instructions use an extension index to specify which operation the logic block performs. The extension index can be up to eight bits wide, allowing a single custom logic block to implement as many as 256 different operations.

The following block diagram shows an extended custom instruction with bit-swap, byte-swap, and half-word swap operations.

Figure 7. Extended Custom Instruction with Swap Operations

UG-20286 | 2020.04.27

The custom instruction in the preceding figure performs swap operations on data received at the dataa port. The instruction hardware uses the two bit wide n port to select the output from a multiplexer, determining which result is presented to the

result port.

Note: This logic is just a simple example, using a multiplexer on the output. You can

implement function selection based on an extension index in any way that is appropriate for your application.

Extended custom instructions can be combinational or multicycle custom instructions. To implement an extended custom instruction, add an n port to your custom instruction logic. The bit width of the n port is a function of the number of operations the custom logic block can perform.

An extended custom instruction block occupies several contiguous selection indices. When the block is instantiated, Platform Designer determines a base selection index. When the Nios II processor decodes a custom instruction, the custom hardware

block's n port decodes the low-order bits of the selection index. Thus, the extension index extends the base index to produce the complete selection index.

Nios II Custom Instruction User Guide

Send Feedback

2. Custom Instruction Hardware Interface

UG-20286 | 2020.04.27

For example, suppose the custom instruction block in Figure 7 on page 12 is instantiated in a Nios II system with a base selection index of 0x1C. In this case, individual swap operations are selected with the following selection indices:

• 0x1C—Bit swap

• 0x1D—Byte swap

• 0x1E—Half-word swap

• 0x1F—reserved Therefore, if n is <m> bits wide, the extended custom instruction component occupies

<m>

select indices.

For example, the custom instruction illustrated above occupies four indices, because n is two bits wide. Therefore, when this instruction is implemented in a Nios II system, 256 - 4 = 252 available indices remain.

Related Information

Custom Instruction Assembly Language Interface on page 20

Information about the custom instruction index

2.1.3.1. Extended Custom Instruction Timing

All extended custom instruction port operations are identical to those for the combinational and multicycle custom instructions, with the exception of the n port.

The n port timing is the same as that of the dataa port. For example, for an extended variable multicycle custom instruction, the processor presents the extension index to the n port on the same rising edge of the clock at which start is asserted, and the n port remains stable during execution of the custom instruction.

The n port is not present in combinational and multicycle custom instructions.

2.1.4. Internal Register File Custom Instructions

The Nios II processor allows custom instruction logic to access its own internal register file.

Internal register file access gives you the flexibility to specify whether the custom instruction reads its operands from the Nios II processor’s register file or from the custom instruction’s own internal register file. In addition, a custom instruction can write its results to the local register file rather than to the Nios II processor’s register file.

Custom instructions containing internal register files use readra, readrb, and

writerc signals to determine if the custom instruction should use the internal

register file or the dataa, datab, and result signals. Ports a, b, and c specify the internal registers from which to read or to which to write. For example, if readra is deasserted (specifying a read operation from the internal register), the a signal value provides the register number in the internal register file. Ports a, b, and c are five bits each, allowing you to address as many as 32 registers.

Send Feedback

Nios II Custom Instruction User Guide

dataa[31..0]

datab[31..0]

writerc

result[31..0]

Multiplier

Adder

D Q

CLR

2. Custom Instruction Hardware Interface

Related Information

Instruction Set Reference

Further details about Nios II custom instruction implementation in the Nios II

Processor Reference Guide

2.1.4.1. Internal Register File Custom Instruction Example

Figure 8. Multiply-accumulate Custom Logic Block

UG-20286 | 2020.04.27

This example shows how a custom instruction can access the Nios II internal register file.

When writerc is deasserted, the Nios II processor ignores the value driven on the

result port. The accumulated value is stored in an internal register. Alternatively, the

processor can read the value on the result port by asserting writerc. At the same time, the internal register is cleared so that it is ready for a new round of multiply and accumulate operations.

2.1.4.2. Internal Register File Custom Instruction Ports

To access the Nios II internal register file, you must implement several custom instruction-specific ports.

The following table lists the internal register file custom instruction-specific optional ports. Use the optional ports only if the custom instruction requires them.

Table 4. Internal Register File Custom Instruction Ports

Port Name Direction Required Description

readra

readrb

writerc

a[4:0]

b[4:0]

c[4:0]

Input No

Input No Custom instruction internal register number for data source A.

Input No Custom instruction internal register number for data source B.

Input No Custom instruction internal register number for data destination.

If readra is high, Nios II processor register a supplies dataa. If readra is low, custom instruction logic reads internal register a.

If readrb is high, Nios II processor register b supplies datab. If readrb is low, custom instruction logic reads internal register b.

If writerc is high, the Nios II processor writes the value on the result port to register c. If writerc is low, custom instruction logic writes to internal register c.

Nios II Custom Instruction User Guide

Send Feedback

dataa[31..0] datab[31..0] clk

clk_en reset start

Conduit Interface

done

result[31..0]

2. Custom Instruction Hardware Interface

UG-20286 | 2020.04.27

The readra, readrb, writerc, a, b, and c ports behave similarly to dataa. When the custom instruction begins, the processor presents the new values of the readra,

readrb, writerc, a, b, and c ports on the rising edge of the processor clock. All six

of these ports remain stable during execution of the custom instructions.

To determine how to handle the register file, custom instruction logic reads the active high readra, readrb, and writerc ports. The logic uses the a, b, and c ports as register numbrs. When readra or readrb is asserted, the custom instruction logic ignores the corresponding a or b port, and receives data from the dataa or datab port. When writerc is asserted, the custom instruction logic ignores the c port and writes to the result port.

All other custom instruction port operations behave the same as for combinational and multicycle custom instructions.

2.1.5. External Interface Custom Instructions

Nios II external interface custom instructions allow you to add an interface to communicate with logic outside of the processor’s datapath.

At system generation, conduits propagate out to the top level of the Platform Designer system, where external logic can access the signals. By enabling custom instruction logic to access memory external to the processor, external interface custom instructions extend the capabilities of the custom instruction logic.

Figure 9. Custom Instruction with External Interface

Custom instruction logic can perform various tasks such as storing intermediate results or reading memory to control the custom instruction operation. The conduit interface also provides a dedicated path for data to flow into or out of the processor. For example, custom instruction logic with an external interface can feed data directly from the processor’s register file to an external first-in first-out (FIFO) memory buffer.

Send Feedback

Nios II Custom Instruction User Guide

UG-20286 | 2020.04.27

Send Feedback

3. Custom Instruction Software Interface

The Nios II custom instruction software interface abstracts logic implementation details from the application code.

During the build process the Nios II software build tools generate macros that allow easy access from application code to custom instructions.

3.1. Custom Instruction Software Examples

These examples illustrate how the Nios II custom instruction software interface fits into your software code.

The following example shows a portion of the system.h header file that defines a macro for a bit-swap custom instruction. This bit-swap example accepts one 32 bit input and performs only one function.

#define ALT_CI_BITSWAP_N 0x00 #define ALT_CI_BITSWAP(A) __builtin_custom_ini(ALT_CI_BITSWAP_N,(A))

In this example, ALT_CI_BITWSWAP_N is defined to be 0x0, which is the custom instruction’s selection index. The ALT_CI_BITSWAP(A) macro accepts a single argument, abstracting out the selection index ALT_CI_BITWSWAP_N. The macro maps to a GNU Compiler Collection (GCC) Nios II built-in function.

The next example illustrates application code that uses the bit-swap custom instruction.

#include "system.h"

int main (void) { int a = 0x12345678; int a_swap = 0;

a_swap = ALT_CI_BITSWAP(a); return 0; }

The code in this example includes the system.h file to enable the application software to use the custom instruction macro definition. The example code declares two integers, a and a_swap. Integer a is passed as input to the bit swap custom

instruction and the results are loaded in a_swap.

The example above illustrates how most applications use custom instructions. The macros defined by the Nios II software build tools use C integer types only. Occasionally, applications require input types other than integers. In those cases, you can use a custom instruction macro to process non-integer return values.

ISO 9001:2015 Registered

3. Custom Instruction Software Interface

UG-20286 | 2020.04.27

Note: You can define custom macros for Nios II custom instructions that allow other 32 bit

input types to interface with custom instructions.

Related Information

Built-in Functions and User-defined Macros on page 17

More information about the GCC built-in functions

3.2. Built-in Functions and User-defined Macros

The Nios II processor uses GCC built-in functions to map to custom instructions. By default, the integer type custom instruction is defined in a system.h file. However,

by using built-in functions, software can use 32 bit non-integer types with custom instructions. Fifty-two built-in functions are available to accommodate the different combinations of supported types.

Built-in function names have the following format:

__builtin_custom_<return type>n<parameter types>

<return type> and <parameter types> represent the input and output types, encoded as follows:

•

i—int

•

f—float

•

p—void *

•

(empty)—void

The following example shows the prototype definitions for two built-in functions.

void __builtin_custom_nf (int n, float dataa); float __builtin_custom_fnp (int n, void * dataa);

n is the selection index. The built-in function __builtin_custom_nf() accepts a float as an input, and does not return a value. The built-in

function__builtin_custom_fnp() accepts a pointer as input, and returns a float.

To support non-integer input types, define macros with mnemonic names that map to the specific built-in function required for the application.

The following example shows user-defined custom instruction macros used in an application.

1. /* define void udef_macro1(float data); */

2. #define UDEF_MACRO1_N 0x00

3. #define UDEF_MACRO1(A) __builtin_custom_nf(UDEF_MACRO1_N, (A));

4. /* define float udef_macro2(void *data); */

5. #define UDEF_MACRO2_N 0x01

6. #define UDEF_MACRO2(B) __builtin_custom_fnp(UDEF_MACRO2_N, (B));

8. int main (void)

9. {

10. float a = 1.789;

11. float b = 0.0;

12. float *pt_a = &a;

13.

14. UDEF_MACRO1(a);

15. b = UDEF_MACRO2((void *)pt_a);

Send Feedback

Nios II Custom Instruction User Guide

16. return 0;

17. }

On lines 2 through 6, the user-defined macros are declared and mapped to the appropriate built-in functions. The macro UDEF_MACRO1() accepts a float as an input parameter and does not return anything. The macro UDEF_MACRO2() accepts a pointer as an input parameter and returns a float. Lines 14 and 15 show code that uses the two user-defined macros.

Related Information

• GCC, the GNU Compiler Collection More information about GCC built-in functions

• GCC Floating-point Custom Instruction Support Overview

• GCC Single-precision Floating-point Custom Instruction Command Line

3.2.1. Built-in Functions with No Return Value

The following built-in functions in the Nios II GCC compiler have no return value. n represents the custom instruction selection index, and dataa and datab represent the input arguments, if any.

•

void __builtin_custom_n (int n);

•

void __builtin_custom_ni (int n, int dataa);

•

void __builtin_custom_nf (int n, float dataa);

•

void __builtin_custom_np (int n, void *dataa);

•

void __builtin_custom_nii (int n, int dataa, int datab);

•

void __builtin_custom_nif (int n, int dataa, float datab);

•

void __builtin_custom_nip (int n, int dataa, void *datab);

•

void __builtin_custom_nfi (int n, float dataa, int datab);

•

void __builtin_custom_nff (int n, float dataa, float datab);

•

void __builtin_custom_nfp (int n, float dataa, void *datab);

•

void __builtin_custom_npi (int n, void *dataa, int datab);

•

void __builtin_custom_npf (int n, void *dataa, float datab);

•

void __builtin_custom_npp (int n, void *dataa, void *datab);

3. Custom Instruction Software Interface

UG-20286 | 2020.04.27

3.2.2. Built-in Functions that Return a Value of Type Int

The following built-in functions in the Nios II GCC compiler return a value of type int.

n represents the custom instruction selection index, and dataa and datab represent

the input arguments, if any.

•

int __builtin_custom_in (int n);

•

int __builtin_custom_ini (int n, int dataa);

•

int __builtin_custom_inf (int n, float dataa);

•

int __builtin_custom_inp (int n, void *dataa);

Nios II Custom Instruction User Guide

Send Feedback

3. Custom Instruction Software Interface

UG-20286 | 2020.04.27

•

int __builtin_custom_inii (int n, int dataa, int datab);

•

int __builtin_custom_inif (int n, int dataa, float datab);

•

int __builtin_custom_inip (int n, int dataa, void *datab);

•

int __builtin_custom_infi (int n, float dataa, int datab);

•

int __builtin_custom_inff (int n, float dataa, float datab);

•

int __builtin_custom_infp (int n, float dataa, void *datab);

•

int __builtin_custom_inpi (int n, void *dataa, int datab);

•

int __builtin_custom_inpf (int n, void *dataa, float datab);

•

int __builtin_custom_inpp (int n, void *dataa, void *datab);

3.2.3. Built-in Functions that Return a Value of Type Float

The following built-in functions in the Nios II GCC compiler return a value of type

float. n represents the custom instruction selection index, and dataa and datab

represent the input arguments, if any.

•

float __builtin_custom_fn (int n);

•

float __builtin_custom_fni (int n, int dataa);

•

float __builtin_custom_fnf (int n, float dataa);

•

float __builtin_custom_fnp (int n, void *dataa);

•

float __builtin_custom_fnii (int n, int dataa, int datab);

•

float __builtin_custom_fnif (int n, int dataa, float datab);

•

float __builtin_custom_fnip (int n, int dataa, void *datab);

•

float __builtin_custom_fnfi (int n, float dataa, int datab);

•

float __builtin_custom_fnff (int n, float dataa, float datab);

•

float __builtin_custom_fnfp (int n, float dataa, void *datab);

•

float __builtin_custom_fnpi (int n, void *dataa, int datab);

•

float __builtin_custom_fnpf (int n, void *dataa, float datab);

•

float __builtin_custom_fnpp (int n, void *dataa, void *datab);

3.2.4. Built-in Functions that Return a Pointer Value

The following built-in functions in the Nios II GCC compiler return a pointer value. n represents the custom instruction selection index, and dataa and datab represent the input arguments, if any.

•

void *__builtin_custom_pn (int n);

•

void *__builtin_custom_pni (int n, int dataa);

•

void *__builtin_custom_pnf (int n, float dataa);

•

void *__builtin_custom_pnp (int n, void *dataa);

•

void *__builtin_custom_pnii (int n, int dataa, int datab);

•

void *__builtin_custom_pnif (int n, int dataa, float datab);

Send Feedback

Nios II Custom Instruction User Guide

3. Custom Instruction Software Interface

•

void *__builtin_custom_pnip (int n, int dataa, void *datab);

•

void *__builtin_custom_pnfi (int n, float dataa, int datab);

•

void *__builtin_custom_pnff (int n, float dataa, float datab);

•

void *__builtin_custom_pnfp (int n, float dataa, void *datab);

•

void *__builtin_custom_pnpi (int n, void *dataa, int datab);

•

void *__builtin_custom_pnpf (int n, void *dataa, float datab);

•

void *__builtin_custom_pnpp (int n, void *dataa, void *datab);

3.3. Custom Instruction Assembly Language Interface

The Nios II custom instructions are accessible in assembly code as well as C/C++.

3.3.1. Custom Instruction Assembly Language Syntax

Nios II custom instructions use a standard assembly language syntax:

custom <selection index>, <Destination>, <Source A>, <Source B>

• <selection index>—The 8-bit number that selects the particular custom instruction

•

<Destination>—Identifies the register where the result from the result port (if any) will be placed

• <Source A>—Identifies the register that provides the first input argument from

the dataa port (if any)

• <Source B>—Identifies the register that provides the first input argument from

the datab port (if any)

UG-20286 | 2020.04.27

You designate registers in one of two formats, depending on whether you want the custom instruction to use a Nios II register or an internal register:

•

r<i>—Nios II register <i>

•

c<i>—Custom register <i> (internal to the custom instruction component)

The use of r or c controls the readra, readrb, and writerc fields in the the custom instruction word.

Custom registers are only available with internal register file custom instructions.

Related Information

Custom Instruction Word Format on page 21

Detailed information about instruction fields and register file selection

3.3.2. Custom Instruction Assembly Language Examples

These examples demonstrate the syntax for custom instruction assembly language calls.

custom 0, r6, r7, r8

Nios II Custom Instruction User Guide

Send Feedback

+ 46 hidden pages