Intel® Time Coordinated Computing Tools (Intel® TCC Tools) 2021.2 Developer Guide

Developer Guide

  • 2021.2
  • 06/11/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. Parameters:
    • .cpuid
       : 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. The affinity should match the CPU affinity used to reserve software SRAM with the cache configurator.
    static int cpuid = 3;
int status = tcc_cache_init(cpuid);
    Return values of the function
    tcc_cache_init()
     are as follows:
    Status code
    Description
    0
    Initialization successful.
    TCC_BUFFER_NOT_FOUND
    The real-time configuration driver (
    tcc_buffer
    ) 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_set_default_latency()
      . The memory will not be zero initialized.
    • tcc_cache_calloc_default()
      : Allocates memory according to the latency requirement set by
      tcc_cache_set_default_latency()
      . The memory will be zero initialized.
    The
    tcc_cache_malloc_default()
     and
    tcc_cache_calloc_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.