4 C code structure

26.1733GPPANSI-C code for the Adaptive Multi-Rate - Wideband (AMR-WB) speech codecRelease 17TS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

This clause gives an overview of the structure of the bit‑exact C code and provides an overview of the contents and organization of the C code attached to this document.

The C code has been verified on the following systems:

– Sun Microsystems workstations and GNU gcc compiler

– HP workstations and cc compiler

– IBM PC compatible computers with Windows NT4 operating system and GNU gcc compiler.

ANSI‑C was selected as the programming language because portability was desirable.

4.1 Contents of the C source code

The C code distribution has all files in the root level.

The distributed files with suffix "c" contain the source code and the files with suffix "h" are the header files. The ROM data is contained mostly in files with suffix "tab".

The C code distribution also contains one speech coder installation verification data file, "spch_dos.inp". The reference encoder output file is named "spch_dos.cod", the reference decoder input file is named "spch_dos.dec" and the reference decoder output file is named "spch_dos.out". These four files are formatted such that they are correct for an IBM PC/AT compatible computer. The same files with reversed byte order of the 16 bit words are named "spch_unx.inp", "spch_unx.cod", "spch_unx.dec" and "spch_unx.out", respectively.

Final verification is to be performed using the GSM Adaptive Multi-Rate Wideband test sequences described in 3GPP TS 26.174 [1].

Makefiles are provided for the platforms in which the C code has been verified (listed above). Once the software is installed, this directory will have a compiled version of encoder and decoder (the bit-exact C executables of the speech codec) and all the object files.

4.2 Program execution

The GSM Adaptive Multi-Rate Wideband codec is implemented in two programs:

– (encoder) speech encoder;

– (decoder) speech decoder.

The programs should be called like:

– encoder [encoder options] <speech input file> <parameter file>;

– decoder <parameter file> <speech output file>.

The speech files contain 16-bit linear encoded PCM speech samples and the parameter files contain encoded speech data and some additional flags.

The encoder and decoder options will be explained by running the applications without input arguments. See the file readme.txt for more information on how to run the encoder and decoder programs.

4.3 Code hierarchy

Tables 1 to 3 are call graphs that show the functions used in the speech codec, including the functions of VAD, DTX, and comfort noise generation.

Each column represents a call level and each cell a function. The functions contain calls to the functions in rightwards neighbouring cells. The time order in the call graphs is from the top downwards as the processing of a frame advances. All standard C functions: printf(), fwrite(), etc. have been omitted. Also, no basic operations (add(), L_add(), mac(), etc.) or double precision extended operations (e.g. L_Extract()) appear in the graphs. The initialization of the static RAM (i.e. calling the _init functions) is also omitted.

The basic operations are not counted as extending the depth, therefore the deepest level in this software is level 6.

The encoder call graph is broken down into two separate call graphs, Table 1 to 2.

Table 1: Speech encoder call structure

coder	Copy
	Decim_12k8	Down_samp	Interpol (function)
		Copy
	Set_zero
	HP50_12k8
	Scale_sig
	wb_vad	Filter_bank	Filter5
			Filter3
			Level_calculation
		vad_decision	Ilog2
			Noise_estimate_update	update_cntrl
			hangover_addition
		Estimate_Speech
	tx_dtx_handler
	Parm_serial
	Autocorr
	Lag_window
	Levinson
	Az_isp	Chebps2
	Int_isp	Isp_Az	Get_isp_pol
	Isp_isf
	Gp_clip_test_isf
	Weight_a
	Residu
	Deemph2
	LP_Decim2
	Scale_mem_Hp_wsp
	Pitch_med_ol	Hp_wsp
		Isqrt_n
	wb_vad_tone_detection
	Med_olag	median5
	dtx_buffer	Copy
	dtx_enc	Find_frame_indices
		Aver_isf_history
		Qisf_ns	Sub_VQ
			Disf_ns	Reorder_isf
		Parm_serial
		Pow2
		Random
		Dot_product12
		Isqrt_n
	Isf_isp
	Isp_Az	Get_isp_pol
	Synthesis	Copy
		Syn_filt_32
		Deemph_32
		HP50_12k8
		Random
		Scale_sig
		Dot_product12
		Isqrt_n
		HP400_12k8
		Weight_a
		Syn_filt
		Filt_6k_7k
	Reset_encoder	Set_zero
		Init_gp_clip
		Init_Phase_dispersion	Set_zero
	Qpisf_2s_36b	VQ_stage1
		Sub_VQ
		Dpisf_2s_36b	Reorder_isf
	Qpisf_2s_46b	VQ_stage1
		Sub_VQ
		Dpisf_2s_46b	Reorder_isf
	Syn_filt
	Preemph2
	Pitch_fr4	Norm_Corr	Convolve
			Isqrt_n
		Interpol_4
	Gp_clip
	Pred_lt4
	Convolve
	G_pitch	Dot_product12
	Updt_tar
	Preemph
	Pit_shrp
	Cor_h_x
	ACELP_2t64_fx	Dot_product12
		Isqrt_n
	ACELP_4t64_fx	See Table 2
	Q_gain2	Dot_product12
		Pow2
	Gp_clip_test_gain_pit
	voice_factor	Dot_product12

