Hardware Function Call Guidelines

  • Stub functions generated in the SDSoC™ environment transfer the exact number of bytes according the compile-time determinable array bound of the corresponding argument in the hardware function declaration. If a hardware function admits a variable data size, you can use the following pragma to direct the SDSoC environment to generate code to transfer data whose size is defined by an arithmetic expression:
    #pragma SDS data copy|zero_copy(arg[0:<C_size_expr>])
    #pragma SDS data zero_copy(arg[0:<C_size_expr>])

    where the <C_size_expr> must compile in the scope of the function declaration.

    The zero_copy pragma directs the SDSoC environment to map the argument into shared memory.

    Be aware that mismatches between intended and actual data transfer sizes can cause the system to hang at runtime, requiring laborious hardware debugging.

  • Align arrays transferred by DMAs on cache-line boundaries (for L1 and L2 caches). Use the sds_alloc() API provided with the SDSoC environment instead of malloc() to allocate these arrays.
  • Align arrays to page boundaries to minimize the number of pages transferred with the scatter-gather DMA, for example, for arrays allocated with malloc.
  • You must use sds_alloc to allocate an array for the following two cases:
    1. You are using zero-copy pragma for the array.
    2. You are using pragmas to explicitly direct the system compiler to use Simple-DMA.
    Note that in order to use sds_alloc() from sds_lib.h, it is necessary to include stdlib.h before including sds_lib.h. stdlib.h is included to provide the size_t type.