Codec Engine GroupIds

Codec Engine Group IDs

Introduction

Group Ids are a mechanism for sharing resources between different algorithms. Algorithms in the same group share resources, and therefore _cannot_ run at the same time. Algorithms in different groups do not share resources, so they can run concurrently, but they will require more resources. This Framework Components FAQ describes some of this resource sharing as well.

How you partition algorithms into Groups can affect performance or whether a algorithm can be created at all.

Note that algs in both a Server.algs[] and an Engine.algs[] array have an optional .groupId config param assignable in the integrator's .cfg script. Understand that there is a distinction between the Server.algs[] and Engine.algs[] arrays. This makes sense, if you consider that "DSP-based algs" on DM644x will be configured into a Server, and the same "DSP-based algs" on DM643x will be configured into an Engine.

Server.algs[].groupId

For each alg in the respective algs array, if this optional parameter is uninitialized, the alg will be configured into a group with other algorithms which 1) have their .groupId field uninitialized and 2) are at the same priority. If no algs have both of these attributes, it will be in a unique groupId. Exactly which groupId it will be assigned into is non-deterministic. See the Uninitialized groupId section below for further details and pitfalls.

An example server config where the algs' .groupId field is set follows:

<syntaxhighlight lang='javascript'> /*

*  ======== Server Configuration ========
*/

var Server = xdc.useModule('ti.sdo.ce.Server');

/*

* The array of algorithms this server can serve up.  This array also configures
* details about the threads which will be created to run the algorithms
* (e.g. stack sizes, priorities, etc.).
*/

Server.algs = [

   {
       name:           "viddec_copy",    // C name for the of codec
       mod:            VIDDEC_COPY,      // var VIDDEC_COPY defined above
       threadAttrs: {
           stackMemId: 0,                // BIOS MEM seg. ID for task's stack
           priority:   Server.MINPRI + 1 // task priority
       },
       groupId :       0,                // scratch group ID
   },
   {
       name:           "videnc_copy",
       mod:            VIDENC_COPY,
       threadAttrs: {
           stackMemId: 0,
           priority:   Server.MINPRI + 1
       },
       groupId :       0,
   },

];

/* Configure 32k of SARAM for groupId 0 */ var DSKT2 = xdc.useModule('ti.sdo.fc.dskt2.DSKT2'); DSKT2.SARAM_SCRATCH_SIZES[0] = 32 * 1024; </syntaxhighlight>

Engine.algs[].groupId

For each local alg, if this optional param is uninitialized, the alg will be configured into its own, unique groupId. This design decision was primarily made because we don't know what priority the alg will run at, so we pessimistically place it into a unique group, which will always provide non-shared resources, and allow pre-emption by any other algorithm. See the Uninitialized groupId section below for further details and pitfalls.

Note that for remote algs, this .groupId field is ignored; in those cases, the alg is placed into the Server-configured groupId, explained in the previous section.

An example Engine config where the algs' .groupId field is set follows:

<syntaxhighlight lang='javascript'> /*

*  ======== Engine Configuration ========
*/

var Engine = xdc.useModule('ti.sdo.ce.Engine'); var myEngine = Engine.create("video1_copy", [

   {
       name    : "viddec1_copy",
       mod     : decoder,
       groupId : 0,
       local   : true
   },
   {
       name    : "videnc1_copy",
       mod     : encoder,
       groupId : 0,
       local   : true
   }

]);

/* Configure 32k of SARAM for groupId 0 */ var DSKT2 = xdc.useModule('ti.sdo.fc.dskt2.DSKT2'); DSKT2.SARAM_SCRATCH_SIZES[0] = 32 * 1024; </syntaxhighlight>

Uninitialized groupId

As described above, setting the .groupId field is strongly recommended if algs share resources - but it is technically optional, so the tools will not warn you if you fail to set it. This section describes the risk with not setting this field.

If the field is uninitialized, the alg will be configured into a non-deterministic groupId. Therefore, it's not possible to configure scratch resources (e.g. DSKT2 scratch memory, DMAN3 DMA resources, etc) for this non-deterministic groupId. It's important therefore, that if the system integrator intends for an alg's resources to be shared, this .groupId field should be appropriately configured.

Note, also, that when the .groupId is non-deterministically assigned, and the alg does request scratch resources, these resources will be granted from [likely non-configured] resource pools! For example, in DSKT2-based systems, DSKT2 will be granting these memory requests using the [likely non-configured] DSKT2.DARAM_SCRATCH_SIZES[<nondeterministic-groupId!>] and DSKT2.SARAM_SCRATCH_SIZES[<nondeterministic-groupId!>] memory blocks. This can lead to strange system behavior, including algs that sometimes can be created but other times will fail.

Common Techniques

For maintenance reasons (and perhaps better readability!), some users prefer to assign a variable for the group id and use the variable rather than a constant value throughout. Using that technique, the Engine config above could be written like this:

<syntaxhighlight lang='javascript'> /* video group id assignment. To change the video group id, simply change this one value */ var videoGroupId = 0;

/*

*  ======== Engine Configuration ========
*/

var Engine = xdc.useModule('ti.sdo.ce.Engine'); var myEngine = Engine.create("video1_copy", [

   {
       name    : "viddec1_copy",
       mod     : decoder,
       groupId : videoGroupId,
       local   : true
   },
   {
       name    : "videnc1_copy",
       mod     : encoder,
       groupId : videoGroupId,
       local   : true
   }

]);

/* Configure 32k of SARAM for videoGroupId */ var DSKT2 = xdc.useModule('ti.sdo.fc.dskt2.DSKT2'); DSKT2.SARAM_SCRATCH_SIZES[videoGroupId] = 32 * 1024; </syntaxhighlight>