H.264 High Profile Encoder on TMS320C6678 Platform Users Guide

Literature Number: SPRUHL4 December 2012

IMPORTANT NOTICE Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, enhancements, improvements and other changes to its semiconductor products and services per JESD46, latest issue, and to discontinue any product or service per JESD48, latest issue. Buyers should obtain the latest relevant information before placing orders and should verify that such information is current and complete. All semiconductor products (also referred to herein as components) are sold subject to TIs terms and conditions of sale supplied at the time of order acknowledgment.

TI warrants performance of its components to the specifications applicable at the time of sale, in accordance with the warranty in TIs terms and conditions of sale of semiconductor products. Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty. Except where mandated by applicable law, testing of all parameters of each component is not necessarily performed.

TI assumes no liability for applications assistance or the design of Buyers products. Buyers are responsible for their products and applications using TI components. To minimize the risks associated with Buyers products and applications, Buyers should provide adequate design and operating safeguards.

TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right relating to any combination, machine, or process in which TI components or services are used. Information published by TI regarding third-party products or services does not constitute a license 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 significant portions 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. TI is not responsible or liable for such altered documentation. Information of third parties may be subject to additional restrictions.

Resale of TI components or services with statements different from or beyond the parameters stated by TI for that component or service voids all express and any implied warranties for the associated TI component or service and is an unfair and deceptive business practice. TI is not responsible or liable for any such statements.

Buyer acknowledges and agrees that it is solely responsible for compliance with all legal, regulatory and safety-related requirements concerning its products, and any use of TI components in its applications, notwithstanding any applications-related information or support that may be provided by TI. Buyer represents and agrees that it has all the necessary expertise to create and implement safeguards which anticipate dangerous consequences of failures, monitor failures and their consequences, lessen the likelihood of failures that might cause harm and take appropriate remedial actions. Buyer will fully indemnify TI and its representatives against any damages arising out of the use of any TI components in safety-critical applications.

In some cases, TI components may be promoted specifically to facilitate safety-related applications. With such components, TIs goal is to help enable customers to design and create their own end-product solutions that meet applicable functional safety standards and requirements. Nonetheless, such components are subject to these terms.

No TI components are authorized for use in FDA Class III (or similar life-critical medical equipment) unless authorized officers of the parties have executed a special agreement specifically governing such use.

Only those TI components which TI has specifically designated as military grade or enhanced plastic are designed and intended for use in military/aerospace applications or environments. Buyer acknowledges and agrees that any military or aerospace use of TI components which have not been so designated is solely at the Buyer's risk, and that Buyer is solely responsible for compliance with all legal and regulatory requirements in connection with such use.

TI has specifically designated certain components as meeting ISO/TS16949 requirements, mainly for automotive use. In any case of use of non-designated products, TI will not be responsible for any failure to meet ISO/TS16949.

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

Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265 Copyright 2012, Texas Instruments Incorporated

http://www.ti.com/audiohttp://www.ti.com/automotivehttp://amplifier.ti.com/http://www.ti.com/communicationshttp://dataconverter.ti.com/http://www.ti.com/computershttp://www.dlp.com/http://www.ti.com/consumer-appshttp://dsp.ti.com/http://www.ti.com/energyappshttp://www.ti.com/clockshttp://www.ti.com/industrialhttp://interface.ti.com/http://www.ti.com/medicalhttp://logic.ti.com/http://www.ti.com/securityhttp://power.ti.com/http://www.ti.com/space-avionics-defensehttp://microcontroller.ti.com/http://www.ti.com/videohttp://www.ti-rfid.com/http://e2e.ti.com/

iii

Preface

Read This First

About This Manual

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

TIs 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 TIs codecs with other software to build a multimedia system based on the TMS320C6678 and Visual C.

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.

Chapter 5 - Frequently Asked Questions, provides answers to few frequently asked questions related to using this encoder.

Appendix A Debug Trace Support, describs the method to use H264 encoder debug and trace mechanism.

Appendix B - Call Back function for NAL Units, describes the Call

back function that provides compressed bit-streams at NAL level.

Read This First

iv

Related Documentation From Texas Instruments

The following documents describe TIs 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 Interface 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 TIs 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.

Using IRES and RMAN Framework Components for C64x+ (literature number SPRAAI5), describes the IRES interface definition and function calling sequence.

eXpressDSP Digital Media (XDM) Standard API Reference (literature number SPRUEC8)

Related Documentation

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

ITU-T Rec. H.264 | ISO/IEC 14496-10 AVC - Draft ITU-T Recommendation and Final Draft International Standard of Joint Video Specification

http://www.ti.com/

Read This First

v

Abbreviations

The following abbreviations are used in this document.

Table 0-1 List of Abbreviations

Abbreviation Description

AIR Adaptive Intra Fresh

API Application Programming Interface

AVC Advanced Video Coding

CAVLC Context Adaptive Variable Length Coding

CIF Common Intermediate Format

COFF Common Object File Format

DMA Direct Memory Access

DMAN3 DMA Manager

DSP Digital Signal Processing

EVM Evaluation Module

GOP Group Of Pictures

IDR Instantaneous Decoding Refresh

IRES Interface for Resources

NAL Network Abstraction Layer

PPS Picture Parameter Set

QCIF Quarter Common Intermediate Format

QP Quantization Parameter

QVGA Quarter Video Graphics Array

RMAN Resource Manager

SPS Sequence Parameter Set

SQCIF Sub Quarter Common Intermediate Format

VGA Video Graphics Array

Read This First

vi

Abbreviation Description

XDAIS eXpressDSP Algorithm Interface Standard

XDM eXpressDSP Digital Media

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 Encoder on TMS320C6678 platform) 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, TMS320C6678, and TMS320C64x+ are trademarks of Texas Instruments.

All trademarks are the property of their respective owners.

vii

Contents

H.264 HIGH PROFILE ENCODER ON TMS320C6678 PLATFORM ................................................................. 1-1

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 ................................................................................................................................. IV ABBREVIATIONS .................................................................................................................................................. V TEXT CONVENTIONS ........................................................................................................................................... VI PRODUCT SUPPORT ............................................................................................................................................ VI TRADEMARKS .................................................................................................................................................... VI

CONTENTS ................................................................................................................................................. VII

FIGURES ...................................................................................................................................................... IX

TABLES ....................................................................................................................................................... XI

INTRODUCTION ........................................................................................................................................ 1-1

1.1 OVERVIEW OF XDAIS, XDM, AND IRES .....................................................................................................1-2 1.1.1 XDAIS Overview ........................................................................................................................1-2 1.1.2 XDM Overview ..........................................................................................................................1-2 1.1.3 IRES Overview ...........................................................................................................................1-3

1.2 OVERVIEW OF H.264 HIGH PROFILE ENCODER ............................................................................................1-4 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.2.1 Installing the Component RTSC Package ...............................................................................2-2 2.2.2 Installing the Component Compressed archive .....................................................................2-4