Table 2: ACELP_4t64_fx call structure

ACELP_4t64_fx	Dot_product12
	Isqrt_n
	cor_h_vec
	search_ixiy
	quant_1p_N1
	quant_2p_2N1
	quant_3p_3N1	quant_2p_2N1
		quant_1p_N1
	quant_4p_4N	quant_4p_4N1	Quant_2p_2N1
		quant_1p_N1
		quant_3p_3N1	Quant_2p_2N1
			Quant_1p_N1
		quant_2p_2N1
	quant_5p_5N	quant_3p_3N1	Quant_2p_2N1
			Quant_1p_N1
		quant_2p_2N1
	quant_6p_6N_2	quant_5p_5N	Quant_3p_3N1	quant_2p_2N1
				Quant_1p_N1
			quant_2p_2N1
		quant_1p_N1
		quant_4p_4N	quant_4p_4N1	quant_2p_2N1
			quant_1p_N1
			quant_3p_3N1	quant_2p_2N1
				quant_1p_N1
			quant_2p_2N1
		quant_2p_2N1
		quant_3p_3N1	quant_2p_2N1
			Quant_1p_N1

Table 3: Speech decoder call structure

decoder	Rx_dtx_handler
	Dtx_dec	Copy
		Disf_ns	Reorder_isf
		Serial_parm
		Pow2
		Random
		Dot_product12
		Isqrt_n
	Serial_parm
	Isf_isp
	Isp_Az	Get_isp_pol
	Copy
	Synthesis	Copy
		Syn_filt_32
		Deemph_32
		HP50_12k8
		Oversamp_16k	Copy
			Up_samp	Interpol
		Random
		Scale_sig
		Dot_product12
		Isqrt_n
		HP400_12k8
		Isf_Extrapolation	Isf_isp
		Isp_Az	Get_isp_pol
		Weight_a
		Syn_filt
		Filt_6k_7k	Copy
		Filt_7k	Copy
	Reset_decoder	Set_zero
		Init_Phase_dispersion	Set_zero
	Dpisf_2s_36b	Reorder_isf
	Dpisf_2s_46b	Reorder_isf
	Int_isp	Isp_Az	Get_isp_pol
	Lagconc	insertion_sort	Insert
		Random
	Pred_lt4
	Random
	DEC_ACELP_2t64_fx
	DEC_ACELP_4t64_fx	dec_1p_N1
		add_pulses
		dec_2p_2N1
		dec_3p_3N1	Dec_2p_2N1
			dec_1p_N1
		dec_4p_4N	dec_4p_4N1	dec_2p_2N1
			dec_1p_N1
			Dec_3p_3N1	Dec_2p_2N1
				Dec_1p_N1
			Dec_2p_2N1
		dec_5p_5N	dec_3p_3N1	Dec_2p_2N1
				Dec_1p_N1
			Dec_2p_2N1
		dec_6p_6N_2	Dec_5p_5N	dec_3p_3N1	Dec_2p_2N1
					Dec_1p_N1
				dec_2p_2N1
			dec_1p_N1
			dec_4p_4N	dec_4p_4N1	dec_2p_2N1
				dec_1p_N1
				Dec_3p_3N1	Dec_2p_2N1
					Dec_1p_N1
				Dec_2p_2N1
			dec_2p_2N1
			dec_3p_3N1	Dec_2p_2N1
				Dec_1p_N1
	Preemph
	Pit_shrp
	D_gain2	Dot_product12
		Isqrt_n
		Median5
		Pow2
	Scale_sig
	voice_factor	Dot_product12
	Phase_dispersion	Set_zero
	Agc2	Isqrt	Isqrt_n
	Set_zero
	Dtx_dec_activity_update	Copy

