You are on page 1of 93

H.

264 High Profile Decoder


(v01.01.00) on C66x

User’s Guide

Literature Number: SPRUH86A


December 2011
IMPORTANT NOTICE

Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, modifications, enhancements,
improvements, and other changes to its products and services at any time and to discontinue any product or service without
notice. Customers should obtain the latest relevant information before placing orders and should verify that such information is
current and complete. All products are sold subject to TI’s terms and conditions of sale supplied at the time of order
acknowledgment.
TI warrants performance of its hardware products to the specifications applicable at the time of sale in accordance with TI’s
standard warranty. Testing and other quality control techniques are used to the extent TI deems necessary to support this
warranty. Except where mandated by government requirements, testing of all parameters of each product is not necessarily
performed.
TI assumes no liability for applications assistance or customer product design. Customers are responsible for their products and
applications using TI components. To minimize the risks associated with customer products and applications, customers should
provide adequate design and operating safeguards.
TI does not warrant or represent that any license, either express or implied, is granted under any TI patent right, copyright, mask
work right, or other TI intellectual property right relating to any combination, machine, or process in which TI products or services
are used. Information published by TI regarding third-party products or services does not constitute a license from TI to use such
products or services or a warranty or endorsement thereof. Use of such information may require a license from a third party
under the patents or other intellectual property of the third party, or a license from TI under the patents or other intellectual
property of TI.
Reproduction of TI information in TI data books or data sheets is permissible only if reproduction is without alteration and is
accompanied by all associated warranties, conditions, limitations, and notices. Reproduction of this information with alteration is
an unfair and deceptive business practice. TI is not responsible or liable for such altered documentation. Information of third
parties may be subject to additional restrictions.
Resale of TI products or services with statements different from or beyond the parameters stated by TI for that product or service
voids all express and any implied warranties for the associated TI product or service and is an unfair and deceptive business
practice. TI is not responsible or liable for any such statements.
TI products are not authorized for use in safety-critical applications (such as life support) where a failure of the TI product would
reasonably be expected to cause severe personal injury or death, unless officers of the parties have executed an agreement
specifically governing such use. Buyers represent that they have all necessary expertise in the safety and regulatory
ramifications of their applications, and acknowledge and agree that they are solely responsible for all legal, regulatory and safety-
related requirements concerning their products and any use of TI products in such safety-critical applications, notwithstanding
any applications-related information or support that may be provided by TI. Further, Buyers must fully indemnify TI and its
representatives against any damages arising out of the use of TI products in such safety-critical applications.
TI products are neither designed nor intended for use in military/aerospace applications or environments unless the TI products
are specifically designated by TI as military-grade or "enhanced plastic." Only products designated by TI as military-grade meet
military specifications. Buyers acknowledge and agree that any such use of TI products which TI has not designated as military-
grade is solely at the Buyer's risk, and that they are solely responsible for compliance with all legal and regulatory requirements
in connection with such use.
TI products are neither designed nor intended for use in automotive applications or environments unless the specific TI products
are designated by TI as compliant with ISO/TS 16949 requirements. Buyers acknowledge and agree that, if they use any non-
designated products in automotive applications, TI will not be responsible for any failure to meet such requirements.

Following are URLs where you can obtain information on other Texas Instruments products and application solutions:

Products Applications
Audio www.ti.com/audio Communications and Telecom ww.ti.com/communications
Amplifiers amplifier.ti.com Computers and Peripherals www.ti.com/computers
Data Converters dataconverter.ti.com Consumer Electronics www.ti.com/consumer-apps
DLP® Products www.dlp.com Energy and Lighting www.ti.com/energy
DSP dsp.ti.com Industrial www.ti.com/industrial
Clocks and Timers www.ti.com/clocks Medical www.ti.com/medical
Interface interface.ti.com Security ww.ti.com/security
Logic logic.ti.com Space, Avionics and Defense www.ti.com/space-avionics-defense
Power Mgmt power.ti.com Transportation and Automotive www.ti.com/automotive
Microcontrollers microcontroller.ti.com Video and Imaging ww.ti.com/video
RFID www.ti-rfid.com
OMAP Mobile Processors www.ti.com/omap
Wireless Connctivity www.ti.com/wirelessconnectivity

TI E2E Community Home Page e2e.ti.com


Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265
Copyright © 2011, Texas Instruments Incorporated
Preface

Read This First

About This Manual


This document describes how to install and work with Texas Instruments’
(TI) H.264 High Profile Decoder implementation on the C66x platform. It
also provides a detailed Application Programming Interface (API)
reference and information on the sample application that accompanies
this component.

TI’s codec implementations are based on the eXpressDSP Digital Media


(XDM) standard. XDM is an extension of the eXpressDSP Algorithm
Interface Standard (XDAIS).

Intended Audience
This document is intended for system engineers who want to integrate
TI’s codecs with other software to build a multimedia system based on
the C66x+ platform.

This document assumes that you are fluent in the C language, have a
good working knowledge of Digital Signal Processing (DSP), digital
signal processors, and DSP applications. Good knowledge of
eXpressDSP Algorithm Interface Standard (XDAIS) and eXpressDSP
Digital Media (XDM) standard will be helpful.

How to Use This Manual


This document includes the following chapters:

 Chapter 1 - Introduction, provides a brief introduction to the XDAIS


and XDM standards. It also provides an overview of the codec and
lists its supported features.

 Chapter 2 - Installation Overview, describes how to install, build,


and run the codec.

 Chapter 3 - Sample Usage, describes the sample usage of the


codec.

 Chapter 4 - API Reference, describes the data structures and


interface functions used in the codec.

iii
Read This First

Related Documentation From Texas Instruments


The following documents describe TI’s DSP algorithm standards such
as, XDAIS and XDM. To obtain a copy of any of these TI documents,
visit the Texas Instruments website at www.ti.com.

 TMS320 DSP Algorithm Standard Rules and Guidelines (literature


number SPRU352) defines a set of requirements for DSP algorithms
that, if followed, allow system integrators to quickly assemble
production-quality systems from one or more such algorithms.

 TMS320 DSP Algorithm Standard API Reference (literature number


SPRU360) describes all the APIs that are defined by the TMS320
DSP Algorithm Inteface Standard (also known as XDAIS)
specification.

 Technical Overview of eXpressDSP - Compliant Algorithms for DSP


Software Producers (literature number SPRA579) describes how to
make algorithms compliant with the TMS320 DSP Algorithm
Standard which is part of TI’s eXpressDSP technology initiative.

 Using the TMS320 DSP Algorithm Standard in a Static DSP System


(literature number SPRA577) describes how an eXpressDSP-
compliant algorithm may be used effectively in a static system with
limited memory.

 DMA Guide for eXpressDSP-Compliant Algorithm Producers and


Consumers (literature number SPRA445) describes the DMA
architecture specified by the TMS320 DSP Algorithm Standard
(XDAIS). It also describes two sets of APIs used for accessing DMA
resources: the IDMA2 abstract interface and the ACPY2 library.

 eXpressDSP Digital Media (XDM) Standard API Reference (literature


number SPRUEC8)

The following documents describe TMS320 devices and related support


tools:

 TMS320C6472/TMS320TCI648x DSP Enhanced DMA (EDMA3)


Controller describes the features and operations of the enhanced
direct memory access (EDMA3) controller in the
TMS320C6472/TMS320TCI648x digital signal processor.

 TMS320c64x+ Megamodule (literature number SPRAA68) describes


the enhancements made to the internal memory and describes the
new features which have been added to support the internal memory
architecture's performance and protection.

 TMS320C64x+ DSP Megamodule Reference Guide (literature


number SPRU871) describes the C64x+ megamodule peripherals.

 TMS320C6000 Optimizing Compiler v 6.0 Beta User's Guide


(literature number SPRU187N) explains how to use compiler tools
such as compiler, assembly optimizer, standalone simulator, library-
build utility, and C++ name demangler.

 TMS320C64x/C64x+ DSP CPU and Instruction Set Reference Guide


(literature number SPRU732) describes the CPU architecture,
pipeline, instruction set, and interrupts of the C64x and C64x+ DSPs.

iv
Read This First

 Multicore Programming Guide – Application Report (literature


number SPRAB27A, August 2009)

 Multicore Synchronization APIs for Family of C6472 video Codecs –


Texas Instruments Internal Report.

 The Future of Digital Video White Paper (literature number


SPRY066)

Related Documentation
You can use the following documents to supplement this user guide:

 ISO/IEC 14496-10:2005 (E) Rec.- Information technology – Coding


of audio-visual objects – H.264 (E) ITU-T Recommendation
Abbreviations
The following abbreviations are used in this document:

Table 1-1. List of Abbreviations


Abbreviation Description

ABI Application Binary Interface

ASO Arbitrary Slice Ordering

AUD Access Unit Delimiter

AVC Advanced Video Coding

BIOS TI’s simple RTOS for DSPs

CABAC Context Adaptive Binary Arithmetic Coding

CAVLC Context Adaptive Variable Length Coding

CSL Chip Support Library

D1 720x480 or 720x576 resolutions in


progressive scan

DCT Discrete Cosine Transform

DMA Direct Memory Access

DPB Decoded Picture Buffer

EDMA Enhanced Direct Memory Access

ELF Executable and Linkable Format

EVM Evaluation Module

FILL Filler Data

FMO Flexible Macroblock Ordering

v
Read This First

Abbreviation Description

HDTV High Definition Television

HRD Hypothetical Reference Decoder

I_PCM Intra-frame pulse code modulation

IDR Instantaneous Decoding Refresh

ITU-T International Telecommunication Union

IRES Resource Interface

IPC Inter Processor Communication

JM Joint Menu

JVT Joint Video Team

MB Macro Block

MBAFF Macro Block Adaptive Field Frame

MPEG Moving Pictures Experts Group

MV Motion Vector

NAL Network Adaptation Layer

NTSC National Television Standards Committee

PicAFF Picture Adaptive Field Frame

POC Picture Order Count

PPS Picture Parameter Set

RMAN Resource Manager

RTOS Real Time Operating System

SEI Supplemental Enhancement Information

SPS Sequence Parameter Set

SWBARR Software Barrier (used for multi-core sync)

VCL Video Coded Layer

VGA Video Graphics Array (640 x 480


resolution)

VUI Video Usability Information

XDAIS eXpressDSP Algorithm Interface Standard

vi
Read This First

Abbreviation Description

XDM eXpressDSP Digital Media

YUV Color space in luminance and


chrominance form

Text Conventions
The following conventions are used in this document:

 Text inside back-quotes (‘‘) represents pseudo-code.

 Program source code, function and macro names, parameters, and


command line commands are shown in a mono-spaced font.

Product Support
When contacting TI for support on this codec, quote the product name
(H.264 High Profile Decoder on C66x) and version number. The version
number of the codec is included in the Title of the Release Notes that
accompanies this codec.

Trademarks
Code Composer Studio, DSP/BIOS, eXpressDSP, TMS320,
TMS320C64x, TMS320C6000, and TMS320C64x+ are trademarks of
Texas Instruments.

All trademarks are the property of their respective owners.

vii
Contents

Read This First ................................................................................................................ iii


About This Manual..................................................................................................... iii
Intended Audience..................................................................................................... iii
How to Use This Manual............................................................................................ iii
Related Documentation From Texas Instruments ...................................................... iv
Related Documentation .............................................................................................. v
Text Conventions...................................................................................................... vii
Product Support........................................................................................................ vii
Trademarks .............................................................................................................. vii
Contents ........................................................................................................................ viii
Figures ..............................................................................................................................x
Tables.............................................................................................................................. xii
Introduction ...................................................................................................................1-1
1.1 Overview of XDAIS and XDM ..........................................................................1-2
1.1.1 XDAIS Overview ................................................................................................ 1-2
1.1.2 XDM Overview ................................................................................................... 1-2
1.2 Overview of H.264 High Profile Decoder ..........................................................1-3
1.3 Supported Services and Features ....................................................................1-6
Installation Overview ....................................................................................................2-1
2.1 System Requirements......................................................................................2-2
2.1.1 Hardware ............................................................................................................ 2-2
2.1.2 Software ............................................................................................................. 2-2
2.2 Installing the Component .................................................................................2-2
2.3 Before Building the Sample Test Application ...................................................2-5
2.3.1 To build and run on CCSv4 IDE ......................................................................... 2-5
2.3.2 Installing DSP/BIOS ........................................................................................... 2-5
2.3.3 Installing Framework Component (FC) .............................................................. 2-5
2.3.4 Installing XDC Tools ........................................................................................... 2-5
2.3.5 Installing BIOS IPC Tools ................................................................................... 2-6
2.4 Building Algorithm Library ................................................................................2-6
2.5 Building and Running the Sample Test Application ..........................................2-6
2.6 Configuration Files ...........................................................................................2-7
2.6.1 Generic Configuration File ................................................................................. 2-7
2.6.2 Decoder Configuration File ................................................................................ 2-8
2.7 Standards Conformance and User-Defined Inputs ...........................................2-9
2.8 Uninstalling the Component .............................................................................2-9
Sample Usage................................................................................................................3-1
3.1 Overview of the Test Application ......................................................................3-2
3.1.1 Parameter Setup ................................................................................................ 3-3
3.1.2 Algorithm Instance Creation and Initialization .................................................... 3-3
3.1.3 Process Call ....................................................................................................... 3-4
3.1.4 Algorithm Instance Deletion ............................................................................... 3-5
3.2 Frame Buffer Management by Application .......................................................3-5
3.2.1 Frame Buffer Input and Output .......................................................................... 3-5

viii
3.2.2 Frame Buffer Management by Application ......................................................... 3-7
3.2.3 Display Delay and Resolution ............................................................................ 3-8
3.3 Handshaking between multiple cores ...............................................................3-9
3.4 Sample Test Application ..................................................................................3-9
API Reference ................................................................................................................4-1
4.1 Symbolic Constants and Enumerated Data Types ...........................................4-2
4.1.1 H.264 Decoder Enumerated Data Types ......................................................... 4-13
4.2 Data Structures ..............................................................................................4-17
4.2.1 Common XDM Data Structures........................................................................ 4-17
4.2.2 H.264 Decoder Data Structures ....................................................................... 4-26
4.3 Interface Functions ........................................................................................4-42
4.3.1 Creation APIs ................................................................................................... 4-43
4.3.2 Initialization API ................................................................................................ 4-45
4.3.3 Control API ....................................................................................................... 4-46
4.3.4 Data Processing API ........................................................................................ 4-47
4.3.5 Termination API................................................................................................ 4-49
4.3.6 Multi-core API ................................................................................................... 4-50

ix
Figures

Figure 1-1. Block Diagram of H.264 Decoder ..............................................................1-6


Figure 2-1. Component Directory Structure ................................................................2-3
Figure 3-1. Test Application Sample Implementation .................................................3-2
Figure 3-2. Frame Buffer Pointer Implementation .......................................................3-6
Figure 3-3. Interaction of Frame Buffers Between Application and Framework ....... 3-7

x
This page is intentionally left blank

xi
Tables

Table 1-1. List of Abbreviations ...................................................................................... v


Table 2-1. Component Directories ...............................................................................2-3
Table 3-1. Process() Implementation. ..........................................................................3-9
Table 4-1. List of Enumerated Data Types ...................................................................4-2
Table 4-2. Error Codes and Values. .............................................................................4-7
Table 4-3. H264 Decoder Enumerated Data Types ....................................................4-14
Table 4-4. H264 Decoder Multi-Core Enumerated Data Types ................................. 4-15