2.3 BEFORE BUILDING THE ALGORITHM LIBRARY AND SAMPLE TEST APPLICATION ....................................................2-9 2.3.1 Installing XDAIS tools(XDAIS) ...................................................................................................2-9 2.3.2 Installing XDC Tools ..................................................................................................................2-9 2.3.3 Installing BIOS tools(SYS/BIOS) ..............................................................................................2-10 2.3.4 Installing Framework Component(FC) ....................................................................................2-10 2.3.5 Installing EDMA3 Low-Level Driver(LLD) ................................................................................2-10 2.3.6 Installing Inter Processor Communication (IPC) .....................................................................2-10

2.4 BUILDING THE ALGORITHM LIBRARY .........................................................................................................2-10 2.4.1 Building Algorithm Library on Visual studio ...........................................................................2-10 2.4.2 Building Algorithm Library on Code Composer Studio ...........................................................2-11

2.5 BUILDING SAMPLE TEST APPLICATION.......................................................................................................2-11

viii

2.5.1 Building Sample Test Application on Visual Studio ................................................................2-11 2.5.2 Building the Sample Test Application on Code Composer Studio Compressed archive .......2-12 2.5.3 Building the Sample Test Application on Code Composer Studio - RTSC Package.................2-12

2.6 RUNNING SAMPLE TEST APPLICATION.......................................................................................................2-13 2.6.1 Running the Sample Test Application on Visual Studio ..........................................................2-13 2.6.2 Running the Sample Test Application on Code Composer Studio ...........................................2-14

2.7 CONFIGURATION FILES ...........................................................................................................................2-15 2.7.1 Encoder Configuration File .....................................................................................................2-15

2.8 UNINSTALLING THE COMPONENT .............................................................................................................2-18

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 .................................................................................................................3-5 3.2.1 Input Frame Buffer ...................................................................................................................3-5

API REFERENCE ......................................................................................................................................... 4-1

4.1 SYMBOLIC CONSTANTS AND ENUMERATED DATA TYPES .................................................................................4-2 4.1.1 Common XDM Data types ........................................................................................................4-2 4.1.2 Common Multi-Core Data types .............................................................................................4-24

4.2 DATA STRUCTURES ...............................................................................................................................4-28 4.2.1 Common XDM Data Structures ..............................................................................................4-28 4.2.2 Common Multi-core Data Structures .....................................................................................4-46 4.2.3 H.264 High Profile Encoder Data Structures ..........................................................................4-48

4.3 DEFAULT AND SUPPORTED VALUES OF PARAMETERS ...................................................................................4-64 4.4 INTERFACE FUNCTIONS ..........................................................................................................................4-74

4.4.1 Creation APIs ..........................................................................................................................4-75 4.4.2 Initialization API .....................................................................................................................4-77 4.4.3 Control API .............................................................................................................................4-79 4.4.4 Data Processing API ...............................................................................................................4-80 4.4.5 Termination API ......................................................................................................................4-86

FREQUENTLY ASKED QUESTIONS .............................................................................................................. 5-1

5.1 CODE BUILD AND EXECUTION ....................................................................................................................5-1 5.2 ALGORITHM RELATED ..............................................................................................................................5-1

DEBUG TRACE SUPPORT ........................................................................................................................... 5-1

A.1 DEBUG TRACE DESIGN IN ENCODER .......................................................................................................5-1 A.2 STEPS TO UTILIZE DEBUG TRACE SUPPORT IN H264 HIGH PROFILE ENCODER ..................................................5-1

CALL BACK FUNCTION FOR NAL UNITS ...................................................................................................... B-1

ix

Figures

FIGURE 1-1 XDM INTRODUCTION ...................................................................................................................1-3 FIGURE 1-2 IRES INTERFACE DEFINITION AND FUNCTION CALLING SEQUENCE ..........................................1-4 FIGURE 1-3 WORKING OF H.264 VIDEO ENCODER ........................................................................................1-5 FIGURE 2-1 COMPONENT DIRECTORY STRUCTURE IN CASE OF RTSC PACKAGE RELEASE ........................2-3 FIGURE 2-2 COMPONENT DIRECTORY STRUCTURE IN CASE OF OBJECT RELEASE ......................................2-5 FIGURE 2-3 COMPONENT DIRECTORY STRUCTURE IN CASE OF SOURCE RELEASE .....................................2-7 FIGURE 3-1 TEST APPLICATION SAMPLE IMPLEMENTATION ...........................................................................3-2 FIGURE 5-1 OVERVIEW OF CALLBACK FUNCTION. ......................................................................................... B-1 FIGURE 5-3 OVERVIEW OF COPYING .............................................................................................................. B-2

file:///C:/Users/Sudheesh/Desktop/H264_Encoder_C6678_UserGuide.doc%23_Toc352429110

x

This page is intentionally left blank

xi

Tables

TABLE 0-1 LIST OF ABBREVIATIONS ................................................................................................................... V TABLE 2-1 COMPONENT DIRECTORIES IN CASE OF RTSC PACKAGE RELEASE.............................................2-3 TABLE 2-2 COMPONENT DIRECTORIES IN CASE OF OBJECT RELEASE ..........................................................2-5 TABLE 2-3 COMPONENT DIRECTORIES IN CASE OF SOURCE RELEASE .........................................................2-7 TABLE 4-1 LIST OF ENUMERATED DATA TYPES .............................................................................................4-2 TABLE 4-2 H264 HIGH PROFILE ENCODER SPECIFIC ENUMERATED DATA TYPES .....................................4-11 TABLE 4-3 H264 ENCODER CONSTANTS .....................................................................................................4-21 TABLE 4-4 H.264 ENCODER ERROR STATUSES ..........................................................................................4-21 TABLE 4-5 DEFAULT AND SUPPORTED VALUES FOR IVIDENC2_PARAMS.................................................4-64 TABLE 4-6 DEFAULT AND SUPPORTED VALUES FOR IVIDENC2_DYNAMICPARAMS .................................4-66 TABLE 4-7 DEFAULT AND SUPPORTED VALUES FOR IH264HPVENC_RATECONTROLPARAMS...............4-67 TABLE 4-8 DEFAULT AND SUPPORTED VALUES FOR IH264HPVENC_INTERCODINGPARAMS .................4-68 TABLE 4-9 DEFAULT AND SUPPORTED VALUES FOR IH264HPVENC_INTRACODINGPARAMS .................4-68 TABLE 4-10 DEFAULT AND SUPPORTED VALUES FOR IH264HPVENC_SLICECODINGPARAMS...............4-69 TABLE 4-11 DEFAULT AND SUPPORTED VALUES FOR IH264HPVENC_LOOPFILTERPARAMS ...............4-70 TABLE 4-12 DEFAULT AND SUPPORTED VALUES FOR IH264HPVENC_VUICODINGPARAMS ..................4-70 TABLE 4-13 DEFAULT AND SUPPORTED VALUES FOR IH264HPVENC_PARAMS......................................4-71 TABLE 4-14 DEFAULT AND SUPPORTED VALUES FOR IH264HPVENC_DYNAMICPARAMS .............................................4-73

xii

This page is intentionally left blank

Introduction

1-1

Chapter 1

Introduction

This chapter provides a brief introduction to XDAIS and XDM. It also provides an overview of TIs implementation of the H.264 High Profile Encoder on the TMS320C6678 platform and its supported features.

Topic Page

