FreeCalypso > hg > gsm-codec-lib

annotate doc/Binary-file-format @ 168:486e19acc66f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Calypso-TCH-downlink: document new utilities
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 25 Dec 2022 09:48:02 +0000
parents b4b1c3a192c7
children 7e490a8efe8a
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
820d88b97924 libtest: implement binary file reader
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 - a 2-byte Themyscira-extension BFI marker, 0xBF signature
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.