xii
This page is intentionally left blank

xiii
Chapter 1

Introduction

This chapter provides a brief introduction to XDAIS and XDM. It also


provides an overview of TI’s implementation of the H.264 High Profile
Decoder on the C66x platform and its supported features.

1-1
Introduction

1.1 Overview of XDAIS and XDM


TI’s multimedia codec implementations are based on the eXpressDSP
Digital Media (XDM) standard. XDM is an extension of the eXpressDSP
Algorithm Interface Standard (XDAIS).

1.1.1 XDAIS Overview


An eXpressDSP-compliant algorithm is a module that implements the
abstract interface IALG. The IALG API takes the memory management
function away from the algorithm and places it in the hosting framework.
Thus, an interaction occurs between the algorithm and the framework. This
interaction allows the client application to allocate memory for the algorithm
and also share memory between algorithms. It also allows the memory to
be moved around while an algorithm is operating in the system. In order to
facilitate these functionalities, the IALG interface defines the following
APIs:
 algAlloc()

 algInit()

 algActivate()

 algDeactivate()

 algFree()

The algAlloc() API allows the algorithm to communicate its memory


requirements to the client application. The algInit() API allows the
algorithm to initialize the memory allocated by the client application. The
algFree() API allows the algorithm to communicate the memory to be
freed when an instance is no longer required.

Once an algorithm instance object is created, it can be used to process


data in real-time. The algActivate() API provides a notification to the
algorithm instance that one or more algorithm processing methods is about
to be run zero or more times in succession. After the processing methods
have been run, the client application calls the algDeactivate() API prior
to reusing any of the instance’s scratch memory.

The IALG interface also defines three more optional APIs algControl(),
algNumAlloc(), and algMoved(). For more details on these APIs, see
TMS320 DSP Algorithm Standard API Reference (literature number
SPRU360).

1.1.2 XDM Overview


In the multimedia application space, you have the choice of integrating any
codec into your multimedia system. For example, if you are building a
video decoder system, you can use any of the available video decoders
(such as MPEG4, H.263, or H.264) in your system. To enable easy
integration with the client application, it is important that all codecs with
similar functionality use similar APIs. XDM was primarily defined as an

1-2
Introduction

extension to XDAIS to ensure uniformity across different classes of codecs


(for example audio, video, image, and speech). The XDM standard defines
the following two APIs:
 control()

 process()

The control() API provides a standard way to control an algorithm


instance and receive status information from the algorithm in real-time. The
control() API replaces the algControl() API defined as part of the
IALG interface. The process() API does the basic processing
(encode/decode) of data.

Apart from defining standardized APIs for multimedia codecs, XDM also
standardizes the generic parameters that the client application must pass
to these APIs. The client application can define additional implementation
specific parameters using extended data structures.

The following figure depicts the XDM interface to the client application.

Client Application

XDM Interface

XDAIS Interface (IALG)

TI’s Codec Algorithms

As depicted in the figure, XDM is an extension to XDAIS and forms an


interface between the client application and the codec component. XDM
insulates the client application from component-level changes. Since TI’s
multimedia algorithms are XDM compliant, it provides you with the flexibility
to use any TI algorithm without changing the client application code. For
example, if you have developed a client application using an XDM-
compliant MPEG4 video decoder, then you can easily replace MPEG4 with
another XDM-compliant video decoder, say H.263, with minimal changes
to the client application.

For more details, see eXpressDSP Digital Media (XDM) Standard API
Reference (literature number SPRUEC8).

1.2 Overview of H.264 High Profile Decoder


H.264 (from ITU-T, also called as H.264/AVC) is a popular video coding
algorithm enabling high quality multimedia services on a limited bandwidth
network. H.264 standard defines several profiles and levels that specify
restrictions on the bit-stream and hence limits the capabilities needed to
decode the bit-streams. Each profile specifies a sub-set of algorithmic
features and limits that all decoders conforming to that profile may support.

1-3
Introduction

Each level specifies a set of limits on the values that may be taken by the
syntax elements in that profile.

Some important H.264 profiles and their special features are:

 Baseline Profile:
o Only I and P type slices are present
o Only frame mode (progressive) picture types are present
o Only CAVLC is supported

 Main Profile:
o Only I, P, and B type slices are present
o Frame and field picture modes (in progressive and interlaced modes)
picture types are present
o Both CAVLC and CABAC are supported
o ASO is not supported

 High Profile:
o Only I, P, and B type slices are present
o Frame and field picture modes (in progressive and interlaced modes)
picture types are present
o Both CAVLC and CABAC are supported
o ASO is not supported
o FMO is not supported
o 8x8 transform supported
o Scaling matrices supported
o Separate quantization parameter for Cb, Cr is supported

The input to the decoder is a H.264 encoded bit-stream in the byte-stream


syntax. The byte-stream consists of a sequence of byte- stream NAL unit
syntax structures. Each byte-stream NAL unit syntax structure contains
one start code prefix of size four bytes and value 0x00000001, followed by
one NAL unit syntax structure. The encoded frame data is a group of slices
each of which is encapsulated in NAL units. The slice consists of the
following:

 Intra coded data: Spatial prediction mode and prediction error data,
which is subjected to DCT and later quantized.

 Inter coded data: Motion information and residual error data


(differential data between two frames), which is subjected to DCT and
later quantized.

The first frame received by the decoder is IDR (Instantaneous Decode


Refresh) picture frame. The decoder reconstructs the frame by spatial
intra-prediction specified by the mode and by adding the prediction error.
The subsequent frames may be intra or inter coded.

In case of inter coding, the decoder reconstructs the bit-stream by adding


the residual error data to the previously decoded image, at the location

1-4
Introduction

specified by the motion information. This process is repeated until the


entire bit-stream is decoded.

The output of the decoder is a YUV sequence, which can be of format 420
planar and 422 interleaved in little endian.

Figure 1-1 depicts the working of the decoder.

1-5
Introduction

Video Out
Video Bit Stream

Entropy Inverse Scan Inverse Deblocking


Buffer Decoding and and Transform Filter
Demultiplexing Quantization +

Spatial Prediction Modes

Current Spatial
Picture Store Compensation SW
Process

Multiple Motion
Previous Compensation
Picture Store Process

Motion Vectors

Figure 1-1. Block Diagram of H.264 Decoder


From this point onwards, all references to H.264 Decoder means H.264
High Profile Decoder only.

1.3 Supported Services and Features


This user guide accompanies TI’s implementation of H.264 Decoder on the
C66x platform.

This version of the codec has the following supported features:

 eXpressDSP Digital Media (XDM 1.0 IVIDDEC2) compliant

 Supports decoding of HD streams (1920x1088).

 Supports progressive, interlaced, Picture Adaptive Frame Field


(PicAFF) and Macroblock Adaptive Frame Field (MBAFF) type picture
decoding

 Supports multiple slices and multiple reference frames

 Supports CAVLC and CABAC decoding

 Supports all intra-prediction and inter-prediction modes

 Supports up to 16 MV per MB

 Supports frame based decoding

1-6
Introduction

 Supports frame size being non-multiple of 16 through frame cropping

 Supports frame width of the range of 32 to 1920 pixels

 Supports byte-stream syntax and NAL unit format for the input bit-
stream

 Supports parsing of Supplemental Enhancement Information (SEI) and


Video Usability Information (VUI)

 Supports long term reference frame and adaptive reference picture


marking

 Supports reference picture list reordering

 Supports gaps in frame number

 Supports decoding of streams with IPCM coded macroblocks

 Supports skipping of non reference pictures

 Supports configurable delay for display of frames

 Supports basic error concealment features

 Outputs are available in YUV 420 planar little endian format

 Tested for compliance with JM version 16.1 reference decoder

 Streams without IDR pictures, but containing pictures with all I-type
slices are decoded

 Supports ELF ABI format.

 Supports “ecpy” for EDMA and “IRES” interface.

This version of the decoder does not support the following features as per
the High Profile feature set:

 Support for ASO, FMO, and RS

 Support for monochrome format

1-7
Chapter 2

Installation Overview

This chapter provides a brief description on the system requirements and


instructions for installing the codec component. It also provides information
on building and running the sample test application.

2-1
Installation Overview

2.1 System Requirements


This section describes the hardware and software requirements for the
normal functioning of the codec component.

2.1.1 Hardware
This codec has been built and tested on the TMS320C6678 EVM with on
board USB emulation XDS100.

2.1.2 Software
The following are the software requirements for the normal functioning of
the codec:

 Development Environment: This project is developed using Code


Composer Studio version 4.2.3.00004.

 Code Generation Tools: This project is compiled, assembled,


archived, and linked using the code generation tools version 7.2.2.

 Cygnus Cygwin V.B20, which includes unix utilities and the ‘make’
program.

2.2 Installing the Component


The codec component is released as a compressed archive. To install the
codec, extract the contents of the zip file onto your local hard disk. The zip
file extraction creates a top-level directory called
100_V_H264AVC_D_01_01, under which another directory named
C6678_HP_001 is created.

Figure 2-1 shows the sub-directories created in the C6678_HP_001


directory.

2-2
Installation Overview

Figure 2-1. Component Directory Structure


Table 2-1 provides a description of the sub-directories created in the
C6678_HP_001 directory.

Table 2-1. Component Directories


Sub-Directory Description

\mkrel Contains files for setting environment variables

\make Contains make files for building the library

\Inc Contains XDM related header files which allow interface to the
codec library

\Lib Contains the codec library file

\Docs Contains user guide and datasheet

2-3
Installation Overview

Sub-Directory Description

\Client\Build\TestAppDecoder Contains the sample test application project, related .cmd file,
configuration files, final application executable (.out) and the
memory map generated on compilation of the code

\Client\Build\Repository Contains test application settings

\Client\Test\Src Contains application C and asm files

\Client\Test\Inc Contains header files needed for the application code

\Client\Test\TestVecs\Input Contains input test vectors

\Client\Test\TestVecs\Output Contains output generated by the codec

\Client\Test\TestVecs\Reference Contains read-only reference output to be used for cross-


checking against codec output

\Client\Test\TestVecs\Config Contains configuration parameter files

\Src\Build\h264vdecalg Contains the algorithm project, .cmd and .bat files

\Src\Build\h264vdecalg\Obj Contains the intermediate .asm and/or .obj files generated on


compilation of the code

\Src\Common Contains the library source C files

\Src\Platform\Inc Contains platform specific files

\Src\Inc Contains the library header files

\Src\ISA\C6xx\CI Contains platform specific algorithm C files

\Src\ISA\C6xx\Inc Contains platform specific algorithm header files

\Src\ISA\C6xx\SA Contains platform specific algorithm .sa files

\Src\Lib Contains the codec library file

Note:

“Src”, “mkrel” & “make” folders will be available as part of release package if it is a source release.
These folders are not available if it just an object/library release.

2-4
Installation Overview

2.3 Before Building the Sample Test Application


This codec is accompanied by a sample test application. To run the sample
test application, you need DSP/BIOS, Bios IPC, XDC Tools and TI
Framework Components (FC).

This version of the codec has been validated with

DSP/BIOS version 6.31.00.18,

Bios IPC version 1.22.04.25,

XDC Tools version 3.20.08.88 &

Framework Component (FC) version 3.20.02.29.

2.3.1 To build and run on CCSv4 IDE


Open CCSv4 IDE. Create new workspace.

In IDE go to Windows -> Preferences -> General -> Workspace -> Linked
Resources. Create new path variable H264VDEC_ROOT and set it to codec
root folder: ex: E:\100_V_H264AVC_D_01_01\C6678_HP_001

2.3.2 Installing DSP/BIOS


You can download DSP/BIOS from the TI external website:

http://softwaredl.ti.com/dsps/dsps_registered_sw/sdo_sb/targetcontent/ind
ex.html

Install DSP/BIOS at the same location where you have installed Code
Composer Studio. For example:

<install directory>\CCStudio_v4.2.3

2.3.3 Installing Framework Component (FC)


You can download FC from the TI external website:

http://softwaredl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/fc/3_20
_02_29/index_FDS.html

Extract the FC zip file to the same location where you have installed Code
Composer Studio. For example:

<install directory>\CCStudio_v4.2.3\ccv4

2.3.4 Installing XDC Tools


You can download XDC Tools from the TI external website:

http://softwaredl.ti.com/dsps/dsps_registered_sw/sdo_sb/targetcontent/ind
ex.html

2-5
Installation Overview

Install XDC Tools at the same location where you have installed Code
Composer Studio. For example:

<install directory>\CCStudio_v4.2.3

2.3.5 Installing BIOS IPC Tools


You can download BIOS IPC Tools from the TI external website:

http://softwaredl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/ipc/inde
x.html

Install BIOS IPC Tools at the same location where you have installed Code
Composer Studio. For example:

<install directory>\CCStudio_v4.2.3

2.4 Building Algorithm Library


To build the algorithm project from source code in Code Composer Studio,
follow these steps:

1) Import the algorithm project in workspace. Go to Project -> Import

existing CCS/CCE Eclipse project. Browse for the root directory of


library project. Ex:

E:\100_V_H264AVC_D_01_01\C6678_HP_001\src\build\h264vdecAlg.
Project file will detect automatically, click on finish.

2) Select library project (h264decAlg) -> right click -> Build Properties ->
Macros. Set the BIOS_ROOT, XDC_ROOT, and FRMWRK_ROOT to
host system path. For example:

BIOS_ROOT- C:\ccstudio_4.2.3\bios_6_31_00_18

FRMWRK_ROOT-
C:\ccstudio_4.2.3\ccsv4\framework_components_3_20_02_29

XDC_ROOT- C:\ccstudio_4.2.3\xdctools_3_20_08_88

3) Select configuration “Release”

4) Build the project

When build is completed, h264vdec_ti.le66 and h264vdec_ti.map can be


found at C6678_HP_001\Lib.

2.5 Building and Running the Sample Test Application


This codec is accompanied by a sample test application. This application
runs in TI’s Code Composer Studio development environment. To build
and run the sample application in Code Composer Studio, follow these
steps:

1) Import the application project in workspace by following the same


procedure as for the algorithm project. Ex:

2-6
Installation Overview

E:\100_V_H264AVC_D_01_01\C6678_HP_001\Client\Build\
TestAppDecoder

2) Set the Build properties -> Macros for test application project for
BIOS_ROOT, XDC_ROOT and FRMWRK_ROOT, e.g.,
BIOS_ROOT - C:\ccstudio_4.2.3\bios_6_31_00_18

FRMWRK_ROOT -
C:\ccstudio_4.2.3\ccsv4\framework_components_3_20_02_29

XDC_ROOT - C:\ccstudio_4.2.3\xdctools_3_20_08_88

3) Verify that the codec object library, h264vdec_ti.le66 exists in the \Lib
sub-directory.

4) Build the project. When build is completed, TestAppDecoder.out and


TestAppDecoder.map can be found at C6678_HP_001\
Client\Build\TestAppDecoder\Debug

5) Create a new configuration - Go to Target -> New Target


Configuration and click “finish”. After this step, select the appropriate
target for execution namely simulator or emulator.

6) Go to View->Target Configuration. Right click on the selected target


configuration and choose “Launch Selected Configuration”.

7) Load the DSP executable (TestAppDecoder.out).

8) Select Target -> Run to execute the sample test application. The
sample test application takes the input files stored in the
\Client\Test\Testvecs\Input sub-directory, runs the codec, and uses
the reference files stored in the \Client\Test\Testvecs\Reference sub-
directory to verify that the codec is functioning as expected.

