codec engine代码阅读七---codecs中的xDM，XDAIS函数解析

写可以被CE使用的算法通常要实现XDAIS或xDM标准。xDM是XDAIS的扩展。xDM自己又包括八种接口，按音频，视频，图像，语音每个再分为编码器和解码器。xDM和XDAIS的关系如图所示。


XDAIS标准分为两个接口，一个是IALG和个是IMOD。其框架如图所示。而xDM则是在XDAIS的基础上增加了一个接口，其框架图如图所示。
首先我们要先了解xDAIS的ialg接口：
ialg接口有七个函数需要我们去实现，这个链接是七个函数的调用流程。这七个函数组成一个结构体称为ialgfxns.其结构原型为： 

typedef struct IALG_Fxns {
    Void    *implementationId;
    Void    (*algActivate)(IALG_Handle);
    Int       (*algAlloc)(const IALG_Params *, struct IALG_Fxns **, IALG_MemRec *);
    Int       (*algControl)(IALG_Handle, IALG_Cmd, IALG_Status *);
    Void    (*algDeactivate)(IALG_Handle);
    Int       (*algFree)(IALG_Handle, IALG_MemRec *);
    Int       (*algInit)(IALG_Handle, const IALG_MemRec *, IALG_Handle, const IALG_Params *);
    Void    (*algMoved)(IALG_Handle, const IALG_MemRec *, IALG_Handle, const IALG_Params *);
    Int       (*algNumAlloc)(Void);
} IALG_Fxns;

有些时候其中的一些函数无需实现，但要赋值为NULL.结构体中只有第一个成员变量比较特殊，不是函数指针而是一个空指针，它的作用是唯一标识模块的实现，经常需要用到。

剩下定义的函数可以分为3类：

1.用于创建algAlloc()、初始化AlgInit()和删除algFree实例对象的函数。

2.算法处理的函数,包括：algActivate()和algDeactivate()；

3.用于控制和重定位 实例对象的函数,包括：algControl()和algMoved()。

剩下的一个algNumAlloc()函数可在任何时候调用且值不变，主要是求得算法实例的需要分配的存储器数目。

按顺序逐一解释一下：

      1.algActivate()。

功能：在数据处理之前，实现临时存储器的初始化。参数是算法实例的句柄IALG_Handle handle，通过该句柄识别出算法需要的不同类型的缓冲，并完成相应的初始化。该函数是可选实现的，仅当在数据处理之前需要初始化时才实现，如不实现可置NULL,以下雷同。

       调用的前提：必须在algInit()成功之后才能调用；handle是一个有效的算法句柄；它不能抢占对象的其它方法；如果算法实现了IDMA2接口，则algActivate()必须在dmaInit()成功后调用。实现此函数之后，算法中所有方法都可使用。

       2.algAlloc()。
功能：得到算法对象对于存储器的需求情况。

第一个参数是指向用于创建算法对象的参数，如果为NULL则是默认参数，

第二个参数是输出参数，返回给父IALG函数；

第三个参数是一个存储器记录的表格。如果成功返回一个非0整数，这个整数说明表格中包含多少个有效项。

       调用前提：存储器表格中记录的个数不能少于algNmAlloc()返回值，params允许为空。

       3.algControl()。
功能：算法的控制和状态信息的提取。

第一个参数是算法实例的句柄，剩下的2个参数是算法特定的。返回值是IALG_EOK或是其它出错信息。这个函数实现是可选的，如不实现设置为空。

       调用条件：只能在algInit()后调用，handle是一个有效句柄，cmd的数值必须小于IALG_SYSCMD。

      4.algDeactivate()。
功能：保存所有的持久数据到非临时存储器上。与algActivate()类似，在其之后只能调用algActive()或algFree()。

      5.algFree()
功能：获得算法的存储器资源。与algAlloc()类似，返回值是存储器表格的有效项数。存储器表格中包含所有传递给算法的指向缓冲的指针。

6.algInit()。

功能：初始化算法实例对象。

algInit()实现在运行阶段创建算法实例对象，在该函数成功返回后，算法实例对象才开始处理数据。

参数解释：

第一个参数是算法实例句柄，它指向一个初始化后的IALG_Obj结构，数值与memTab[0].base相同（看不明白先看下他们的数据结构）；

第二个参数是存储器记录表格，有效记录项目数与algAlloc()相同；

第三个参数是另一个算法实例对象的句柄，通常为NULL，表示没有父对象存在；

最后一个是算法特定参数，可以为NULL。

     调用条件较复杂。。。。。。

    7. algMoved()。    
功能：重新定位算法实例的存储器资源。主要是当算法实例需要移动时调用，可选实现，不实现表明不可移动。参数与algInit()中一样。

    8. algNumAlloc()。
