Project

General

Profile

Libosmocore » History » Revision 21

Revision 20 (fixeria, 01/18/2018 08:40 PM) → Revision 21/33 (Sec, 04/25/2018 06:16 PM)

h1. libosmocore 

 {{>toc}} 

 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. 

 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. 

 The libosmcoore.git repository build multiple libraries: 
 * *libosmocore* contains some general-purpose functions like select-loop abstraction, message buffers, timers, linked lists 
 * *libosmovty* contains routines related to the interactive command-line interface called VTY 
 * *libosmogsm* contains definitions and helper code related to GSM protocols 
 * *libosmoctrl* contains a shared implementation of the Osmocom control interface 
 * *libosmogb* contains an implementation of the Gb interface with its NS/BSSGP protocols 
 * *libosmocodec* contains an implementation of GSM voice codecs 
 * *libosmocoding* contains an implementation of GSM 05.03 burst transcoding functions 
 * *libosmosim* contains infrastructure to interface SIM/UICC/USIM cards 
 * *libosmotrau* contains encoding/decoding functions for A-bis TRAU frames 


 h2. Preconditions  

 To compile libosmocore you will need the following tools: 

 <pre> 
 sudo apt-get install build-essential libtool libtalloc-dev shtool autoconf automake git-core pkg-config make gcc 
 </pre> 

 and the following (optional) libraries: 
 <pre> 
 sudo apt-get install libpcsclite-dev 
 </pre> 

 h2. Obtaining it 

 To obtain libosmocore, you can use the following git URL: 

 <pre> 
 git clone git://git.osmocom.org/libosmocore.git 
 </pre> 

 h2. Compiling and installing it 

 To compile and install it as standalone: 
 <pre> 
 cd libosmocore/ 
 autoreconf -i 
 ./configure 
 make 
 sudo make install 
 sudo ldconfig -i 
 cd .. 
 </pre> 

 to compile without pcsclite library, run 
 <pre> 
 ./configure --disable-pcsc 
 </pre> 


 h2. Licensing 

 This library is GPL licensed. This means you *cannot use this library from non-GPL licensed code without infringing copyright! 

 h2. API documentation 

 * http://ftp.osmocom.org/api/latest/libosmocore/core/html/ 
 * http://ftp.osmocom.org/api/latest/libosmocore/codec/html/ 
 * http://ftp.osmocom.org/api/latest/libosmocore/coding/html/ 
 * http://ftp.osmocom.org/api/latest/libosmocore/gb/html/ 
 * http://ftp.osmocom.org/api/latest/libosmocore/gsm/html 
 * http://ftp.osmocom.org/api/latest/libosmocore/vty/html 

 h2. Browsing its source code 

 You can do that using our cgit installation at http://cgit.osmocom.org/libosmocore/ http://cgit.osmocom.org/cgit/libosmocore/ 

 h2. Features 

 h3. Select loop abstraction 

 This is implemented in select.[ch] and enables you to build complex asynchronous/non-blocking I/O 
 programs in a single thread. 


 h3. Message buffer handling 

 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. 

 h3. Bitvector 

 A convenient set of routines to deal with bit-vectors in C.    This was originally written 
 for rest-octet parsing. 

 h3. TLV handling 

 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@ 

 h3. Timers 

 Provides a timer core where you can register timers with a callback function. The function 
 is called when the timer expires. 

 h3. COMP128v1-3 

 A COMP128v1 implementation by Sylvain Munaut and COMP128v23 is included. 


 h3. Rate Counter 

 Provides infrastructure for maintaining _rate counters_, i.e. counters that can be incremented 
 and will also keep track of the rate of events per second, minute, hour and day.    A group of rate 
 counters is defined as an abstract _class_, from which you can then allocate instances.    The 
 _class_ description includes information about the counter names. 

 h3. Protocol helper code 

 h4. GSM utils 

 * conversion functions for ARFCN, [[RxLevel]], 7bit GSM character set, power level, frame numbers, ... 

 h4. GSM 04.08 

 * extensive header files for the GSM 04.08 (Layer 3 RR/MM/CC) messages 
 * TLV parser definitions to parse the optional IEs 
 * utility functions such as 
 ** human readable strings for RR cause names 
 ** converting GSM Mobile Identities (MI) to string and back 
 * encoding and decoding functions for call control IEs 


 h4. GSM 08.08 (A Interface) 

 * API to wrap 04.08 messages in BSSMAP/DTAP message 
 * TLV parser definitions 


 h4. GSM 08.58 (A-bis RSL) 

 * header file with structure and enum definitions for GSM 08.58 protocol 
 * TLV parser definitions for RSL optional IEs 
 * human readable strings for RSL Error values and RLM cause values 
 * encoding and decoding of RSL channel number 


 h4. GSM 12.21 (A-bis OML) 

 * header file with structure and enum definitions for GSM 12.21 (and 08.59) protocol 


 h4. GSM 04.11 (SMS) 

 * header file with structure and enum definitions for GSM 04.11 (SMS RP and CP layers) protocol 


 h3. talloc memory allocator 

 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. 

 h3. Logging framework 

 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. 
 * logging with various log levels for various subsystems inside the application 
 * logging to stderr, syslog or application-defined targets 
 * runtime reconfigurable per-subsystem log levels 
 * timestamping of log lines 
 * colorized log output 

 h3. Write Queue 

 This is a write queue implementation on top of libosmocore's select loop abstraction. 
 It allows you to simply say "write this msg_buff to this file descriptor as soon as 
 the file descriptor is writable". 


 h2. Development Cycle 

 As we are still developing the GSM protocol stacks on the network side (OpenBSC) and phone side (OsmocomBB), 
 every so often there is a need to add some new code to libosmocore.    Even worse, we sometimes need to break 
 the API and ABI of the library. 

 However, by keeping libosmocore in a separate git repository, we run into one problem: Checking out an old 
 version of e.g. [[OpenBSC:]] or [[OsmocomBB:]] will result in failed builds, as we don't remember which old version 
 of libosmocore was required.    This makes debugging and things like git bisect very hard to impossible. 

 In order to solve this problem, we use "git-subtree":http://github.com/apenwarr/git-subtree to import the 
 full libosmocore.git repository into [[OsmocomBB:]]. 

 This way, we ensure that there is always a compatible version of libosmocore inside the tree if we check out 
 old [[OsmocomBB:]] versions from git. 


 h3. Making changes to libosmocore 

  *NEVER COMMIT CHANGES DIRECTLY TO osmocom-bb.git:src/shared/libosmocore* 

 Instead, use the following process: 
  1. make your changes to your local copy of libosmocore 
  1. test them together with [[OsmocomBB:]] and [[OpenBSC:]] 
  1. test if libosmocore still builds for both host and target (ARM) 
  1. create a _diff_ of your local libosmocore changes 
  1. apply that diff to the libosmocore.git repository 
  1. use the script in osmocom-bb.git/src/shared/update-libosmocore.sh (uses git-subtree) to import your changes from libosmocore.git 
  1. test + commit your [[OsmocomBB:]] changes that depend on the newly introduced code to libosmocore 

 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)