9) On successful completion, the application displays one of the following


messages for each frame:
o “Decoder output dump completed” (for output dump mode).

2.6 Configuration Files


This codec is shipped along with:

 Generic configuration file (Testvecs.cfg) – specifies input and reference


files for the sample test application.

 Decoder configuration file (Testparams.cfg) – specifies the


configuration parameters used by the test application to configure the
Decoder.

2.6.1 Generic Configuration File


The sample test application shipped along with the codec uses the
configuration file, Testvecs.cfg for determining the input and reference files
for running the codec and checking for compliance. The Testvecs.cfg file is
available in the \Client\Test\TestVecs\Config sub-directory.

2-7
Installation Overview

The format of the Testvecs.cfg file is:


X
Config
Input
Output/Reference

where:

 X may be set as:

o 1 - for compliance checking, no output file is created


o 0 - for writing the output to the output file

 Config is the Decoder configuration file. For details, see section 2.7.2

 Input is the input file name (use complete path).

 Output/Reference is the output file name (if X is 0) or reference file


name (if X is 1).

A sample Testvecs.cfg file is as shown:

1
..\..\Test\TestVecs\Config\Testparams.cfg
..\..\Test\TestVecs\Input\football_704x480_IBBP_CABAC_16mv_mbaff_3Mbps.264
..\..\Test\TestVecs\Reference\football_704x480_IBBP_CABAC_16mv_mbaff_3Mbps.yuv
0
..\..\Test\TestVecs\Config\Testparams.cfg
..\..\Test\TestVecs\Input\ football_704x480_IBBP_CABAC_16mv_mbaff_3Mbps.264
..\..\Test\TestVecs\Output\ football_704x480_IBBP_CABAC_16mv_mbaff_3Mbps.yuv

2.6.2 Decoder Configuration File


The decoder configuration file, Testparams.cfg contains the configuration
parameters required for the decoder. The Testparams.cfg file is available in
the \Client\Test\TestVecs\Config sub-directory.

A sample Testparams.cfg file for Multicore is as shown:

# Input File Format is as follows


# <ParameterName> = <ParameterValue> # Comment
#
###########################################################
Parameters
###########################################################

ImageWidth = 1920 # Image width in Pels, must be multiple of 16


ImageHeight = 1088 # Image height in Pels, must be multiple of 16
ChromaFormat = 1 # 1 => XMI_YUV_420P, 3 => XMI_YUV_422IBE,
# 4 => XMI_YUV_422ILE
FramesToDecode = 1800 # Number of frames to be coded
ncores = 2 # Number of cores to be used for decoding
Master_id = 4 # Master core number
Slave_id = 5 # Slave core number
InputStreamFormat = 0 # 0 = > ByteStreamFormat, 1 => NAL unit format

2-8
Installation Overview

A sample Testparams.cfg file for Single core is as shown:

# Input File Format is as follows


# <ParameterName> = <ParameterValue> # Comment
#
###########################################################
Parameters
###########################################################

ImageWidth = 1920 # Image width in Pels, must be multiple of 16


ImageHeight = 1088 # Image height in Pels, must be multiple of 16
ChromaFormat = 1 # 1 => XMI_YUV_420P, 3 => XMI_YUV_422IBE,
# 4 => XMI_YUV_422ILE
FramesToDecode = 1800 # Number of frames to be coded
ncores = 1 # Number of cores to be used for decoding
Master_id = 4 # Master core number, Will not have any effect when ncores=1
Slave_id = 5 # Slave core number, Will not have any effect when ncores=1
InputStreamFormat = 0 # 0 = > ByteStreamFormat, 1 => NAL unit format

2.7 Standards Conformance and User-Defined Inputs


To check the conformance of the codec for the default input file shipped
along with the codec, follow the steps as described in Section 2.7.

To check the conformance of the codec for other input files of your choice,
follow these steps:

1) Copy the input files to the \Client\Test\TestVecs\Inputs sub-directory.

2) Copy the reference files to the \Client\Test\TestVecs\Reference sub-


directory.

3) Edit the configuration file, Testvecs.cfg available in the


\Client\Test\TestVecs\Config sub-directory. For details on the format of
the Testvecs.cfg file, see section 2.7.1.

4) Execute the sample test application. On successful completion, the


application displays one of the following message for each frame:
o “Decoder compliance test passed/failed” (if X is 1)
o “Decoder output dump completed” (if X is 0)

If you have chosen the option to write to an output file (X is 0), you can use
any standard file comparison utility to compare the codec output with the
reference output and check for conformance.

2.8 Uninstalling the Component


To uninstall the component, delete the codec directory from your hard disk.

2-9
Installation Overview

This page is intentionally left blank

2-10
Chapter 3

Sample Usage

This chapter provides a detailed description of the sample test application


that accompanies this codec component.

3-1
Sample Usage

3.1 Overview of the Test Application


The test application exercises the IVIDDEC2 base class of the H.264
Decoder library. The main test application files are TestAppDecoder.c and
TestAppDecoder.h. These files are available in the \Client\Test\Common
and \Client\Test\Inc sub-directories respectively

Figure 3-1 depicts the sequence of APIs exercised in the sample test
application.

Figure 3-1. Test Application Sample Implementation

3-2
Sample Usage

The test application is divided into four logical blocks:

 Parameter setup

 Algorithm instance creation and initialization

 Process call

 Algorithm instance deletion

3.1.1 Parameter Setup


Each codec component requires various codec configuration parameters to
be set at initialization. For example, a video codec requires parameters
such as video height, video width, and so on. The test application obtains
the required parameters from the Decoder configuration files.

In this logical block, the test application does the following:

1) Opens the generic configuration file, Testvecs.cfg and reads the


compliance checking parameter, Decoder configuration file name
(Testparams.cfg), input file name, and output/reference file name.

2) Opens the Decoder configuration file, (Testparams.cfg) and reads the


various configuration parameters required for the algorithm.
For more details on the configuration files, see Section 2.6.

3) Sets the IVIDDEC2_Params structure based on the values it reads


from the Testparams.cfg file.

4) Reads the input bit-stream into the application input buffer.

After successful completion of the above steps, the test application does
the algorithm instance creation and initialization.

3.1.2 Algorithm Instance Creation and Initialization


In this logical block, the test application accepts the various initialization
parameters and returns an algorithm instance pointer. The following APIs
are called in sequence:

1) algNumAlloc() - To query the algorithm about the number of


memory records it requires.

2) algAlloc() - To query the algorithm about the memory requirement


to be filled in the memory records.

3) algInit() - To initialize the algorithm with the memory structures


provided by the application.

A sample implementation of the create function that calls


algNumAlloc(), algAlloc(), and algInit() in sequence is provided
in the ALG_create() function implemented in the alg_create.c file.

After successful creation of the algorithm instance, the test application


does RMAN resource allocation for the algorithm. This requires

3-3
Sample Usage

initialization of RMAN resources. This is implemented by calling RMAN


interface functions in the following sequence:

1.RMAN_init() - To initialize the RMAN module.

2.RMAN_assignResources() - To grant the RMAN resources to the


algorithm instance.

3.1.3 Process Call


After algorithm instance creation and initialization, the test application does
the following:

1) Sets the dynamic parameters (if they change during run-time) by


calling the control() function with the XDM_SETPARAMS command.

2) Sets the input and output buffer descriptors required for the
process() function call. The input and output buffer descriptors are
obtained by calling the control() function with the XDM_GETBUFINFO
command.

3) Calls the process() function to encode/decode a single frame of


data. The behavior of the algorithm can be controlled using various
dynamic parameters. The inputs to the process function are input and
output buffer descriptors, pointer to the IVIDDEC2_InArgs and
IVIDDEC2_OutArgs structures.

The control() and process() functions should be called only within the
scope of the algActivate() and algDeactivate() XDAIS functions
which activate and deactivate the algorithm instance respectively. Once an
algorithm is activated, there could be any ordering of control() and
process() functions. The following APIs are called in sequence:

4) algActivate() - To activate the algorithm instance.

5) control() (optional) - To query the algorithm on status or setting of


dynamic parameters and so on, using the six available control
commands.

6) process() - To call the Decoder with appropriate input/output buffer


and arguments information.

7) control() (optional) - To query the algorithm on status or setting of


dynamic parameters and so on, using the six available control
commands.

8) algDeactivate() - To deactivate the algorithm instance.

In the master core, the do-while loop encapsulates frame level process()
call and updates the input buffer pointer every time before the next call.
The do-while loop breaks off either when an error condition occurs or when
the input buffer exhausts. It also protects the process() call from file
operations by placing appropriate calls for cache operations as well. The
test application does a cache invalidate for the valid input buffers before

3-4
Sample Usage

process() and a cache write back invalidate for output buffers after
process(). The slave core just calls the process() in the do-while loop.

In the multi-core application, the master and slave cores synchronize within
the do-while loop to exit if there is an error condition or input buffer
exhausts.

In the sample test application, after calling algDeactivate(), the master-


core dumps the output data to a file or compares it with a reference file.

3.1.4 Algorithm Instance Deletion


Once encoding/decoding is complete, the test application must delete the
current algorithm instance. The following APIs are called in a sequence:

9) algNumAlloc() - To query the algorithm about the number of memory


records it used.

10) algFree() - To query the algorithm to get the memory record


information.

11) RMAN_freeResources() - To remove logical channel resources from


an algorithm instance.

12) RMAN_exit() - To free RMAN memory resources.

A sample implementation of the delete function that calls algNumAlloc()


and algFree() in sequence is provided in the ALG_delete() function
implemented in the alg_create.c file.

3.2 Frame Buffer Management by Application

3.2.1 Frame Buffer Input and Output


With the new XDM 1.0, decoder does not ask for frame buffer at the time of
alg_create(). It uses buffer from XDM1_BufDesc *outBufs, which it
reads during each decode process call. Hence, there is no distinction
between DPB and display buffers. The framework needs to ensure that it
does not overwrite the buffers that are locked by the codec.

ALG_create(…);

iVidDecFxns->control(…,XDM_GETBUFINFO,…); /* Returns default D1 size */


do{
iVidDecFxns->process(…); //call the decode API
iVidDecFxns->control(…,XDM_GETBUFINFO,…); /* updates the memory
required as per the size
parsed in stream
header */
}
while(all frames)

3-5
Sample Usage

Note:

 Application can take the information returned by the control function with
the XDM_GETBUFINFO command and change the size of the buffer
passed in the next process call.

 Application can re-use the extra buffer space of the 1st frame, if the
above control call returns a small size than that was provided.

 The master core handles frame buffer management.

The frame pointer given by the application and that returned by the algorithm
may be different. BufferID (InputID/outputID) provides the unique ID to
keep a record of the buffer given to the algorithm and released by the
algorithm. The following figure explains the frame pointer usage.

Pointer given by framework


in XDM1_BufDesc *outBufs
INPUT

ID: X

Pointer given by framework


in IVIDDEC2_InArgs->
inputID

Pointer returned by codec in


IVIDDEC2_OutArgs- OUTPUT
>displayBufs
Frame Height

ID: X Frame width

Frame pitch
Pointer given by framework
in IVIDDEC2_OutArgs-

Figure 3-2. Frame Buffer Pointer Implementation

3-6
Sample Usage

Note:

 Frame pointer returned by the codec in display_bufs will point to the


actual start location of the picture

 Frame height and width is the actual height and width (after removing
cropping and padded width)

 Frame pitch indicates the offset between the pixels at the same
horizontal co-ordinate on two consecutive lines

As explained above, buffer pointer cannot be used as a unique identifier to


keep a record of frame buffers. Any buffer given to algorithm should be
considered locked by algorithm, unless the buffer is returned to the
application through IVIDDEC2_OutArgs->freeBufID[].

Note:
BufferID returned in IVIDDEC2_OutArgs ->outputID[] is just for
display purpose. Application should not consider it free unless it is a part of
IVIDDEC2_OutArgs->freeBufID[].

3.2.2 Frame Buffer Management by Application

The application framework can efficiently manage frame buffers by keeping


a pool of free frames from which it gives the decoder empty frames on
request.

Algorithm Framework
GetFreeBuffer( )
Video Decode
Thread Free Post
Frame Processing or
XDM API Buffers Display
ReleaseBuffer( )
Subsystem
Video Decoder

Figure 3-3. Interaction of Frame Buffers Between Application and Framework

3-7
Sample Usage

The sample application also provides a prototype for managing frame


buffers. It implements the following functions, which are defined in file
buffermanager.c provided along with test application.

 BUFFMGR_Init() - BUFFMGR_Init function is called by the test


application to initialize the global buffer element array to default and to
allocate the required number of memory data for reference and output
buffers. The maximum required DPB size is defined by the supported
profile and level.

 BUFFMGR_ReInit() - BUFFMGR_ReInit function allocates global


luma and chroma buffers and allocates entire space to the first
element. This element will be used in the first frame decode. After the
picture height and width and its luma and chroma buffer requirements
are obtained, the global luma and chroma buffers are re-initialized to
other elements in the buffer array.

 BUFFMGR_GetFreeBuffer() - BUFFMGR_GetFreeBuffer function


searches for a free buffer in the global buffer array and returns the
address of that element. Incase none of the elements are free, then it
returns NULL.

 BUFFMGR_ReleaseBuffer() - BUFFMGR_ReleaseBuffer function


takes an array of buffer-IDs which are released by the test application.
0 is not a valid buffer ID, hence this function moves until it encounters
a buffer ID as zero or it hits the MAX_BUFF_ELEMENTS.

 BUFFMGR_DeInit()- BUFFMGR_DeInit function releases all


memory allocated by buffer manager.

3.2.3 Display Delay and Resolution


The number of buffers in the DPB of the decoder is dependent on the
resolution at the given level. For example, for Level 3.0 for which the DPB
size (as given by the H264 Standard Annex A – Table A-1) is 3037.5 Kbytes.
The dependency of the number of buffers on the given resolution is
explained as follows.

For 720 x 576 @ Level 3.0, number of buffers in DPB = MIN(((3037.5 *


1024)/(1.5 * 720 * 576)),16) = 5

For 352 x 288 @ Level 3.0, number of buffers in DPB = MIN(((3037 *


1024)/(1.5 * 352 * 288)),16) = 16

In general, the formula is:

N = MIN(((3037.5 * 1024)/(1.5 * Width * Height)),16)

The number of buffers requested by the decoder from the application is N+2.
The additional buffer is for writing the YUV output for the current decoded
picture.

Therefore, while decoding a stream of resolution 720 x 576, the decoder will
buffer up to 5 frames before it provides the first buffer for display. Similarly,
for 352 x 288 resolution, the decoder buffers up to 16 frames. That is, for

3-8
Sample Usage

720 x 576, process call 6 will provide the first buffer for display. Similarly, for
the other resolutions.

The decoder and the application refers to any buffer by the unique buffer ID
assigned by the application at the time of providing the buffer to the decoder
through InArgs.inputID. The decoder internally bookmarks these buffers
using the assigned buffer ID. The decoder conveys the buffers to be
displayed to the application using the array outArgs.outputID[]. It
populates the buffer IDs of the buffers to be displayed in the order of display
in this array terminated by a zero, which is an invalid buffer ID (a buffer ID
has to be a non-zero value). Similarly, the decoder conveys the buffers to be
freed to the application using the array outArgs.freeBufID[]. It populates
the buffer IDs of the buffers to be freed in this array terminated by a zero,
which is an invalid buffer ID.