功能：返回需要的存储器数目。必须大于等于algAlloc()的返回值，可以在任何时刻调用，且值不变

本楼结合videnc_copy和viddec_copy中的代码详细介绍一下第一个函数algAlloc()。
2.algAlloc()。

功能：得到算法对象对于存储器的需求情况。

第一个参数是指向用于创建算法对象的参数，如果为NULL则是默认参数，

第二个参数是输出参数，返回给父IALG函数；

第三个参数是一个存储器记录的表格。如果成功返回一个非0整数，这个整数说明表格中包含多少个有效项。

       调用前提：存储器表格中记录的个数不能少于algNmAlloc()返回值，params允许为空。

/*
 *  ======== VIDENCCOPY_TI_alloc ========
 */
Int VIDENCCOPY_TI_alloc(const IALG_Params *algParams,
    IALG_Fxns **pf, IALG_MemRec memTab[])
{
    /* Request memory for my object 为对象申请内存 */
    memTab[0].size = sizeof(VIDENCCOPY_TI_Obj);//设置内存表项的大小。
    memTab[0].alignment = 0;   //设置内存的对齐方式。
    memTab[0].space = IALG_EXTERNAL;//设置请求的内存类型
    memTab[0].attrs = IALG_PERSIST; //设置内存的属性


    return (1);  //只做了一个表项，返回一。
}


另一个，viddec_copy的内容是一样的：


/*
 *  ======== VIDDECCOPY_TI_alloc ========
 */
Int VIDDECCOPY_TI_alloc(const IALG_Params *algParams,
    IALG_Fxns **pf, IALG_MemRec memTab[])
{
    if (curTrace.modName == NULL) {   /* initialize GT (tracing) */
        GT_create(&curTrace, GTNAME);
    }


    GT_3trace(curTrace, GT_ENTER, "VIDDECCOPY_TI_alloc(0x%lx, 0x%lx, 0x%lx)\n",
        algParams, pf, memTab);


    /* Request memory for my object */
    memTab[0].size = sizeof(VIDDECCOPY_TI_Obj);
    memTab[0].alignment = 0;
    memTab[0].space = IALG_EXTERNAL;
    memTab[0].attrs = IALG_PERSIST;

    return (1);
}

然后我们还看algcontrol:这个函数在app中的app.c中被调用了，我们可以直接看看是怎么调用的：
status = VIDDEC_control(dec, XDM_GETSTATUS, &decDynParams, &decStatus);
参数：VIDDEC_Handle dec = VIDDEC_create(ce, decoderName, NULL); 
dec是一个解码器实例的句柄。
XDM_GETSTATUS这个参数显然是描述控制动作是获得状态。
&decDynParams 动态参数
&decStatus 状态

关于这个函数的描述是：
第一个参数是算法实例的句柄，剩下的2个参数是算法特定的。返回值是IALG_EOK或是其它出错信息。这个函数实现是可选的，如不实现设置为空。

       调用条件：只能在algInit()后调用，handle是一个有效句柄，cmd的数值必须小于IALG_SYSCMD
实际上在xDM中control函数与ialg中的ialg_control还有些许不同，这里先不理，下面直接看实现代码：

/*
 *  ======== VIDENCCOPY_TI_control ========
 */
XDAS_Int32 VIDENCCOPY_TI_control(IVIDENC_Handle handle, IVIDENC_Cmd id,
    IVIDENC_DynamicParams *params, IVIDENC_Status *status)
{
    XDAS_Int32 retVal;

    GT_4trace(curTrace, GT_ENTER, "VIDENCCOPY_TI_control(0x%x, 0x%x, 0x%x, "
        "0x%x)\n", handle, id, params, status);


    /* validate arguments - this codec only supports "base" xDM. */
    if ((params->size != sizeof(*params)) ||
        (status->size != sizeof(*status))) {


        GT_2trace(curTrace, GT_ENTER,
            "VIDENCCOPY_TI_control, unsupported size "
            "(0x%x, 0x%x)\n", params->size, status->size);


        return (IVIDENC_EFAIL);
    }

    switch (id) {  //根据命令id来决定动作
        case XDM_GETSTATUS: //获得状态
        case XDM_GETBUFINFO: //获得缓冲区信息
            status->extendedError = 0;
            status->bufInfo.minNumInBufs = MININBUFS; //填充状态的信息域
            status->bufInfo.minNumOutBufs = MINOUTBUFS;
            status->bufInfo.minInBufSize[0] = MININBUFSIZE;
            status->bufInfo.minOutBufSize[0] = MINOUTBUFSIZE;

            retVal = IVIDENC_EOK;

            break;

        case XDM_SETPARAMS: //设定参数
        case XDM_SETDEFAULT: //设为默认
        case XDM_RESET: //复位
        case XDM_FLUSH: //清空
            /* TODO - for now just return success. 现在只是返回EOK*/

            retVal = IVIDENC_EOK;
            break;

        default:
            /* unsupported cmd 如果是不支持的命令,则返回EFAIL*/
            retVal = IVIDENC_EFAIL;

            break;
    }

    return (retVal);
}

