DSPLink POOL Module Overview

END OF LIFE

DSP Link is still available for download, but no further releases or updates are planned. Please see IPC Software Options for details and alternatives.

DSPLink POOL Module Overview

Overview

The POOL component provides APIs for configuring shared memory regions across processors.
These buffers are used by other modules from DSP/BIOS Link for providing inter-processor communication functionality.

Availability

The POOL module as part of MSGQ is available in DSPLink releases from 1.20 onwards.
However, APIs for allocating and freeing buffers, and dynamic configuration are available from 1.40.03 onwards.

Features

The specific features provided by this module are:

• Configure the shared memory region through open & close calls.
• Allocate and free buffers from the shared memory region.
• Translate address of a buffer allocated to different address spaces (e.g. GPP to DSP)
• Synchronize contents of memory as seen by the different CPU cores.

This component is responsible for providing a uniform view of different memory pool implementations, which may be specific to the hardware architecture or OS on which DSPLink is ported. This component is based on the POOL interface in DSP/BIOS.
The DSPLink POOL is not a heap-based pool. It is a fixed-size buffer pool. It requires the specific configuration of number of buffers and sizes as will be used by the application. The exactMatchReq property only allows users the flexibility of configuring an approximate size for each buffer. However, the maximum number of buffers still must be configured.

Usage

Header files

The header file to be included for using POOL module on both GPP and DSP-side is pool.h <syntaxhighlight lang=c>

1. include <pool.h>

</syntaxhighlight> On DSP-side, additional header file sma_pool.h is required to be included. This contains the definitions for DSPLink-specific multi-processor POOL implementation. <syntaxhighlight lang=c>

1. include <sma_pool.h>

</syntaxhighlight>

Dependencies

• POOL module has a dependency on PROC module. The PROC module is expected to be initialized through calls to PROC_setup and PROC_attach. Since DSP will be used, PROC_load and PROC_start are also needed.
• POOL module internally uses MPCS module for protection of its shared structures.
• For allocation of buffers from multi-processor POOLs (part of DSPLink), POOL APIs must be used only after DSPLINK_init() is called so that the modules have been initialized on DSP-side. Usually DSPLink will get initialized automatically before main (through DSPLink POOL initialization function plugged into DSP/BIOS, which internally calls DSPLINK_init.). Hence POOL APIs can be called from DSP-side main function.

Configuration

Configuration parameters

The POOL_open () call is used to configure the shared memory requirement for the application. Since the pool is shared between DSP and GPP, the sizes of the buffers must be cache aligned. DSPLink provides an API DSPLINK_ALIGN which can be used to get the cache aligned size.
For SMA Pool, we need to configure a parameter of type SMAPOOL_Attrs in the POOL_open call. The POOL_open call takes a structure of type SMAPOOL_Attrs for the POOL_open call. The elements in the structure are:

• numBufPools(): Number of buffer pools.
• bufSizes(): Array of sizes of the buffers in each buffer pools. The buffer sizes must be cache aligned.
• numBuffers(): Array of number of buffers in each buffer pools.
• exactMatchReq(): Flag indicating whether requested size is to be rounded to nearest available larger size in Pools or exact match has to be performed.

Exact match required

• exactMatchReq specified as TRUE: With this configuration, error is returned if the exact size is not found configured.
• exactMatchReq specified as FALSE: With this configuration, the highest buffer size next closest in size to the specified size to be allocated is returned. If the nearest higher size buffers are exhausted, POOL_alloc () call will return with DSP_EMEMORY or memory allocation failure.
  • You can set exactMatchReq field in the SMAPOOL_Attrs while opening the pool to FALSE, and use a large buffer size for the configuring the pool (all allocations must be less than this size).
  • Please note that the disadvantage of using exactMatchReq as FALSE is possible wastage of memory, since even a buffer of size 128 bytes may result in an allocation of size 1024 bytes if only buffers of 1024 bytes are configured in the pool.

Buffer configuration

To set the pool attributes, you need to know how many buffers that you need in the shared memory as well as their size. Depending on your application needs, you configure your pool according to the size and the number of the buffers required. You can also configure the pool to return the buffer only if an exact match size is configured or to return a buffer with a size which fits best to what has been asked.

Example

If you want to configure the pool (with exact match TRUE) to allocate 10 buffers of size 128, 10 buffers of size 512 and 10 buffers of size 2048 you may configure the pool as follows. <syntaxhighlight lang=c>

1. define NUM_BUF_SIZES 3 /* 3 buffer sizes to be configured */
2. define SAMPLE_POOL_NO 0 /* Pool no as in the config CFG_<PLATFORM>.c.

Uint32 numBufs [NUM_BUF_SIZES] ; Uint32 size [NUM_BUF_SIZES] ; SMAPOOL_Attrs poolAttrs ;

. . .

if (DSP_SUCCEEDED (status)) {

   size    [0] = 128;
   numBufs [0] = 10;

   size    [1] = 512;
   numBufs [1] = 15;

   size    [2] = 2048;
   numBufs [2] = 5;

   poolAttrs.bufSizes      = (Uint32 *) &size;
   poolAttrs.numBuffers    = (Uint32 *) &numBufs;
   poolAttrs.numBufPools   = NUM_BUF_SIZES;
   poolAttrs.exactMatchReq = TRUE;

   /* Make the pool id from pool no and dsp processor id. Applicable
    * GPP side only
    */
   poolId = POOL_makePoolId(ID_PROCESSOR, SAMPLE_POOL_NO);
   status = POOL_open(poolId, &poolAttrs);
   if (DSP_FAILED(status)) {
       APP_Print("POOL_open() failed. Status = [0x%x]\n", status);
   }

} </syntaxhighlight>

Note: The above is just a dummy representation of how to configure the POOL. In real world applications, this is more tuned to the application buffer size requirements.

In the above example:

• Consider a scenario where exactMatchReq is TRUE. The application can successfully allocate 10 buffers of size 128, 15 buffers of size 512, and 5 buffers of size 2048. If you want to allocate a buffer of size 256, the above configuration will not support it and POOL_alloc() will return error.
• Consider a scenario where exactMatchReq is FALSE. The application can successfully allocate 10 buffers of size 128, 15 buffers of size 512, and 5 buffers of size 2048. as before. However, the difference is that an attempt to allocate a buffer of size 256 will result in the POOL_alloc() call returning a buffer of next larger size i.e. 512 if available. If buffer of size 512 is not available it will return DSP_EMEMORY or memory allocation failure.

Usage

API usage to be added ...

Other POOL topics

• DSPLink POOL FAQs
• Opening DSP Pools dynamically
• Changing DSPLink POOL size