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 |