另一个和上面的区别不大,只是列出代码,不做过多解释,从这两个代里我们看到这里有一个很重要的东西就是status结构体:

/*
 *  ======== VIDDECCOPY_TI_control ========
 */
XDAS_Int32 VIDDECCOPY_TI_control(IVIDDEC_Handle handle, IVIDDEC_Cmd id,
    IVIDDEC_DynamicParams *params, IVIDDEC_Status *status)
{
    XDAS_Int32 retVal;


    GT_4trace(curTrace, GT_ENTER, "VIDDECCOPY_TI_control(0x%lx, 0x%lx, 0x%lx, "
        "0x%lx)\n", handle, id, params, status);


    /* validate arguments - this codec only supports "base" xDM. */
    if ((params->size != sizeof(*params)) ||
        (status->size != sizeof(*status))) {

        GT_2trace(curTrace, GT_ENTER, "VIDDECCOPY_TI_control, unsupported size "
            "(0x%lx, 0x%lx)\n", params->size, status->size);

        return (IVIDDEC_EFAIL);
    }


    switch (id) {
        case XDM_GETSTATUS:
            status->extendedError = 0;
            status->outputHeight = 0;  /* TODO */
            status->outputWidth = 0;  /* TODO */
            status->frameRate = 0;  /* TODO */
            status->bitRate = 0;  /* TODO */
            status->contentType = 0;  /* TODO */
            status->outputChromaFormat = 0;  /* TODO */

            /* Note, intentionally no break here so we fill in bufInfo, too */


        case XDM_GETBUFINFO:
            status->bufInfo.minNumInBufs = MININBUFS;
            status->bufInfo.minNumOutBufs = MINOUTBUFS;
            status->bufInfo.minInBufSize[0] = MININBUFSIZE;
            status->bufInfo.minOutBufSize[0] = MINOUTBUFSIZE;

            retVal = IVIDDEC_EOK;

            break;


        case XDM_SETPARAMS:
        case XDM_SETDEFAULT:
        case XDM_RESET:
        case XDM_FLUSH:
            /* TODO - for now just return success. */

            retVal = IVIDDEC_EOK;
            break;


        default:
            /* unsupported cmd */
            retVal = IVIDDEC_EFAIL;

            break;
    }

    return (retVal);
}

楼上讲的control函数实际上并非ialg接口定义的ialgcontrol函数,而是xDM定义的control函数,xDM还定义了一个process函数,这个函数是ialg没有的.
简单 起见去掉里面的trace代码:

/*
 *  ======== VIDDECCOPY_TI_process ========
 */
XDAS_Int32 VIDDECCOPY_TI_process(IVIDDEC_Handle h, XDM_BufDesc *inBufs,
    XDM_BufDesc *outBufs, IVIDDEC_InArgs *inArgs, IVIDDEC_OutArgs *outArgs)
{//传入参数五个//0-->IVIDDEC_Handle,即解码器实例句柄//1-->XDM_BufDesc *inBufs,一个xDM缓冲区描述符型的输入缓冲区//-1-->XDC_BufDesc *outBufs,一个xDM缓冲区描述符型的输出缓冲区//2-->IVIDDEC_InArgs型 传入参数//-2-->传出参数
    XDAS_Int32 curBuf;
    XDAS_Int32 minSamples;


    /* 验证传入传出参数大小是否合法,不合法则返回失败*/
    if ((inArgs->size != sizeof(*inArgs)) ||
        (outArgs->size != sizeof(*outArgs))) {
        return (IVIDDEC_EFAIL);
    }


    /* outArgs->bytesConsumed reports the total number of bytes consumed */
    outArgs->bytesConsumed = 0; //消耗的字节总数/*
     * A couple constraints for this simple "copy" codec:这个简单复制算法的限制
     *    - Given a different number of input and output buffers, only //给定一组不同输入和输出缓冲区数目
     *      decode (i.e., copy) the lesser number of buffers.//只解码较小数目的缓冲区
     *    - Given a different size of an input and output buffers, only//给定一组不同输出输入缓冲区大小
     *      decode (i.e., copy) the lesser of the sizes.//只解码较小大小的字节数
     */


    for (curBuf = 0; (curBuf < inBufs->numBufs) &&
        (curBuf < outBufs->numBufs); curBuf++) {//for loop的条件:当前缓冲区序号同时小于输入和输出缓冲区数目


        /* there's an available in and out buffer, how many samples? 给定一组输入输入缓冲区,用多少样本? */
        minSamples = inBufs->bufSizes[curBuf] < outBufs->bufSizes[curBuf] ?
            inBufs->bufSizes[curBuf] : outBufs->bufSizes[curBuf];  //minSamples为inBufs结构的当前缓冲区大小和outBufs结构的当前缓冲区大小的最小值.


        /* process the data: read input, produce output 处理数扰,读输出,产生输出*/
        memcpy(outBufs->bufs[curBuf], inBufs->bufs[curBuf], minSamples); //纯的memcpy
outArgs->bytesConsumed += minSamples;//消耗的字节数增加minSamples个字节.
    }


    /* Fill out the rest of the outArgs struct 复制完之后,填充outArgs结构的其他域*/
    outArgs->extendedError = 0;
    outArgs->decodedFrameType = 0;     /* TODO */
    outArgs->outputID = inArgs->inputID;
    outArgs->displayBufs.numBufs = 0;  /* important: indicate no displayBufs */


    return (IVIDDEC_EOK);//返回成功
}

