Project

General

Profile

Libosmocore » History » Version 29

laforge, 06/06/2021 08:00 PM

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 20 fixeria
* *libosmocoding* contains an implementation of GSM 05.03 burst transcoding functions
17 16 laforge
* *libosmosim* contains infrastructure to interface SIM/UICC/USIM cards
18 12 tsaitgaist
19 15 fixeria
h2. Preconditions 
20
21
To compile libosmocore you will need the following tools:
22 1 laforge
23
<pre>
24 29 laforge
sudo apt-get install build-essential libtool libtalloc-dev libsctp-dev shtool autoconf automake git-core pkg-config make gcc gnutls-dev python-minimal libusb-1.0.0-dev libmnl-dev
25 1 laforge
</pre>
26 29 laforge
27
_In case this list should become out of date, it is a good idea to check the Build-Depends line of source:debian/control which should always be up-to-date as it is automatically verified._
28 12 tsaitgaist
29 15 fixeria
and the following (optional) libraries:
30 1 laforge
<pre>
31 16 laforge
sudo apt-get install libpcsclite-dev
32
</pre>
33 15 fixeria
34
h2. Obtaining it
35 5 laforge
36 1 laforge
To obtain libosmocore, you can use the following git URL:
37 15 fixeria
38 7 tsaitgaist
<pre>
39 16 laforge
git clone git://git.osmocom.org/libosmocore.git
40
</pre>
41 15 fixeria
42
h2. Compiling and installing it
43
44 1 laforge
To compile and install it as standalone:
45
<pre>
46
cd libosmocore/
47
autoreconf -i
48 15 fixeria
./configure
49 1 laforge
make
50
sudo make install
51 7 tsaitgaist
sudo ldconfig -i
52 1 laforge
cd ..
53 15 fixeria
</pre>
54 1 laforge
55
to compile without pcsclite library, run
56 15 fixeria
<pre>
57 16 laforge
./configure --disable-pcsc
58
</pre>
59 15 fixeria
60
61 1 laforge
h2. Licensing
62
63
This library is GPL licensed. This means you *cannot use this library from non-GPL licensed code without infringing copyright!
64 18 laforge
65
h2. API documentation
66
67
* http://ftp.osmocom.org/api/latest/libosmocore/core/html/
68
* http://ftp.osmocom.org/api/latest/libosmocore/codec/html/
69 19 laforge
* http://ftp.osmocom.org/api/latest/libosmocore/coding/html/
70
* http://ftp.osmocom.org/api/latest/libosmocore/gb/html/
71 18 laforge
* http://ftp.osmocom.org/api/latest/libosmocore/gsm/html
72
* http://ftp.osmocom.org/api/latest/libosmocore/vty/html
73
74
h2. Browsing its source code
75
76 21 Sec
You can do that using our cgit installation at http://cgit.osmocom.org/libosmocore/
77 1 laforge
78
h2. Features
79 15 fixeria
80
h3. Select loop abstraction
81
82 1 laforge
This is implemented in select.[ch] and enables you to build complex asynchronous/non-blocking I/O
83
programs in a single thread.
84
85 15 fixeria
86
h3. Message buffer handling
87
88 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.
89 1 laforge
90
h3. Bitvector
91 15 fixeria
92
A convenient set of routines to deal with bit-vectors in C.  This was originally written
93
for rest-octet parsing.
94 1 laforge
95 15 fixeria
h3. TLV handling
96 1 laforge
97 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@
98 1 laforge
99 15 fixeria
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 15 fixeria
104
h3. COMP128v1-3
105
106
A COMP128v1 implementation by Sylvain Munaut and COMP128v23 is included.
107 3 laforge
108 15 fixeria
109
h3. Rate Counter
110 1 laforge
111
Provides infrastructure for maintaining _rate counters_, i.e. counters that can be incremented
112
and will also keep track of the rate of events per second, minute, hour and day.  A group of rate
113 15 fixeria
counters is defined as an abstract _class_, from which you can then allocate instances.  The
114 1 laforge
_class_ description includes information about the counter names.
115 3 laforge
116 1 laforge
h3. Protocol helper code
117
118 15 fixeria
h4. GSM utils
119 1 laforge
120
* conversion functions for ARFCN, [[RxLevel]], 7bit GSM character set, power level, frame numbers, ...
121 15 fixeria
122 3 laforge
h4. GSM 04.08
123 1 laforge
124 6 laforge
* extensive header files for the GSM 04.08 (Layer 3 RR/MM/CC) messages
125 15 fixeria
* TLV parser definitions to parse the optional IEs
126
* utility functions such as
127
** human readable strings for RR cause names
128
** converting GSM Mobile Identities (MI) to string and back
129
* encoding and decoding functions for call control IEs
130
131
132
h4. GSM 08.08 (A Interface)
133
134
* API to wrap 04.08 messages in BSSMAP/DTAP message
135
* TLV parser definitions
136
137
138
h4. GSM 08.58 (A-bis RSL)
139 1 laforge
140 15 fixeria
* header file with structure and enum definitions for GSM 08.58 protocol
141
* TLV parser definitions for RSL optional IEs
142 1 laforge
* human readable strings for RSL Error values and RLM cause values
143 15 fixeria
* encoding and decoding of RSL channel number
144
145
146
h4. GSM 12.21 (A-bis OML)
147
148
* header file with structure and enum definitions for GSM 12.21 (and 08.59) protocol
149 1 laforge
150 15 fixeria
151
h4. GSM 04.11 (SMS)
152
153 1 laforge
* header file with structure and enum definitions for GSM 04.11 (SMS RP and CP layers) protocol
154 6 laforge
155
156 16 laforge
h3. talloc memory allocator
157 3 laforge
158 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.
159 15 fixeria
160 3 laforge
h3. Logging framework
161
162 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.
163 15 fixeria
* logging with various log levels for various subsystems inside the application
164
* logging to stderr, syslog or application-defined targets
165
* runtime reconfigurable per-subsystem log levels
166
* timestamping of log lines
167 2 laforge
* colorized log output
168 15 fixeria
169
h3. Write Queue
170
171 2 laforge
This is a write queue implementation on top of libosmocore's select loop abstraction.
172
It allows you to simply say "write this msg_buff to this file descriptor as soon as
173
the file descriptor is writable".
174 28 laforge
175
{{include(cellular-infrastructure:MacroCommercialSupport)}} 
Add picture from clipboard (Maximum size: 48.8 MB)