1.1 Overview of XDAIS, XDM, and IRES 1-2

1.2 Overview of H.264 High Profile Encoder 1-4

1.3 Supported Services and Features 1-6

Introduction

1-2

1.1 Overview of XDAIS, XDM, and IRES

TIs multimedia codec implementations are based on the eXpressDSP Digital Media (XDM) standard. XDM is an extension of the eXpressDSP Algorithm Interface Standard (XDAIS). IRES is the interface for management and utilization of special resource types such as hardware accelerators, certain types of memory, and DMA. This interface allows the client application to query and provide the algorithm its requested resources.

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 instances 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 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()

Introduction

1-3

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.

As depicted in Figure 1-1, 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 TIs 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.1.3 IRES Overview

IRES is a generic, resource-agnostic, extendible resource query, initialization and activation interface. The application framework defines, implements, and supports concrete resource interfaces in the form of IRES extensions. Each algorithm implements the generic IRES interface, to request one or more concrete IRES resources. IRES defines standard interface functions that the framework uses to query, initialize, activate/deactivate and reallocate concrete IRES resources. To create an algorithm instance within an application framework, the algorithm and the application framework agrees on the concrete IRES resource types that are requested. The framework calls the IRES interface functions, in addition to the IALG functions, to perform IRES resource initialization, activation, and deactivation.

Client Application

XDAIS Interface (IALG)

TIs Codec Algorithms

XDM Interface

Figure 1-1 XDM Introduction

Introduction

1-4

The IRES interface introduces support for a new standard protocol for cooperative preemption, in addition to the IALG-style non-cooperative sharing of scratch resources. Co-operative preemption allows activated algorithms to yield to higher priority tasks sharing common scratch resources. Framework components include the following modules and interfaces to support algorithms requesting IRES-based resources:

IRES - Standard interface allowing the client application to query and provide the algorithm with its requested IRES resources.

RMAN - Generic IRES-based resource manager, which manages and grants concrete IRES resources to algorithms and applications. RMAN uses a new standard interface, the IRESMAN, to support run-time registration of concrete IRES resource managers.

Client applications call the algorithms IRES interface functions to query its concrete IRES resource requirements. If the requested IRES resource type matches a concrete IRES resource interface supported by the application framework, and if the resource is available, the client grants the algorithm logical IRES resource handles representing the allotted resources. Each handle provides the algorithm with access to the resource as defined by the concrete IRES resource interface.

IRES interface definition and function-calling sequence is depicted in the Figure 1-2. For more details, see Using IRES and RMAN Framework Components for C64x+ (literature number SPRAAI5).

Figure 1-2 IRES Interface Definition and Function Calling Sequence

For more details, see Using IRES and RMAN Framework Components for C64x+ (literature number SPRAAI5).

1.2 Overview of H.264 High Profile Encoder

H.264 is the latest video compression standard from the ITU-T Video Coding Experts Group and the ISO/IEC Moving Picture Experts Group. H.264 provides greater compression ratios at a very low bit-rate. The new advancements and greater compression ratios available at a very low bit- rate has made devices ranging from mobile and consumer electronics to set-top boxes and digital terrestrial broadcasting to use the H.264 standard.

Introduction

1-5

Figure 1-3 depicts the working of the H.264 High Profile Encoder algorithm.

Figure 1-3 Working of H.264 Video Encoder

In H.264 Encoder, the operations are performed on set of specific N macro blocks. The selection of N depends on the availability of internal memory. The operations such as motion compensation, transform and quantization, run length encoding and inverse quantization, and inverse transform blocks are called once for all the inter macro blocks in the set of N.

The encoder is designed such that, it always tries to maximize the throughput of each unit by allowing it to perform on maximum possible number of macro blocks.

Motion Estimation is the step where encoder searches for the best match in the available reference frame(s). After quantization, contents of some blocks become zero. The H.264 Encoder keeps track of this information and passes the information of coded 4x4 blocks to inverse transform so that it can skip computation for those blocks that contains all zero co-efficients and are not coded.

The H.264 Encoder defines in-loop filtering to avoid blocks across the 4x4 block boundaries. It is the second most computational task of H.264 encoding process after motion estimation. In-loop filtering is applied on all 4x4 edges as a post-process and the operations depend upon the edge strength of the particular edge.

The H.264 Encoder applies entropy coding methods to use context based adaptivity, which in turn improves the coding performance. All the macro blocks, which belong to a slice, must be encoded in a raster scan order. Entropy coding methods such has Golomb coding, Context Adaptive Variable Length Coding (CAVLC) and Context Adaptive Binary Arthmetic Coding (CABAC). Syntax parameter, which will be used for decoding will be coded in Golomb code. CAVLC is the stage where transformed and quantized co-efficients are entropy coded using context adaptive table switching across different symbols. The syntax defined by the H264 Encoder stores the information at 4x4 block level. CABAC coding depend on context based probability model is selected. Using State and Most Probable Bit each bits of the syntax elements and residual data are encoded.

Introduction

1-6

1.3 Supported Services and Features

This user guide accompanies TIs implementation of H.264 High Profile Encoder on the TMS320C6678 platform.

This version of the codec has the following supported features of the standard:

Supports H.264 baseline, main and high profile up to level 4.0

Supports B frame encoding

Supports arbitrary video resolutions from 64x64 upto 4kx4k

Supports image width and height that are multiple of 16, also supports image width and height being non-multiple of 16

Supports progressive and field based interlace coding with different controls as ARF(Adaptive Reference Field), MRF(Most Recent Reference Field), and SPF(Same Parity Reference Field)

Supports control to have Bottom field first for interlaced coding

Supports user controlled partition size till 8x8 block for inter prediction

Supports user controlled all intra modes (16x16, 8x8, and 4x4)

Supports user controllable quantization parameter range, initial quantization parameter, HRD buffer size

Supports 8x8 and 4x4 transform size

Supports separate Cb and Cr Quantisation parameter control

Supports multiple Scaling Matrix Preset and User Defined Scaling Matrices

Supports user controlled quarter-pel interpolation and integer pel for motion estimation

Supports in-loop filtering which can be switched off for whole picture as well for slice boundaries

Supports unrestricted motion vector search which allows motion vectors to be outside the frame boundary

Supports multiple slices per picture based upon number of macroblocks in each slice

Controls the balance between encoder speed and quality by using the user definable encoding preset option

Supports AIR (Adaptive Intra Refresh) with cyclic intra macro blocks

Supports constrained intra prediction

Supports user controlled all POC types: 0, 1 and 2

Supports user configurable parameters like pic_order_cnt_type, log2_max_frame_num_minus4, and chroma_qp_index_offset

Introduction

1-7

Supports insertion of IDR frame at random point with forceFrame control

Supports user controlled IDR frequency control

Supports change of frame rate, and bit rate dynamically

Supports user configurable Group of Pictures (GOP) length and different GOP structures: Non-Uniform(IBBP) and Uniform(BBIBBP)

Supports byte stream format and NAL unit format.

Support capability to generating only headers

The other explicit features that TIs H.264 HP Encoder provides are:

eXpressDSP Digital Media (XDM IVIDENC2) interface compliant

Independent of any operating system

Supports only YUV420 planar color sub-sampling format

