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:
- Make sure you have read Before Using the Cache Allocation Library.
- 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:
- Calltcc_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 calltcc_cache_init()withcpuid = 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 functiontcc_cache_init()are as follows:Status codeDescription0Initialization successful.TCC_BUFFER_NOT_FOUNDThe real-time configuration driver (tcc_buffer) is unavailable. The cache allocation library falls back to the standard Linuxmalloc()functions. Latency requirements are not guaranteed.status < 0An error occurred, it is not possible to continue using the cache allocation library. - Calltcc_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);Thetcc_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 bytcc_cache_set_default_latency(). The memory will not be zero initialized.
- tcc_cache_calloc_default(): Allocates memory according to the latency requirement set bytcc_cache_set_default_latency(). The memory will be zero initialized.
Thetcc_cache_malloc_default()andtcc_cache_calloc_default()functions have the same signature as standardmalloc()andcalloc(). They can be used to replace the standard functions without modifying the code. Pointers totcc_cache_*_default()can be used where pointers to the standard functions are expected. - Use the memory pointer. The following example copies time-critical data to the buffer, wherecritical_datais the pointer to the data andcritical_data_sizeis the size of the data in bytes.memcpy(mem, critical_data, critical_data_size);
- (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) - Calltcc_cache_free()to deallocate the memory. Parameters:
- ptr: Pointer to the memory block
tcc_cache_free(mem); - Calltcc_cache_finish()to release all resources and reset settings initialized bytcc_cache_init().tcc_sts = tcc_cache_finish();
The Cache Allocation Sample is an example of using the library.