4.5 Variables, constants and tables

The data types of variables and tables used in the fixed point implementation are signed integers in 2’s complement representation, defined by:

– Word16 16 bit variable;

– Word32 32 bit variable.

4.5.1 Description of constants used in the C-code

This subclause contains a listing of all global constants defined in cnst.h.

Table 5: Global constants

Constant	Value	Description
L_TOTAL	384	total size of speech buffer.
L_WINDOW	384	window size in LP analysis
L_NEXT	64	Look-ahead size
L_FRAME	256	frame size in 12.8 kHz
L_FRAME16k	320	frame size in 16 kHz
L_SUBFR	64	Subframe size in 12.8 kHz
L_SUBFR16k	80	Subframe size in 16 kHz
NB_SUBFR	4	Number of subframes
M16k	20	order of LP filter in high-band synthesis in 6.60 mode
M	16	order of LP filter
L_FILT16k	15	Delay of down-sampling filter in 16 kHz
L_FILT	12	Delay of down-sampling filter in 12.8 kHz
GP_CLIP	15565	Pitch gain clipping
PIT_SHARP	27853	pitch sharpening factor
PIT_MIN	34	minimum pitch lag (all modes)
PIT_FR2	128	Minimum pitch lag with resolution ½
PIT_FR1_9b	160	Minimum pitch lag with resolution for 9 bit quantization
PIT_FR1_8b	92	Minimum pitch lag with resolution for 8 bit quantization
PIT_MAX	231	maximum pitch lag
L_INTERPOL	(16+1)	length of filter for interpolation
OPL_DECIM	2	Decimation in open-loop pitch analysis
PREEMPH_FAC	22282	preemphasis factor
GAMMA1	30147	Weighting factor (numerator)
TILT_FAC	22282	tilt factor (denominator)
Q_MAX	8	scaling max for signal
RANDOM_INITSEED	21845	random init value
L_MEANBUF	3	Size of ISF buffer
ONE_PER_MEANBUF	10923	Inverse of L_MEANBUF

4.5.2 Description of fixed tables used in the C-code

This section contains a listing of all fixed tables sorted by source file name and table name. All table data is declared as Word16.

Table 6: Fixed tables

