Project

General

Profile

Libosmocore » History » Version 18

laforge, 03/07/2016 08:11 PM
add docbook links; re-order items to have user docs before devel docs

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