3.3 Handshaking between multiple cores


In case of the multi-core execution, the same .out file is loaded on both the
cores and executed. The master and slave core synchronize at multiple
points using a software barrier implementation.

3.4 Sample Test Application


The test application exercises the IVIDDEC2 base class of the H.264
Decoder.

Table 3-1. Process () Implementation.

3-9
Sample Usage

/* Setting the sizes of Base Class Objects */


params.viddecParams.size = sizeof(IH264HPVDEC_Params);
status.viddecStatus.size = sizeof(IH264HPVDEC_Status);
dynamicParams.size = sizeof(IVIDDEC2_DynamicParams);
inArgs.viddecInArgs.size = sizeof(IH264HPVDEC_InArgs);
outArgs.viddecOutArgs.size = sizeof(IH264HPVDEC_OutArgs);

...

/* Create the Algorithm object (instance) */


printf("\nCreating Algorithm Instance...");

if ((handle = (IALG_Handle)ALG_create (
(IALG_Fxns *) &H264HPDEC_CIT_IH264HPDEC,
(IALG_Handle) NULL, (IALG_Params *) &(params.viddecParams))) == NULL)
{
printf( "\nFailed to Create Instance... Exiting for this configuration..");
continue;
}

...

/* Assigning Algorithm handle fxns field to ividDecfxns */


ividDecFxns = (IVIDDEC2_Fxns *)handle->fxns;

handle->fxns->algActivate(handle);

/* Get Buffer information */


ividDecFxns->control((IVIDDEC2_Handle)handle, XDM_GETBUFINFO,
(IVIDDEC2_DynamicParams *)&dynamicParams,
(IVIDDEC2_Status *)&status);

handle->fxns->algDeactivate(handle);

