readme.txt.svn-base

MP3 for ARM codec. [asm+C]

Fixed-point HE-AAC decoder
Developed by RealNetworks, 2005
===============================

Overview
--------
This module contains a high-performance HE-AAC decoder for 32-bit fixed-point 
processors. The following is a summary of what is and is not supported:

Supported:
 - MPEG2, MPEG4 low complexity decoding (intensity stereo, M-S, TNS, PNS)
 - spectral band replication (SBR), high-quality mode
 - mono, stereo, and multichannel modes
 - ADTS, ADIF, and raw data block file formats

Not currently supported:
 - main or SSR profile, LTP
 - coupling channel elements (CCE)
 - 960/1920-sample frame size
 - low-power mode SBR
 - downsampled (single-rate) SBR
 - parametric stereo

Highlights
----------
 - highly optimized for ARM processors (details in docs/ subdirectory)
 - reference x86 implementation
 - C and assembly code only (C++ not required for codec library)
 - reentrant, statically linkable
 - low memory (details in docs/ subdirectory)
 - option to use Intel Integrated Performance Primitives (details below)

Supported platforms and toolchains
----------------------------------
This codec should run on any 32-bit fixed-point processor which can perform a full 32x32-bit 
multiply (providing a 64-bit result). The following processors and toolchains are supported:
 - x86, Microsoft Visual C++
 - x86, GNU toolchain (gcc)
 - ARM, ARM Developer Suite (ADS)
 - ARM, Microsoft Embedded Visual C++
 - ARM, GNU toolchain (gcc)

ARM refers to any processor supporting ARM architecture v.4 or above. Thumb is not required.

Generally ADS produces the fastest code. EVC 3 does not support inline assembly code for
ARM targets, so calls to MULSHIFT32 (smull on ARM) are left as function calls. This incurs
a significant performance penalty. For the fastest code on targets which do not normally use 
ADS consider compiling with ADS, using the -S option to output assembly code, and 
feeding this assembly code to the assembler of your choice. This might require some 
syntax changes in the .S file.

Adding support for a new processor is fairly simple. Simply add a new block to the file 
real/assembly.h which implements the required inline assembly functions for your processor. 
Something like

...
#elif defined NEW_PROCESSOR

/* you implement MULSHIFT32() and so forth */

#else
#error Unsupported platform in assembly.h
#endif

Optionally you can rewrite or add assembly language files optimized for your platform. Note 
that many of the algorithms are designed for an ARM-type processor, so performance of the
unmodified C code might be noticeably worse on other architectures. 

Adding support for a new toolchain is straightforward. Use the sample projects or the
Helix makefiles as a template for which source files to include.

Multichannel
------------
For multichannel, just set AAC_MAX_NCHANS in pub/aacdec.h to the desired max number 
of channels (default = 2) and recompile. This increases RAM usage since more memory 
is required to save state for multiple channels. See docs/memory.xls for details.
  
Directory structure
-------------------
fixpt/           platform-independent code and tables, public API
fixpt/docs       memory and CPU usage figures, callgraphs
fixpt/hxwrap     Helix wrapper code and makefiles
fixpt/ipp        source code which uses IPP for decoding (see the "IPP" section below)
fixpt/pub        public header files
fixpt/real       source code for RealNetworks' AAC decoder
fixpt/testwrap   sample code to build a command-line test application

Code organization
-----------------
fixpt/
  aacdec.c       main decode functions, exports C-only API
  aactabs.c      common tables used by all implementations
fixpt/pub/
  aaccommon.h    low-level codec API which aacdec.c calls
  aacdec.h       high-level codec API which applications call
  statname.h     symbols which get name-mangled by C preprocessor to allow static linking
fixpt/ipp        source code for wrapper files which link in IPP libraries
fixpt/real       full source code for RealNetworks AAC decoder, including SBR
fixpt/real/asm   optimized assembly code files for certain platforms

To build an AAC decoder library, you'll need to compile the top-level files and EITHER 
real/*.c OR ipp/*.c and the appropriate IPP library. 

Decoder using Real code: aacdec.c + aactabs.c + real/*.c + real/asm/[platform]/*.s (if necessary)
Decoder using IPP code:  aacdec.c + aactabs.c + ipp/*.c + ippac*.lib

IPP 
--- 
For certain platforms Intel