Getting started with IUNIVERSAL

From Texas Instruments Embedded Processors Wiki

Revision as of 20:50, 5 February 2010 by Mariana (Talk | contribs)
Jump to: navigation, search

  • Image:Google-16x16.png Search for an article here:

Contents

Getting Started with IUNIVERSAL

Who is this doc for?

If you’ve got an algorithm (or are developing one) and just want it to work with Codec Engine even though it's not a video, imaging, speech or audio codec, read on...

What is Codec Engine and why would I want to use it?

Quite a lot has already been written on Codec Engine, so we’ll point you to the DaVinci Wiki CE Overview as a starting point: Codec Engine Wiki Category.

What is IUNIVERSAL?

The IUNIVERSAL API was introduced to provide an easy way for non-VISA, but still XDAIS compliant, algorithms to run via Codec Engine. If you’re a pro, skip over this section.

If you're not quite sure what this all means, let's take a few steps back: in the beginning, we wanted to be able to run multiple algorithms from multiple developers on a single DSP, so TI created a standard to ensure the algorithms didn't steal resources from each other, had unique namespaces, and could "play nice" together in general. There are a number of app notes and docs on this, so check out XDAIS Documentation. If you learn better by example, go to XDAIS Sample Algorithm. There's even a clever tool to make sure you’ve got it right: QualiTI.

Since most of the algorithms were strictly multimedia, TI then extended XDAIS to create a standard API (called XDM) specifically designed for multimedia codecs. These codecs are frequently referred to as VISA (for video, imaging, speech, and audio). Check out the XDM Users Guide. When combined with Codec Engine, we then have a nice way to simply "plug and play" our VISA codecs.

We then started getting questions like, "How can I get my face detection algorithm to work with Codec Engine?" One solution is to create custom stubs and skeletons as described here and this worked well for a number of folks. But surely there should be another (possibly easier) way to get your algorithm to run – thus we get the introduction of the IUNIVERSAL API.

If you want a crash course on the above (XDAIS, XDM, RTSC Packaging, etc. but not IUNIVERSAL in particular), check out the freely available OMAP and DaVinci Software for Dummies book.

So how do I get started?

First, we need to download the right tools. IUNIVERSAL didn't exist until Codec Engine 2.20 (which was an OMAP-only Codec Engine version), so I'd suggest getting Codec Engine 2.21 (for OMAP and DaVinci) or later from here. You'll also need DSP BIOS (for this and all others, check out the CE Release Notes to find the version requirements for these), XDCTools, and the appropriate DVSDK for your platform. Also verify that you’re using the right tools – if you’re going the Montavista route, you’ll need to use MV 5.0 since it's a prerequisite to CE 2.20 and later. From here on out we’ll assume that you’ve been able to build and run the DVSDK demos and Codec Engine examples.

Example code always makes it easier, so you may want to download a set of IUNIVERSAL Examples from here.

Let's first checkout some examples and source within the XDAIS and CE products:

Code:

XDAIS IUNIVERSAL Header File: xdais_X_YY/packages/ti/xdais/dm/iuniversal.h - Notice here that each of the IUNIVERSAL structs (i.e. IUNIVERSAL_Params, IUNIVERSAL_InArgs, etc) contain a size field. Only a few structs contain other fields, such as IUNIVERSAL_Status contains extendedError and data.

CE Universal Code (of particular interest is universal.h): codec_engine_X_YY/packages/ti/sdo/ce/universal - Notice that universal.h is where UNIVERSAL_process(), UNIVERSAL_control(), etc. are defined. These functions differ from the traditional XDM classes only slightly – mainly UNIVERSAL_process() includes an XDM1_BufDesc *inOutBufs argument that can be used for buffers that are used for both input and output to/from the algorithm.

Examples:

Universal Copy Codec: xdais_X_YY/examples/ti/xdais/dm/examples/universal_copy/ - Compare this to the viddec1_copy VISA example in the same directory and you'll see that the usage of the XDM API are almost the same

Universal Copy Codec Package: codec_engine_X_YY/examples/ti/sdo/ce/examples/codecs/universal_copy - Don’t worry about creating this since tooling exists to take care of it.

Universal Copy Server Package: codec_engine_X_YY/examples/ti/sdo/ce/examples/servers/all_codecs - Again, don't worry about all of the files. Just check out the main.c file to see that the DSP executable (aka "Server") merely inits CE and trace. It is useful to note that the memory map is contained in the tci (or tcf) and the codec configuration is done in the .cfg file.

