readme.txt
1 Fixed-point MP3 decoder 2 Developed by RealNetworks, 2003 3 =============================== 4 5 Overview 6 -------- 7 This module contains a high-performance MPEG layer 3 audio decoder for 32-bit fixed-point 8 processors. The following is a quick summary of what is and is not supported: 9 10 Supported 11 - layer 3 12 - MPEG1, MPEG2, and MPEG2.5 (low sampling frequency extensions) 13 - constant bitrate, variable bitrate, and free bitrate modes 14 - mono and all stereo modes (normal stereo, joint stereo, dual-mono) 15 16 Not currently supported 17 - layers 1 and 2 18 19 Highlights 20 ---------- 21 - highly optimized for ARM processors (details in docs/ subdirectory) 22 - reference x86 implementation 23 - C and assembly code only (C++ not required) 24 - reentrant, statically linkable 25 - low memory (details in docs/ subdirectory) 26 - option to use Intel Integrated Performance Primitives (details below) 27 28 Supported platforms and toolchains 29 ---------------------------------- 30 This codec should run on any 32-bit fixed-point processor which can perform a full 32x32-bit 31 multiply (providing a 64-bit result). The following processors and toolchains are supported: 32 - x86, Microsoft Visual C++ 33 - ARM, ARM Developer Suite (ADS) 34 - ARM, Microsoft Embedded Visual C++ 35 - ARM, GNU toolchain (gcc) 36 37 ARM refers to any processor supporting ARM architecture v.4 or above. Thumb is not required. 38 Typically this means an ARM7TDMI or better (including ARM9, StrongARM, XScale, etc.) 39 40 Generally ADS produces the fastest code. EVC 3.0 does not support inline assembly code for 41 ARM targets, so calls to MULSHIFT32 (smull on ARM) are left as function calls. For the 42 fastest code on targets which do not normally use ADS consider compiling with ADS, 43 using the -S option to output assembly code, and feeding this assembly code to the assembler 44 of your choice. This might require some syntax changes in the .S file. 45 46 Adding support for a new processor is fairly simple. Simply add a new block to the file 47 real/assembly.h which implements the required inline assembly functions for your processor. 48 Something like 49 50 ... 51 #elif defined NEW_PROCESSOR 52 53 /* you implement MULSHIFT32() and so forth */ 54 55 #else 56 #error Unsupported platform in assembly.h 57 #endif 58 59 Optionally you can rewrite or add assembly language files optimized for your platform. Note 60 that many of the algorithms are designed for an ARM-type processor, so performance of the 61 unmodified C code might be noticeably worse on other architectures. 62 63 Adding support for a new toolchain should be straightforward. Use the sample projects or the 64 Umakefil as a template for which source files to include. 65 66 Directory structure 67 ------------------- 68 fixpt/ platform-independent code and tables, public API 69 fixpt/docs algorithm notes, memory and CPU usage figures, optimization suggestions 70 fixpt/ipp source code which uses IPP for decoding (see the "IPP" section below) 71 fixpt/pub public header files 72 fixpt/real source code for RealNetworks' MP3 decoder 73 fixpt/testwrap sample code to build a command-line test application 74 75 Code organization 76 ----------------- 77 fixpt/ 78 mpadecobj.cpp optional shim which exports API used by Helix clients (see mp3/renderer) 79 mp3dec.c main decode functions, exports C-only API 80 mp3tabs.c common tables used by all implementations (bitrates, frame sizes, etc.) 81 fixpt/pub/ 82 mp3common.h defines low-level codec API which mp3dec.c calls 83 mp3dec.h defines high-level codec API which applications call 84 mpadecobjfixpt.h optional C++ shim API (only necessary if mpadecobj.cpp is used) 85 statname.h symbols which get name-mangled by C preprocessor to allow static linking 86 fixpt/ipp source code for wrapper files which link in IPP libraries 87 fixpt/real full source code for RealNetworks MP3 decoder 88 89 To build an MP3 decoder library, you'll need to compile the top-level files and EITHER 90 real/*.c OR ipp/*.c and the correct IPP library. 91 92 Decoder using Real code: mp3dec.c + mp3tabs.c + real/*.c + real/arm/[files].s (if ARM) 93 Decoder using IPP code: mp3dec.c + mp3tabs.c + ipp/*.c + ippac*.lib 94 95 Although the real/ and ipp/ source code follow the same top-level API (for Dequantize(), 96 Subband(), etc.) mixing and matching is not guaranteed to work. The outputs might 97 be ordered differently for optimization purposes, scaled differently, etc. 98 99 IPP 100 --- 101 For certain platforms Intel� has created highly-optimized object code libraries of DSP 102 routines. These are called the Intel� Integrated Performance Primitives (IPP). If IPP 103 libraries are available for a platform, this MP3 decoder can link them in and use them 104 instead of the RealNetworks source code. To use IPP, you still need to build the top-level 105 files (mp3dec.c, mp3tabs.c). You also build the files in ipp/*.c. These are just thin 106 wrappers which provide the glue logic between the top-level decode functions in 107 mp3dec.c and the optimized DSP primitives in the IPP libraries. IPP libraries are not 108 included in this module. You must obtain them WITH A LICENSE directly from Intel. 109 Further info on the latest versions of IPP (as of the date of this readme) is available 110 from the URLs below 111 112 Intel� Integrated Performance Primitives for the 113 Intel� PXA25x and PXA26x family of Processors, Version 3.0 114 * http://www.intel.com/design/pca/applicationsprocessors/swsup/IPPv30.htm 115 116 Intel� Integrated Performance Primitives for 117 Intel� Pentium� Processors and Intel� Itanium� Architectures 118 * http://www.intel.com/software/products/ipp/ipp30/ 119 120 These sites explain how to obtain IPP and the terms under which IPP libraries may be used. 121 The code in this module is merely wrapper code which calls IPP functions. You are fully 122 responsible for adhering to the license agreement under which you obtain the IPP 123 libraries from Intel. 124 125 To-Do list and status 126 --------------------- 127 faster/lower-memory dequantizer (in progress) 128 tighter fixed-point scaling (in progress) 129 remove all run-time math calls (/, %) (in progress) 130 ARM assembly code for DCT32, IMDCT (if necessary) 131 add test scripts and compliance docs 132 write 32-bit C polyphase filter 133 (where 64-bit MACC not available) 134 135 As these optimizations are completed, they will be added to the Helix codebase. Please 136 continue to check there for updates. Changes will be noted in this readme. 137 138 readme.txt last updated 07/23/03 139 140