Osmocom Libraries » libosmocore

[[PageOutline]]

= libosmocore =

libosmocore is a library with various utility functions that were originally developed as part of 

the [wiki: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 Open Source mobile communications.

There is no clear scope of it.  We simply move all shared code between [wiki:OsmocomBB] and [wiki:OpenBSC]

in this library to avoid code duplication.

== Obtaining it ==

When you download and build [wiki:OsmocomBB], then libosmocore is automatically part of the package,

no special action is required.

If you want to obtain a standalone version of libosmocore, you can use the following git URL:

{{{git clone git://git.osmocom.org/libosmocore.git}}}

== Licensing ==

This library is GPL licensed, as the code is taken from the similarly GPL-licensed OpenBSC codebase.

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

== Features ==

=== 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.

=== 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.

=== Bitvector ===

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

for rest-octet parsing.

=== 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}}}

=== Timers ===

Provides a timer core where you can register timers with a callback function. The function

is called when the timer expires.

=== Comp128v1 ===

A Comp128v1 implementation by Sylvain Munaut is included.

=== Talloc memory allocator ===

The talloc memory allocator from the Samba project.

== 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 [http://github.com/apenwarr/git-subtree 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.

=== 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