Project

General

Profile

Libosmocore » History » Version 15

fixeria, 02/19/2016 10:49 PM

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