IRES HDVICP2

From Texas Instruments Embedded Processors Wiki

Jump to: navigation, search

Translate this page to

IRES HDVICP2 refers to an implementation of the IRES (resource request) and IRESMAN (resource manager) interfaces for the HDVICP2 or the IVAHD accelerator as seen on some TI81XX and recent OMAP devices. As described in the Framework Components Resource Management article, when an algorithm/codec requests an IRES resource via its resource descriptor, it is granted an IRES object by the resource manager, that describes/identifies the 'physical' resource being granted.

FC's IRES HDVICP2 resource manager also supports IRES LATEACQUIRE type of requests and along with the ID of the resource, it exposes certain other functional APIs that the algorithms/codecs can call after being granted the resource.

HDVICP2 Protocol Arguments

The following attributes are used by the algorithm when requesting an IRES_HDVICP resource:

int	base.size
IRES_RequestMode	base.mode
XDAS_Int32	id

The field definitions are described in the following list:

int size

Size of this structure in bytes.

IRES_RequestMode mode

The mode can be IRES_SCRATCH, IRES_PERSISTENT or IRES_LATEACQQUIRE. When persistent, the resource will be allocated exclusively for this algorithm. In scratch or late acquire type requests, the resource could be shared with the other codecs/algorithms.

XDAS_Int32 id

id can be one of the following co-processor types:

