Libosmocore » History » Version 14
fixeria, 02/19/2016 10:49 PM
1 | 1 | laforge | [[PageOutline]] |
---|---|---|---|
2 | = libosmocore = |
||
3 | |||
4 | libosmocore is a library with various utility functions that were originally developed as part of |
||
5 | the [wiki:OpenBSC] project, but which are of a more generic nature and thus useful to (at least) |
||
6 | 8 | laforge | other programs that we develop in the sphere of Free Software / Open Source mobile communications. |
7 | 1 | laforge | |
8 | There is no clear scope of it. We simply move all shared code between [wiki:OsmocomBB] and [wiki:OpenBSC] |
||
9 | in this library to avoid code duplication. |
||
10 | |||
11 | 10 | laforge | To build osmocom-bb it is mandatory to install libosmocom in advance. |
12 | |||
13 | 9 | laforge | == Browsing its source code == |
14 | |||
15 | You can do that using our cgit installation at http://cgit.osmocom.org/cgit/libosmocore/ |
||
16 | 12 | tsaitgaist | |
17 | == Preconditions == |
||
18 | |||
19 | To compile libosmocore you will need the following tools: |
||
20 | |||
21 | 14 | fixeria | {{{sudo apt-get install build-essential libtool libtalloc-dev shtool autoconf automake git-core pkg-config make gcc}}} |
22 | 12 | tsaitgaist | |
23 | and the following (optional) libraries: |
||
24 | |||
25 | {{{sudo apt-get install libpcsclite-dev}}} |
||
26 | |||
27 | 1 | laforge | == Obtaining it == |
28 | |||
29 | 10 | laforge | To obtain libosmocore, you can use the following git URL: |
30 | 5 | laforge | |
31 | 1 | laforge | {{{git clone git://git.osmocom.org/libosmocore.git}}} |
32 | |||
33 | 7 | tsaitgaist | == Compiling and installing it == |
34 | |||
35 | To compile and install it as standalone: |
||
36 | |||
37 | {{{ |
||
38 | cd libosmocore/ |
||
39 | autoreconf -i |
||
40 | ./configure |
||
41 | make |
||
42 | sudo make install |
||
43 | 13 | tsaitgaist | sudo ldconfig -i |
44 | 7 | tsaitgaist | cd .. |
45 | }}} |
||
46 | 12 | tsaitgaist | |
47 | to compile without pcsclite library, run |
||
48 | |||
49 | {{{./configure --disable-pcsc}}} |
||
50 | 7 | tsaitgaist | |
51 | 1 | laforge | == Licensing == |
52 | |||
53 | This library is GPL licensed, as the code is taken from the similarly GPL-licensed OpenBSC codebase. |
||
54 | |||
55 | This means you '''cannot use this library from non-GPL licensed code without infringing copyright! |
||
56 | |||
57 | == Features == |
||
58 | |||
59 | === Select loop abstraction === |
||
60 | This is implemented in select.[ch] and enables you to build complex asynchronous/non-blocking I/O |
||
61 | programs in a single thread. |
||
62 | |||
63 | === Message buffer handling === |
||
64 | Inspired by the Linux kernel {{{struct sk_buff}}}, this is our message buffer {{{struct msgb}}} |
||
65 | implementation. It provides handling of packet buffers, putting them in queues, prepending |
||
66 | and appending data to it, etc. |
||
67 | |||
68 | === Bitvector === |
||
69 | A convenient set of routines to deal with bit-vectors in C. This was originally written |
||
70 | for rest-octet parsing. |
||
71 | |||
72 | === TLV handling === |
||
73 | The GSM Layer3 and above are full of TV / TLV / TL16V and other data fields. Our implementation |
||
74 | provides parser and generator functions, tightly coupled to {{{struct msgb}}} |
||
75 | |||
76 | === Timers === |
||
77 | Provides a timer core where you can register timers with a callback function. The function |
||
78 | is called when the timer expires. |
||
79 | |||
80 | 11 | laforge | === COMP128v1-3 === |
81 | A COMP128v1 implementation by Sylvain Munaut and COMP128v23 is included. |
||
82 | 1 | laforge | |
83 | 6 | laforge | === Rate Counter === |
84 | Provides infrastructure for maintaining ''rate counters'', i.e. counters that can be incremented |
||
85 | and will also keep track of the rate of events per second, minute, hour and day. A group of rate |
||
86 | counters is defined as an abstract ''class'', from which you can then allocate instances. The |
||
87 | ''class'' description includes information about the counter names. |
||
88 | |||
89 | |||
90 | 3 | laforge | === Protocol helper code === |
91 | 1 | laforge | |
92 | 3 | laforge | ==== GSM utils ==== |
93 | * conversion functions for ARFCN, RxLevel, 7bit GSM character set, power level, frame numbers, ... |
||
94 | |||
95 | ==== GSM 04.08 ==== |
||
96 | * extensive header files for the GSM 04.08 (Layer 3 RR/MM/CC) messages |
||
97 | * TLV parser definitions to parse the optional IEs |
||
98 | * utility functions such as |
||
99 | * human readable strings for RR cause names |
||
100 | * converting GSM Mobile Identities (MI) to string and back |
||
101 | * encoding and decoding functions for call control IEs |
||
102 | |||
103 | 6 | laforge | ==== GSM 08.08 (A Interface) ==== |
104 | * API to wrap 04.08 messages in BSSMAP/DTAP message |
||
105 | * TLV parser definitions |
||
106 | |||
107 | 4 | laforge | ==== GSM 08.58 (A-bis RSL) ==== |
108 | 3 | laforge | * header file with structure and enum definitions for GSM 08.58 protocol |
109 | * TLV parser definitions for RSL optional IEs |
||
110 | 1 | laforge | * human readable strings for RSL Error values and RLM cause values |
111 | 4 | laforge | * encoding and decoding of RSL channel number |
112 | |||
113 | ==== GSM 12.21 (A-bis OML) ==== |
||
114 | * header file with structure and enum definitions for GSM 12.21 (and 08.59) protocol |
||
115 | 3 | laforge | |
116 | ==== GSM 04.11 (SMS) ==== |
||
117 | 1 | laforge | * header file with structure and enum definitions for GSM 04.11 (SMS RP and CP layers) protocol |
118 | 3 | laforge | |
119 | 1 | laforge | === Talloc memory allocator === |
120 | 6 | laforge | The talloc memory allocator from the Samba project is (optionally) part of libosmocore. |
121 | It provides hierarchical memory allocation and extensive debugging features such as dumping |
||
122 | the currently allocated objects (at runtime) to the console. |
||
123 | 1 | laforge | |
124 | === Logging framework === |
||
125 | 6 | laforge | A generic logging implementation, supporting a dynamic number of 'log targets', understanding |
126 | the notion of log levels and log categories. Filtering based on levels and categories is |
||
127 | implemented in the core, while context-specific filtering can be implemented by the application |
||
128 | using libosmocore. |
||
129 | 3 | laforge | * logging with various log levels for various subsystems inside the application |
130 | * logging to stderr, syslog or application-defined targets |
||
131 | * runtime reconfigurable per-subsystem log levels |
||
132 | * timestamping of log lines |
||
133 | * colorized log output |
||
134 | |||
135 | === Write Queue === |
||
136 | |||
137 | This is a write queue implementation on top of libosmocore's select loop abstraction. |
||
138 | It allows you to simply say "write this msg_buff to this file descriptor as soon as |
||
139 | the file descriptor is writable". |
||
140 | 2 | laforge | |
141 | == Development Cycle == |
||
142 | |||
143 | As we are still developing the GSM protocol stacks on the network side (OpenBSC) and phone side (OsmocomBB), |
||
144 | every so often there is a need to add some new code to libosmocore. Even worse, we sometimes need to break |
||
145 | the API and ABI of the library. |
||
146 | |||
147 | However, by keeping libosmocore in a separate git repository, we run into one problem: Checking out an old |
||
148 | version of e.g. OpenBSC or OsmocomBB will result in failed builds, as we don't remember which old version |
||
149 | of libosmocore was required. This makes debugging and things like git bisect very hard to impossible. |
||
150 | |||
151 | In order to solve this problem, we use [http://github.com/apenwarr/git-subtree git-subtree] to import the |
||
152 | full libosmocore.git repository into OsmocomBB. |
||
153 | |||
154 | This way, we ensure that there is always a compatible version of libosmocore inside the tree if we check out |
||
155 | old OsmocomBB versions from git. |
||
156 | |||
157 | === Making changes to libosmocore === |
||
158 | |||
159 | '''NEVER COMMIT CHANGES DIRECTLY TO osmocom-bb.git:src/shared/libosmocore''' |
||
160 | |||
161 | Instead, use the following process: |
||
162 | 1. make your changes to your local copy of libosmocore |
||
163 | 1. test them together with OsmocomBB and OpenBSC |
||
164 | 1. test if libosmocore still builds for both host and target (ARM) |
||
165 | 1. create a ''diff'' of your local libosmocore changes |
||
166 | 1. apply that diff to the libosmocore.git repository |
||
167 | 1. use the script in osmocom-bb.git/src/shared/update-libosmocore.sh (uses git-subtree) to import your changes from libosmocore.git |
||
168 | 1. test + commit your OsmocomBB changes that depend on the newly introduced code to libosmocore |
||
169 | |||
170 | It is important that the steps are followed in the order state above to ensure consistency of our repositories |