Project

General

Profile

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
Add picture from clipboard (Maximum size: 48.8 MB)