if(DNUM==CORE_TEAM[0])
{
/* Initialize all buffers to be FREE */
/* Get the first free buffer */
ret_val = BUFFMGR_Init
(
status.viddecStatus.bufInfo.minNumOutBufs,
status.viddecStatus.bufInfo.minOutBufSize
);
if (ret_val)
{
fprintf (stdout,"\nMemory could not get allocated for output
buffers\n");
break;
}
}

...

/* Do-While Loop for Decode Call */


do
{
/* Activate the Algorithm */
handle->fxns->algActivate(handle);

...

/* Optional: Set Run time parameters in the Algorithm via control() */


ividDecFxns->control((IVIDDEC2_Handle)handle, XDM_SETPARAMS,

3-10
Sample Usage

(IVIDDEC2_DynamicParams *)&dynamicParams,
(IVIDDEC2_Status *)&status);

/* Cache Invalidate for Input Buffer */


for(ii=0 ; ii < inputBufDesc.numBufs ; ii++ )
{
/* Cache Invalidate for Input Buffer */
BCACHE_inv(inputBufDesc.descs[ii].buf, validBytes, TRUE);
}

H264VDEC_mcore_sync(DNUM,IH264_SWBARR5, ncores);

if(DNUM!=CORE_TEAM[0])
{
/*Slave core - Check for end of frames*/
if(multiCoreSync[0])
break;
}

/* Basic Algorithm process() call */


retVal = ividDecFxns->process((IVIDDEC2_Handle)handle,
(XDM1_BufDesc *)&inputBufDesc,
(XDM_BufDesc *)&outputBufDesc,
(IVIDDEC2_InArgs *)&inArgs,
(IVIDDEC2_OutArgs *)&outArgs);

...
...

/* DeActivate the Algorithm */


handle->fxns->algDeactivate(handle);

BUFFMGR_ReleaseBuffer((XDAS_UInt32 *)outArgs.viddecOutArgs.freeBufID);

...

H264VDEC_mcore_sync(DNUM,IH264_SWBARR5, ncores);

if(multiCoreSync[0])
break;

} while(1); /* end of Do-While loop */

Note:
This sample test application does not depict the actual function parameter or
control code. It shows the basic flow of the code.

3-11
Chapter 4

API Reference

This chapter provides a detailed description of the data structures and


interfaces functions used in the codec component.

4-1
API Reference

4.1 Symbolic Constants and Enumerated Data Types


This section summarizes all the symbolic constants specified as either
#define macros and/or enumerated C data types. For each symbolic
constant, the semantics or interpretation of the same is also provided.

Table 4-1. List of Enumerated Data Types


Group or Enumeration Class Symbolic Constant Name Description or Evaluation

IVIDEO_FrameType IVIDEO_NA_FRAME Frame type not available

IVIDEO_I_FRAME Intra coded frame (default value)

IVIDEO_P_FRAME Forward inter coded frame

IVIDEO_B_FRAME Bi-directional inter coded frame

IVIDEO_IDR_FRAME Intra coded frame that can be used


for refreshing video content

IVIDEO_II_FRAME Interlaced Frame, both fields are I


frames

IVIDEO_IP_FRAME Interlaced Frame, first field is an I


frame, second field is a P frame

IVIDEO_IB_FRAME Interlaced Frame, first field is an I


frame, second field is a B frame

IVIDEO_PI_FRAME Interlaced Frame, first field is a P


frame, second field is a I frame

IVIDEO_PP_FRAME Interlaced Frame, both fields are P


frames

IVIDEO_PB_FRAME Interlaced Frame, first field is a P


frame, second field is a B frame

IVIDEO_BI_FRAME Interlaced Frame, first field is a B


frame, second field is an I frame.

IVIDEO_BP_FRAME Interlaced Frame, first field is a B


frame, second field is a P frame

IVIDEO_BB_FRAME Interlaced Frame, both fields are B


frames

IVIDEO_MBAFF_I_FRAME Intra coded MBAFF frame

IVIDEO_MBAFF_P_FRAME Forward inter coded MBAFF frame

IVIDEO_MBAFF_B_FRAME Bi-directional inter coded MBAFF


frame

4-2
API Reference

Group or Enumeration Class Symbolic Constant Name Description or Evaluation

IVIDEO_MBAFF_IDR_FRAME Intra coded MBAFF frame that can


be used for refreshing video content.

IVIDEO_FRAMETYPE_DEFAUL Default set to IVIDEO_I_FRAME


T

IVIDEO_ContentType IVIDEO_CONTENTTYPE_NA Content type not available

IVIDEO_PROGRESSIVE Progressive video content

IVIDEO_INTERLACED Interlaced video content

IVIDEO_CONTENTTYPE_DEFA Default set to


ULT IVIDEO_PROGRESSIVE

IVIDEO_FrameSkip IVIDEO_NO_SKIP Do not skip the current frame. This


is the default value.

IVIDEO_SKIP_P Skip forward inter coded frame.


Not supported in this version of
H.264 decoder.

IVIDEO_SKIP_B Skip non -referenced frame. (See


Section 4.2.2.5 for details).

IVIDEO_SKIP_I Skip intra coded frame.


Not supported in this version of
H.264 decoder.

IVIDEO_SKIP_IP Skip I and P frame/field(s)


Not supported in this version of
H264 Decoder.

IVIDEO_SKIP_IB Skip I and B frame/field(s).


Not supported in this version of
H264 decoder.

IVIDEO_SKIP_PB Skip P and B frame/field(s).


Not supported in this version of
H264 Decoder.

IVIDEO_SKIP_IPB Skip I/P/B/BI frames


Not supported in this version of
H264 Decoder.

IVIDEO_SKIP_IDR Skip IDR Frame


Not supported in this version of
H264 Decoder.

IVIDEO_SKIP_DEFAULT Default set to IVIDEO_NO_SKIP

IVIDEO_OutputFrameStatus IVIDEO_FRAME_NOERROR The output buffer is available.

IVIDEO_FRAME_NOTAVAILAB The codec does not have any output


LE buffers.

4-3
API Reference

Group or Enumeration Class Symbolic Constant Name Description or Evaluation

IVIDEO_FRAME_ERROR The output buffer is available and


corrupted.

IVIDEO_OUTPUTFRAMESTATU Default set to


S_DEFAULT IVIDEO_FRAME_NOERROR

XDM_DataFormat XDM_BYTE Big endian stream

XDM_LE_16 16-bit little endian stream.


Not applicable for H.264 decoder.

XDM_LE_32 32-bit little endian stream.


Not applicable for H.264 decoder.

XDM_ChromaFormat XDM_CHROMA_NA Chroma format not applicable

XDM_YUV_420P YUV 4:2:0 planar


Not supported in this version of
H264 Decoder.

XDM_YUV_422P YUV 4:2:2 planar.


Not supported in this version of
H264 Decoder.

XDM_YUV_422IBE YUV 4:2:2 interleaved (big endian).


Not supported in this version of
H264 Decoder.

XDM_YUV_422ILE YUV 4:2:2 interleaved (little endian)


Not supported in this version of
H264 Decoder.

XDM_YUV_444P YUV 4:4:4 planar.


Not supported in this version of
H264 Decoder.

XDM_YUV_411P YUV 4:1:1 planar.


Not supported in this version of
H264 Decoder.

XDM_GRAY Gray format.


Not supported in this version of
H264 Decoder.

XDM_RGB RGB color format.


Not supported in this version of
H264 Decoder.

XDM_CHROMAFORMAT_DEFAUL Default set to XDM_YUV_422ILE


T

XDM_CmdId XDM_GETSTATUS Query algorithm instance to fill


Status structure

4-4
API Reference

Group or Enumeration Class Symbolic Constant Name Description or Evaluation

XDM_SETPARAMS Set run-time dynamic parameters


via the DynamicParams structure
Not supported in this version of
H264 Decoder.

XDM_RESET Reset the algorithm.

XDM_SETDEFAULT Initialize all fields in Params


structure to default values specified
in the library.
Not supported in this version of
H264 Decoder.

XDM_FLUSH Handle end of stream conditions.


This command forces algorithm
instance to output data without
additional input.

XDM_GETBUFINFO Query algorithm instance regarding


the properties of input and output
buffers

XDM_GETVERSION Query the algorithm’s version. The


result will be returned in the @c data
field of the respective
_Status structure.
Not supported in this version of
H264 Decoder.

XDM_AccessMode XDM_ACCESSMODE_READ The algorithm read from the buffer


using the CPU.

XDM_ACCESSMODE_WRITE The algorithm wrote from the buffer


using the CPU

XDM_ErrorBit XDM_APPLIEDCONCEALMEN Bit 9


T
 1 - Applied concealment
 0 - Ignore

XDM_INSUFFICIENTDATA Bit 10
 1 - Insufficient data
 0 - Ignore

XDM_CORRUPTEDDATA Bit 11
 1 - Data problem/corruption
 0 - Ignore

XDM_CORRUPTEDHEADER Bit 12
 1 - Header problem/corruption
 0 - Ignore

4-5
API Reference

Group or Enumeration Class Symbolic Constant Name Description or Evaluation

XDM_UNSUPPORTEDINPUT Bit 13
 1 - Unsupported
feature/parameter in input
 0 - Ignore

XDM_UNSUPPORTEDPARAM Bit 14
 1 - Unsupported input
parameter or configuration
 0 - Ignore

XDM_FATALERROR Bit 15
 1 - Fatal error (stop encoding)
 0 - Recoverable error

Note:

The remaining bits that are not mentioned in XDM_ErrorBit are


interpreted as:
 Bit 16-32: Reserved
 Bit 8: Reserved
 Bit 0-7: Codec and implementation specific. The type of error
encountered while decoding the bitstream is returned through
extendedError field of outputArgs. Bits 8-15 are set as per XDM
convention. Bits 0-7 are used to indicate errors specific to H.264
Decoder. The various error codes returned by the H.264 Decoder (in
the lower 8-bits) and their values are given in the table below.

The algorithm can set multiple bits to 1 depending on the error condition.

4-6
API Reference

The following table lists the detailed error codes and their values.

Table 4-2. Error Codes and Values.


Error codes Description Values

NAL Unit specific semantic Errors

H264D_ERR_SEM_NALU_EOSTRMREACHED Additional NALU is received after an end of 0x21


stream NALU.

H264D_ERR_SEM_NALU_FORBIDDENBIT NALU syntax forbidden bit is not zero. 0x22

H264D_ERR_SEM_NALU_NALREFIDC The nal_ref_idc field has a value that 0x23


violates constraints specified in the
standard.

H264D_ERR_SEM_NALU_NALUTYP Incorrect NALU type received. It may not be 0x25


an illegal NALU type, but incorrect based
on the type of previous NALU.

H264D_ERR_SEM_NALU_EOSEQ End of sequence NALU is incorrectly 0x26


received when a picture is partially
decoded.
This is not an error. It is displayed as a
warning only.

H264D_ERR_SEM_NALU_STARTCODEPREFIX Start code prefix not found in the bitstream 0x27

SPS specific semantic Errors

H264D_ERR_SEM_SPS_INVLD_PROFILE The profile specified in SPS is invalid or is 0x41


unsupported by the decoder.

H264D_ERR_SEM_SPS_POCTYPE The pic_order_cnt_type field 0x43


decoded as part of SPS has an illegal
value.

H264D_ERR_SEM_SPS_MAXPOCLSB The 0x44


log2_max_pic_order_cnt_lsb_min
us4 field decoded as a part of SPS has an
illegal value.

H264D_ERR_SEM_SPS_NUMREFFRAMESINPOCC The 0x45


YCLE num_ref_frames_in_pic_order_cn
t_cycle field decoded as part of SPS has
an illegal value.

H264D_ERR_SEM_SPS_DIRECT8X8FLAG The direct_8x8_inference_flag 0x46


field decoded as part of SPS has an illegal
value.

H264D_ERR_SEM_SPS_FRAMECROP The frame cropping parameters decoded as 0x47


part of SPS have an illegal value.

4-7
API Reference

Error codes Description Values

H264D_ERR_SEM_SPS_ACTIVESPS_MISMATCH If in between access unit decoding, a SPS 0x48


is received with same seq_parm_set_id
as active_sps_id, then contents of
received_sps should be equal to
active_sps. Otherwise, this error code is
set.

H264D_ERR_SEM_SPS_SEQID The field seq_parameter_set_id of 0x49


SPS has an illegal value

H264D_ERR_SEM_SPS_UNSUPPORTEDPICWIDT The width specified in SPS is not supported 0x4A


H by the decoder

H264D_ERR_SEM_SPS_REF_FRAMES_BEYOND_ The number of reference frames specified 0x4B


LIMIT in SPS is beyond the limit allowed by the
standard

H264D_ERR_SEM_SPS_UNSUPPORTEDPICHEIG The height specified in SPS is not 0x4C


HT supported by the decoder

PPS specific semantic Errors

H264D_ERR_SEM_PPS_PPSID The field pic_parameter_set_id part 0x61


of PPS has an illegal value

H264D_ERR_SEM_PPS_SEQID The seq_parameter_set_id field part 0x62


of PPS has an illegal value

H264D_ERR_SEM_PPS_SLCGRPMAPTYPE The slice_group_map_type field in 0x63


PPS has an illegal or incorrect value

H264D_ERR_SEM_PPS_TOPLEFT The field in PPS used for certain type of 0x64


FMO has a wrong value

H264D_ERR_SEM_PPS_BOTRIGHT The field in PPS used for certain type of 0x65


FMO has a wrong value

H264D_ERR_SEM_PPS_TOPBOTMOD The field in PPS used for certain type of 0x66


FMO has a wrong value

H264D_ERR_SEM_PPS_RUNLENGTH The field in PPS used for certain type of 0x67


FMO has a wrong value

H264D_ERR_SEM_PPS_SLCGRPCHNGRATE The field in PPS used for certain type of 0x68


FMO has a wrong value

H264D_ERR_SEM_PPS_PICSIZEMAPUNITS The field 0x69


pic_size_in_map_units_minus1 in
PPS has an incorrect value

H264D_ERR_SEM_PPS_NUMREFIDXACTIVEL The field 0x6A


0 num_ref_idx_l0_active_minus1 in
PPS has an illegal value

4-8
API Reference

Error codes Description Values

H264D_ERR_SEM_PPS_NUMREFIDXACTIVEL The field 0x6B


1 num_ref_idx_l0_active_minus1 in
PPS has an illegal value

H264D_ERR_SEM_PPS_INITDQP The field pic_init_qp_minus26 in 0x6C


PPS has a value out of bounds with what is
specified by standard

H264D_ERR_SEM_PPS_INITDQS The field pic_init_qs_minus26 in 0x6D


PPS has a value out of bounds with what is
specified by standard

H264D_ERR_SEM_PPS_QPINDEXOFFSET The field chroma_qp_index_offset in 0x6E


PPS has a value out of bounds with what is
specified by standard

H264D_ERR_SEM_PPS_ACTIVEPPS_MISMAT If in between access unit decoding, a PPS 0x6F


CH is received with same pic_parm_set_id
as active_pps_id, then contents of
received_pps should be equal to
active_pps. Otherwise, this error code is
set.

H264D_ERR_SEM_PPS_NUMSLCGRP The num_slice_groups_minus1 field 0x70


in PPS has an illegal value

H264D_ERR_SEM_PPS_SLCGRPID The field slice_group_id in PPS has 0x71


an incorrect value (based on
num_slice_groups_minus1 field)

H264D_ERR_SEM_PPS_BIPREDIDC_INVALI The weighted_bipred_idc field in 0x72


D PPS has an illegal value

Slice Header semantic Errors

H264D_ERR_SEM_SLCHDR_DELTAPICCNTBO The delta_pic_order_cnt_bottom 0x81


T field in slice header has an incorrect value

H264D_ERR_SEM_SLCHDR_PICPARAMSETID The pic_parameter_set_id field in 0x82


slice header has an illegal value

H264D_ERR_SEM_SLCHDR_SLCTYP Incorrect or unsupported slice type detected 0x83

H264D_ERR_SEM_SLCHDR_FIRSTMBINSLC The first_mb_in_slice field is greater 0x84


than PicSizeInMbs

H264D_ERR_SEM_SLCHDR_IDRPICID The idr_pic_id field in slice header has 0x85


an illegal value

H264D_ERR_SEM_SLCHDR_REDUNDANTPICC The field redundant_pic_cnt in slice 0x86


NT header has an illegal value

4-9
API Reference

Error codes Description Values

H264D_ERR_SEM_SLCHDR_NUMREFIDXACTI The 0x87


VEL0 num_ref_idx_l0_active_minus1
decoded in slice header or obtained from
PPS (based on
num_ref_idx_active_override_fl
ag) has an illegal value

H264D_ERR_SEM_SLCHDR_NUMREFIDXACTI The 0x88


VEL1 num_ref_idx_l1_active_minus1
decoded in slice header or obtained from
PPS (based on
num_ref_idx_active_override_fl
ag) has an illegal value

H264D_ERR_SEM_SLCHDR_CABACINITIDC The field cabac_init_idc in slice 0x89


header has an illegal value

H264D_ERR_SEM_SLCHDR_SLCQPDELTA Invalid quantisation paramter in slice 0x8A


header

H264D_ERR_SEM_SLCHDR_SLCQSDELTA The value of slice_qs_delta+ 0x8B


pic_init_qs_minus is out of bounds
with what is specified by standard

H264D_ERR_SEM_SLCHDR_DISABLEDEBLOC The 0x8C


KFILTERIDC disable_deblocking_filter_idc
field parsed in slice header has an illegal
value

H264D_ERR_SEM_SLCHDR_PICINVAR This is set if any of the conditions governing 0x8D


syntax elements in slice headers (for
multiple slices per picture) is not satisfied.

H264D_ERR_SEM_SLCHDR_SLCALPHAC0OFF The field 0x8E


SET slice_alpha_c0_offset_div2 has a
value out of bounds

H264D_ERR_SEM_SLCHDR_SLCBETAOFFSET The field slice_beta_offest_div2 0x8F


has a value out of bounds

H264D_ERR_SEM_SLCHDR_NON_ZERO_FRAM The frame_num field has non-zero value 0x90


E_NUM_IN_IDR in an IDR slice

H264D_ERR_SEM_SLCHDR_ILLEGAL_PRED_ Any of the variables associated with the 0x91


WEIGHT computation of prediction weights has an
illegal value

H264D_ERR_SEM_SLCHDR_UNSUPPORTED_L Level specified in bitstream is greater than 0x93


EVEL the supported level

H264D_ERR_SEM_SLCHDR_SPS_CHANGE_IN Change of IDR detected in a non-IDR 0x94


_NONIDR picture

4-10
API Reference

Error codes Description Values

H264D_ERR_SEM_SLCHDR_WAIT_SYNC_POI Decoding is skipping NAL units till a valid 0x95


NT sync point is found

H264D_ERR_SEM_SLCHDR_SLC_GRP_CHNG_ Slice_group_change_cycle value parsed in 0x96


CYCLE the slice header is illegal. This is not an
error. It is displayed as a warning only.

H264D_ERR_SEM_SLCHDR_GAPSINFRAMENU Gaps in frame number or wrong frame 0x97


M number coded.

CAVLC semantic Errors

H264D_ERR_SEM_CAVLC_LEVEL_DECODE Error in CAVLD level decoding 0xA1

H264D_ERR_SEM_CAVLC_CTOKEN_YY_AC Error in CTOKEN for luma AC coefficients 0xA2

H264D_ERR_SEM_CAVLC_CTOKEN_YY_DC Error in CTOKEN for luma DC coefficients 0xA3

H264D_ERR_SEM_CAVLC_CTOKEN_UV_AC Error in CTOKEN for chroma AC 0xA4


coefficients

H264D_ERR_SEM_CAVLC_CTOKEN_UV_DC Error in CTOKEN for chroma DC 0xA5


coefficients

H264D_ERR_SEM_CAVLC_LEVEL_YY_AC Error in level of luma AC coefficients 0xA6

H264D_ERR_SEM_CAVLC_LEVEL_YY_DC Error in level of luma DC coefficients 0xA7

H264D_ERR_SEM_CAVLC_LEVEL_UV_AC Error in level of chroma AC coefficients 0xA8

H264D_ERR_SEM_CAVLC_LEVEL_UV_DC Error in level of chroma DC coefficients 0xA9

H264D_ERR_SEM_CAVLC_TOTZERO_YY_AC Error in total zero value for luma AC 0xAA


coefficients

H264D_ERR_SEM_CAVLC_TOTZERO_YY_DC Error in total zero value for luma DC 0xAB


coefficients

H264D_ERR_SEM_CAVLC_TOTZERO_UV_AC Error in total zero value for chroma AC 0xAC


coefficients

H264D_ERR_SEM_CAVLC_TOTZERO_UV_DC Error in total zero value for chroma DC 0xAD


coefficients

H264D_ERR_SEM_CAVLC_RUNBEF_YY_AC Error in run before value for luma AC 0xAE


coefficients

H264D_ERR_SEM_CAVLC_RUNBEF_YY_DC Error in run before value for luma DC 0xAF


coefficients

H264D_ERR_SEM_CAVLC_RUNBEF_UV_AC Error in run before value for chroma AC 0xB0


coefficients

H264D_ERR_SEM_CAVLC_RUNBEF_UV_DC Error in run before value for chroma DC 0xB1


coefficients

4-11
API Reference

Error codes Description Values

These error codes reports that the specific feature is


not available in the decoder, or implementation
specific errors.

H264D_ERR_IMPL_PPSUNAVAIL The PPS referred to in the slice header is 0xC1


unavailable

H264D_ERR_IMPL_SPSUNAVAIL The SPS referred by the PPS id specified in 0xC2


slice header is unavailable

H264D_ERR_IMPL_NOMEMORY Memory insufficient to buffer MMCO 0xC3


commands or HRD CPB count is greater
than available memory

H264D_ERR_IMPL_CORRUPTED_BITSTREAM Corruption in bit-stream 0xC5

H264D_ERR_IMPL_NOTSUPPORTED_VUI VUI is not supported for this profile 0Xc9

H264D_ERR_IMPL_NOTSUPPORTED_REDUNT Redundant picture not supported for this 0xCA


ANT_PICTURE profile

H264D_ERR_IMPL_NOTSUPPORTED_ASOFMO ASO/FMO not supported for this profile 0xCE

H264D_ERR_IMPL_INSUFFICIENT_DATA Data insufficient to decode a picture 0xD1

H264D_ERR_IMPL_NO_DATA No slice type NALU was processed 0xD2


(available for processing).

H264D_ERR_IMPL_ERR_IN_REF_FRAME No error in the current picture, but the 0xD3


quality is likely to be affected due to the
propagation from an erroneous reference
frame.

H264D_ERR_IMPL_MISSING_FIELD Missing/Unpaired field detected. 0xD4

H264D_ERR_IMPL_UNAVAIL_REF_FRAME Referenced picture not found 0xD5

Annex B and other semantic errors

H264D_ERR_SEM_MBPRED_REFIDXL0 Decoded reference index exceeds the 0xE1


maximum ref_idx

H264D_ERR_SEM_MBPRED_INTRACHROMAPR Error in intra chroma prediction mode 0xE3


EDMODE

H264D_ERR_SEM_RPLR Reference picture list reordering is 0xE6


executed more than the bound

H264D_ERR_SEM_RPLR_PICNUMSIDC Value of 0xE7


reordering_of_pic_nums_idc is out

4-12
API Reference

Error codes Description Values

of bounds

H264D_ERR_SEM_RPLR_ABSDIFFPICNUMMI Value of abs_diff_pic_num_minus1 0xE8


NUS1 is out of bounds

H264D_ERR_SEM_MBLAYER_QPDELTA Decoded MB_QP_Delta is out of bounds 0xEB

H264D_ERR_SEM_MBLAYER_MBTYPE Decoding of MB_type had an error 0xEC

H264D_ERR_SEM_MBLAYER_CBP Decoding of CBP had an error 0xED

H264D_ERR_SEM_SLCDATA_MBSKIPRUN Value of mb_skip_run is out of bounds 0xEE

H264D_ERR_SEM_NOT_FRAME_MBS_ONLY Non-frame MBs are not supported at this 0xF1


level of the standard

H264D_ERR_SEM_ILLEGAL_INTRA_PRED_M Decoded value of the chroma intra 0xF4


ODE prediction mode is out of bounds

H264D_ERR_SEM_ILLEGAL_VALUE_OCCURE Indicates that mb_mode is illegal for the ref- 0xF5


D_TERMINATE idx decoding

Minor Errors

H264D_ERR_MINOR_SPS_MAXFRAMENUM The log2_max_pic_order_cnt_lsb_minus4 0x101


field has a value that violates constraints
specified in the Standard.

H264D_ERR_MINOR_NALU_NALORDERING Ordering of NAL units violates constraints 0x105


specified in the standard.

H264D_ERR_MINOR_NALU_NALUTYP_IDR An expected IDR NAL was not found in the 0x106


bit stream

H264D_ERR_MINOR_SPS_CHROMAFORMAT The chroma_format_idc field has a value 0x109


that violates constraints specified in the
Standard.

H264D_ERR_MINOR_SPS_BITDEPTHLUMA The bit_depth_luma_minus8 field has a 0x10A


value that violates constraints specified in
the Standard.

H264D_ERR_MINOR_SPS_BITDEPTHCHROMA The bit_depth_chroma_minus8 field has a 0x10B


value that violates constraints specified in
the Standard.

H264D_ERR_MINOR_SPS_LOSSLESS The 0x10C


qpprime_y_zero_transform_bypass_flag
field has a value that violates constraints
specified in the Standard.

4.1.1 H.264 Decoder Enumerated Data Types


This section describes the H.264 Decoder specific data structures.

4-13
API Reference

Table 4-3. H264 Decoder Enumerated Data Types


Group or Enumeration Class Symbolic Constant Name Description or Evaluation

eH264VDEC_TI_Level LEVEL_1 10: Level 1.0

LEVEL_1_1 11: Level 1.1

LEVEL_1_2 12: Level 1.2

LEVEL_1_3 13: Level 1.3

LEVEL_2 20: Level 2

LEVEL_2_1 21: Level 2.1

LEVEL_2_2 22: Level 2.2

LEVEL_3 30: Level 3

LEVEL_3_1 31: Level 3.1

LEVEL_3_2 32: Level 3.2

LEVEL_4 40: Level 4

LEVEL_4_1 41: Level 4.1

LEVEL_4_2 42: Level 4.2

LEVEL_5 50: Level 5

LEVEL_5_1 51: Level 5.1

LEVEL_INVALID 0xFF

MAX_NUM_LEVELS 15: Maximum Level ID which is not


supported.

eH264VDEC_TI_Profile PROFILE_INVALID -1

BASELINE 0: Decode if Baseline profile only

MAIN 1: Decode if Main profile only

EXTENDED 2: Not Supported

HIGH 3: Decode if High Profile only

MAX_PROFILES_TYPES 4: Maximum number of profiles

ePicStruct_t TOP_FIELD Indicates top field in field picture

BOTTOM_FIELD Indicates bottom field in field picture

4-14
API Reference

Group or Enumeration Class Symbolic Constant Name Description or Evaluation

FRAME Indicates frame picture

MAXSTRUCT

Table 4-4. H264 Decoder Multi-Core Enumerated Data Types


Group or Enumeration Class Symbolic Constant Name Description or Evaluation

IH264VDEC_Swbarrier IVIDMC_SWBARR0 0: Preslice decode sync point

IVIDMC_SWBARR1 1: N-MB level sync point

IVIDMC_SWBARR2 2: Postslice decode sync point

IVIDMC_SWBARR15 5: End of frame sync point in test


application.

IH264VDEC_ShmemKey IVIDMC_SHMEM_KEY_0 0: Key for shared buffer for inter-


core DMA transfer addresses

IVIDMC_SHMEM_KEY_1 1: Key for shared buffer for inter-


core synchronization and error
handling

IVIDMC_SHMEM_KEY_2 2: Key for shared external memory


data.

IVIDMC_SHMEM_KEY_CLEAN 0xFFFF: Key for cleaning the entire


cache.

IVIDMC_TASK_e IVIDMC_TASK_MASTER 0: Task ID for master core

IVIDMC_TASK_SLAVE 1: Task ID for slave core

IVIDMC_TASK_SLAVE_1 2

IVIDMC_TASK_SLAVE_2 3

IVIDMC_TASK_SLAVE_3 4

IVIDMC_TASK_SLAVE_4 5

IVIDMC_TASK_SLAVE_5 6

IVIDMC_TASK_SLAVE_6 7

4-15
API Reference

Group or Enumeration Class Symbolic Constant Name Description or Evaluation

IVIDMC_TASK_SLAVE_7 8

IVIDMC_TASK_SLAVE_8 9

4-16
API Reference

4.2 Data Structures


This section describes the XDM defined data structures, which are
common across codec classes. These XDM data structures can be
extended to define any implementation specific parameters for a codec
component.

4.2.1 Common XDM Data Structures


This section includes the following common XDM data structures:
 XDM_BufDesc

 XDM1_BufDesc

 XDM_SingleBufDesc

 XDM1_SingleBufDesc

 XDM_AlgBufInfo

 IVIDEO1_BufDesc

 IVIDDEC2_Fxns

 IVIDDEC2_Params

 IVIDDEC2_DynamicParams

 IVIDDEC2_InArgs

 IVIDDEC2_Status

 IVIDDEC2_OutArgs

4-17
API Reference

4.2.1.1 XDM_BufDesc

║ Description

This structure defines the buffer descriptor for input and output buffers.
║ Fields

Field Data type Input/ Description


Output

**bufs XDAS_Int8 Input Pointer to the vector containing buffer addresses

NumBufs XDAS_Int32 Input Number of buffers

*bufSizes XDAS_Int32 Input Size of each buffer in bytes

4.2.1.2 XDM1_BufDesc

║ Description

This structure defines the buffer descriptor for input and output buffers.
║ Fields

Field Datatype Input/ Description


Output

NumBufs XDAS_Int32 Input Number of buffers

descs[XDM_MA XDM1_SingleBufDes Input Array of buffer descriptors.


X_IO_BUFFERS c
]

4.2.1.3 XDM_SingleBufDesc

║ Description

This structure defines the buffer descriptor for single input and output
buffers.
║ Fields

Field Datatype Input/ Description


Output

*buf XDAS_Int8 Input Pointer to the buffer

BufSize XDAS_Int32 Input Size of the buffer in bytes

4.2.1.4 XDM1_SingleBufDesc

║ Description

4-18
API Reference

This structure defines the buffer descriptor for single input and output
buffers.
║ Fields

Field Datatype Input/ Description


Output

*buf XDAS_Int8 Input Pointer to the buffer

bufSize XDAS_Int32 Input Size of the buffer in bytes

accessMask XDAS_Int32 Output If the buffer was not accessed by the algorithm
processor (For example, it was filled by DMA or other
hardware accelerator that does not write through the
algorithm CPU), then no bits in this mask should be
set.

4.2.1.5 XDM_AlgBufInfo

║ Description

This structure defines the buffer information descriptor for input and output
buffers. This structure is filled when you invoke the control() function
with the XDM_GETBUFINFO command.
║ Fields

Field Data type Input/ Description


Output

minNumInBufs XDAS_Int32 Output Number of input buffers

minNumOutBufs XDAS_Int32 Output Number of output buffers

minInBufSize[XDM_ XDAS_Int32 Output Size in bytes required for each input buffer
MAX_IO_BUFFERS]

minOutBufSize[XDM XDAS_Int32 Output Size in bytes required for each output buffer
_MAX_IO_BUFFERS]

4-19
API Reference

Note:

For H.264 High Profile Decoder, the buffer details are:


 Number of input buffer required is 1.
 Number of output buffer required is 3 for YUV420P.
 There is no restriction on input buffer size except that it should
contain atleast one frame of encoded data.
 The output buffer sizes (in bytes) for worst case 625SD format are:
 For YUV 420P:
Y buffer = 720 * 576
U buffer = 360 * 288
V buffer = 360 * 288

These are the maximum buffer sizes but you can reconfigure
depending on the format of the bit-stream.

4.2.1.6 IVIDEO1_BufDesc

║ Description

This structure defines the buffer descriptor for input and output buffers.
║ Fields

Field Datatype Input/ Description


Output

NumBufs XDAS_Int32 Input Number of buffers

FrameWidth XDAS_Int32 Input Width of the video frame

FrameHeight XDAS_Int32 Input Height of the video frame

FramePitch XDAS_Int32 Input Frame pitch used to store the frame

bufDesc[IVIDEO_MAX_YUV_BUFF XDM1_Singl Input Pointer to the vector containing


ERS] eBufDesc buffer addresses

ExtendedError XDAS_Int32 Input Extended Error Field

FrameType XDAS_Int32 Input Video frame types. See


IVIDEO_FrameType enumeration
for details.

TopFieldFirstFlag XDAS_Int32 Input Flag to indicate when the application


Should display the top field first

RepeatFirstFieldFlag XDAS_Int32 Input Flag to indicate when the first field

4-20
API Reference

Field Datatype Input/ Description


Output

Should be repeated

FrameStatus XDAS_Int32 Input Video output buffer status. See


IVIDEO_OutputFrameStatus
enumeration for details.

RepeatFrame XDAS_Int32 Input Number of times the display process


needs to repeat the displayed
progressive frame

ContentType XDAS_Int32 Input Content type of the buffer. See


IVIDEO_ContentType
enumeration for details.

ChromaFormat XDAS_Int32 Input Chroma formats. See


XDM_ChromaFormat and
eChromaFormat_t for details.

Note:
IVIDEO_MAX_YUV_BUFFERS:

 Max YUV buffers - one each for Y, U, and V.


 repeatFirstFieldFlag and repeatFrame are not supported and
their default value is 0.

4.2.1.7 IVIDDEC2_Fxns

║ Description

This structure contains pointers to all the XDAIS and XDM interface
functions.
║ Fields

Field Datatype Input/ Description


Output

Ialg IALG_Fxns Input Structure containing pointers to all the XDAIS


interface functions.

For more details, see TMS320 DSP Algorithm


Standard API Reference (literature number
SPRU360).

*process XDAS_Int3 Input Pointer to the process() function


2

*control XDAS_Int3 Input Pointer to the control() function


2

4-21
API Reference

4.2.1.8 IVIDDEC2_Params

║ Description

This structure defines the creation parameters for an algorithm instance


object. Set this data structure to NULL, if you are not sure of the values to
be specified for these parameters.

║ Fields

Field Datatype Input/ Description


Output

Size XDAS_Int32 Input Size of the basic or extended (if being used)
data structure in bytes.

MaxHeight XDAS_Int32 Input Maximum video height to be supported in pixels


Default is 1088

MaxWidth XDAS_Int32 Input Maximum video width to be supported in pixels


Default is 1920

maxFrameRate XDAS_Int32 Input Maximum frame rate in fps * 1000 to be


supported. Default is 30000

MaxBitRate XDAS_Int32 Input Maximum bit rate to be supported in bits per


second. For example, if bit rate is 10 Mbps, set
this field to 10485760. Default is 10000000.

dataEndianness XDAS_Int32 Input Endianness of input data. See


XDM_DataFormat enumeration for details.
Default is XDM_BYTE

ForceChromaForma XDAS_Int32 Input Sets the output to the specified format. Only 420
t semi-planar format supported currently. Set
forceChromaFormat to XDM_YUV_420SP.

See XDM_ChromaFormat and


eChromaFormat_t enumerations for details.

Note:
 H.264 Decoder does not use the maxFrameRate and maxBitRate fields for
creating the algorithm instance. In the current implementation,
maxFrameRate is set to 1000 * 30, and maxBitRate is set to 10000000.

 Maximum video height and width supported are 576 pixels and 720 pixels
respectively.
 dataEndianness field should be set to XDM_BYTE.

4-22
API Reference

4.2.1.9 IVIDDEC2_DynamicParams

║ Description

This structure defines the run-time parameters for an algorithm instance


object. Set this data structure to NULL, if you are not sure of the values to
be specified for these parameters.
║ Fields

Field Datatype Input/ Description


Output

size XDAS_Int3 Input Size of the basic or extended (if being used) data
2 structure in bytes.

decodeHeader XDAS_Int3 Input Number of access units to decode:


2  0 (XDM_DECODE_AU) - Decode entire frame
including all the headers
 1 (XDM_PARSE_HEADER) - Decode only one
NAL unit (Not Supported)

displayWidth XDAS_Int3 Input If the field is set to:


2  0 - Uses decoded image width as pitch
 If any other value greater than the decoded image
width is given, then this value in pixels is used as
pitch.

frameSkipMode XDAS_Int3 Input Frame skip mode. See IVIDEO_FrameSkip


2 enumeration for details.

frameOrder XDAS_Int3 Input Frame Display Order. See IVIDDEC2_FrameOrder


2 enumeration for details.

newFrameFlag XDAS_Int3 Input Flag to indicate that the algorithm should start a new
2 frame. Valid values are XDAS_TRUE and
XDAS_FALSE. This is useful for error recovery, for
example, when the end of frame cannot be detected
by the codec but is known to the application.

mbDataFlag XDAS_Int3 Input Flag to indicate that the algorithm should generate MB
2 Data in addition to decoding the data.

Note:
 H264 Decoder does not support decodeHeader field. It is set to
the default value as zero.
 H.264 Decoder does not use displayWidth field. It is set to the
default value as zero.
 frameOrder is a set to the enum value of
IVIDDEC2_DISPLAY_ORDER.

 Frame skip is not supported. Set the frameSkipMode field to

4-23
API Reference

IVIDEO_NO_SKIP.
 H264 Decoder does not support newFrameFlag and mbDataFlag
in this version. Their values are set as zero.

4.2.1.10 IVIDDEC2_InArgs

║ Description

This structure defines the run-time input arguments for an algorithm


instance object.
║ Fields

Field Datatype Input/ Description


Output

Size XDAS_Int32 Input Size of the basic or extended (if being used) data
structure in bytes.

numBytes XDAS_Int32 Input Size of input data (in bytes) provided to the algorithm for
decoding

inputID XDAS_Int32 Input Application passes this ID to algorithm and decoder will
attach this ID to the corresponding output frames. This is
useful in case of re-ordering (for example, B frames). If
there is no re-ordering, outputID field in the
IVIDDEC2_OutArgs data structure will be same as
inputID field.

Note:

H264 Decoder copies the inputID value to the outputID value of


IVIDDEC2_OutArgs structure after factoring in the display delay.

4.2.1.11 IVIDDEC2_Status

║ Description

This structure defines parameters that describe the status of an algorithm


instance object.
║ Fields

Field Datatype Input/ Description


Output

size XDAS_Int32 Input Size of the basic or extended (if


being used) data structure in bytes.

4-24
API Reference

Field Datatype Input/ Description


Output

extendedError XDAS_Int32 Output Extended error code. See


XDM_ErrorBit enumeration for
details. Error! Reference source
not found. lists all the codec
specific codes generated by H264
Decoder. These are populated in the
8 LSBs of this field. If concealment
is applied the decoder sets the
XDM_APPLIEDCONCEALMENT bit-
field.

Data XDM_SingleBufDesc Output Buffer information structure for


information passing buffer.

maxNumDisplayBufs XDAS_Int32 Output The maximum number of buffers


required by the codec.

outputHeight XDAS_Int32 Output Output height in pixels

outputWidth XDAS_Int32 Output Output width in pixels

frameRate XDAS_Int32 Output This value will be derived from VUI


parameters as,
frameRate = time_scale / (2 *
num_units_in_ticks).
In case the VUI parameters are
absent, the frameRate will be
reported as -1, which should be
inferred as ‘not available’.

bitRate XDAS_Int32 Output Average bit-rate in bits per second

contentType XDAS_Int32 Output Video content. See


IVIDEO_ContentType
enumeration for details.

outputChromaFormat XDAS_Int32 Output Output chroma format. See


XDM_ChromaFormat and
eChromaFormat_t enumeration
for details.

bufInfo XDM_AlgBufInfo Output Input and output buffer information.


See XDM_AlgBufInfo data
structure for details.

4.2.1.12 IVIDDEC2_OutArgs

║ Description

This structure defines the run-time output arguments for an algorithm


instance object.
║ Fields

4-25
API Reference

Field Datatype Input/ Description


Output

size XDAS_Int3 Input Size of the basic or extended (if being used) data
2 structure in bytes.

bytesConsumed XDAS_Int3 Output Bytes consumed per decode call


2

outputID[XDM_MA XDAS_Int3 Output Output ID corresponding to displayBufs


X_IO_BUFFERS] 2 A value of zero (0) indicates an invalid ID. The first
zero entry in array will indicate end of valid
outputIDs within the array. Hence, the application
can stop reading the array when it encounters the
first zero entry.

decodedBufs IVIDEO1_B Output The decoder fills this structure with buffer pointers to
ufDesc the decoded frame. Related information fields for the
decoded frame are also populated.
When frame decoding is not complete, as indicated
by outBufsInUseFlag, the frame data in this
structure will be incomplete. However, the algorithm
will provide incomplete decoded frame data in case
application may choose to use it for error recovery
purposes.

displayBufs[XDM IVIDEO1_B Output Array containing display frames corresponding to


_MAX_IO_BUFFERS ufDesc valid ID entries in the outputID array.
]

outputMbDataID XDAS_Int3 Output Output ID corresponding with the MB Data


2

mbDataBuf XDM1_Sing Output The decoder populates the last buffer among the
leBufDesc buffers supplied within outBufs->bufs[] with the
decoded MB data generated by the Decoder module.

freeBufID[IVIDD XDAS_Int3 Output This is an array of inputIDs corresponding to the


EC2_MAX_IO_BUFF 2 frames that have been unlocked in the current
ERS] process call.

outBufsInUseFla XDAS_Int3 Output Flag to indicate that the outBufs provided with the
g 2 process() call are in use. No outBufs are
required to be supplied with the next process()
call.

Note:
 OutputMbDataID and mbDataBuf ID are not used in this version
of the decoder, as dumping of MB data is not supported.
 XDM_MAX_IO_BUFFERS - Maximum number of I/O buffers set to 20.

4.2.2 H.264 Decoder Data Structures


This section includes the following H.264 decoder specific data structures:

4-26
API Reference

 IH264VDEC_Params

 IH264VDEC_DynamicParams

 IH264VDEC_InArgs

 IH264VDEC_Status

 IH264VDEC_OutArgs

4.2.2.1 IH264VDEC _Params

║ Description

This structure defines the creation parameters and any other


implementation specific parameters for the H.264 Decoder instance object.
The creation parameters are defined in the XDM data structure,
IVIDDEC2_Params.
║ Fields

Field Data type Input/ Description


Output

viddecParams IVIDDEC2_Params Input See IVIDDEC2_Params data structure for


details.

*McViddecPara IVIDMC_t Input See Section 4.2.2.1.1


ms

displayDelay XDAS_Int32 Input Maximum delay between decode and display of


a frame.

inputStreamFo XDAS_Int32 Input Input stream unit format


rmat 0 – ByteStreamFormat
1 – NALUnitStreamFormat

4.2.2.1.1 IVIDMC_t

║ Description

This structure includes the static params provided by the Framework in


Video Codec creation phase.
║ Fields

Field Data type Input/ Description


Output

*swbarr XDAS_Void Input Codec generates call out and sends number
(swbarr_cnt) of cores from the team (ncores) that
need to reach the software barrier, before
execution proceeds. It is possible to have multiple
software barriers in the system present

4-27
API Reference

simultaneously. This is why codec needs to


identify barrier with swbarr_id parameter. Core
needs to provide correct value for swbarr_cnt or 0.

*shmmap XDAS_Int32 * Input Dynamically allocate shared memory region


identified with global key (shmem_key). If region
with the same global key (shmem_key) is already
allocated, its base address is provided. Attribute
provided here indicates shared memory region
placement: SL2 , DDR2 cached, or DDR2 un-
cached.

*shmmunmap XDAS_Int32 Input Deallocate shared memory region. It is completely


recycled after all clients do unmap operation.

*shmmap_sync XDAS_Int32 Input Synchronize or flush shared memory region.


Explicit cache coherency operation

*Lock XDAS_Int32 Input Critical region lock acquire.

*UnLock XDAS_Int32 Input Critical region lock release.

ncores XDAS_Int32 Input Number of cores in the team, i.e., cores running
together for processing same stream

core_task_id IVIDMC_TASK_e Input Core task identification

CoreID XDAS_Int32 Input Specifies the current core id.

4.2.2.2 IH264VDEC_DynamicParams

║ Description

This structure defines the run-time parameters and any other


implementation specific parameters for the H.264 Decoder instance object.
The run-time parameters are defined in the XDM data structure,
IVIDDEC2_DynamicParams.
║ Fields

Field Data type Input/ Description


Output

viddecDynamicParam IVIDDEC2_DynamicParam Input See


s s IVIDDEC2_DynamicParams
data structure for details.

4-28
API Reference

4.2.2.3 IH264VDEC_InArgs

║ Description

This structure defines the run-time input arguments for the H.264 Decoder
instance object.
║ Fields

Field Data type Input/ Description


Output

Input See IVIDDEC2_InArgs data


viddecInArgs IVIDDEC2_InArgs
structure for details.

Input Number NAL unit in the Input


numNALunits XDAS_Int32 Buffer

Input Sizes of NAL units in the input


*numBytesInNALarr XDAS_Int32 buffer

4.2.2.4 IH264VDEC_Status

║ Description

This structure defines parameters that describe the status of the H.264
Decoder and any other implementation specific parameters. The status
parameters are defined in the XDM data structure, IVIDDEC2_Status.
║ Fields

Field Data type Input/ Description


Output

viddecStatus IVIDDEC2_Status Output See IVIDDEC2_Status data structure for


details

Profile eH264VDEC_TI_Prof Output Profile of the bit-stream. The H.264 decoder


ile supports only main profile.

Level eH264VDEC_TI_Leve Output Level number of the bit-stream. The H.264


lIdc decoder supports only upto Level 3.

Qp XDAS_Int32 Output Frame quantization parameter

last_decoded_m XDAS_UInt32 Output Raster scan address of the last decoded


b_addr MB.

slice_header_f XDAS_UInt32 Output Frame number present in the slice header.


rame_num

full_frame_dec XDAS_UInt32 Output The flag indicates whether the full frame is
oded decoded without any errors.

4-29
API Reference

Field Data type Input/ Description


Output

poc_num XDAS_UInt32 Output POC number of the current frame.

core_task_ID IVIDMC_TASK_e Output Specifies task of current core (master or


slave)

ncores XDAS_Int32 Output Specifies the number of cores in use

Note:

Following is the decoder behavior for supporting frame size being non-
multiple of 16 through frame cropping:
 The decoder populates the output buffers at a resolution equal to the
size of the cropped image. Also, it returns status parameters for
picture resolution (outputHeight and outputWidth) as equal to
the cropped values.
 If the displayWidth (element in DynamicParams) is lesser than
the cropped image width, then the decoder writes at a width equal to
the display width.

4.2.2.5 IH264VDEC_OutArgs

║ Description

This structure defines the run - time output arguments for the H.264
Decoder instance object.
║ Fields

Field Data type Input/ Description


Output

viddecOutArgs IVIDDEC2_OutArgs Output See IVIDDEC2_OutArgs data structure


for details.

pict_struct ePicStruct_t Output This argument returns enumeration


indicating the decoded picture is frame, top
field, or bottom field. See ePicStruct_t
enumeration for details.

display_frame_ XDAS_Int32 Output This flag, when set to one indicates that the
skip_flag frame returned in this call was skipped and
hence nothing was written into this buffer.

SeiVui_buffer sSeiVuiParams_t Output Instance to hold the SEI, VUI parameters

non_VCL_length XDAS_Int32 Output This variable is set to the number of bytes in


_at_start all non-VCL NALU (such as AUD, SEI, FILL,
SPS, PPS) that precede the first VCL NALU
in an Access Unit (Refer to Appendix C for
details).

4-30
API Reference

Field Data type Input/ Description


Output

disp_top_field XDAS_Int32 Output This flag indicates if the top or bottom field
_first should be displayed first (Refer to Appendix
C for details).

end_of_stream XDAS_Int32 Output This flag is set to TRUE, if the End of


Stream NAL unit is found. Otherwise, this
flag returns FALSE.

numNALdecoded XDAS_Int32 Output This variable indicates number of NAL units


decoded.

4.2.2.5.1 sSeiVuiParams_t

║ Description

This structure defines Supplemental Enhancement Information (SEI )


messages and parameters that describe the values of various Video
Usability parameters(VUI).
║ Fields

Field Data type Input/ Description


Output

Parsed_flag unsigned int Output


 1 - Indicates that in the current process call,
contents of the structure is updated
 0 - Indicates contents of the structure is not
updated

vui_params SVSP_t Output Video Usability Information

sei_messages sSeiMessages_t Output Supplemental Enhancement Information

Note:

A brief description of SEI and VUI contents are given below. For details
see H.264 standard (ISO/IEC 14496-10:2005 (E) Rec.- Information
technology – Coding of audio-visual objects – H.264 (E) ITU-T
Recommendation.)

4.2.2.5.2 sSeiMessages_t

║ Description

Structure containing Supplemental Enhancement Information (SEI)


messages.

4-31
API Reference

║ Fields

Field Data type Input/ Description


Output

parsed_flag unsigned int Output


 1 - Indicates that in the
current process call,
contents of the structure is
updated
 0 - Indicates contents of the
structure is not updated

frame_freeze_rep sFullFrameFreezeRepet Output Specifies the persistence of the


etition ition_t full-frame freeze SEI message
and may specify a picture order
count interval within which
another full-frame freeze SEI
message or a full-frame freeze
release SEI or the end of the
coded video sequence shall be
present in the bit-stream.

frame_freeze_rel sFullFrameFreezeRelea Output Cancels the effect of any full-


ease se_t frame freeze SEI message sent
with pictures that precede the
current picture in output order.

prog_refine_star sProgRefineStart_t Output Specifies the beginning of a set


t of consecutive coded pictures
that is labeled as the current
picture followed by a sequence of
one or more pictures of
refinement of the quality of the
current picture, rather than as a
representation of a continually
moving scene.

prog_refine_end sProgRefineEnd_t Output Specifies end of progressive


refinement.

recovery_pt_info sRecoveryPointInfo_t Output The recovery point SEI message


assists a decoder in determining
when the decoding process will
produce acceptable pictures for
display after the decoder initiates
random access or after the
encoder indicates a broken link in
the sequence.

pic_timing sPictureTiming_t Output Specifies timing information


regarding cpb delays, dpb output
delay and so on.

4-32
API Reference

4.2.2.5.3 sFullFrameFreezeRepetition_t

║ Description

Structure contains information regarding frame freeze.


║ Fields

Field Data type Input/ Description


Output

parsed_flag unsigned int Output


 1 - Indicates that in the current process
call, contents of the structure is updated
 0 - Indicates contents of the structure is
not updated

full_frame_freeze unsigned int Output Specifies the persistence of the full-frame


_ freeze SEI message
repetition_period

4.2.2.5.4 sFullFrameFreezeRelease_t

║ Description

Structure contains information regarding frame freeze.


║ Fields

Field Data type Input/ Description


Output

parsed_flag unsigned int Output


 1 - Indicates that in the current process
call, contents of the structure is updated
 0 - Indicates contents of the structure is
not updated

full_frame_freeze unsigned char Output Cancels the effect of any full-frame freeze
_ SEI message sent with pictures that precede
release_flag the current picture in output order.

4-33
API Reference

4.2.2.5.5 sProgRefineStart_t

║ Description

Structure contains information regarding progressive refinement.


║ Fields

Field Data type Input/ Description


Output

parsed_flag unsigned int Output


 1 - Indicates that in the current
process call, contents of the structure
is updated
 0 - Indicates contents of the structure
is not updated

progressive_refinem unsigned int Output Specifies an identification number for the


ent_id progressive refinement operation.

num_refinement_step unsigned int Output Specifies the number of reference frames


s_minus1 in the tagged set of consecutive coded
pictures

4.2.2.5.6 sProgRefineEnd_t

║ Description

Structure contains information regarding progressive refinement.


║ Fields

Field Data type Input/ Description


Output

parsed_flag unsigned int Output


 1 - Indicates that in the current process
call, contents of the structure is
updated
 0 - Indicates contents of the structure is
not updated

progressive_ unsigned int Output Specifies an identification number for the


refinement_id progressive refinement operation.

4-34
API Reference

4.2.2.5.7 sRecoveryPointInfo_t

║ Description

Structure contains information regarding recovery points.


║ Fields

Field Data type Input/ Description


Output

parsed_flag unsigned int Output


 1 - Indicates that in the current process
call, contents of the structure is updated
 0 - Indicates contents of the structure is
not updated

recovery_frame_cnt unsigned int Output Specifies the recovery point of output


pictures in output order.

exact_match_flag unsigned Output Indicates whether decoded pictures at and


char subsequent to the specified recovery point in
output order
derived by starting the decoding process at
the access unit associated with the recovery
point SEI message shall be an
exact match to the pictures that would be
produced by starting the decoding process
at the location of a previous IDR access unit
in the NAL unit stream.

broken_link_flag unsigned Output Indicates the presence or absence of a


char broken link in the NAL unit stream

changing_slice_gro unsigned Output Indicates whether decoded pictures are


up_idc char correct or approximately correct in content at
and subsequent to the recovery point in
output order when all macro-blocks of the
primary coded pictures are decoded within
the changing slice group period.

4.2.2.5.8 sPictureTiming_t

║ Description

Structure contains timing information such as DPB delay and CPD delay.
║ Fields

Field Data type Input/ Description


Output

parsed_flag unsigned int Output


 1 - Indicates that in the current
process call, contents of the structure
is updated

4-35
API Reference

Field Data type Input/ Description


Output

 0 - Indicates contents of the structure


is not updated

cpb_removal_delay unsigned int Output Specifies how many clock ticks to wait
after removal from the CPB of the access
unit associated with the most recent
buffering period SEI message before
removing from the buffer the access unit
data associated with the picture timing SEI
message.

dpb_output_delay unsigned int Output Used to compute the DPB output time of
the picture.

pic_struct unsigned int Output Indicates whether a picture should be


displayed as a frame or field

clock_timestamp_fl unsigned int Output


 1 - Indicates number of clock
ag
timestamp syntax elements present
and follow immediately
 0 – Indicates associated clock
timestamp syntax elements not
present

ct_type unsigned int Output Indicates the scan type(interlaced or


progressive) of the source material

nuit_field_based_f unsigned int Output Used to calculate the clockTimestamp


lag

counting_type unsigned int Output Specifies the method of dropping values


of n_frames

full_timestamp_fla unsigned int Output


 1 - Specifies that the n_frames
g
syntax element is followed by
seconds_value,
minutes_value, and
hours_value.
 0 - Specifies that the n_frames
syntax element is followed by
seconds_flag

discontinuity_flag unsigned int Output Indicates whether the difference between


the current value of clockTimestamp
and the value of clockTimestamp
computed from the previous
clockTimestamp in output order can
be interpreted as the time difference
between the times of origin or capture of
the associated frames or fields.

cnt_dropped_flag unsigned int Output Specifies the skipping of one or more

4-36
API Reference

Field Data type Input/ Description


Output

values of n_frames using the counting


method

n_frames unsigned int Output Specifies the value of nFrames used to


compute clockTimestamp.

seconds_value unsigned int Output Specifies the value of sS used to compute


clockTimestamp.

minutes_value unsigned int Output Specifies the value of mM used to compute


clockTimestamp.

hours_value unsigned int Output Specifies the value of hH used to


compute clockTimestamp.

time_offset unsigned int Output Specifies the value of tOffset used to


compute clockTimestamp

4.2.2.5.9 sVSP_t

║ Description

This structure defines parameters that describe the values of various video
usability parameters that come as a part of Sequence Parameter Set in the
bit-stream.
║ Fields

Field Data type Input/ Description


Output

parsed_flag unsigned Output


 1 - Indicates that in the current process
int
call, contents of the structure is updated
 0 - Indicates contents of the structure is
not updated

aspect_ratio_info_p unsigned int Output Indicates whether aspect ratio idc is present
resent_flag or not.

aspect_ratio_idc unsigned int Output Aspect ratio of Luma samples

sar_width unsigned int Output Horizontal size of sample aspect ratio

sar_height unsigned int Output Vertical size of sample aspect ratio

overscan_info_prese unsigned int Output Overscan_appropriate_flag


nt_flag

overscan_appropriat unsigned int Output Cropped decoded pictures are suitable for
e_flag display or not.

4-37
API Reference

Field Data type Input/ Description


Output

video_signal_type_p unsigned int Output This flag tells whether video_format,


resent_flag video_full_range_flag and
colour_description_present_flag
are present or not

video_format unsigned int Output Video format indexed by a table. For


example, PAL/NTSC

video_full_range_fl unsigned int Output Black level, luma and chroma ranges. It
ag should be used for BT.601 compliance

colour_description_ unsigned int Output Indicates whether colour_primaries,


present_flag transfer_characteristics and
matrix_coefficients are present.

colour_primaries unsigned int Output Chromaticity co-ordinates of source


primaries

transfer_characteri unsigned int Output Opto-electronic transfer characteristics of


stics the source picture

matrix_coefficients unsigned int Output Matrix coefficients for deriving Luma and
chroma data from RGB components.

chroma_location_inf unsigned int Output This flag tells whether


o_present_flag chroma_sample_loc_type_top
field and chroma_sample_loctype
bottom_field are present.

chroma_sample_loc_t unsigned int Output Location of chroma_sample top field


ype_top_field

chroma_sample_loc_t unsigned int Output Location of chroma_sample bottom field


ype_bottom_field

timing_info_present unsigned int Output It indicates whether


_flag num_units_in_tick, time_scale,
and fixed_frame_rate_flag are
present.

num_units_in_tick unsigned int Output number of units of a clock that corresponds


to 1 increment of a clock tick counter

time_scale unsigned int Output Indicates actual increase in time for 1


increment of a clock tick counter

fixed_frame_rate_fl unsigned int Output It tells how the temporal distance between
ag HRD output times of any two output pictures
is constrained

nal_hrd_parameters_ unsigned int Output Indicates whether nal_hrd_parameters


present_flag are present

4-38
API Reference

Field Data type Input/ Description


Output

nal_hrd_parameters sHrdParm_t Output See sHrdParm_t datastructure for


details.

vcl_hrd_parameters_ unsigned int Output Indicates whether vcl_hrd_parameters


present_flag are present

vcl_hrd_parameters sHrdParm_t Output See sHrdParm_t datastructure for


details.

low_delay_hrd_flag unsigned int Output HRD operational mode as in Annex C of the


standard

pic_struct_present_ unsigned int Output Indicates whether picture timing SEI


flag messages are present

bitstream_restricti unsigned int Output Indicates if the bit-stream restriction


on_flag parameters are present

motion_vectors_over unsigned int Output Specifies whether motion vectors can point
_pic_boundaries_fla to regions outside the picture boundaries
g

max_bytes_per_pic_d unsigned int Output Maximum number of bytes not exceeded by


enom the sum of sizes of all VCL NAL units of a
single coded picture

max_bits_per_mb_den unsigned int Output Maximum number of bits taken by any


om coded MB

log2_max_mv_length_ unsigned int Output Maximum value of any motion vector’s


vertical vertical component

log2_max_mv_length_ unsigned int Output Maximum value of any motion vector’s


horizontal horizontal component

num_reorder_frames unsigned int Output Maximum number of frames that need to be


re-ordered

max_dec_frame_buffe unsigned int Output Size of HRD decoded buffer (DPB) in terms
ring of frame buffers

4.2.2.5.10 sHrdParm_t

║ Description

This structure defines the HRD parameters that come in a H264 bit-stream
as a part of video usability Information.
║ Fields

4-39
API Reference

Field Data type Input/ Description


Output

cpb_cnt unsigned int Output Number of alternative CPB specifications in


the bitstream

bit_rate_scale unsigned int Output Together with bit_rate_value[i], it


th
specifies the maximum input bitrate for the i
CPB.

cpb_size_scale unsigned int Output Together with cpb_size_value[i],


th
specifies the maximum CPB size for the i
CPB.
th
bit_rate_value[i] unsigned int Output Maximum input bitrate for the i CPB

th
cpb_size_value[i] unsigned int Output Maximum CPB size for the i CPB

th
vbr_cbr_flag[i] unsigned int Output Specifies the i CPB is operated in Constant
Bit-rate mode or variable bit-rate mode

initial_cpb_removal unsigned int Output Length in bits of


_delay_length_minus initial_cpb_removal_length syntax
1 element

cpb_removal_delay_l unsigned int Output Length in bits of


ength_minus1 cpb_removal_delay_length syntax
element

dpb_output_delay_le unsigned int Output Length in bits of


ngth_minus1 dpb_output_delay_length syntax
element

time_offset_length unsigned int Output Length in bits of time_offset syntax


element

Note:

SEI / VUI parsing is handled by the decoder as follows:

A flag “parsed_flag” is present as the first element of structure of


every SEI message, VUI structure and the SEI_VUI structure. This flag
when set to one by the decoder indicates that in the current process call,
contents of this structure was updated.

Currently parsing of the following SEI messages are supported.


 Full-frame freeze SEI message
 Full-frame freeze release
 Progressive refinement segment start
 Progressive refinement segment end
 Recovery point SEI message

4-40
API Reference

 Picture timing SEI message

Other types of SEI messages will be simply skipped by the decoder.

4-41
API Reference

4.3 Interface Functions


This section describes the application programming interfaces used in the
H264 Decoder. The H264 Decoder APIs are logically grouped into the
following categories:

 Creation – algNumAlloc(), algAlloc()

 Initialization – algInit()

 Control – control()

 Data processing – algActivate(), process(), algDeactivate()

 Termination – algFree()

 Multi-core – *swbarr(), **shmmap(), *shmunmap(), *shmmap_sync()

You must call these APIs in the following sequence:


1) algNumAlloc()
2) algAlloc()
3) algInit()
4) algActivate()
5) process()
6) algDeactivate()
7) algFree()

