Visible to Intel only — GUID: GUID-5D83E50F-29C4-492F-9A97-FB554CF66588
Visible to Intel only — GUID: GUID-5D83E50F-29C4-492F-9A97-FB554CF66588
Memory-Mapped (MM) Agent Kernel Invocation Interface
The compiler generates an invocation interface for your SYCL* kernel that you can use to control the kernel and pass in kernel arguments.
By default, the Intel® oneAPI DPC++/C++ Compiler generates a memory-mapped (MM) agent interface to control the kernel and pass in the kernel arguments.
Examples of MM Agent Kernel Invocation Interfaces
#include <sycl/sycl.hpp> using namespace sycl; struct MyFunctorIP { int *input_a, *input_b, *input_c; int n; void operator()() const { for (int i = 0; i < n; i++) { input_c[i] = input_a[i] + input_b[i]; } } }; ... q.single_task(MyFunctorIP{functor_input_A, functor_input_B, functor_input_C, kN}).wait();
#include <sycl/sycl.hpp> using namespace sycl; class MyLambdaIP; ... q.single_task<MyLambdaIP>([=] { for (int i = 0; i < n; i++) { lambda_input_C[i] = lambda_input_A[i] + lambda_input_B[i]; } }).wait();
Register Map Layout
Byte Address | Read/Write | Description |
---|---|---|
0x00 | Read only | 64-bit status register |
0x08 | Write only | 64-bit start register |
0x10 | reserved | |
0x18 | ||
0x20 | ||
0x28 | ||
0x30 | Read only | finish counter |
0x38 | reserved | |
0x40 | ||
0x48 | ||
0x50 | ||
0x58 | ||
0x60 | ||
0x68 | ||
0x70 | ||
0x78 | ||
0x80 | Write only | kernel arguments and pipes that use protocol_name::avalon_mm or protocol_name::avalon_mm_uses_ready |
0x88 | Write only | |
… | Write only |
Byte | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
Description | reserved | CSR Address Map Version* | kernel_status Bits |
The CSR address map version might change when you update the Intel® oneAPI DPC++/C++ Compiler. If the CSR address map version changes, review the generated CSR structure and any code that you that depends on the CSR structure.
Bit | 15 | 14:3 | 2 | 1 | 0 |
Description | running | reserved | busy | done | reserved |
- bit 15: running
Set to 1 if there is an invocation of the corresponding IP that started but not finished.
- bit 2: busy
This bit is set to 1 by the IP when it cannot accept any new input. New arguments can be written to the argument registers, but they overwrite any buffered arguments that have not been consumed. Any writes to the start bit in the start register are ignored.
If your kernel arguments do not change while the kernel is executing, you can disable this behavior to try to save some hardware area in your design. For more information, refer to Stable Arguments.
- bit 1: done
This bit is set to 1 by the IP when an invocation of the IP finishes processing. This bit is cleared by reading the finish_counter register.
Bit | 63:1 | 0 |
Description | reserved | start |
Register Map Header File
The compiler generates a header file that provides the addresses of various registers in the agent memory map. A top-level header file named register_map_offsets.h is created in the .prj/include directory for each device image that you can include if you are interfacing with the SYCL* device image.
An additional header is generated for each of your kernels within the .prj directory. Each kernel has a <kernel_name>_register_map.h file associated with it. The file is located in the .prj/include/kernel_headers directory.
The register_map_offsets.h header file includes these <kernel_name>_register_map.h files and defines the address offsets for each kernel.
In most cases, include only the register_map_offsets.h file directly. However, you might still need to refer to the individual kernel <kernel_name>_register_map.h files for the macro definitions that you need to use in your application.
/* This header file describes the Register Map for the MyFunctorIP kernel */ /* Note that this header file should NOT be included directly! */ /* Please include the top-level header file register_map_offsets.h instead! */ #ifndef __MYFUNCTORIP_REGISTER_MAP_REGS_H__ #define __MYFUNCTORIP_REGISTER_MAP_REGS_H__ /* Status register contains all the control bits to control kernel execution */ /******************************************************************************/ /* Memory Map Summary */ /******************************************************************************/ /* Address | Access | Register | Argument | Description ---------|--------|--------------|---------------------|----------------------------- 0x0 | R | reg0[63:0] | Status[63:0] | * Read the status bits | | | | that are described below ---------|--------|--------------|---------------------|----------------------------- 0x8 | W | reg1[31:0] | Start[31:0] | * Write 1 to initiate a | | | | kernel start ---------|--------|--------------|---------------------|----------------------------- 0x30 | R | reg6[31:0] | FinishCounter[31:0] | * Read to get number of | | reg6[63:32] | FinishCounter[31:0] | kernel finishes, note | | | | that this register | | | | will clear on read ---------|--------|--------------|---------------------|----------------------------- 0x80 | W | reg16[63:0] | arg_input_a[63:0] | ---------|--------|--------------|---------------------|----------------------------- 0x88 | W | reg17[63:0] | arg_input_b[63:0] | ---------|--------|--------------|---------------------|----------------------------- 0x90 | W | reg18[63:0] | arg_input_c[63:0] | ---------|--------|--------------|---------------------|----------------------------- 0x98 | W | reg19[31:0] | arg_n[31:0] | The status register (0x00) has the following layout: Byte | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -------------|---------------|-------------------------|--------------------| Description | Reserved | CSR Address Map Version | kernel_status Bits | If the structure of the generated CSR changes in future versions of the Intel® oneAPI DPC++/C++ Compiler, the CSR address map version will be updated. The current CSR address map version is 5. If the CSR address map version changes, review the generated CSR structure and any code that depends on the CSR structure. The kernel_status bits have the following layout: Bit | 15 | 14:3 | 2 | 1 | 0 | -------------|---------|----------|---------|---------|------------| Description | running | reserved | busy | done | reserved | */ #define CSR_VERSION_NUMBER (5) /******************************************************************************/ /* Register Address Macros */ /******************************************************************************/ /* Status Register Bit Offsets (Bits) */ /* Note: Bits In Status Registers Are Marked As Read-Only or Read-Write Please Do Not Write To Read-Only Bits */ #ifndef __REGISTER_BITOFFSET_MACROS__ #define __REGISTER_BITOFFSET_MACROS__ #define KERNEL_REGISTER_MAP_DONE_OFFSET (1) // Read-only #define KERNEL_REGISTER_MAP_BUSY_OFFSET (2) // Read-only #define KERNEL_REGISTER_MAP_RUNNING_OFFSET (15) // Read-only #endif /* Status Register Bit Masks (Bits) */ #ifndef __REGISTER_BITMASK_MACROS__ #define __REGISTER_BITMASK_MACROS__ #define KERNEL_REGISTER_MAP_DONE_MASK (0x2) #define KERNEL_REGISTER_MAP_BUSY_MASK (0x4) #define KERNEL_REGISTER_MAP_RUNNING_MASK (0x8000) #endif /* Byte Addresses */ #define MYFUNCTORIP_REGISTER_MAP_STATUS_REG (0x0 + MYFUNCTORIP_REGISTER_MAP_OFFSET) #define MYFUNCTORIP_REGISTER_MAP_START_REG (0x8 + MYFUNCTORIP_REGISTER_MAP_OFFSET) #define MYFUNCTORIP_REGISTER_MAP_FINISHCOUNTER_REG (0x30 + MYFUNCTORIP_REGISTER_MAP_OFFSET) #define MYFUNCTORIP_REGISTER_MAP_FINISHCOUNTER_REG (0x30 + MYFUNCTORIP_REGISTER_MAP_OFFSET) #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_INPUT_A_REG (0x80 + MYFUNCTORIP_REGISTER_MAP_OFFSET) #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_INPUT_B_REG (0x88 + MYFUNCTORIP_REGISTER_MAP_OFFSET) #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_INPUT_C_REG (0x90 + MYFUNCTORIP_REGISTER_MAP_OFFSET) #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_N_REG (0x98 + MYFUNCTORIP_REGISTER_MAP_OFFSET) /* Argument Sizes (bytes) */ #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_INPUT_A_SIZE (8) #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_INPUT_B_SIZE (8) #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_INPUT_C_SIZE (8) #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_N_SIZE (4) /* Argument Masks */ #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_INPUT_A_MASK (0xffffffffffffffffULL) #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_INPUT_B_MASK (0xffffffffffffffffULL) #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_INPUT_C_MASK (0xffffffffffffffffULL) #define MYFUNCTORIP_REGISTER_MAP_ARG_ARG_N_MASK (0xffffffffULL) #endif /* __MYFUNCTORIP_REGISTER_MAP_REGS_H__ */