Supports multi-channel functionality

This version of the codec does not support the following features of the standard:

Does not support MBAFF/PicAFF

Does not support BASE CLASS only mode

2-1

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.

Topic Page

2.1 System Requirements 2-2

2.2 Installing the Component 2-2

2.3 Before Building the Algorithm Library and Sample Test Application

2-9

2.4 Building the Algorithm Library 2-10

2.5 Building Sample Test Application 2-11

2.6 Running Sample Test Application 2-13

2.7 Configuration Files 2-15

2.8 Uninstalling the Component 2-18

Installation Overview

2-2

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 using Code Composer Studio Version 5.1.0.09000 and sanity testing is done on Shannon (TMS320C6678) platform.

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 5.1.0.09000. This project is sanity tested on Shannon (TMS320C6678) platform

Code Generation Tools: This project is compiled, assembled, archived, and linked using C6000 Code Generation tools version 7.4.1 for C66x CPU.

2.2 Installing the Component

The codec component is released as RTSC package or compressed archive. Following sub sections details on installation along with directory structure.

2.2.1 Installing the Component RTSC Package

The codec component is released as executable. When the excutable is run, a top-level directory called C66x_h264hpvenc_01_00_00_00_ELF created. Figure 2-1 shows sub directorys created and Table 2-1 provides description of sub directories from the folder h264hpvenc.

Installation Overview

2-3

Figure 2-1 Component Directory Structure In case of RTSC package Release

Table 2-1 Component Directories in case of RTSC package release

Sub-Directory Description

\h264hpvenc Contains RTSC package build files along with Sample test application folders, XDM related codec interface files.

\h264hpvenc\App Contains sample test application, which uses codec library using IVIDENC2 codec interface.

\h264hpvenc\App\Client\Build\C66X\Map

Contains map file generated after building with 66X compiler

\h264hpvenc\App\Client\Build\C664X\Obj

Contains intermediate Object files generated after building host test application with C66X compiler

\h264hpvenc\App\Client\Build\C66X\Out

Contains the final application executable (.out) file generated by the sample test application.

Installation Overview

2-4

Sub-Directory Description

\h264hpvenc\App\Client\Build\packages

Platform RTSC package for building Test application.

\h264hpvenc\App\Client\Test\Inc

Contains standalone test application header files

\h264hpvenc\App\Client\Test\Src\C66X

Contains standalone test application source files specific to C66x processor

\h264hpvenc\Client\Test\Src\Common

Conatains standalone test application common source files

\h264hpvenc\App\Client \Test\TestVecs\Config

Contains sample configuration files for H264 High Profile encoder

\h264hpvenc\App\Client \Test\TestVecs\Input

Contains input test vectors

\h264hpvenc\App\Client \Test\TestVecs\Output

Contains output generated by the codec. It is empty directory as part of release

\h264hpvenc\App\Client \Test\TestVecs\Reference

Contains read-only reference output to be used for cross-checking against codec output

\h264hpvenc\Docs Contains user guide, data sheet, release notes and software manifest

\h264hpvenc\Lib Contains the library file named as h264hpvenc_ti.le66 for encoding the compressed video data

2.2.2 Installing the Component Compressed archive

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.H264HP.E.C6678.01.00, under which directory named C6678_001 is created.

C6678_001: This package runs on TMS320C6678 platform.

Figure 2-2 shows the sub-directories created in the C6678_001 directory in case of object release. Figure 2-3 will show directory structure in case of Source release. Only Src is additional in source release compared to object only release package, remaining folders being same.

Installation Overview

2-5

Figure 2-2 Component Directory Structure In case of Object Release

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

Table 2-2 Component Directories in case of Object release

Sub-Directory Description

\Client\Build\C66X\Map Contains map file generated after building with 66X compiler

\Client\Build\C664X\Obj Contains intermediate Object files generated after building host test application with C66X compiler

\Client\Build\C66X\Out Contains the final application executable (.out) file generated by the sample test application.

\Client\Build\packages Platform RTSC package for building Test application.

\Client\Build\VC\h264hpvenc_ti_vc

Contains project files to build stand alone test application for encoder on VC

\Client\Test\Inc Contains standalone test application header files

\Client\Test\Src\C66X Contains standalone test application source files specific to C66x processor

\Client\Test\Src\Common Conatains standalone test application common source files

Installation Overview

2-6

Sub-Directory Description

\Client \Test\TestVecs\Config

Contains sample configuration files for H264 encoder

\Client \Test\TestVecs\Input

Contains input test vectors

\Client \Test\TestVecs\Output

Contains output generated by the codec. It is empty directory as part of release

\Client \Test\TestVecs\Reference

Contains read-only reference output to be used for cross-checking against codec output

\docs Contains user guide, data sheet and release notes

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

\Lib Contains the library file named as h264hpvenc_ti_vc.lib,h264hpvenc_ti.le66 for encoding the compressed video data

Installation Overview

2-7

Figure 2-3 Component Directory Structure In case of Source Release

Table 2-3 below provides a description of the additional sub-directories, which are part of source release package compared to Object release directories (as in Table 2-2)

Table 2-3 Component Directories in case of Source release

Sub-Directory Description

\Src\Build\C66X Contains project files needed to build codec with C66X compiler

\Src\Build\C66X\Obj Contains intermediate Object files generated after building codec with C66X compiler

\Src\Build\VC\h264hpvenc_ti_vc_lib

Contains project files needed to build codec with Microsoft Visual studio compiler

\Src\Build\VC\Obj Contains intermediate Object files generated after building codec with C66X compiler

\Src\Common Contains common source files needed to build codec

\Src\Inc Contains common header files needed to build codec

Installation Overview

2-8

Sub-Directory Description

\Src\Platform\Inc Contains Platform specific header files ex. ECPY wrapper APIs

\Src\ISA\C66X\ASM Contains hand written assembly files specific to C66X processor

\Src\ISA\C66X\C Contains source files specific to the TMS320C6678 platform

\Src\ISA\C66X\CI Contains intrinsic implementation of source files for TMS320C6678 platform

\Src\ISA\C66X\Inc Contains header files of codec specific to TMS320C6678 platform

\Src\ISA\C66X\SA Contains linear assembly files specific to TMS320C6678 platform

\Src\ISA\VC\C Contains Visual studio specific C source files for encoder algorithm.

\Src\ISA\VC\Inc Contains Visual studio specific Include files for encoder algorithm.

Installation Overview

2-9

2.3 Before Building the Algorithm Library and Sample Test Application

This codec is accompanied by a sample test application. To run the sample test application, XDAIS tools, BIOS tools, Framework Components, and XDC tools are required.

This version of the codec has been validated with XDAIS tools containing IVIDENC2 interface version

The version of the XDAIS tools required is 7.21.01.07

The version of the XDC tools required is 3.22.04.46

The version of the BIOS tools required is 6.32.5.54

The version of the Code Generation tools required is 7.4.1

The version of Framework Components required is 3.23.02.16

The version of EDMA low-level driver required is 2.11.03.03

The version of IPC tools required is 1.23.05.40

Make sure environmental variable CG_TOOL_ROOT is set to proper code generation tools installation path.