control() can be called any time after calling the algInit() API.

4-42
API Reference

4.3.1 Creation APIs


Creation APIs are used to create an instance of the component. The term
creation could mean allocating system resources, typically memory.
║ Name

algNumAlloc() – determine the number of buffers that an algorithm


requires
║ Synopsis

XDAS_Int32 algNumAlloc(Void);
║ Arguments

Void
║ Return Value

XDAS_Int32; /* number of buffers required */


║ Description

algNumAlloc() returns the number of buffers that the algAlloc()


method requires. This operation allows you to allocate sufficient space to
call the algAlloc() method.

algNumAlloc() may be called at any time and can be called repeatedly


without any side effects. It always returns the same result. The
algNumAlloc() API is optional.

For more details, see TMS320 DSP Algorithm Standard API Reference.
║ See Also
algAlloc()

4-43
API Reference

║ Name

algAlloc() – determine the attributes of all buffers that an algorithm


requires
║ Synopsis

XDAS_Int32 algAlloc(const IALG_Params *params, IALG_Fxns


**parentFxns, IALG_MemRec memTab[]);
║ Arguments

IALG_Params *params; /* algorithm specific attributes */

IALG_Fxns **parentFxns;/* output parent algorithm


functions */

IALG_MemRec memTab[]; /* output array of memory records */