File	Table name	Length	Description
c4t64fx.c	tipos	36	Starting points of iterations
cod_main.c	HP_gain	16	High band gain table for 23.85 kbit/s mode
cod_main.c	interpol_frac	4	LPC interpolation coefficients
cod_main.c	isp_init	16	Isp tables for initialization
cod_main.c	isf_init	16	Isf tables for initialization
d_gain2.c	cdown_unusable	7	Attenuation factors for codebook gain in lost frames
d_gain2.c	cdown_usable	7	Attenuation factors for codebook gain in bad frames
d_gain2.c	pdown_unusable	7	Attenuation factors for adaptive codebook gain in lost frames
d_gain2.c	pdown_usable	7	Attenuation factors for adaptive codebook gain in bad frames
d_gain2.c	pred	4	Algebraic code book gain MA predictor coefficients
dec_main.c	HP_gain	16	High band gain table for 23.85 kbit/s mode
dec_main.c	interpol_frac	4	LPC interpolation coefficients
dec_main.c	isp_init	16	Isp tables for initialization
dec_main.c	isf_init	16	Isf tables for initialization
decim54.c	fir_down	120	Downsample FIR filter coefficients
decim54.c	fir_up	120	Upsample FIR filter coefficients
dtx.c	en_adjust	9	Energy scaling factor for each mode during comfort noise
grid100.tab	grid	101	Grid points of Chebyshev polynomials
ham_wind.tab	window	384	LP analysis window
hp400.c	a	3	HP filter coefficients (denominator) in higher band energy estimation
hp400.c	b	3	HP filter coefficients (numerator) in higher band energy estimation
hp50.c	a	3	HP filter coefficients (denominator) in pre-filtering
hp50.c	b	3	HP filter coefficients (numerator) in pre-filtering
hp6k.c	fir_6k_7k	31	Bandpass FIR filter coefficients for higher band generation
hp7k.c	fir_7k	31	Bandpass FIR filter coefficients for higher band in 23.85 kbit/s mode
hp_wsp.c	a	3	HP filter coefficients (denominator) in open-loop lag gain computation
hp_wsp.c	b	3	HP filter coefficients (numerator) in open-loop lag gain computation
isp_isf.tab	slope	128	Table to compute acos(x) in Isp_isf()
isp_isf.tab	table	129	Table to compute cos(x) in Isf_isp()
lag_wind.tab	lag_h	16	High part of the lag window table
lag_wind.tab	lag_l	16	Low part of the lag window table
lp_dec2.c	h_fir	5	HP FIR filter coefficients in open-loop lag search
math_op.c	table_isqrt	49	Table used in inverse square root computation
math_op.c	table_pow2	33	Table used in power of two computation
p_med_ol.tab	corrweight	199	Weighting of the correlation function in open loop LTP search
ph_disp.c	ph_imp_low	64	Phase dispersion impulse response
ph_disp.c	ph_imp_mid	64	Phase dispersion impulse response
pitch_f4.c	inter4_1	32	Interpolation filter coefficients
pred_lt4.c	inter4_2	128	Interpolation filter coefficients
q_gain2.c	pred	4	Algebraic code book gain MA predictor coefficients
q_gain2.tab	t_qua_gain6b	2*64	Gain quantization table for 6-bit gain quantization
q_gain2.tab	t_qua_gain7b	2*128	Gain quantization table for 7-bit gain quantization
qisf_ns.tab	dico1_isf_noise	2*64	1st ISF quantizer for comfort noise
qisf_ns.tab	dico2_isf_noise	3*64	2nd ISF quantizer for comfort noise
qisf_ns.tab	dico3_isf_noise	3*64	3rd ISF quantizer for comfort noise
qisf_ns.tab	dico4_isf_noise	4*32	4th ISF quantizer for comfort noise
qisf_ns.tab	dico5_isf_noise	4*32	5th ISF quantizer for comfort noise
qisf_ns.tab	mean_isf_noise	16	ISF mean for comfort noise
qpisf_2s.tab	dico1_isf	9*256	1st ISF quantizer of the 1st stage
qpisf_2s.tab	dico2_isf	7*256	2nd ISF quantizer of the 1st stage
qpisf_2s.tab	dico21_isf	3*64	1st ISF quantizer of the 2nd stage (not the 6.60 kbit/s mode)
qpisf_2s.tab	dico21_isf_36b	5*128	1st ISF quantizer of the 2nd stage (the 6.60 kbit/s mode)
qpisf_2s.tab	dico22_isf	3*128	2nd ISF quantizer of the 2nd stage (not the 6.60 kbit/s mode)
qpisf_2s.tab	dico22_isf_36b	4*128	2nd ISF quantizer of the 2nd stage (the 6.60 kbit/s mode)
qpisf_2s.tab	dico23_isf	3*128	3rd ISF quantizer of the 2nd stage (not the 6.60 kbit/s mode)
qpisf_2s.tab	dico23_isf_36b	7*64	3rd ISF quantizer of the 2nd stage (the 6.60 kbit/s mode)
qpisf_2s.tab	dico24_isf	3*32	4th ISF quantizer of the 2nd stage (not the 6.60 kbit/s mode)
qpisf_2s.tab	dico25_isf	4*32	5th ISF quantizer of the 2nd stage (not the 6.60 kbit/s mode)
qpisf_2s.tab	mean_isf	16	ISF mean