2.3.1 Installing XDAIS tools(XDAIS)

XDAIS version 7.21 can be downloaded from the following website:

http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/xdais/7_21_01_07/index_FDS.html

Extract the XDAIS zip file to the same location where Code Composer Studio is installed. For example:

C:\CCStudio5.0

Set a system environment variable named XDAIS_INSTALL_DIR pointing to \

2.3.2 Installing XDC Tools XDC Tools are required to build the test application. The test application uses the standard files like from XDC tools. The xdc tools can be downloaded and installed from the following website:

http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/rtsc/3_22_04_46/index_FDS.html

Also Ensure that the environment variable XDCROOT is set to the XDC installation directory. Eg:set XDCROOT to \

Set a system environment variable named XDC_INSTALL_DIR pointing to \

http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/xdais/7_21_01_07/index_FDS.htmlhttp://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/xdais/7_21_01_07/index_FDS.htmlhttp://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/rtsc/3_22_04_46/index_FDS.htmlhttp://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/rtsc/3_22_04_46/index_FDS.html

Installation Overview

2-10

2.3.3 Installing BIOS tools(SYS/BIOS) Unit test application uses SYS/BIOS tools to create tasks, cache programming etc. The xdc tools version 6.32.5.54 can be downloaded from the following website: http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/bios/sysbios/6_32_05_54/index_FDS.html

2.3.4 Installing Framework Component(FC)

Framework Components are required for using IRES interface for EDMA3 hardware. FC tools can be downloaded and installed from the following website

http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/fc/3_23_02_16/index_FDS.html

Mare sure that FC tools are recognized as RTSC package in CCS V5 by adding installation directory path RTSC products search path in CCS V5 preferences.

Set a system environment variable named FC_INSTALL_DIR pointing to \

2.3.5 Installing EDMA3 Low-Level Driver(LLD)

EDMA3 low-level driver tools are used for configuring EDMA channels and data transfer across DDR memory to L2 memory using EDMA hardware. EDMA low-level driver can be downloaded from the following website.

http://software-dl.ti.com/dsps/dsps_public_sw/sdo_tii/psp/edma3_lld/edma3-lld-bios6/02_11_03_03/index_FDS.html

Mare sure that EDMA3 LLD tools are recognized as RTSC package in CCS V5 by adding installation directory path at RTSC products search path in CCS V5 preferences.

2.3.6 Installing Inter Processor Communication (IPC)

Inter processor communication software is used to synchronize multiple cores and share data between cores via messaging. IPC software version 1.23.5.40 can be downloaded from the following website

http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/ipc/1_23_05_40/index_FDS.html

2.4 Building the Algorithm Library

Building algorithm library on Visual studio and CCS is specified in section 2.4.1 and 2.4.2 resepctively.

2.4.1 Building Algorithm Library on Visual studio

To build the algorithm library from source code in Visual Studio, follow these steps:

1) Verify that you have installed Microsoft Visual Studio 2008 Express Edition development environment. Open the source project

http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/bios/sysbios/6_32_05_54/index_FDS.htmlhttp://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/bios/sysbios/6_32_05_54/index_FDS.htmlhttp://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/bios/sysbios/6_32_05_54/index_FDS.htmlhttp://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/fc/3_23_02_16/index_FDS.htmlhttp://software-dl.ti.com/dsps/dsps_public_sw/sdo_tii/psp/edma3_lld/edma3-lld-bios6/02_11_03_03/index_FDS.htmlhttp://software-dl.ti.com/dsps/dsps_public_sw/sdo_tii/psp/edma3_lld/edma3-lld-bios6/02_11_03_03/index_FDS.htmlhttp://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/ipc/1_23_05_40/index_FDS.htmlhttp://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/ipc/1_23_05_40/index_FDS.html

Installation Overview

2-11

h264hpvenc_ti_vc_lib.vcproj from ..\Src\Build\VC\h264hpvenc_ti_vc_lib\.

2) This project contains two build configurations Debug and Release. Debug configuration will disable all the optimizations to debug the code. Release configuration will enable all the optimizations without exposing symbols. Please select Debug configuration.

3) Right click on the above project in Visual Studio IDE and select Build Project to build the algorithm library.

The built library, h264hpvenc_ti_vc.lib is available in the \Lib sub-directory.

2.4.2 Building Algorithm Library on Code Composer Studio

To build the algorithm library from source code in CCSv5, follow these steps:

1) Select the CCS Edit perspective in the workbench.

2) Add the project named h264hpvenc_ti_c66x_lib through Import Existing CCS/CCE Eclipse Project option to the workspace. All files required for this project are available in the \C6678_001\Src\Build\C66X\ sub-directory.

3) This project contains three build configurations Debug, Release and Profile. Debug configuration will disable all the optimizations to debug the code in ELF mode. Release configuration will enable all the optimizations without exposing symbols in ELF mode. Please select Release configuration.

4) Right click on the above project in CCSv5 IDE and select Build Project to build the algorithm library.

The built library, h264hpvenc_ti.le66 is available in the \Lib sub-directory.

2.5 Building Sample Test Application

Building Sample test application on Visual studio is specified in section 2.5.1. Building Sample test application on CCS in case of compressed archive and RTSC package is specified in section 2.5.2 and 2.5.3 resepctively.

2.5.1 Building Sample Test Application on Visual Studio

The sample test application that accompanies this codec component will run in Microsoft Visual Studio 2008 development environment. To build the sample test application in Visual studio 2008 Express edition, follow these steps:

1) Verify that you have installed Microsoft Visual Studio 2008 Express Edition development environment.

2) Verify that the following codec object libraries should exist in \Lib sub-directory

o h264hpvenc_ti_vc.lib: H264 HP Encoder.

3) Start the Visual studio 2008 Express Edition.

Installation Overview

2-12

4) Select File->Open->Project/Solution and open h264hpvenc_ti_vc.sln located at ..\Client\Build\VC\h264hpvenc_ti_vc\

5) Select Build->Build solution it builds the stand alone test application

2.5.2 Building the Sample Test Application on Code Composer Studio Compressed archive

The sample test application that accompanies this codec component will run on TMS320C6678 Evaluation Module platform. To build the sample test application in Code Composer Studio, follow these steps:

1) Verify that you have an installation of TIs Code Composer Studio version 5.1.0.09000 and code generation tools version 7.4.1 Verify that the following codec object libraries should exist in C6678_001\Lib sub-directory

o h264hpvenc_ti.le66: H264 HP Encoder.

2) Make sure all the tools installed and configured as specified in section 2.3.

3) Select the CCS Edit perspective in the workbench.

4) Add the C66X project named h264hpvenc_ti_c66x through Import Existing CCS/CCE Eclipse Project option to the workspace. All files required for this project are available in the \C6678_001\Client\Build\C66X\ sub-directory

5) This project contains two build configurations Debug and Release. Debug configuration will disable all the optimizations to debug the code in ELF mode. Release configuration will enable all the optimizations without exposing symbols in ELF mode. Please select Debug configuration.

6) Open the build properties by right clicking the project, under CCS build options->Build Variables tab, updateFC_ROOT, XDAIS_ROOT, SYSBIOS_ROOT, EDMA3LLD_ROOT, IPC_ROOT, variables with appropriate installation paths.

