Codec Engine Server Integrator User's Guide Literature Number: SPRUED5B September 2007
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.
This is a draft version printed from file: pref.fm on 9/25/07 Preface About This Book The intended audience for this document is the Server Integrator, who creates a Codec Server for use by the Engine Integrator and thus the Application Author. This manual tells what steps the Server Integrator should take to configure DSP/BIOS and other components to create a Codec Server. Additional Documents and Resources You can use the following sources to supplement this user’s guide: ❏ Codec Engine API Reference.
Notational Conventions Notational Conventions This document uses the following conventions: P +DS P P G ❏ Program listings, program examples, and interactive displays are shown in a special typeface. Examples use a bold version of the special typeface for emphasis; interactive displays use a bold version of the special typeface to distinguish commands that you enter from items that the system displays (such as prompts, command output, error messages, etc.).
This is a draft version printed from file: ce_serv_integTOC.fm on 9/25/07 Contents 1 Codec Engine Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1 This chapter introduces the Codec Engine. 1.1 What is the Codec Engine? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2 1.2 Why Should I Use It? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-vi
Chapter 1 Codec Engine Overview This chapter introduces the Codec Engine. Topic Page 1.1 What is the Codec Engine? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–2 1.2 Why Should I Use It? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–3 1.3 Where Does the Codec Engine Fit into My Architecture? . . . . . . . . 1–4 1.4 What Are the User Roles? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1–6 1.
What is the Codec Engine? 1.1 What is the Codec Engine? From the application developer’s perspective, the Codec Engine is a set of APIs that you use to instantiate and run xDAIS algorithms. A VISA interface is provided as well for interacting with xDM-compliant xDAIS algorithms. The API is the same for all of the following situations: P +DS P P G ❏ The algorithm may run locally (on the GPP) or remotely (on the DSP). ❏ The system may be a GPP+DSP, DSP only, or GPP only system.
Why Should I Use It? 1.2 Why Should I Use It? The Codec Engine is designed to solve some common problems associated with developing system-on-a-chip (SoC) applications. The most significant problems include: P +DS GPP ❏ Debugging in a heterogeneous processor environment can be painful. There are multiple debuggers and complex bootstrapping. ❏ Different implementations of the same algorithm, such as MP3, have different APIs. Changing to a more efficient algorithm involves significant recoding.
Where Does the Codec Engine Fit into My Architecture? 1.3 Where Does the Codec Engine Fit into My Architecture? The application code (or the middleware it uses) calls the Codec Engine APIs. Within the Codec Engine, the VISA APIs use stubs and skeletons to access the core engine and the actual codecs, which may be local or remote. The following figure shows the general architecture of an application that uses the Codec Engine.
Where Does the Codec Engine Fit into My Architecture? G DSP PP+ The following figure is a modification of the previous diagram that shows how this architecture is distributed in a GPP+DSP system. In this example, yellow portions run on the GPP, and grey portions run on the DSP. This is, the video encoder skeleton and the video encoder codecs are on the DSP and the application and video encoder stubs are on the GPP.
What Are the User Roles? 1.4 What Are the User Roles? The Codec Engine has several customer use cases, from GPP-side application developers to DSP-side codec authors. Is some cases, these roles may be played by a single person. In other development environments, a different developer may be assigned each role. This topic describes the primary roles that Codec Engine users will play.
What Are the User Roles? 1.4.2 Server Integrator To support Engines with remote codecs, a Codec Server must be created. The Codec Server integrates the various components necessary to house the codecs (e.g. DSP/BIOS, Framework Components, link drivers, codecs, Codec Engine, etc.) and generates an executable.
What Are the User Roles? 1.4.3 Engine Integrator The Engine Integrator defines various Engine configurations. This can include the names of the Engines, as well as the codecs and their names within each Engine, whether each codec is local or remote relative to the application, which groups each codec should be integrated into (for environments which support resource sharing), the name of the Codec Server image if a particular Engine contains remote codecs, etc.
Where Can I Get More Information? ❏ Various Codec packages from Algorithm Creators ❏ A Codec Server DSP executable from the Server Integrator if codec will run on a DSP ❏ An Engine config file (.cfg) from the Engine Integrator The Application Author write application code, generates output from the Engine configuration file (.c and .xdl output files) using the XDC Tools, compiles the application code and generated files. This person then links the files, including the generated linker command file (.
1-10
Chapter 2 Configuring a Codec Server This chapter describes how the Server Integrator should configure a Codec Server for use by the Engine Integrator. Topic Page 2.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–2 2.2 Creating a Codec Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2–7 2.3 Delivering a Codec Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview 2.1 Overview As described in Section 1.4.2, Server Integrator, the Server Integrator provides a Codec Server to the Engine Integrator. In practice, these roles may be shared by one person. There are two configuration steps that the Server Integrator performs: ❏ Configure DSP/BIOS through a Tconf script ❏ Configure "the rest" of the components through XDC configuration of Framework Components, DSP/BIOS Link, the Codec Engine, etc.
Overview 2.1.1 What is a Codec Server? A Codec Server is a binary that integrates codecs, framework components, and system code. When the Codec Server is on a DSP, it uses DSP/BIOS as the DSP kernel. SP P+D P G In the context of the DaVinci DM644x platforms (and other GPP+DSP platforms), a Codec Server is a DSP binary. It includes a DSP/BIOS task thread that responds to requests from a client to create codecs, provide performance information (MIPS and MEM usage).
Overview ■ A message queue is created to allow the remote node to receive commands from the GPP. ■ The node-specific "create" function (for example, AUDENC_create() ) is called to initialize the node state and algorithm-specific memory and resources. (Note that this call is made from within the dispatcher execution context.) ■ A dedicated execution thread (task) is created for the node. The new thread does not run yet, but is in a suspended state.
Overview ■ Any algorithm scratch memory is then "deactivated". ■ The skeleton writebacks output buffers to ensure that CPU writes to the cache are flushed to external memory. ■ The node's thread then replies with the status back to the GPP and then blocks waiting for the next message.
Overview 2.1.4 What Algorithms Can a Codec Server Integrate? You can use any algorithm that is xDM-compliant in a Codec Server. In addition, if you want to use a xDAIS-compliant algorithm that is not xDM-compliant, you can first implement your own stubs and skeletons for that algorithm, and then use that algorithm in a Codec Server. See the Codec Engine Algorithm Creator User’s Guide (SPRUED6) for details. The Codec Engine does not provide APIs for chaining algorithms.
Creating a Codec Server 2.2 Creating a Codec Server To create a Codec Server, you perform the following configuration steps: ❏ Configure DSP/BIOS through a Tconf script ❏ Configure "the rest" of the components through XDC configuration (for example, Framework Components, DSP/BIOS Link, the Codec Engine, etc.). You will modify the following files: ❏ package.xdc. The package definition file. ❏ package.bld. The build script. ❏ servername.cfg. The Codec Server configuration script. ❏ servername.
Creating a Codec Server 3) Edit the examples/xdcpaths.mak file with a text editor to specify the CE_INSTALL_DIR, XDC_ROOT, and BIOS_ROOT variables. Again, see examples/build_instructions.html for details. 4) Make a duplicate of one of the Codec Server examples in the examples/servers directory. Each of these directories is a "package". Packages must have names that match their directory location.
Creating a Codec Server To see documentation for the attributes of the Server module, follow these steps: 1) Open CE_INSTALL_DIR/xdoc/index.html to see the Configuration Reference. Depending on your browser, you may need to enable active content to view the list of nodes on the left. 2) Click the link to the ti.sdo.ce package. 3) Click the link to the Server module. 4) You see the config params that you can set for this module.
Creating a Codec Server For example, these statements from the video_copy.cfg file have been modified (bold text) to reference the speech encoder/decoder. /* get various codec modules; i.e. codec implementations */ var SPHDEC_COPY = xdc.useModule('codecs.sphdec_copy.SPHDEC_COPY'); var SPHENC_COPY = xdc.useModule('codecs.sphenc_copy.SPHENC_COPY'); 5) Modify the attributes of the threadAttrs structure as desired. See CE_INSTALL_DIR/xdoc/index.html for details about these attributes. Server.threadAttrs.
Creating a Codec Server 2.2.3.1 Controlling I/O Buffer Caching for xDM 0.9 Codecs The DSP server's support—the "skeletons"—for remote execution of codecs written for xDM 0.9 always manages the cache for all codec I/O buffers exchanged with the ARM application. This can be a performance problem for some video codecs, where the codec accesses the buffers exclusively via DMA, yet the generic skeleton invalidates and flushes those buffers anyway, thus wasting up to a few milliseconds for every frame.
Creating a Codec Server 2.2.3.2 Codec Specifying "Scratch Group" and DMA Resources for a When you put together several codecs into a single DSP server, you may need to make them share memory and DMA resources. Two codecs can share what is called a "scratch" memory. This is a working memory area, typically in fast internal memory, that is initialized before one frame of data is processed and discarded afterwards. The codecs can share this memory only if they run at the same priority.
Creating a Codec Server How you define the groupId field can affect performance or whether a codec can be created at all. For detailed information on shared scratch memory, see the Framework Components documentation. You may save some time by reading the commentary for the server configuration script in the video_copy example, which is in /examples /ti/sdo/ce/examples/servers/video_copy/video_copy.cfg. What is true for sharing memory is also true for sharing DMA resources among codecs.
Creating a Codec Server Engine.algs[].groupId For each local algorithm, if the optional groupId field is uninitialized, the algorithm is configured into its own, unique groupId. This is because we don't know what priority the algorithm will run at, so we place it into a unique group to prevent preemption by any other algorithm. Note that for remote algorithms, the groupId field is ignored. In such cases, the algorithm is placed into the Server-configured groupId. 2.2.
Creating a Codec Server 2.2.4.1 DSP/BIOS Threads and Module Use Each “remote” algorithm instance that runs on the DSP executes in a DSP/BIOS thread whose priority is specified by a static configuration parameter (see ti.sdo.ce.Server). The stack size of the thread that runs a “remote” algorithm is specified by the algorithm’s implementation of the ICodec interface (see ti.sdo.ce.ICodec).
Delivering a Codec Server Change the bold text in the following line to match your server name: var serverName = "my_server"; When you have finished development, you may want to change "debug" in the following line to "release": Pkg.attrs.profile = "release"; Do not edit package.mak, any files that begin with a period, or anything in the "package" directory. These files are generated when you build. Any modifications to these files are overwritten whenever you rebuild. 2.2.
Delivering a Codec Server In addition to including the server executable in the server package, you must also add the generated package/info/* files to the package. These files contain information in text form about the codecs included in the server, the server's memory map, and other relevant information. To create a deliverable package, we recommend you use the built-in method in XDC to create a .tar package archive, as shown in the following section. 2.3.
Delivering a Codec Server DSP servers built with Configuro do not require a package to build the server itself, but you must create one to produce a server deliverable. In that package, you must include both the server executable and the Configuro-generated "package/info/*" files. While each Configuro-using makefile is different, here's an example of how the server package generation may look.
This is a draft version printed from file: ce_serv_integIX.fm on 9/25/07 Index A D algorithm 2-6 specifying 2-10 Algorithm Creator 1-6, 2-2 all.
Index L link.cmd file 2-7, 2-16 linker commands 2-16 Linux 1-2 local codecs 2-5 M main.c file 2-7, 2-16 makefile 2-15, 2-16 middleware 1-4 MINPRI attribute 2-9 N name of server 2-16 O online help 1-9 P package creating 2-7 directory path 2-8 making a copy 2-8 naming 2-8 package directory 2-16 package.bld file 2-7, 2-15 package.mak file 2-16 package.xdc file 2-7, 2-8 path definitions 2-7 PrOS 1-2 server configuration 2-9 Server Integrator 1-7, 2-2 server name 2-16 Server, Codec 2-3 Server.
