g711.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * g711.h - In line A-law and u-law conversion routines
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2001 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU Lesser General Public License version 2.1,
00014  * as published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  */
00025 
00026 /*! \file */
00027 
00028 /*! \page g711_page A-law and mu-law handling
00029 Lookup tables for A-law and u-law look attractive, until you consider the impact
00030 on the CPU cache. If it causes a substantial area of your processor cache to get
00031 hit too often, cache sloshing will severely slow things down. The main reason
00032 these routines are slow in C, is the lack of direct access to the CPU's "find
00033 the first 1" instruction. A little in-line assembler fixes that, and the
00034 conversion routines can be faster than lookup tables, in most real world usage.
00035 A "find the first 1" instruction is available on most modern CPUs, and is a
00036 much underused feature. 
00037 
00038 If an assembly language method of bit searching is not available, these routines
00039 revert to a method that can be a little slow, so the cache thrashing might not
00040 seem so bad :(
00041 
00042 Feel free to submit patches to add fast "find the first 1" support for your own
00043 favourite processor.
00044 
00045 Look up tables are used for transcoding between A-law and u-law, since it is
00046 difficult to achieve the precise transcoding procedure laid down in the G.711
00047 specification by other means.
00048 */
00049 
00050 #if !defined(_SPANDSP_G711_H_)
00051 #define _SPANDSP_G711_H_
00052 
00053 /* The usual values to use on idle channels, to emulate silence */
00054 /*! Idle value for A-law channels */
00055 #define G711_ALAW_IDLE_OCTET        0x5D
00056 /*! Idle value for u-law channels */
00057 #define G711_ULAW_IDLE_OCTET        0xFF
00058 
00059 enum
00060 {
00061     G711_ALAW = 0,
00062     G711_ULAW
00063 };
00064 
00065 /*!
00066     G.711 state
00067  */
00068 typedef struct g711_state_s g711_state_t;
00069 
00070 #if defined(__cplusplus)
00071 extern "C"
00072 {
00073 #endif
00074 
00075 /* N.B. It is tempting to use look-up tables for A-law and u-law conversion.
00076  *      However, you should consider the cache footprint.
00077  *
00078  *      A 64K byte table for linear to x-law and a 512 byte table for x-law to
00079  *      linear sound like peanuts these days, and shouldn't an array lookup be
00080  *      real fast? No! When the cache sloshes as badly as this one will, a tight
00081  *      calculation may be better. The messiest part is normally finding the
00082  *      segment, but a little inline assembly can fix that on an i386, x86_64 and
00083  *      many other modern processors.
00084  */
00085  
00086 /*
00087  * Mu-law is basically as follows:
00088  *
00089  *      Biased Linear Input Code        Compressed Code
00090  *      ------------------------        ---------------
00091  *      00000001wxyza                   000wxyz
00092  *      0000001wxyzab                   001wxyz
00093  *      000001wxyzabc                   010wxyz
00094  *      00001wxyzabcd                   011wxyz
00095  *      0001wxyzabcde                   100wxyz
00096  *      001wxyzabcdef                   101wxyz
00097  *      01wxyzabcdefg                   110wxyz
00098  *      1wxyzabcdefgh                   111wxyz
00099  *
00100  * Each biased linear code has a leading 1 which identifies the segment
00101  * number. The value of the segment number is equal to 7 minus the number
00102  * of leading 0's. The quantization interval is directly available as the
00103  * four bits wxyz.  * The trailing bits (a - h) are ignored.
00104  *
00105  * Ordinarily the complement of the resulting code word is used for
00106  * transmission, and so the code word is complemented before it is returned.
00107  *
00108  * For further information see John C. Bellamy's Digital Telephony, 1982,
00109  * John Wiley & Sons, pps 98-111 and 472-476.
00110  */
00111 
00112 /* Enable the trap as per the MIL-STD */
00113 //#define G711_ULAW_ZEROTRAP
00114 /*! Bias for u-law encoding from linear. */
00115 #define G711_ULAW_BIAS      0x84
00116 
00117 /*! \brief Encode a linear sample to u-law
00118     \param linear The sample to encode.
00119     \return The u-law value.
00120 */
00121 static __inline__ uint8_t linear_to_ulaw(int linear)
00122 {
00123     uint8_t u_val;
00124     int mask;
00125     int seg;
00126 
00127     /* Get the sign and the magnitude of the value. */
00128     if (linear >= 0)
00129     {
00130         linear = G711_ULAW_BIAS + linear;
00131         mask = 0xFF;
00132     }
00133     else
00134     {
00135         linear = G711_ULAW_BIAS - linear;
00136         mask = 0x7F;
00137     }
00138 
00139     seg = top_bit(linear | 0xFF) - 7;
00140 
00141     /*
00142      * Combine the sign, segment, quantization bits,
00143      * and complement the code word.
00144      */
00145     if (seg >= 8)
00146         u_val = (uint8_t) (0x7F ^ mask);
00147     else
00148         u_val = (uint8_t) (((seg << 4) | ((linear >> (seg + 3)) & 0xF)) ^ mask);
00149 #if defined(G711_ULAW_ZEROTRAP)
00150     /* Optional ITU trap */
00151     if (u_val == 0)
00152         u_val = 0x02;
00153 #endif
00154     return  u_val;
00155 }
00156 /*- End of function --------------------------------------------------------*/
00157 
00158 /*! \brief Decode an u-law sample to a linear value.
00159     \param ulaw The u-law sample to decode.
00160     \return The linear value.
00161 */
00162 static __inline__ int16_t ulaw_to_linear(uint8_t ulaw)
00163 {
00164     int t;
00165     
00166     /* Complement to obtain normal u-law value. */
00167     ulaw = ~ulaw;
00168     /*
00169      * Extract and bias the quantization bits. Then
00170      * shift up by the segment number and subtract out the bias.
00171      */
00172     t = (((ulaw & 0x0F) << 3) + G711_ULAW_BIAS) << (((int) ulaw & 0x70) >> 4);
00173     return  (int16_t) ((ulaw & 0x80)  ?  (G711_ULAW_BIAS - t)  :  (t - G711_ULAW_BIAS));
00174 }
00175 /*- End of function --------------------------------------------------------*/
00176 
00177 /*
00178  * A-law is basically as follows:
00179  *
00180  *      Linear Input Code        Compressed Code
00181  *      -----------------        ---------------
00182  *      0000000wxyza             000wxyz
00183  *      0000001wxyza             001wxyz
00184  *      000001wxyzab             010wxyz
00185  *      00001wxyzabc             011wxyz
00186  *      0001wxyzabcd             100wxyz
00187  *      001wxyzabcde             101wxyz
00188  *      01wxyzabcdef             110wxyz
00189  *      1wxyzabcdefg             111wxyz
00190  *
00191  * For further information see John C. Bellamy's Digital Telephony, 1982,
00192  * John Wiley & Sons, pps 98-111 and 472-476.
00193  */
00194 
00195 /*! The A-law alternate mark inversion mask */
00196 #define G711_ALAW_AMI_MASK      0x55
00197 
00198 /*! \brief Encode a linear sample to A-law
00199     \param linear The sample to encode.
00200     \return The A-law value.
00201 */
00202 static __inline__ uint8_t linear_to_alaw(int linear)
00203 {
00204     int mask;
00205     int seg;
00206     
00207     if (linear >= 0)
00208     {
00209         /* Sign (bit 7) bit = 1 */
00210         mask = G711_ALAW_AMI_MASK | 0x80;
00211     }
00212     else
00213     {
00214         /* Sign (bit 7) bit = 0 */
00215         mask = G711_ALAW_AMI_MASK;
00216         linear = -linear - 1;
00217     }
00218 
00219     /* Convert the scaled magnitude to segment number. */
00220     seg = top_bit(linear | 0xFF) - 7;
00221     if (seg >= 8)
00222     {
00223         if (linear >= 0)
00224         {
00225             /* Out of range. Return maximum value. */
00226             return (uint8_t) (0x7F ^ mask);
00227         }
00228         /* We must be just a tiny step below zero */
00229         return (uint8_t) (0x00 ^ mask);
00230     }
00231     /* Combine the sign, segment, and quantization bits. */
00232     return (uint8_t) (((seg << 4) | ((linear >> ((seg)  ?  (seg + 3)  :  4)) & 0x0F)) ^ mask);
00233 }
00234 /*- End of function --------------------------------------------------------*/
00235 
00236 /*! \brief Decode an A-law sample to a linear value.
00237     \param alaw The A-law sample to decode.
00238     \return The linear value.
00239 */
00240 static __inline__ int16_t alaw_to_linear(uint8_t alaw)
00241 {
00242     int i;
00243     int seg;
00244 
00245     alaw ^= G711_ALAW_AMI_MASK;
00246     i = ((alaw & 0x0F) << 4);
00247     seg = (((int) alaw & 0x70) >> 4);
00248     if (seg)
00249         i = (i + 0x108) << (seg - 1);
00250     else
00251         i += 8;
00252     return (int16_t) ((alaw & 0x80)  ?  i  :  -i);
00253 }
00254 /*- End of function --------------------------------------------------------*/
00255 
00256 /*! \brief Transcode from A-law to u-law, using the procedure defined in G.711.
00257     \param alaw The A-law sample to transcode.
00258     \return The best matching u-law value.
00259 */
00260 SPAN_DECLARE(uint8_t) alaw_to_ulaw(uint8_t alaw);
00261 
00262 /*! \brief Transcode from u-law to A-law, using the procedure defined in G.711.
00263     \param ulaw The u-law sample to transcode.
00264     \return The best matching A-law value.
00265 */
00266 SPAN_DECLARE(uint8_t) ulaw_to_alaw(uint8_t ulaw);
00267 
00268 /*! \brief Decode from u-law or A-law to linear.
00269     \param s The G.711 context.
00270     \param amp The linear audio buffer.
00271     \param g711_data The G.711 data.
00272     \param g711_bytes The number of G.711 samples to decode.
00273     \return The number of samples of linear audio produced.
00274 */
00275 SPAN_DECLARE(int) g711_decode(g711_state_t *s,
00276                               int16_t amp[],
00277                               const uint8_t g711_data[],
00278                               int g711_bytes);
00279 
00280 /*! \brief Encode from linear to u-law or A-law.
00281     \param s The G.711 context.
00282     \param g711_data The G.711 data.
00283     \param amp The linear audio buffer.
00284     \param len The number of samples to encode.
00285     \return The number of G.711 samples produced.
00286 */
00287 SPAN_DECLARE(int) g711_encode(g711_state_t *s,
00288                               uint8_t g711_data[],
00289                               const int16_t amp[],
00290                               int len);
00291 
00292 /*! \brief Transcode between u-law and A-law.
00293     \param s The G.711 context.
00294     \param g711_out The resulting G.711 data.
00295     \param g711_in The original G.711 data.
00296     \param g711_bytes The number of G.711 samples to transcode.
00297     \return The number of G.711 samples produced.
00298 */
00299 SPAN_DECLARE(int) g711_transcode(g711_state_t *s,
00300                                  uint8_t g711_out[],
00301                                  const uint8_t g711_in[],
00302                                  int g711_bytes);
00303 
00304 /*! Initialise a G.711 encode or decode context.
00305     \param s The G.711 context.
00306     \param mode The G.711 mode.
00307     \return A pointer to the G.711 context, or NULL for error. */
00308 SPAN_DECLARE(g711_state_t *) g711_init(g711_state_t *s, int mode);
00309 
00310 /*! Release a G.711 encode or decode context.
00311     \param s The G.711 context.
00312     \return 0 for OK. */
00313 SPAN_DECLARE(int) g711_release(g711_state_t *s);
00314 
00315 /*! Free a G.711 encode or decode context.
00316     \param s The G.711 context.
00317     \return 0 for OK. */
00318 SPAN_DECLARE(int) g711_free(g711_state_t *s);
00319 
00320 #if defined(__cplusplus)
00321 }
00322 #endif
00323 
00324 #endif
00325 /*- End of file ------------------------------------------------------------*/

Generated on Thu Oct 18 15:26:53 2012 for spandsp by  doxygen 1.4.7