Developer Guide

  • 2021.1
  • 11/03/2021
  • Public
Contents

Allocate a Buffer

The following steps show how to use cache allocation library APIs to allocate a buffer in your code. For more information, see the API Reference (Related Documentation).
Note:
  • Before using the cache allocation library to allocate low-latency buffers, you need to configure buffers using Cache Configurator. Without this step, only DRAM buffers can be used.
  • Root privileges are required.
  • Since cache is smaller than DRAM, take extra care not to overuse the cache, and handle the return value carefully (always checking for NULL).
  • Call the cache allocation library from the initialization stage, rather than the control loop itself, to avoid overhead.
To allocate a buffer:
  1. Call
    tcc_cache_init()
    to initialize internal structures and global settings. You can use optional parameters to customize the behavior of this function. To specify optional parameters, use the
    .parameter_name = value
    notation, similar to C99 structure designated initializers. Optional parameters:
    • .cpuid
      (optional): Processor core where your real-time application should run (CPU affinity). When you call
      tcc_cache_init()
      with
      .cpuid = 3
      , for example, the API moves the application to Core 3, where it will run. Default -1 (keep existing affinity). Affinity should match the CPU affinity used to reserve software SRAM with the cache configurator.
    • .latency
      (optional): Maximum tolerable time for a single cache line access in nanoseconds, without taking into account possible OS influence, such as interrupts. Used for subsequent
      tcc_cache_malloc_default()
      and
      tcc_cache_calloc_default()
      calls. Default is 0. You need to set this to a non-default value for
      tcc_cache_malloc_default()
      and
      tcc_cache_calloc_default()
      calls; otherwise, they will return NULL, as zero latency cannot be achieved.
    static int cpuid = 3; int status = tcc_cache_init(.cpuid=cpuid, .latency = 80);
    The optional parameters are implemented using designated initializers, which have been available for C language since C99. This function is not applicable to C++ language including C++20 standard.
    Return value of the function
    tcc_cache_init()
    indicates if initialization was successful:
    Status code
    Description
    0
    initialization successful
    TCC_BUFFER_NOT_FOUND
    tcc_buffer
    driver is unavailable. The cache allocation library falls back to the standard Linux
    malloc()
    functions. Latency requirements are not guaranteed.
    status < 0
    An error occurred, it is not possible to continue using the cache allocation library.
  2. Call
    tcc_cache_malloc()
    to allocate a buffer. Parameters:
    • size
      : Size of the memory block in bytes. This is the standard input parameter to a malloc call.
    • latency
      : Maximum tolerable time for a single cache line access in nanoseconds, without taking into account possible OS influence, such as interrupts.
    void *mem = tcc_cache_malloc(critical_data_size, latency);
    The
    tcc_cache_malloc()
    function is one of several allocation functions that you can choose from. For more information about these functions, see the API Reference.
    • tcc_cache_malloc()
      : Allocates memory according to the specified latency requirement. The memory will not be zero initialized.
    • tcc_cache_calloc()
      : Allocates memory according to the specified latency requirement. The memory will be zero initialized.
    • tcc_cache_malloc_default()
      : Allocates memory according to the latency requirement set by
      tcc_cache_init()
      . The memory will not be zero initialized.
    • tcc_cache_calloc_default()
      : Allocates memory according to the latency requirement set by
      tcc_cache_init()
      . The memory will be zero initialized.
    The
    tcc_cache_*_default()
    functions have the same signature as standard
    malloc()
    and
    calloc()
    . They can be used to replace the standard functions without modifying the code. Pointers to
    tcc_cache_*_default()
    can be used where pointers to the standard functions are expected.
  3. Use the memory pointer. The following example copies time-critical data to the buffer, where
    critical_data
    is the pointer to the data and
    critical_data_size
    is the size of the data in bytes.
    memcpy(mem, critical_data, critical_data_size);
  4. (Optional) Change the size of the memory block. The latency requirement remains the same. Parameters:
    • ptr
      : Pointer to the memory block to be reallocated
    • size
      : New size of the array in bytes
    tcc_cache_realloc(mem, 32)
  5. Call
    tcc_cache_free()
    to deallocate the memory. Parameters:
    • ptr
      : Pointer to the memory block
    tcc_cache_free(mem);
  6. Call
    tcc_cache_finish()
    to release all resources and reset settings initialized by
    tcc_cache_init()
    .
    tcc_sts = tcc_cache_finish();
The Cache Allocation Sample is an example of using the library.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.