3.5.1.21.4 Pointer Argument Driver Functions

For each pointer (including array, struct types) argument that is configured to use AXI4 target interface (see AXI4 Target Interface), SmartHLS™ generates driver functions for the CPU to write and read the argument into and from the SmartHLS module, respectively. The type of transfer is also reflected in the signature by using *_memcpy_* or *_dma_*.
Table 3-10. Pointer Argument Driver Functions
Operating SystemFunction SignatureDescription
Linuxvoid <TopFunc>_memcpy_write_<PtrArg>(void* <PtrArg>, uint64_t byte_size, void *virt_addr);These functions perform memory-mapped write/read operations (using the standard memcpy function). It is the CPU who copies the data from its memory as pointed to by <PtrArg> and the SmartHLS module's on-chip storage. The total size to transfer is defined by the 'byte_size' argument. These functions do NOT use DMA.
Baremetalvoid <TopFunc>_memcpy_write_<PtrArg>(void* <PtrArg>, uint64_t byte_size, uint32_t base_addr);
Linuxvoid <TopFunc>_memcpy_read_<PtrArg> (void* <PtrArg>, uint64_t byte_size, void *virt_addr);
Baremetalvoid <TopFunc>_memcpy_read_<PtrArg> (void* <PtrArg>, uint64_t byte_size, uint32_t base_addr);
Linuxvoid <TopFunc>_dma_write_<PtrArg>(void* <PtrArg>, uint64_t byte_size, void *virt_addr);These functions perform memory-mapped write/read operations using the DMA engine in the HSS to move data between the CPU's memory at <PtrArg> and the SmartHLS module's on-chip storage. The total size to transfer is defined by the 'byte_size' argument.
Baremetalvoid <TopFunc>_dma_write_<PtrArg>(void* <PtrArg>, uint64_t byte_size, uint32_t base_addr);
Linuxvoid <TopFunc>_dma_read_<PtrArg> (void* <PtrArg>, uint64_t byte_size, void *virt_addr);
Baremetalvoid <TopFunc>_dma_read_<PtrArg> (void* <PtrArg>, uint64_t byte_size, uint32_t base_addr);

The DMA driver functions can use one of two different DMA engines depending on the target FPGA family and HLS project settings. Note that when the HLS project's target flow is set to Icicle_SoC (see set_project), SmartHLS™ by default uses the harden platform DMA (PDMA) engine in the Microprocessor Sub-System (MSS). In this case, the DMA driver functions are expected to run on a Linux Operating System (see Step 5: Flashing the Linux Image to the Board), and the processor memory referenced by the pointer argument (PtrArg) must be allocated by the hls_malloc function (see Memory Allocation Library). On PolarFire® SoC devices, it is recommended to use the PDMA engine for data transfer when the transfer size is equal to or bigger than 16KB, and use the memcpy driver functions when the transfer size is smaller than 16KB.

When targeting a Soft-MiV CPU or other FPGA device families,SmartHLS assumes that a Soft-DMA core IP CoreAXI4DMAController is implemented in FPGA Fabric and is connected with the processor memory and the HLS accelerator's AXI4 target interface. When using a project type MiV_SoC then SmartHLS SoC flow will automatically instantiate and connect the Soft-DMA core. For the IP flow or a Custom Flow, it is the user's responsibility to instantiate the Soft-DMA module, if the DMA APIs are to be used. In this case, the DMA_BASE_ADDR macro in the accelerator driver header file (i.e., hls_output/accelerator_drivers/<PROJ_NAME>_accelerator_driver.h) should be updated to the base address of the DMA IP's AXI4-lite control interface.