FreeCalypso > hg > gsm-codec-lib

annotate doc/Binary-file-format @ 535:bf7bbc7d494f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/FR1-library-API: document new additions
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 20 Sep 2024 07:27:18 +0000
parents f469bad44c0e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
302
f469bad44c0e doc/Binary-file-format: s/gsm_explode/gsmfr_unpack_to_array/
Mychaela Falconia <falcon@freecalypso.org>
parents: 210
diff changeset
25 parameters with gsmfr_unpack_to_array() or EFR_frame2params(), and then displays
f469bad44c0e doc/Binary-file-format: s/gsm_explode/gsmfr_unpack_to_array/
Mychaela Falconia <falcon@freecalypso.org>
parents: 210
diff changeset
26 those parameters in a sensible manner, with a per-frame header line followed by
f469bad44c0e doc/Binary-file-format: s/gsm_explode/gsmfr_unpack_to_array/
Mychaela Falconia <falcon@freecalypso.org>
parents: 210
diff changeset
27 4 lines of subframe parameters.
133
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.