再看编码器的代码,里面涉及了一段涉及使用ACPY3的算法,这里先不理.
我们接着看这个代码在app.c中是怎么用的:

/*
     * Read complete frames from in, encode, decode, and write to out.*从输入文件读取,编码,再解编,写到输出
     */
    for (n = 0; fread(inBuf, IFRAMESIZE, 1, in) == 1; n++) {//for loop从输入文件每次读一帧


#ifdef CACHE_ENABLED
#ifdef xdc_target__isaCompatible_64P
        /*
         *  fread() on this processor is implemented using CCS's stdio, which
         *  is known to write into the cache, not physical memory.  To meet
         *  xDAIS DMA Rule 7, we must writeback the cache into physical
         *  memory.  Also, per DMA Rule 7, we must invalidate the buffer's
         *  cache before providing it to any xDAIS algorithm.*fread在这个处理器上的实现是通过CCS工具实现的.是读入cache的,不是物理内存,为*満足xDAIS DMA规则7,我们必须从cache中写加内存,而且必须验证cache,再提供给算法.
         */
        Memory_cacheWbInv(inBuf, IFRAMESIZE);
#else
#error Unvalidated config - add appropriate fread-related cache maintenance
#endif
        /* Per DMA Rule 7, our output buffer cache lines must be cleaned */
        Memory_cacheInv(encodedBuf, EFRAMESIZE);
#endif


        GT_1trace(curMask, GT_1CLASS, "App-> Processing frame %d...\n", n);


        /* encode the frame */
        status = VIDENC_process(enc, &inBufDesc, &encodedBufDesc, &encInArgs,
            &encOutArgs);//这里是process函数,参数是编码器句柄,inBufDesc结构中有inBuf的指针,encodedBufDesc中有encodeBuf的指针,参数也是各自设置的.


        GT_2trace(curMask, GT_2CLASS,
            "App-> Encoder frame %d process returned - 0x%x)\n",
            n, status);


#ifdef CACHE_ENABLED
        /* Writeback this outBuf from the previous call.  Also, as encodedBuf
         * is an inBuf to the next process call, we must invalidate it also, to
         * clean buffer lines.
         */
        Memory_cacheWbInv(encodedBuf, EFRAMESIZE);


        /* Per DMA Rule 7, our output buffer cache lines must be cleaned */
        Memory_cacheInv(outBuf, OFRAMESIZE);
#endif


        if (status != VIDENC_EOK) {
            GT_3trace(curMask, GT_7CLASS,
                "App-> Encoder frame %d processing FAILED, status = 0x%x, "
                "extendedError = 0x%x\n", n, status, encOutArgs.extendedError);
            break;
        }

补充代码:

/* clear and initialize the buffer descriptors */
    memset(src,     0, sizeof(src[0])     * XDM_MAX_IO_BUFFERS);
    memset(encoded, 0, sizeof(encoded[0]) * XDM_MAX_IO_BUFFERS);
    memset(dst,     0, sizeof(dst[0])     * XDM_MAX_IO_BUFFERS);


    src[0]     = inBuf;
    encoded[0] = encodedBuf;
    dst[0]     = outBuf;


    inBufDesc.numBufs = encodedBufDesc.numBufs = outBufDesc.numBufs = 1;


    inBufDesc.bufSizes      = inBufSizes;
    encodedBufDesc.bufSizes = encBufSizes;
    outBufDesc.bufSizes     = outBufSizes;


    inBufSizes[0] = encBufSizes[0] = outBufSizes[0] = NSAMPLES;


    inBufDesc.bufs      = src;
    encodedBufDesc.bufs = encoded;
    outBufDesc.bufs     = dst;