FreeCalypso > hg > gsm-codec-lib
annotate doc/Binary-file-format @ 269:bd2271cb95d4
libgsmfr2: integrate preprocess.c from libgsm
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sun, 14 Apr 2024 01:58:35 +0000 |
parents | 7e490a8efe8a |
children | f469bad44c0e |
rev | line source |
---|---|
10
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
1 We (Themyscira Wireless) define our own binary file format for testing of GSM |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
2 06.10 (FR) and EFR codec functions; this format of ours is an extension of |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
3 classic .gsm format from libgsm/toast. The original libgsm file format is a |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
4 directly abutted sequence of 33-byte libgsm frames, equivalent to RTP frames |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
5 for GSM FR, with the upper nibble of the first byte in each frame equal to 0xD, |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
6 serving as a signature. We simply extend this idea: our version is still a |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
7 directly abutted sequence of binary records, but each record is now one of 3 |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
8 possibilities: |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
9 |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
10 - a 33-byte GSM FR frame in libgsm/RTP format, 0xD signature |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
11 - a 31-byte GSM EFR frame in RTP format (ETSI TS 101 318), 0xC signature |
210
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
12 - a 2-byte Themyscira-extension BFI marker, 0xBF signature, see below |
10
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
13 |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
14 File reading functions begin by reading only one byte; this byte, once decoded, |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
15 tells us how many more bytes need to be read, and frame synchronization is thus |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
16 maintained. |
820d88b97924
libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
17 |
124
598ee3ce238b
doc/Binary-file-format: document .gsmx suffix
Mychaela Falconia <falcon@freecalypso.org>
parents:
10
diff
changeset
|
18 The recommended filename suffix for extended-libgsm binary files in the present |
598ee3ce238b
doc/Binary-file-format: document .gsmx suffix
Mychaela Falconia <falcon@freecalypso.org>
parents:
10
diff
changeset
|
19 format is .gsmx; of course dot-separated filename suffixes hold absolutely no |
598ee3ce238b
doc/Binary-file-format: document .gsmx suffix
Mychaela Falconia <falcon@freecalypso.org>
parents:
10
diff
changeset
|
20 special meaning on Unix systems, but many developers still strongly prefer to |
598ee3ce238b
doc/Binary-file-format: document .gsmx suffix
Mychaela Falconia <falcon@freecalypso.org>
parents:
10
diff
changeset
|
21 have them for psychological comfort. |
133
b4b1c3a192c7
doc/Binary-file-format: document gsmrec-dump
Mychaela Falconia <falcon@freecalypso.org>
parents:
124
diff
changeset
|
22 |
b4b1c3a192c7
doc/Binary-file-format: document gsmrec-dump
Mychaela Falconia <falcon@freecalypso.org>
parents:
124
diff
changeset
|
23 Any gsmx file (FR or EFR) can be dumped in human-readable form with our |
b4b1c3a192c7
doc/Binary-file-format: document gsmrec-dump
Mychaela Falconia <falcon@freecalypso.org>
parents:
124
diff
changeset
|
24 gsmrec-dump utility. This utility turns every read frame from bytes into codec |
b4b1c3a192c7
doc/Binary-file-format: document gsmrec-dump
Mychaela Falconia <falcon@freecalypso.org>
parents:
124
diff
changeset
|
25 parameters with gsm_explode() or EFR_frame2params(), and then displays those |
b4b1c3a192c7
doc/Binary-file-format: document gsmrec-dump
Mychaela Falconia <falcon@freecalypso.org>
parents:
124
diff
changeset
|
26 parameters in a sensible manner, with a per-frame header line followed by 4 |
b4b1c3a192c7
doc/Binary-file-format: document gsmrec-dump
Mychaela Falconia <falcon@freecalypso.org>
parents:
124
diff
changeset
|
27 lines of subframe parameters. |
b4b1c3a192c7
doc/Binary-file-format: document gsmrec-dump
Mychaela Falconia <falcon@freecalypso.org>
parents:
124
diff
changeset
|
28 |
b4b1c3a192c7
doc/Binary-file-format: document gsmrec-dump
Mychaela Falconia <falcon@freecalypso.org>
parents:
124
diff
changeset
|
29 FR and EFR frames are not expected to be mixed in the same stream recording; |
b4b1c3a192c7
doc/Binary-file-format: document gsmrec-dump
Mychaela Falconia <falcon@freecalypso.org>
parents:
124
diff
changeset
|
30 our low-level binary file reading function and gsmrec-dump will grok such mixing |
b4b1c3a192c7
doc/Binary-file-format: document gsmrec-dump
Mychaela Falconia <falcon@freecalypso.org>
parents:
124
diff
changeset
|
31 just fine, but each higher-level test program (beyond gsmrec-dump) is expected |
b4b1c3a192c7
doc/Binary-file-format: document gsmrec-dump
Mychaela Falconia <falcon@freecalypso.org>
parents:
124
diff
changeset
|
32 to be written for only one codec, either FR or EFR. |
210
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
33 |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
34 BFI marker format |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
35 ================= |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
36 |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
37 Every 20 ms frame in our gsmx files is either a good FR/EFR frame or a BFI (Bad |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
38 Frame Indication) marker. The BFI marker format used in our gsmx file format is |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
39 the same format which we (Themyscira Wireless) previously used in our GSM RAN |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
40 RTP transport, before switching to our current TRAUlike RTP format. This BFI |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
41 marker format is quite simple: |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
42 |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
43 byte 0: 0xBF signature; |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
44 byte 1: least-significant bit encoding TAF per GSM 06.31 or GSM 06.81, |
7e490a8efe8a
doc/Binary-file-format: document BFI marker format
Mychaela Falconia <falcon@freecalypso.org>
parents:
133
diff
changeset
|
45 section 6.1.1 in both documents; other bits are reserved. |