4.5.3 Static variables used in the C-code

In this section two tables that specify the static variables for the speech encoder and decoder respectively are shown. All static variables are declared within a C struct.

Table 7: Speech encoder static variables

Struct name	Variable	Type[Length]	Description
Coder_State	mem_decim	Word16[30]	Decimation filter memory
	mem_sig_in	Word16[6]	Prefilter memory
	mem_preemph	Word16	Preemphasis filter memory
	old_speech	Word16[128]	speech buffer
	old_wsp	Word16[115]	buffer holding spectral weighted speech
	old_exc	Word16[248]	excitation vector
	mem_levinson	Word16[18]	Levinson memories
	Ispold	Word16[16]	Old ISP vector
	ispold_q	Word16[16]	Old quantized ISP vector
	past_isfq	Word16[16]	past quantized ISF prediction error
	mem_wsp	Word16	Open-loop LTP deemphasis filter memory
	mem_decim2	Word16[3]	Open-loop LTP decimation filter memory
	mem_w0	Word16	weighting filter memory (applied to error signal)
	mem_syn	Word16[16]	synthesis filter memory
	tilt_code	Word16	Preemhasis filter memory
	old_wsp_max	Word16	Open loop scaling factor
	old_wsp_shift	Word16	Maximum open loop scaling factor
	Q_old	Word16	Old scaling factor
	Q_max	Word16[2]	Maximum scaling factor
	gp_clip	Word16[2]	memory of pitch clipping
	qua_gain	Word16[4]	Gain quantization memory
	old_T0_med	Word16	weighted open loop pitch lag
	ol_gain	Word16	Open-loop gain
	ada_w	Word16	weigthing level depeding on open loop pitch gain
	ol_wght_flg	Word16	switches lag weighting on and off
	old_ol_lag	Word16[5]	Open loop lag history
	hp_wsp_mem	Word16[9]	Open-loop lag gain filter memory
	old_hp_wsp	Word16[243]	Open-loop lag
	vadSt	VadVars*	see below in this table
	dtx_encSt	dtx_encState*	see below in this table
	first_frame	Word16	First frame indicator
	Isfold	Word16[16]	Old ISF vector
	L_gc_thres	Word16	Noise enhancer threshold
	mem_syn_hi	Word16[16]	synthesis filter memory (most significant word)
	mem_syn_lo	Word16[16]	synthesis filter memory (least significant word)
	mem_deemph	Word16	Deemphasis filter memory
	mem_sig_out	Word16[6]	HP filter memory in the synthesis
	mem_hp400	Word16[6]	HP filter memory
	mem_oversamp	Word16[2*12]	Oversampling filter memory
	mem_syn_hf	Word16[16]	Higher band synthesis filter memory
	mem_hf	Word16[30]	Estimated BP filter memory (23.85 kbit/s mode)
	mem_hf2	Word16[30]	Input BP filter memory (23.85 kbit/s mode)
	mem_hf3	Word16[30]	Input LP filter memory (23.85 kbit/s mode)
	seed2	Word16	Random generation seed
	disp_mem	Word16[8]	Phase dispersion memory
	vad_hist	Word16	VAD history
	Gain_alpha	Word16	Higher band gain weighting factor (23.85 kbit/s mode)
dtx_encState	Isf_hist	Word16[128]	LSP history (8 frames)
	Log_en_hist	Word16[8]	logarithmic frame energy history (8 frames)
	Hist_ptr	Word16	pointer to the cyclic history vectors
	Log_en_index	Word16	Index for logarithmic energy
	Cng_seed	Word16	Comfort noise excitation seed
	D	Word16[28]	ISF history distance matrix
	sumD	Word16[8]	Sum of ISF history distances
	dtxHangoverCount	Word16	is decreased in DTX hangover period
	decAnaElapsedCount	Word16	counter for elapsed speech frames in DTX