0 -> HDVICP processor 0 (Valid on OMAP4, TI81XX)
1 -> HDVICP processor 1 (Valid only on TI816X)
2 -> HDVICP processor 2 (Valid only on TI816X)
IRES_HDVICP_ID_ANY -> Any available HDVICP processor (Valid on OMAP4, TI81XX)
IRES_HDVICP2_ID_LATE_ACQUIRE -> Resource to be requested later in the cycle (typically during the algorithm's process() call.

HDVICP2 Resource Properties

The following fields are introduced as an extension of the IRES_Obj structure:

Void *info

Currently undefined.

XDAS_Int32 id

The ID of the HDVICP2 that has been granted. Could be a valid number (0 for OMAP4;0,1,2 for Netra) or it could be set to IRES_HDVICP2_ID_LATE ACQUIRE to indicate that the resource was requested and will be granted later via some APIs below

Void * memoryBaseAddress

Memory space base address of the HDVICP2 being granted

Void *registerBaseAddress

Register space base address of the HDVICP2 being granted

Void *resetControlAddress

HDVICP2 reset controller address

XDAS_Void (*acquire)(IALG_Handle algHandle, struct IRES_HDVICP2_Obj * this, IRES_YieldContext * yieldCtxt, XDAS_UInt32 * hdvicp2Status, XDAS_UInt32 *configurationId, XDAS_Int32 lateAcquireArg);

API used to acquire an HDVICP2 instance that was previously requested as type IRES_LATEACQUIRE.

yieldCtxt argument is required because this is a blocking call and the framework might choose to yield context to other same/higher priority algorithms/codecs or if the resource being acquired is unavailable. This argument is required to allow other algorithms to run without messing up context of current algorithm/codec.

configurationId is both an input and output argument; it is a codec specified parameter that is associated with the resource being granted. The value passed in via the API is saved against the resource being returned, and the value passed by the previous running codec is returned via this call. Codec typically uses this information to optimize on the kind of reload required for the IVAHD

lateAcquireArg is an optional framework supplied parameter, used by specific codecs. Use IRES_HDVICP2_UNKNOWNLATEACQUIREARG is this isn't supplied.

XDAS_Void (*release)(IALG_Handle algHandle, struct IRES_HDVICP2_Obj * this);

API to release the HDVICP2 reosurce being used to make it available for other algorithms/codecs.

XDAS_UInt32 (*reacquireIfOwner)(IALG_Handle algHandle, struct IRES_HDVICP2_Obj * this);

API to reacquire the HDVICP2 resource that was recently acquired and released(using above APIs). A valid resource handle with a status of XDAS_TRUE is returned if the handle is still valid (not yet acquired by some other algorithm), else a status of XDAS_FALSE is returned.

XDAS_Void (*configure)(IALG_Handle algHandle, struct IRES_HDVICP2_Obj * this, IRES_HDVICP2_CallbackFxn cbFunctionPtr, XDAS_Void * cbArgs);

API to register a callback funtion and arguments with a particular HDVICP2 instance. The callback API is called when an interrupt fires after processing data. It is the codec's responsibility to configure the HDVICP2 to process data and fire the interrupt when done.

XDAS_UInt32 (*wait)(IALG_Handle algHandle, struct IRES_HDVICP2_Obj * this, IRES_YieldContext * yieldCtxt);

API to wait till the HDVICP2 is done processing and then return. This is a blocking call, unless a positive timeout value is configured, in which case, the call returns after timeout with a status (XDAS_TRUE, XDAS_FALSE) indicating success or failure.

XDAS_Void (*done) (IALG_Handle algHandle, struct IRES_HDVICP2_Obj * this);

This API is called from within the interrupt handler function when processing completes, and is used to unblock the wait API above. Typically, this API is called from within the codec's callback function (see acquire call above).

XDAS_UInt32 (*reset)(IALG_Handle algHandle, struct IRES_HDVICP2_Obj * this);

This API can be called by the codec to "reset" the HDVICP2, and it is usually called when an acquired HDVICP2 is "dirty", i.e, it requires both program/data reload. It works off of a configured maximum reset cycle delay, and returns with a status (XDAS_TRUE, XDAS_FALSE) indicating success or failure.

HDVICP2 API FAQ

Here are some FAQ about the IRES HDVICP2 resource and associated APIs. We will add to this section as we get/answer more queries:-

If a resource of type `IRES_HDVICP2` is acquired with `IRES_RequestMode` set to `IRES_LATEACQUIRE`, what is returned by the framework at the time the algorithm is created and granted resources ?	Since `IRES_LATEACQUIRE` will not grant a resource at the time of algorithm creation, it will return an `IRES_HDVICP2` handle that exposes the APIs that can be used to `acquire` the resource "just-in-time". These resource ares typically requested within the codec/algorithm's `process` call using APIs discussed above.
What happens if a resource is unavailable when the `acquire` API is called ?	The implementation of these APIs is framework dependent. In the current implementation, the thread that requested the resource blocks while the processor is freed up to run other threads that may have all the resources they need to proceed.
What is the purpose of the `reacquireIfOwner` API and how is it different from the `acquire` ?	The `reacquireIfOwner` API doesn't attempt to find a free HDVICP2 resource to return to the requesting algorithm. It simply checks to see if the resource previously used by the algorithm (via calls to `acquire` and `release`) is still active, i.e, it hasn't been granted to some other algorithm. The return status of the call (`XDAS_TRUE` vs `XDAS_FALSE`) indicates if the resource is still 'active'. Some codecs use this API to determine if that data/information associated with a particular codec is still available in SL2 or has been restored to DDR2, but the use of this API is codec implementation dependent.
In the `acquire` call, what is the purpose of the `hdvicp2Status` and `configurationId` fields and how are they different ?	Both `hdvicp2Status` and the `configurationId` are used to communicate information about the HDVICP2 resource being returned to the codec. `hdvicp2Status` returns one of 3 values of type `IRES_HDVICP2_Status`:- `SAMECODEC` indicating that the last user of this resource, is the same as the requesting codec/algorithm `SAMECODECTYPE` indicating that the last user of this resource, is a different instance of the same codec class as the requesting codec/algorithm `DIFFERENTCODEC` indicating that the last user of this resource doesn't have any apparent similarity to the currently running codec. The `configurationId` field is a codec implementation specific input/output field that can be used to associate some codec specific information with the resource. During a call to `acquire`, codec populates this field, the contents of which are associated with the resource being granted to it. Also the `configurationId` information, specified by the last algorithm/codec that used this resource is returned via the same `acquire` call. The idea is to give the codec information via the `configurationId` and `hdvicp2Status` that it can use to optimize on the operations it needs to perform.