annotate INSTALL @ 242:f081a6850fb5

libgsmfrp: new refined implementation The previous implementation exhibited the following defects, which are now fixed: 1) The last received valid SID was cached forever for the purpose of handling future invalid SIDs - we could have received some valid SID ages ago, then lots of speech or NO_DATA, and if we then get an invalid SID, we would resurrect the last valid SID from ancient history - a bad design. In our new design, we handle invalid SID based on the current state, much like BFI. 2) GSM 06.11 spec says clearly that after the second lost SID (received BFI=1 && TAF=1 in CN state) we need to gradually decrease the output level, rather than jump directly to emitting silence frames - we previously failed to implement such logic. 3) Per GSM 06.12 section 5.2, Xmaxc should be the same in all 4 subframes in a SID frame. What should we do if we receive an otherwise valid SID frame with different Xmaxc? Our previous approach would replicate this Xmaxc oddity in every subsequent generated CN frame, which is rather bad. In our new design, the very first CN frame (which can be seen as a transformation of the SID frame itself) retains the original 4 distinct Xmaxc, but all subsequent CN frames are based on the Xmaxc from the last subframe of the most recent SID.
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 09 May 2023 05:16:31 +0000
parents 34f8549ff0b1
children 4b6fa53a8240
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
208
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Dependency graph
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 ================
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 The complete Themyscira GSM codec libraries & utilities package as presented
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 here consists of two principal parts:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 Division 1: libgsmefr and libgsmfrp, the two C code libraries intended to be
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 usable by other software;
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 Division 2: various command line utilities that were developed under the
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 umbrella of this project and are being released accordingly.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 Division 2 components have a compile-time dependency on Division 1 (some of
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 these Division 2 command line utilities link with libgsmefr or libgsmfrp), but
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 not the other way around: neither libgsmefr nor libgsmfrp has any dependency on
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 any other part of this package.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 However, the original GSM 06.10 library (libgsm) from 1990s is a required
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 dependency for several components of the present Themyscira package: libgsmfrp
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 and several Division 2 command line utilities have a compile-time dependency on
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 <gsm.h> header file provided by libgsm, and several Division 2 utilities also
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 have a link dependency on libgsm itself. Therefore, libgsm should be considered
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 a hard dependency for the present GSM codec libraries & utilities package as a
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 whole, and it needs to be installed system-wide prior to compiling the present
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 software.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 Compiling and installing Themyscira libraries and utilities
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 ===========================================================
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 Running 'make' at the top level of the present gsm-codec-lib package will
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 compile both Division 1 and Division 2 software components (both libraries and
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 utilities), with the top level Makefile codifying the dependency graph among
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 them. Installation, however, is a little more complicated in that there is no
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 single 'make install' target at the top level - instead of a single install
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 target, the top Makefile provides two separate installation targets:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 make install-lib Install libgsmefr and libgsmfrp system-wide:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 gsm_efr.h and gsm_fr_preproc.h are installed in
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 /usr/local/include; libgsmefr.a and libgsmfrp.a are
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 installed in /usr/local/lib. Superuser privileges
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 are usually required to write to these directories.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 make install-utils Install Division 2 command line utilities into
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 /opt/freecalypso/bin directory, which is non-standard
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 in the muggle world but has been established in our
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 Themyscira community as the location for Themyscira-
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 developed command line utilities working with GSM.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 The just-described separation between install-lib and install-utils targets has
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 been created because of the difference in install paths: libraries and their
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 header files that need to be easily findable and usable by other people's
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 unrelated software need to be installed under /usr/local, requiring su to root
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 before each install cycle, whereas /opt/freecalypso/bin (writable without root
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 privileges on the Mother's development machine) is much more convenient for
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 Division 2 command line utilities.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 However, the present gsm-codec-lib package differs from FreeCalypso host tools
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 and SIM tools packages in that in the present package, you ARE allowed to freely
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 change these installation directories to fit your own preferences. FC host
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 tools and FC SIM tools packages carry very strong admonitions in their INSTALL
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 documents to the effect that they MUST be installed under /opt/freecalypso and
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 that this path cannot be changed; this strict imposition is made because of
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 strong intercomponent dependencies within those software suites, with different
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 components invoking each other or looking for their support files using hard-
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 coded absolute pathnames. But the present gsm-codec-lib package is different:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 you are free to move our Division 2 command line utilities from
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 /opt/freecalypso/bin to /usr/local/bin or anywhere else you like, and you are
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 likewise free to move our Division 1 libraries from /usr/local/{include,lib} to
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 whatever location would be most appropriate in your environment.
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 To change installation directories, you will need to edit subdirectory Makefiles
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 as follows:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 Division 1:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 libgsmefr/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 libgsmfrp/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 Division 2:
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 amrconv/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 efrtest/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 frtest/Makefile
13d27ff5b5df add documents for release
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 miscutil/Makefile