vadState1	bckr_est	Word16[12]	background noise estimate
	ave_level	Word16[12]	averaged input components for stationary estimation
	old_level	Word16[12]	input levels of the previous frame
	sub_level	Word16[12]	input levels calculated at the end of a frame (lookahead)
	a_data5	Word16[5][2]	memory for the filter bank
	a_data3	Word16[6]	memory for the filter bank
	burst_count	Word16	counts length of a speech burst
	Hang_count	Word16	hangover counter
	Stat_count	Word16	stationary counter
	Vadreg	Word16	15 flags for intermediate VAD decisions
	Tone_flag	Word16	15 flags for tone detection
	sp_est_cnt	Word16	Speech level estimation counter
	Sp_max	Word16	Maximum signal level
	sp_max_cnt	Word16	Maximum level estimation counter
	Speech_level	Word16	Speech level
	prev_pow_sum	Word16	Power of previous frame

Table 8: Speech decoder static variables

Struct name	Variable	Type[Length]	Description
Decoder_State	old_exc	Word16[248]	excitation vector
	ispold	Word16[16]	Old ISP vector
	isfold	Word16[16]	Old ISF vector
	isf_buf	Word16[48]	ISF vector history
	past_isfq	Word16[16]	past quantized ISF prediction error
	tilt_code	Word16	Preemhasis filter memory
	Q_old	Word16	Old scaling factor
	Qsubfr	Word16	Scaling factor history
	L_gc_thres	Word16	Noise enhancer threshold
	mem_syn_hi	Word16[16]	synthesis filter memory (most significant word)
	mem_syn_lo	Word16[16]	synthesis filter memory (least significant word)
	mem_deemph	Word16	Deemphasis filter memory
	mem_sig_out	Word16[6]	HP filter memory in the synthesis
	mem_oversamp	Word16[24]	Oversampling filter memory
	mem_syn_hf	Word16[20]	Higher band synthesis filter memory
	mem_hf	Word16[30]	Estimated BP filter memory (23.85 kbit/s mode)
	mem_hf2	Word16[30]	Input BP filter memory (23.85 kbit/s mode)
	mem_hf3	Word16[30]	Input LP filter memory (23.85 kbit/s mode)
	seed	Word16	Random code generation seed for bad frames
	seed2	Word16	Random generation seed for higher band
	old_T0	Word16	Old LTP lag (integer part)
	old_T0_frac	Word16	Old LTP lag (fraction part)
	lag_hist	Word16[5]	LTP lag history
	dec_gain	Word16[23]	Gain decoding memory
	seed3	Word16	Random LTP lag generation seed for bad frames
	disp_mem	Word16[8]	Phase dispersion memory
	mem_hp400	Word16[6]	HP filter memory
	prev_bfi	Word16	Previous BFI
	state	Word16	BGH state machine memory
	first_frame	Word16	First frame indicator
	dtx_decSt	dtx_decState*	see below in this table
	Vad_hist	Word16	VAD history
dtx_decState	Since_last_sid	Word16	number of frames since last SID frame
	true_sid_period_inv	Word16	inverse of true SID update rate
	log_en	Word16	logarithmic frame energy
	old_log_en	Word16	previous value of log_en
	isf	Word16[16]	ISF vector
	Isf_old	Word16[16]	Previous ISF vector
	Cng_seed	Word16	Comfort noise excitation seed
	Isf_hist	Word16[128]	ISF vector history (8 frames)
	Log_en_hist	Word16[8]	logarithmic frame energy history
	Hist_ptr	Word16	index to beginning of LSF history
	dtxHangoverCount	Word16	counts down in hangover period
	DecAnaElapsedCount	Word16	counts elapsed speech frames after DTX
	sid_frame	Word16	flags SID frames
	valid_data	Word16	flags SID frames containing valid data
	log_en_adjust	Word16	mode-dependent frame energy adjustment
	dtxHangoverAdded	Word16	flags hangover period at end of speech
	dtxGlobalState	Word16	DTX state flags
	data_updated	Word16	flags CNI updates