From: Richard Mudgett <rmudgett@digium.com>
Date: Tue, 5 Aug 2014 19:12:40 +0000 (+0000)
Subject: format.c: Add reason comments for the format_list ordering.
X-Git-Tag: 12.5.0-rc1~25
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=92b343c219f181ffb7dd8fd483f198deb29652c9;p=thirdparty%2Fasterisk.git

format.c: Add reason comments for the format_list ordering.
........

Merged revisions 420054 from http://svn.asterisk.org/svn/asterisk/branches/11


git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/12@420060 65c4cc65-6c06-0410-ace0-fbb531ad65f3
---

diff --git a/main/format.c b/main/format.c
index d24e1c386f..ca9c2fab7d 100644
--- a/main/format.c
+++ b/main/format.c
@@ -1039,7 +1039,16 @@ static int format_list_init(void)
 	if (!(format_list = ao2_container_alloc(1, NULL, list_cmp_cb))) {
 		return -1;
 	}
-	/* initiate static entries XXX DO NOT CHANGE THIS ORDER! */
+	/*
+	 * initiate static entries XXX DO NOT CHANGE THIS ORDER!
+	 *
+	 * Reason:
+	 * The order is requried by chan_iax2 to send out the IAX_IE_CODEC_PREFS
+	 * list over the wire.  The following order is historical to how v1.8
+	 * and earlier listed the formats in format.c:AST_FORMAT_LIST[].  These
+	 * formats have format compatibility bits assigned which makes chan_iax2
+	 * in particular and other legacy modules aware of them.
+	 */
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_G723_1, 0), "g723", 8000, "G.723.1", 20, 30, 300, 30, 30, 0, 0);       /*!< G723.1 */
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_GSM, 0), "gsm",  8000, "GSM", 33, 20, 300, 20, 20, 0, 0);              /*!< codec_gsm.c */
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_ULAW, 0), "ulaw", 8000, "G.711 u-law", 80, 10, 150, 10, 20, 0, 0);     /*!< codec_ulaw.c */
@@ -1069,7 +1078,19 @@ static int format_list_init(void)
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_TESTLAW, 0), "testlaw", 8000, "G.711 test-law", 80, 10, 150, 10, 20, 0, 0);    /*!< codec_ulaw.c */
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_G719, 0), "g719", 48000, "ITU G.719", 160, 20, 80, 20, 20, 0, 0);
 
-	/* ORDER MAY CHANGE AFTER THIS POINT IN THE LIST */
+	/*
+	 * XXX Because of a coding blunder, Opus and VP8 have assigned
+	 * format compatibility bits and were placed after eight
+	 * formats that do NOT have format compatibility bits.  This
+	 * means that chan_iax2 now has a gap of eight between G.719
+	 * and Opus for the IAX_IE_CODEC_PREFS list sent out over the
+	 * wire.
+	 *
+	 * Eight formats now must stay between G.719 and Opus.  If more
+	 * formats are added with assigned format compatibility bits,
+	 * they can displace the place holder formats below to fill the
+	 * gap.
+	 */
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_SPEEX32, 0), "speex32", 32000, "SpeeX 32khz", 10, 10, 60, 10, 20, 0, 0);   /*!< codec_speex.c */
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_SLINEAR12, 0), "slin12", 12000, "16 bit Signed Linear PCM (12kHz)", 240, 10, 70, 10, 20, AST_SMOOTHER_FLAG_BE, 0);/*!< Signed linear (12kHz) */
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_SLINEAR24, 0), "slin24", 24000, "16 bit Signed Linear PCM (24kHz)", 480, 10, 70, 10, 20, AST_SMOOTHER_FLAG_BE, 0);/*!< Signed linear (24kHz) */
@@ -1078,11 +1099,22 @@ static int format_list_init(void)
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_SLINEAR48, 0), "slin48", 48000, "16 bit Signed Linear PCM (48kHz)", 960, 10, 70, 10, 20, AST_SMOOTHER_FLAG_BE, 0);/*!< Signed linear (48kHz) */
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_SLINEAR96, 0), "slin96", 96000, "16 bit Signed Linear PCM (96kHz)", 1920, 10, 70, 10, 20, AST_SMOOTHER_FLAG_BE, 0);/*!< Signed linear (96kHz) */
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_SLINEAR192, 0), "slin192", 192000, "16 bit Signed Linear PCM (192kHz)", 3840, 10, 70, 10, 20, AST_SMOOTHER_FLAG_BE, 0);/*!< Signed linear (192kHz) */
+
 	/* Opus (FIXME: real min is 3/5/10, real max is 120...) */
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_OPUS, 0), "opus", 48000, "Opus Codec", 10, 20, 60, 20, 20, 0, 0);   /*!< codec_opus.c */
 	/* VP8 (passthrough) */
 	format_list_add_static(ast_format_set(&tmpfmt, AST_FORMAT_VP8, 0), "vp8", 0, "VP8 Video", 0, 0, 0, 0 ,0 ,0, 0);         /*!< Passthrough support, see format_h263.c */
 
+	/*
+	 * ORDER MAY CHANGE AFTER THIS POINT IN THE LIST
+	 *
+	 * Reason:
+	 * These formats and any that follow do NOT have format compatibility
+	 * bits assigned so chan_iax2 in particular and other legacy modules
+	 * that use compatibility bits will not be aware of them.
+	 */
+	/* Add new codecs here that do NOT have format compatibility bits assigned. */
+
 	return 0;
 }