7) Right click the above projects on CCSv5 IDE and select Rebuild Project to build all the files present in the project.

8) After successful completion of the build executable h264hpvenc_ti_c66x.out will be present in \C6478_001\Client\Build\C6X\Out sub-directory.

2.5.3 Building the Sample Test Application on Code Composer Studio - RTSC Package

The sample test application that accompanies this codec component will run on TMS320C6678 Evaluation Module platform. To build the sample test application in Code Composer Studio, follow these steps:

1) Verify that you have an installation of TIs Code Composer Studio version 5.1.0.09000 and code generation tools version 7.4.1 Verify that the following codec object libraries should exist in h264hpvenc\Lib sub-directory

Installation Overview

2-13

o h264hpvenc_ti.le66: H264 HP Encoder.

2) Make sure all the tools installed and configured as specified in section 2.3.

3) Select the CCS Edit perspective in the workbench

4) Add the C66X project named h264hpvenc_ti_c66x through Import Existing CCS/CCE Eclipse Project option to the workspace. All files required for this project are available in the \h264hpvenc\App\Client\Build\C66X\ sub-directory

5) This project contains two build configurations Debug and Release. Debug configuration will disable all the optimizations to debug the code in ELF mode. Release configuration will enable all the optimizations without exposing symbols in ELF mode. Please select Debug configuration.

6) Open the build properties by right clicking the project, under CCS build options->Build Variables tab, updateFC_ROOT, XDAIS_ROOT, SYSBIOS_ROOT, EDMA3LLD_ROOT, IPC_ROOT, variables with appropriate installation paths.

7) Right click on the above project in CCSv5 IDE and select Rebuild Project to build all the files present in the project.

8) After successful completion of the build executable h264hpvenc_ti_c66x.out will be present in \h264hpvenc\App\Client\Build\C66X\Out sub-directory.

2.6 Running Sample Test Application

Sample test application is used to run codec library in single core or multicore mode. Number of cores involved can be controlled with ncores parameter. Running sample test application on Visual studio and Code composer studio is specified in section 2.6.1 and section 2.6.2 respectively.

2.6.1 Running the Sample Test Application on Visual Studio

A wrapper function on top of main encode task is written to mimic multicore scenario using multiple threads. Based on number of cores specified in configuration file, multiple threads are created and accordingly DDR, SL2, L2 memory is allocated for each thread. To run sample test application visual studio 2008 follow these steps:

1) Start the Visual studio 2008 Express Edition.

2) Select File->Open->Project/Solution and open h264hpvenc_ti_vc.sln located at ..\Client\Build\VC\h264hpvenc_ti_vc\

3) Make sure code is built as specified in section 2.5.1.

4) Set number of cores and cores to be used in ncores, CoreTeamMap variables of configuration parameters.

5) Select Debug->Debug solution (F5) to run test application.

6) The sample test application takes the input files stored in the \Client\Test\TestVecs\Input sub-directory, runs the codec, and uses the

Installation Overview

2-14

reference files stored in the Client\Test\TestVecs\Reference sub-directory to verify that the codec is functioning as expected.

7) On successful completion, the application displays the following messages for every display frame:

9) "---Num Frames Encoded : Frame Type Bits ----"

8) The output is written to the file specified (this can then be manually compared against the reference).

9) On failure, the application exits after encoding the frame in which codec failed to generate the correct result with printing the error message from which module it failed.

2.6.2 Running the Sample Test Application on Code Composer Studio

The sample test application that accompanies this codec component will run on TMS320C6678 Evaluation Module platform. To run the sample test application in Code Composer Studio, follow these steps:

1) Verify that you have an installation of TIs Code Composer Studio version 5.1.0.09000 and executable is created in ..\Client\Build\C66x\Out folder, after following steps in section 2.5.2 or 2.5.3.

2) Open Code Composer Studio.

3) Open CCS Debug Perspective by clicking on Window->Open Perspective->other and then by clicking CCS Debug.

4) Make sure TMS320C6678 target is configured with TMS320C6678 EVM by checking View->Target Configurations-> user Defined. One should see the specific target; if it is not available go to Target->New Target Configuration. Give name of the target, next select TMS320C6678 Device according to the type of JTAG availability.

5) Set number of cores and cores to be used in ncores, CoreTeamMap variables of configuration parameters based on usecase.

6) Select each C66x device and do Run->Connect Target to connect to the C66x core of EVM. Once connected, do Run->Reset->System Reset.

7) For connected cores do Run->Load->Load Program, browse to the..\Client\Build\C66X\Out\ sub-directory, select the codec executable h264hpvenc_ti_c66x.out and load it for execution.

8) After loading executable on all the specified cores do Run->Resume to start encoding.

9) 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.

10) On successful completion, the application displays the following messages for every display frame:

Installation Overview

2-15

10) "---Num Frames Encoded : Frame Type BitsPadding Bits---"

11) On failure, the application exits after decoding the frame in which codec failed to generate the correct result with printing the error message from which module it failed.

11)

2.7 Configuration Files

This codec is shipped along with:

Encoder configuration file (encoder.cfg) specifies the configuration parameters used by the test application to configure the Encoder.

TestCases.txt This file has list of config files, these needs to be executed with parameter (integer) preceding. The meaning of the parameter is below.

0 execute the test case

1 Skip the test case.

2 Terminate the regression

2.7.1 Encoder Configuration File

The encoder configuration file, encoder.cfg contains the configuration parameters required for the encoder. The Encoder.cfg file is available in the \Client\Test\TestVecs\Config sub-directory. A sample encoder.cfg file is as shown.

# = # Comment

##################################################################################

# Files

##################################################################################

InputFile = ..\..\..\Test\TestVecs\Input\airshow_p352x288.yuv

EncodedFile= ..\..\..\Test\TestVecs\Output\airshow_p352x288.264

ReferenceFile = ..\..\..\Test\TestVecs\Reference\airshow_p352x288_ref.264

##################################################################################

# Multicore Parameters

##################################################################################

ncores = 8

CoreTeamMap = 0,1,2,3,4,5,6,7

##################################################################################

# Encoder Control

##################################################################################

EncodingPreset = 3 # encoding preset 0: Default, 1: High_Quality,

2: High_Speed, 3: User Defined

RateControlPreset = 5 # 5: IVIDEO_USER_DEFINED, 4: IVIDEO_NONE, 2:

Note: Reference file specified in Reference folder can be used only for comparing eight-core output.

Installation Overview

2-16

IVIDEO_STORAGE, 1: IVIDEO_LOW_DELAY

framesToEncode = 300 # Total number of frames to encode

MaxWidth = 640 # Max Frame width

MaxHeight = 480 # Max Frame height

MaxInterFrameInterval= 3 # I to P frame distance

InputChromaFormat = 1 # 1 => XDM_YUV_420P, Only 1 is supported.

InputContentType = 0 # Input buffer content type, 0 -> Progressive Type, 1->

Interlaced.

Profile = 100 # Encoding profile 100 => HP, 77 => MP, 66 => BP

Level = 40 # Level IDC (e.g. 20 = level 2.0)

inputWidth = 352 # width of image

