Version checking

From Texas Instruments Embedded Processors Wiki

Jump to: navigation, search

Translate this page to

This topic shows various methods to attain versioning information from codecs. It covers both static (i.e. run a tool to get the information) and dynamic (i.e. run the code, call an API, read the version number) methods.

Static - 'vers' and the 'strings' command

Most TI codecs, and many 3rd party codecs add a version stamp inside the codec source code build which can be extracted by the 'vers' utility. This util doesn't parse COFF, it just walks through every byte in a binary file looking for a magic character string "@(#)"

Typically the version information is inserted into the codec programmatically as follows: -

#include <version.h>
 
   //        ID      Version  Released by
   VERSION(M4H3DEC_TI, "1.10.011", "DEV_100E_V_MPEG4_D_1_10_011_DM6437_SP_001");

where version.h includes: -

#define VERSION(id, rev, tag) \
  const char id##_version[] = "@(#)Id:" #id " Ver:" rev " Released by:" tag " Built:" __DATE__ " " __TIME__
#endif

The 'vers' utility can then be invoked on the codec library as follows: -

[alan@lab1 watermark]$ /opt/dmsw/xdc_3_00_06/vers m4h3dec_ti.l64P 
m4h3dec_ti.l64P:
	Id:M4H3DEC_TI Ver:1.10.010 Released by:DEV_100E_V_MPEG4_D_1_10_010_DM6437_SP_001 Built:Apr 16 2007 15:05:49

If we then run the same command on an application we'd expect to see a list of all version numbers of all version-instrumented codecs right?

[alan@lab1 mpeg4dec_unitserver_evmdm6446]$ /opt/dmsw/xdc_3_00_06/vers mpeg4dec_unitserver_evmdm6446.x64P
mpeg4dec_unitserver_evmdm6446.x64P:
	*** xdcutils-d08
	__ASM__ = /home/alan/workdir/dm6446_dev/combos_eval/packages/ti/sdo/servers/mpeg4dec_unitserver_evmdm6446/package/cfg/mpeg4dec_unitserver_evmdm6446_x64P
	__ISA__ = 64P
	__PLAT__ = ti.platforms.evmDM6446
	__TARG__ = ti.targets.C64P
	 ti.sdo.ce; version 1, 0, 5; /db/atree/library/trees/ce-g30x/src/; Jan 14 2008 09:26:19

That doesn't help much! The codec version information got lost!

The reason is that because version.c is 'pure data' and it does not get referenced by any other code (only by host side utilities), the linker got smart and removed it altogether in the final application link.

To preserve the codec-version info we need to instruct the linker to keep the symbol(s) we need. The simplest way to do that is to use the -u symbolName technique. Check the linker chapter of tidoc:spru186 for full details on -u. In essence it introduces an unreferenced symbol into the symbol-table. It is a pretty standard trick to keep key symbols around for host tools to take advantage of. GUIDs are often used the same way.

Simply add the following to link.cmd in the application: -

-u _M4H3DEC_TI_version

Rebuilding & re-running 'vers' now yields: -

[alan@lab1 mpeg4dec_unitserver_evmdm6446]$ /opt/dmsw/xdc_3_00_06/vers mpeg4dec_unitserver_evmdm6446.x64P
mpeg4dec_unitserver_evmdm6446.x64P:
	*** xdcutils-d08
	__ASM__ = /home/alan/workdir/dm6446_dev/combos_eval/packages/ti/sdo/servers/mpeg4dec_unitserver_evmdm6446/package/cfg/mpeg4dec_unitserver_evmdm6446_x64P
	__ISA__ = 64P
	__PLAT__ = ti.platforms.evmDM6446
	__TARG__ = ti.targets.C64P
	Id:M4H3DEC_TI Ver:1.10.010 Released by:DEV_100E_V_MPEG4_D_1_10_010_DM6437_SP_001 Built:Apr 16 2007 15:05:49
	 ti.sdo.ce; version 1, 0, 5; /db/atree/library/trees/ce-g30x/src/; Jan 14 2008 09:26:19

The codec version information is now available from the application level.

The obvious caveat to the above technique is how did you know the symbol name was _M4H3DEC_TI_version? The answer is that we simply searched for strings containing the word 'version' in the codec library - this is clumsy. A better way to do this is for the codec itself to add the -u _symbolName to its TopTenCodecPackageCheckList#9._Preserving_all_important_codec_performance_in_any_framework_via_link.xdt link.xdt linker contribution. This automatically ensures the version information goes into the final application without the system integrator being involved.

Retrieving version information on the target

You may not have access to the 'vers' utility from the target since it may not be ported to your target. So how do you extract the required version without it?

The answer is to use the standard Unix/Linux 'strings' command to see the strings of printable characters in the file.

[root@123.12.23.123]$ strings mpeg4dec_unitserver_evmdm6446.x64P | grep '@(#)'
...
@(#)Id:M4H3DEC_TI Ver:1.10.010 Released by:DEV_100E_V_MPEG4_D_1_10_010_DM6437_SP_001 Built:Apr 16 2007 15:05:49

Dynamic - using XDM 1.x XDM_GETVERSION

Static version retrieval may not be what you want. Instead you might wish to make programmatic decisions based on the version information e.g. if (codecNameVersion < X.Y) { flagError(); }

Codec Engine ships an example that shows how to use the XDM 1.x XDM_GETVERSION information to dynamically get codec version info from the control() call context.

#define G711DEC_SUN_VERSIONSTRING "1.00.00.0"
 
        case XDM_GETVERSION:
            if ((status->data.buf != NULL) &&
                (status->data.bufSize >= strlen(G711DEC_SUN_VERSIONSTRING))) {
                strncpy((char *)status->data.buf, G711DEC_SUN_VERSIONSTRING,
                    strlen(G711DEC_SUN_VERSIONSTRING));
 
                /* null terminate the string */
                status->data.buf[strlen(G711DEC_SUN_VERSIONSTRING)] = '\0';
 
                /* strncpy wrote to the data buffer */
                XDM_SETACCESSMODE_WRITE(status->data.accessMask);
 
                retVal = ISPHDEC1_EOK;
            }
            else {
                retVal = ISPHDEC1_EFAIL;
            }
 
            break;