║ Return Value

XDAS_Int32 /* number of buffers required */


║ Description

algAlloc() returns a table of memory records that describe the size,


alignment, type, and memory space of all buffers required by an algorithm.
If successful, this function returns a positive non-zero value indicating the
number of records initialized.

The first argument to algAlloc() is a pointer to a structure that defines


the creation parameters. This pointer may be NULL; however, in this case,
algAlloc(), must assume default creation parameters and must not fail.

The second argument to algAlloc() is an output parameter.


algAlloc() may return a pointer to its parent’s IALG functions. Since the
client does not require a parent object to be created, this pointer must be
set to NULL.

The third argument is a pointer to a memory space of size


nbufs * sizeof(IALG_MemRec) where, nbufs is the number of buffers
returned by algNumAlloc() and IALG_MemRec is the buffer-descriptor
structure defined in ialg.h.

After calling this function, memTab[] is filled up with the memory


requirements of an algorithm.

For more details, see TMS320 DSP Algorithm Standard API Reference.
║ See Also
algNumAlloc(), algFree()

4-44
API Reference

4.3.2 Initialization API


Initialization API is used to initialize an instance of the H264 Decoder. The
initialization parameters are defined in the IVIDDEC2_Params structure
(see Data Structures section for details).
║ Name

algInit() – initialize an algorithm instance