inputHeight = 288 # Height of image

targetFrameRate = 30000 # Target frame rate in fps * 1000

targetBitRate = 1000000 # Target Bit Rate in Bits per second.

intraFrameInterval = 15 # Interval between two consecutive intra frames

interFrameInterval = 3 # M: Number of (M-1) B frames between two ref. frames.

mvAccuracy = 2 # 0 => integer pel 2=> quarter pel

generateHeader = 0 # 1: Encode only header, 0: Encode entire access unit,

including the headers

forceFrame = -1 # -1: IVIDEO_NA_FRAME, 3: IVIDEO_IDR_FRAME

dataLayout = 0 # input data buffer layout 0=> interleaved, 1=> seprated.

sampleAspectRatioHeight = 1 # Aspect Ratio Height

sampleAspectRatioWidth = 1 # Aspect Ratio Width

##################################################################################

# Rate Control Params

##################################################################################

rateControlParamsPreset = 1 # 0: default, 1: user defined

rcAlgo = 0 # 0: Variable Bitrate, 1 : Constant bitrate.

qpI = -1 # Initial QP for I/IDR frames, -1: codec chosen

qpP = -1 # Initial QP for P frames

qpOffsetB = 4 # Offset of B frames QP from P frames

qpMaxI = 51 # Maximum QP for I/IDR frames

qpMinI = 1 # Minimum QP for I/IDR frames

qpMaxP = 51 # Maximum QP for P frames

qpMinP = 1 # Minimum QP for P frames

qpMaxB = 51 # Maximum QP for B frames

qpMinB = 1 # Minimum QP for B frames

CbQPIndexOffset = 0 # Specifies offset to be added to luma QP for

addressing QPC values table for chroma component Cb

CrQPIndexOffset = 0 # Specifies offset to be added to luma QP for

addressing QPC values table for chroma component Cr

initialBufferLevel = 26214400 # Initial Buffer level for HRD compliance

HRDBufferSize = 26214400 # HRD Buffer Size in bits - 2*bitrate for VBR

enablePRC = 1 # 0 => Disable, Non-Zero => Enable

frameSkipAfterSceneChange = 1 # 0=> no forced skip after scenechange, 1=>force

skip frame after coding scene change frame.

##################################################################################

# InterCoding Control

##################################################################################

interCodingPreset = 1 # 0 => deafult values, 1 => user defined

MvRangeVerP = 32 #Vertical MV Range for P frames in integer pixels (16 to 496)

MvRangeHorP = 144# Horizontal MV Range for P frames in integer pixels(16to496)

MvRangeVerB = 32# Vertical MV Range for B frames in integer pixels (16 to 496)

MvRangeHorB = 144# Horizontal MV Range for P frames in integer pixels(16to496)

maxMVperMB = 1 # Maximum MV per MB (Values of 1 & 4 are valid)

##################################################################################

# IntraCoding Control

Installation Overview

2-17

##################################################################################

intraCodingPreset = 1 # 0 => deafult values, 1 => user defined

enableIntraPartition = 4 # 0 => INTRA_PARTITION_NONE , 1 =>

INTRA_PARTITION_ISLICES, 2 =>

INTRA_PARTITION_IPSLICES, 3 =>

INTRA_PARTITION_IBSLICES, 4 =>

INTRA_PARTITION_IPBSLICES

intraRefreshMethod = 0 # IH264_INTRAREFRESH_NONE = 0,

IH264_INTRAREFRESH_CYCLIC_MBS = 1

intraRefreshRate = 0 # Rate at which intra MB Refresh is done.

constrainedIntraPredEnable = 0 # Controls the intra MB coding in inter slices

##################################################################################

# Entropy Coding Mode

##################################################################################

entropyCodingMode = 1 # Enropy coding type, (0 => CAVLC, 1 => CABAC)

##################################################################################

# Slice Mode Configuration

##################################################################################

sliceCodingPreset = 0 # 0 => deafult values, 1 => user defined

streamFormat = 0 # format (0 =>Byte stream format, 1 => NALU stream format)

sliceMode = 0 # Type of slice coding, (0 => frame based, 1 => Slices are

controlled based upon number of Macroblocks

sliceUnitSize = 0 # Number of macroblocks per slice

##################################################################################

# Loop Filter Control

##################################################################################

loopfilterPreset = 1 # 0 => deafult values, 1 => user defined

loopfilterDisableIDC = 2 # (0=Filter, 1= NoFilter, 2 = No filter across slices)

filterOffsetA = 0 # Alpha offset for loop filter

filterOffsetB = 0 # Beta offset for loop filter

##################################################################################

# VUI Control Params

##################################################################################

vuiCodingPreset = 0 # 0 => deafult values, 1 => user defined

aspectRatioInfoPresentFlag = 1 # Controls the insertion of aspect ratio

information in VUI part of bit-stream

aspectRatioIdc = 1 # Aspect ratio ID

videoSignalTypePresentFlag = 0 # insertion of video signal type in VUI part of

bit-stream

videoFormat = 2 # Video signal type

videoFullRangeFlag = 0 # Flag to specigy Range of the pixels

colourDescriptionPresentFlag = 1 # Specifies whether colour_primaries,

transfer_characteristics and

matrix_coefficients are present or not.

colourPrimaries = 5 # Indicates the chromaticity coordinates of the

source primaries(Table E-3 in standard)

transferCharacteristics = 5 # Indicates the opto-electronic transfer

characteristic of the source picture(Table E-4 in

standard)

matrixCoefficients = 5 # Describes the matrix coefficients used in deriving

luma and chroma signals from the green, blue,and

red primaries(Table E-5 in standard)

timingInfoPresentFlag = 1 # Controls the insertion of timing info related

parameters in VUI part of bit-stream

##################################################################################

# MISC

Installation Overview

2-18

##################################################################################

gopStructure = 0 # 0 => Open or Non uniform(IBBPBBP), 1 => Closed or

Uniform (BBIBBPBB

log2MaxFNumMinus4 = 0 # # sliceParams::frame_num syntax element will be reset

after every (1IDR BBP I BBP I,

1=>IDR BBP IDR BBP IDR, 2=>IDR BBP I BBP IDR,

3=>IDR BBP I BBP I BBP IDR

transformBlockSize = 1 # 0:4x4 only, 1: 8x8 only,

topFieldFirstFlag = 1 # to indicate field order in interlaced content

interlaceCodingType = 3 # Interlced field coding type selection, 2 => MRF 3=> ARF

4=> SPF

DebugTraceLevel = 0 # Debug trace Enable 0 - Disable, 1- Level 1, 2 - Level

2, 3 - Level 3,

lastNFramesToLog = 5 # Last N frames to log into debug trace buffer

Any field in the IVIDENC2_Params structure (see Section 4.2.1.7) can be set in the encoder.cfg file

using the syntax as shown in the code snippet. If you specify additional fields in the encoder.cfg file, ensure that you modify the test application appropriately to handle these fields.

2.8 Uninstalling the Component

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

3-1

Chapter 3

Sample Usage

This chapter provides a detailed description of the sample test application that accompanies this codec component.

Topic Page

3.1 Overview of the Test Application 3-2

3.2 Frame Buffer Management 3-5

Sample Usage

3-2

3.1 Overview of the Test Application

The test application exercises the IVIDENC2 and extended class of the H.264 High Profile Encoder

library. The source files for this application are available in the \Client\Test\Src and \Client\Test\Inc sub-directories.

Figure 3-1 Test Application Sample Implementation

The test application is divided into four logical blocks:

Parameter setup

Algorithm instance creation and initialization

Process call

Algorithm instance deletion

Sample Usage

3-3

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 Encoder configuration files.

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

1) Opens the configuration file, listed in TesCases.txt and reads the

2) various configuration parameters required for the algorithm.