Universal Copy Sample application: codec_engine_X_YY/examples/ti/sdo/ce/examples/apps/universal_copy - This shows a short application that can run the codec either locally or remotely. Compare it to the standard video_copy example.

As a quick refresher and outline of the next few steps: we’ll first need to create an XDAIS algorithm, then modify it for IUNIVERSAL, followed by creating codec and server packages to hold our content in a way that is understood by CE, and finally, creating a test app to verify that it actually works.

How do I create an XDAIS algorithm?

If you’re going at this from scratch, then start with an example that already uses IUNIVERSAL. If you’ve already got an XDAIS algorithm and just want to tweak it to work with Codec Engine, jump to the next section.

Obviously don't start with a blank page—start with an example. The IUNIVERSAL Examples from here or the Codec Engine universal copy example are probably a good place to start. If you’re new to XDAIS, read the XDAIS docs to figure out what each function does and why, and then you should be able to draw out a mapping between what your algorithm does and where it should go.

If you feel better about working in CCS, you can develop your XDAIS algorithm entirely within CCS. If you want a CCS project to start from, try out the FIR Algorithm.

Finally, don't forget to check your algorithm with QualiTI when you're done.

If I've already got an XDAIS algorithm – now what?

Now, supposing that you have an XDAIS algorithm that's reminiscent of the CE "scale" example (meaning you've defined your own CE interface), and just need to know the tweaks to get it to work with Codec Engine:

  1. You need to convert all of your interface structs to use the IUNIVERSAL structs. For example, if you have defined your own interface such as IFIR_Fxns, then replace it with IUNIVERSAL_Fxns, or IFIR_Handle with IUNIVERSAL_Handle.
  2. Recall that each XDM algorithm has a create(), control(), process() and delete() function, so we'll need to create "XDM wrapper" functions for your already-existing functions. First, identify your processing function, that is, the function that actually does the task that your algorithm repeatedly does. For a filtering algorithm, this function will perform the filtering on one input array and one coefficient array, producing the output in a single output array. Most likely your processing function will have some input and output, and we’ll need to create a process() function that takes in your function’s arguments in the way specified in codec_engine_2_21/packages/ti/sdo/ce/universal/universal.h and then calls your already-existing function. Similarly, create a control() function that is analogous to the UNIVERSAL_control() function. If your codec has more than one process()-like function, you'll need to include all of these functions in your "XDM wrapper" function and add an extra input argument to indicate which type of processing to do.
  3. Don’t forget to update your IUNIVERSAL_Fxns to include your IALGFXN, process() wrapper, and control() wrapper functions.
  4. It probably goes without saying that you’ll need to include the XDAIS ti/xdais/dm/iuniversal.h file in your source code.

What about all of this packaging?

We package content in a particular format everyday – rpm, Java packages, and countless others – to make it understandable by other people and tools. Codec Engine understands RTSC packages (for general information on RTSC, see link) so we’ll need to create one for the codec (obviously containing the codec) and one for the DSP server (assuming your codec can run on the DSP). Both of these packages contain the extra information (meta-data) needed for CE to run your algorithm. For some more details, see this article. Luckily it’s quite easy to create both of these packages using the RTSC Codec and Server Package Wizards described here. Note that any version of the RTSC Codec and Server Package Wizard will support IUNIVERSAL since it picks up the interfaces directly from your CE version.

How can I test it now?

Write a Codec Engine application! The CE examples (recall there’s even a universal_copy app) are a good place to start.

You can debug both DaVinci and OMAP CE applications via CCS, see the Debugging_the_DSP_side_of_a_CE_application_on_DaVinci_using_CCS or Debugging_the_DSP_side_of_a_DSPLink_application_on_OMAP_using_CCS articles.

It’s also a good idea to check that you haven't written to any read-only structs – see link.

Can you offer some more tips?

FAQ about IUNIVERSAL Examples

Can I use CE 2.20/DSPLink 1.51 (i.e. components from the OMAP Beta DVSDK)?

Unfortunately not due to a bug in CE 2.20. See the CE 2.21 release notes for bug fixes: "CreateFromServer no longer automatically map internal memory segments". Using CE 2.20 (or CE 2.20.01) will cause a program crash. The minimum requirements are as stated in the release notes: CE 2.21 and DSPLink 1.60.


See Also


For technical support please post your questions at http://e2e.ti.com. Please post only comments about the article Getting started with IUNIVERSAL here.
Retrieved from "http://processors.wiki.ti.com/index.php/Getting_started_with_IUNIVERSAL"
Leave a Comment