║ Synopsis

XDAS_Int32 algInit(IALG_Handle handle, IALG_MemRec


memTab[], IALG_Handle parent, IALG_Params *params);
║ Arguments

IALG_Handle handle; /* handle to the algorithm instance*/

IALG_memRec memTab[]; /* array of allocated buffers */

IALG_Handle parent; /* handle to the parent instance */

IALG_Params *params; /* algorithm initialization


parameters */
║ Return Value
IALG_EOK; /* status indicating success */

IALG_EFAIL; /* status indicating failure */


║ Description

algInit() performs all initialization necessary to complete the run-time


creation of an algorithm instance object. After a successful return from
algInit(), the instance object is ready to be used to process data.

The first argument to algInit() is a handle to an algorithm instance. This


value is initialized to the base field of memTab[0].

The second argument is a table of memory records that describe the base
address, size, alignment, type, and memory space of all buffers allocated
for an algorithm instance. The number of initialized records is identical to
the number returned by a prior call to algAlloc().

The third argument is a handle to the parent instance object. If there is no


parent object, this parameter must be set to NULL.

The last argument is a pointer to a structure that defines the algorithm


initialization parameters. All fields in the params structure must be set as
described in IALG_Params structure (see Data Structures section for
details).

For more details, see TMS320 DSP Algorithm Standard API Reference.
║ See Also
algAlloc(), algMoved()

4-45
API Reference

4.3.3 Control API


Control API is used for controlling the functioning of H264 Decoder during
run-time. This is done by changing the status of the controllable
parameters of the decoder during run-time. These controllable parameters
are defined in the IVIDDEC2_DynamicParams data structure (see Data
Structures section for details).
║ Name

control() – change run-time parameters of the H264 Decoder and


query the decoder status
║ Synopsis

XDAS_Int32 (*control)(IVIDDEC2_Handle handle, IVIDDEC2_Cmd


id,IVIDDEC2_DynamicParams *params, IVIDDEC2_Status
*status);
║ Arguments

IVIDDEC2_Handle handle; /* handle to the H264 decoder


instance */

IVIDDEC2_Cmd id; /* H264 decoder specific control


commands*/

IVIDDEC2_DynamicParams *params /* H264 decoder run-time


parameters */

IVIDDEC2_Status *status /* H264 decoder instance status


parameters */
║ Return Value
IALG_EOK; /* status indicating success */

IALG_EFAIL; /* status indicating failure */


║ Description

This function changes the run-time parameters of H264 Decoder and


queries the status of decoder. control() must only be called after a
successful call to algInit() and must never be called after a call to
algFree().

The first argument to control() is a handle to the H264 Decoder instance


object.

The second argument is a command ID. See IVIDDEC2_Cmd in


enumeration table for details.

The third and fourth arguments are pointers to the


IVIDDEC2_DynamicParams and IVIDDEC2_Status data structures
respectively.
║ See Also
algInit()

4-46
API Reference

4.3.4 Data Processing API


Data processing API is used for processing the input data using the H264
Decoder.
║ Name

algActivate()– initialize scratch memory buffers prior to processing.


║ Synopsis

Void algActivate(IALG_Handle handle);


║ Arguments

IALG_Handle handle; /* algorithm instance handle */


║ Return Value
Void
║ Description

algActivate() initializes any of the instance’s scratch buffers using the


persistent memory that is part of the algorithm’s instance object.

The first (and only) argument to algActivate() is an algorithm instance


handle. This handle is used by the algorithm to identify various buffers that
must be initialized prior to calling any of the algorithm’s processing
methods.

For more details, see TMS320 DSP Algorithm Standard API Reference.
(literature number SPRU360).
║ See Also
algDeactivate()

4-47
API Reference

║ Name

process() – basic video decoding call


║ Synopsis

XDAS_Int32 (*process)(IVIDDEC2_Handle handle, XDM1_BufDesc


*inBufs, XDM_BufDesc *outBufs, IVIDDEC2_InArgs *inargs,
IVIDDEC2_OutArgs *outargs);
║ Arguments

IVIDDEC2_Handle handle; /* handle to the H264 decoder


instance */

XDM1_BufDesc *inBufs; /* pointer to input buffer


descriptor data structure */

XDM_BufDesc *outBufs; /* pointer to output buffer


descriptor data structure */

IVIDDEC2_InArgs *inargs /* pointer to the H264 decoder


runtime input arguments data structure */

IVIDDEC2_OutArgs *outargs /* pointer to the H264 decoder


runtime output arguments data structure */
║ Return Value
IALG_EOK; /* status indicating success */

IALG_EFAIL; /* status indicating failure */


║ Description

This function does the basic H264 video decoding. The first argument to
process() is a handle to the H264 Decoder instance object.

The second and third arguments are pointers to the input and output buffer
descriptor data structures respectively (see XDM1_BufDesc and
XDM_BufDesc data structure for details).

The fourth argument is a pointer to the IVIDDEC2_InArgs data structure


that defines the run-time input arguments for the H264 Decoder instance
object.

Note:
Prior to each decode call, ensure that all fields are set as described
in XDM1_BufDesc, XDM_BufDesc, and IVIDDEC2_InArgs structures.

The last argument is a pointer to the IVIDDEC2_OutArgs data structure


that defines the run-time output arguments for the H264 Decoder instance
object.

The algorithm may also modify the output buffer pointers. The return value
is IALG_EOK for success or IALG_EFAIL in case of failure. The
extendedError field of the IVIDDEC2_Status structure contains error
conditions flagged by the algorithm. This structure can be populated by a
calling Control API using XDM_GETSTATUS command.

4-48
API Reference

║ See Also
control()

║ Name

algDeactivate()– save all persistent data to non-scratch memory


║ Synopsis

Void algDeactivate(IALG_Handle handle);


║ Arguments

IALG_Handle handle; /* algorithm instance handle */


║ Return Value
Void
║ Description

algDeactivate() saves any persistent information to non-scratch buffers


using the persistent memory that is part of the algorithm’s instance object.

The first (and only) argument to algDeactivate() is an algorithm


instance handle. This handle is used by the algorithm to identify various
buffers that must be saved prior to next cycle of algActivate() and
processing.

For more details, see TMS320 DSP Algorithm Standard API Reference.
║ See Also
algActivate()

4.3.5 Termination API


Termination API is used to terminate the H264 Decoder and free up the
memory space that it uses.

║ Name

algFree() – determine the addresses of all memory buffers used by the


algorithm
║ Synopsis

XDAS_Int32 algFree(IALG_Handle handle, IALG_MemRec


memTab[]);
║ Arguments

IALG_Handle handle; /* handle to the algorithm instance */

IALG_MemRec memTab[]; /* output array of memory records */


║ Return Value
XDAS_Int32; /* Number of buffers used by the algorithm */
║ Description

algFree() determines the addresses of all memory buffers used by the


algorithm. The primary aim of doing so is to free up these memory regions
after closing an instance of the algorithm.

4-49
API Reference

The first argument to algFree() is a handle to the algorithm instance.

The second argument is a table of memory records that describe the base
address, size, alignment, type, and memory space of all buffers previously
allocated for the algorithm instance.

For more details, see TMS320 DSP Algorithm Standard API Reference
(literature number SPRU360).
║ See Also
algAlloc()

4.3.6 Multi-core API


These APIs are implemented by the Framework to facilitate multi-core
implementation.

║ Name

*swbarr() – call out to core that need to reach the software barrier
║ Synopsis

XDAS_Void (*swbarr) (XDAS_Int32 coreID, IVIDMC_SWBARR


swbarr_id, XDAS_UInt32 swbarr_cnt);
║ Arguments

XDAS_Int32 coreID;

IVIDMC_SWBARR swbarr_id;

XDAS_UInt32 swbarr_cnt;
║ Return Value
XDAS_Void
║ Description

Codec generates call out and sends number (swbarr_count) of cores from
the team (ncores) that need to reach the software barrier, before execution
proceeds. It is possible to have multiple software barriers in the system
present simultaneously. This is why codec needs to identify barrier with
swbarr_id parameter. Core needs to provide correct value for swbarr_cnt
or 0.
║ See Also
**shmmap(), *shmunmap()

║ Name

**shmmap() – dynamically allocate shared memory region


║ Synopsis

XDAS_Int32 *(*shmmap) (XDAS_Int32 coreID, IVIDMC_SHMEMKEY


shmem_key, XDAS_Int32 shmem_size, IVIDMC_SHMEM_ATTRS attr,
XDAS_Int32 alignment);
║ Arguments

4-50
API Reference

XDAS_Int32 coreID;

IVIDMC_SHMEMKEY shmem_key;

XDAS_Int32 shmem_size;

IVIDMC_SHMEM_ATTRS attr;

XDAS_Int32 alignment;
║ Return Value
XDAS_Int32 *
║ Description

Dynamically allocate shared memory region identified with global key


(shmem_key). If region with the same global key (shmem_key) is already
allocated, its base address is provided. Attribute provided here indicates
shared memory region placement: SL2, DDR2 cached, or DDR2 un-
cached. The alignment variable is to indicate specific alignment
requirements for the buffer if required.
║ See Also
*shmunmap(), *swbarr(), *shmmap_sync()

║ Name

*shmunmap() – deallocate shared memory region


║ Synopsis

XDAS_Int32 (*shmunmap) (XDAS_Int32 coreID,


IVIDMC_SHMEMKEY shmem_key, XDAS_Int32 *shmem_base);
║ Arguments

XDAS_Int32 coreID;

IVIDMC_SHMEMKEY shmem_key;

XDAS_Int32 *shmem_base;
║ Return Value
XDAS_Int32
║ Description

Deallocate shared memory region allocated using **shmmap() call.


║ See Also
*shmmap(), *swbarr()

4-51
API Reference

║ Name

*shmmap_sync() – Synchronize/flush shared memory region.

║ Synopsis

XDAS_Int32 (*shmmap_sync)(XDAS_Int32 coreID,


IVIDMC_SHMEMKEY shmem_key, XDAS_Int32 *shmem_base);
║ Arguments

XDAS_Int32 coreID;

IVIDMC_SHMEMKEY shmem_key;

XDAS_Int32 *shmem_base;

║ Return Value
XDAS_Int32
║ Description

Synchronize/flush shared memory region - explicit cache coherency


operation.
║ See Also
*shmmap(), *swbarr()

4-50