For more details on the configuration files, see Section 2.5.

3) Sets the interface structure based on the values it reads from the

configuration file.

4) Does the algorithm instance creation and other handshake via. control methods

5) For each frame reads the input yuv frame into the application input buffer and makes a process call

6) For each frame dumps out the generated bit-stream into the specified file

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 implemented by the codec are called in sequence by

ALG_create():

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 resource allocation for the algorithm. This requires initialization of Resource Manager Module (RMAN) and grant of required resources (EDMA channels). This is implemented by calling RMAN interface functions in following sequence:

1) numResourceDescriptors() - To understand the number of

resources needed by algorithm.

2) getResourceDescriptors() To get the attributes of the resources.

initResources() - After resources are created, application gives the resources to algorithm

through this API

Sample Usage

3-4

3.1.3 Process Call

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

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

calling the control() function with the XDM_SETPARAMS command.

4) 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.

5) Calls the process() function to encode/decode a single frame of data.

The behavior of the algorithm can be controlled using various dynamic parameters (see Section 4.2.1.8). The inputs to the process function are input and output buffer descriptors, pointer to the

IVIDENC2_InArgs and IVIDENC2_OutArgs structures.

6) When the process() function is called for encoding/decoding a single

frame of data, the software triggers the start of encode/decode. After triggering the start of the encode/decode frame, the video task can be placed in SEM-pend state using semaphores. On receipt of interrupt signal at the end of frame encode/decode, the application releases the semaphore and resume the video task, which does any book-keeping operations by the codec and updates the output parameters.

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. If the same algorithm is in-use between two process/control function calls, calling these functions can be avoided. Once an algorithm is activated, there can be

any ordering of control() and process() functions. The following APIs are called in sequence:

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

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

dynamic parameters and so on, using the eight control commands.

3) process() - To call the Encoder with appropriate input/output buffer

and arguments information.

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

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

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

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.

If the algorithm uses any resources through RMAN, then user must activate the resource after the algorithm is activated and deactivate the resource before algorithm deactivation.

Sample Usage

3-5

3.1.4 Algorithm Instance Deletion

Once decoding/encoding is complete, the test application must release the resources granted by the IRES resource Manager interface and delete the current algorithm instance. The following APIs are called in sequence:

1) Free all resources granted by RMAN

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

records it used.

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

information.

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.

After successful execution of the algorithm, the test application frees up the DMA Resource allocated for the algorithm. This is implemented by calling the RMAN interface functions in the following sequence:

4) RMAN_freeResources () - To free the resources that were allocated

to the algorithm before process call.

5) RMAN_exit() - To delete the generic IRES RMAN and release memory.

3.2 Frame Buffer Management

3.2.1 Input Frame Buffer

The encoder has input buffers that stores frames until they are processed. These buffers at the input level are associated with a buffer input IDs. The IDs are required to track the buffers that have been processed or locked. The encoder uses this ID, at the end of the process call, to inform back to application whether it is a free buffer or not. Any buffer given to the algorithm should be considered locked by the algorithm, unless the buffer is returned to the application through

IVIDENC2_OutArgs->freeBufID[].For more information, see section 4.2.1.11.

For example, consider the GOP structure for IPPPP frames.

Frame Type I P P P P

Input ID 1 2 3 4 5

Free Buffer ID 1 2 3 4 5

As shown in the table, if the input ID for the first frame is 1, the same input ID is returned as the free buffer ID at the end of the process call. There is no locking of buffers at any point.

Now, consider the GOP structure that has B frames, IBBPBBP.

Frame Type I B B P B B P

Input ID 1 2 3 4 5 6 7

Free Buffer ID 0 0 1 4 2 3 7

Sample Usage

3-6

As shown in the table, the first frame input ID (1) is returned as a free buffer ID at the end of the third process call that is after accumulating buffers for two B frames. For the first two process calls, free buffer IDs are returned as zero. This initial delay is equal to the number of B frames.

Since the 4th frame is a P frame, it is returned immediately at the end of the process call. Then,

input IDs, 2 and 3 are returned as free buffers while frames 5 and 6 are being processed. Hence, if there are two B frames between P frames, the input images for the B frames are stored and the P frame is encoded first, and then the two B frames are encoded. This results in two frame period initial delay.

4-1

Chapter 4

API Reference

This chapter provides a detailed description of the data structures and interfaces functions used in the codec component.

Topic Page

4.1 Symbolic Constants and Enumerated Data Types 4-2

4.2 Data Structures 4-28

4.3 Default and Supported Values of Parameters 4-64

4.4 Interface Functions 4-74

API Reference

4-2

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.

4.1.1 Common XDM Data types

This section includes common XDM Enumerated data types:

Table 4-1 List of Enumerated Data Types

Group or Enumeration Class

Symbolic Constant Name

Description or Evaluation

IVIDEO_FrameType For the various IVIDEO_xy_FRAME values, this frame

type is interlaced where both top and bottom fields

are provided in a single frame. The first field is

an x frame, the second field is y field.

IVIDEO_NA_FRAME Frame type not available

IVIDEO_I_FRAME

IVIDEO_FRAMETYPE_D

EFAULT

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.

4-3

Group or Enumeration Class

Symbolic Constant Name

Description or Evaluation

IVIDEO_BB_FRAME Interlaced frame, both fields are B frames.

IVIDEO_MBAFF_I_FRA

ME

Intra coded MBAFF frame.

IVIDEO_MBAFF_P_FRA

ME

Forward inter coded MBAFF frame.

IVIDEO_MBAFF_B_FRA

ME

Bi-directional inter coded MBAFF frame.

IVIDEO_MBAFF_IDR_F

RAME

Intra coded MBAFF frame that can be used for refreshing video content.

IVIDENC2_Control Process based Controls operation for Video encoder

IVIDENC2_CTRL_NONE

IVIDENC2_CTRL_DEFA

ULT

No special control operation

IVIDENC2_CTRL_FORC

ESKIP

Force frame to be skipped. The encoder should ignore this operation if the frame for which the control is issued is IDR/I frame.

IVIDEO_MetadataType IVIDEO_METADATAPLA

NE_NONE

Used to indicate no metadata is requested or available

IVIDEO_METADATAPLA

NE_MBINFO

Used to indicate that MB info metadata is requested or available

IVIDEO_METADATAPLA

NE_EINFO

Used to indicate that Error info metadata is requested or available

IVIDEO_METADATAPLA

NE_ALPHA

Used to indicate that Alpha metadata is requested or available

IVIDEO_ContentType IVIDEO_CONTENTTYPE