This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

libqmi

The GLib-based libqmi library to use the QMI protocol

1: API reference
2: Dependencies
3: Building

3.1: Building libqmi 1.30 or later with Meson
3.2: Building libqmi 1.30 or earlier using GNU autotools

This section provides information about the libqmi library.

1 - API reference

Reference manual for the libqmi-glib library.

The libqmi-glib API reference provides a detailed list of operations that may be performed with QMI devices.

Most of the documentation pages are automatically generated from the database of messages that the project maintains, and therefore it won’t give information about the purpose of the operations, or the exact format of the retrieved fields. The documentation is anyway extremely helpful when writing software using the library, as it provides a quick way to browse the interfaces and the expected fields in each message.

In order to know the exact purpose of each message or the format of the retrieved fields, please refer to the generic QMI services references from Qualcomm or to the vendor-specific service references. Most of these documents are only provided by Qualcomm under NDAs.

Online references

The most up to date API reference of the libqmi-glib library is kept in the following location:

Latest

The full list of API references published is kept for future reference:

There is no API reference published for stable release updates that didn’t have any API change.

Local reference

The API reference is usually installed along with the libqmi-glib library (sometimes as a separate distribution package) under /usr/share/gtk-doc/html/libqmi-glib/ and can be browsed locally via the Devhelp tool. The version of the installed reference will be the one applying to the libqmi-glib library installed in the system.

2 - Dependencies

Build and runtime dependencies of the libqmi library.

Common dependencies

Before you can compile the libqmi library, you will need at least the following tools:

A compliant C toolchain: e.g. glibc or musl libc, gcc or clang/llvm.
pkg-config, a tool for tracking the compilation flags needed for libraries.
The glib2 library.
- For libqmi >= 1.30, glib2 >= 2.56.
- For libqmi >= 1.26, glib2 >= 2.48.
- For libqmi >= 1.18 and < 1.26, glib2 >= 2.36
- For libqmi >= 1.0 and < 1.18, glib2 >= 2.32

In addition to the previous mandatory requirements, the project also has several optional dependencies that would be needed when enabling additional project features:

libmbim, in order to use the QMI-over-MBIM feature.
- For libqmi >= 1.22, libmbim >= 1.18.
- For libqmi >= 1.16 and < 1.22, libmbim >= 1.14.
libqrtr-glib, in order to use the QMI-over-QRTR feature.
- For libqmi >= 1.28, libqrtr-glib >= 1.0.
The libgudev library, in order to extend the qmi-firmware-update options and behavior.
- For libqmi >= 1.30, libgudev >= 232.
- For libqmi >= 1.18, libgudev >= 147.
gtk-doc tools, in order to regenerate the documentation.
gobject-introspection, in order to generate the introspection support.

Dependencies when building libqmi 1.30 or later with meson

When building with meson, the following additional dependencies are required:

meson.
ninja.

The following optional dependencies are available when building with meson:

bash-completion, in order to add completion support for the command line tools.

Dependencies when building libmbim 1.30 or earlier with GNU autotools

When building with the GNU autotools, the following additional dependencies are required:

make

There are two main ways to build the library using GNU autotools: from a git repository checkout and from a source release tarball. When building from a git checkout instead of from a source tarball, the following additional dependencies are required:

GNU autotools (autoconf/automake/libtool).
Autoconf archive, in the 1.26 and 1.28 series exclusively.

3 - Building

How to build and install the libqmi library.

This section provides information about how to build and install the libqmi library.

3.1 - Building libqmi 1.30 or later with Meson

How to build and install the libqmi library using the meson and ninja build systems.

The first stable series with support for building with the meson suite is 1.30. All the older stable series before 1.30 exclusively used the GNU autotools build system.

Building from a git checkout

When using meson, the builds are always triggered from git checkouts, there is no source release tarball involved. The basic build steps would be as follows:

  $ git clone https://gitlab.freedesktop.org/mobile-broadband/libqmi.git
  $ cd libqmi
  $ meson setup build --prefix=/usr
  $ ninja -C build

Optional switches

Additional optional switches that may be given to the meson command above would be:

In Debian/Ubuntu systems the default location for libraries depends on the architecture of the build, so instead of the default /usr/lib path that would be in effect due to --prefix=/usr, the user should also give an explicit --libdir path pointing to the correct location. E.g. on a 64bit Ubuntu/Debian build, the user would use --prefix=/usr --libdir=/usr/lib/x86_64-linux-gnu.
The QMI-over-MBIM feature is enabled by default. In order to disable it, the additional -Dmbim_qmux=false switch should be given.
The QMI-over-QRTR feature is enabled by default. In order to disable it, the additional -Dqrtr=false switch should be given.
If the project should build support for only a certain subset of QMI commands, the user can select which collection of commands should be used with the -Dcollection switch:
- -Dcollection=minimal will select the minimum number of QMI commands required to have a data connection up.
- -Dcollection=basic will select the minimum number of QMI commands required by ModemManager.
- -Dcollection=full, or omitting the switch, will select all the available QMI commands.
- -Dcollection=XXXX will select the QMI commands listed in the user-provided data/qmi-collection-XXXX.json file in the project sources.
The gtk-doc documentation is disabled by default. In order to enable it, the additional -Dgtk_doc=true switch should be given.
The GObject introspection support is enabled by default. In order to disable it, the additional -Dintrospection=false switch should be given.
The bash-completion support is enabled by default. In order to disable it, the additional -Dbash_completion=false switch should be given.
The default build type in meson if none explicitly specified is debug, which means debug symbols are included and optimization is fully disabled. The --buildtype=release switch can be used to remove debug symbols and to enable optimization level to the maximum.

An example project build using all the above optional switches could be:

  $ meson setup build                     \
      --prefix=/usr                       \
      --libdir=/usr/lib/x86_64-linux-gnu  \
      --buildtype=release                 \
      -Dcollection=basic                  \
      -Dmbim_qmux=false                   \
      -Dqrtr=false                        \
      -Dgtk_doc=true                      \
      -Dintrospection=false               \
      -Dbash_completion=false
  $ ninja -C build

Installing

The installation on the prefix selected during meson setup can be done with the following command:

  $ sudo ninja -C build install

Please note that the command above will install the library in the system default path for libraries, possibly overwriting any previous libqmi library that may already exist from a package manager installed package. See the FAQ section for comments on how to install in /usr/local instead.

Uninstalling

If you have manually installed the project with the steps above, it can be uninstalled in the same way:

  $ sudo ninja -C build uninstall

If the manual install overwrote the package manager installed files, it is suggested to force a re-install of the corresponding packages at this point, so that the system is not left with missing files.

3.2 - Building libqmi 1.30 or earlier using GNU autotools

How to build and install the libqmi library using GNU autotools.

The last stable series with support for building with the GNU autotools suite is 1.30. All the new stable series after 1.30 will exclusively use the meson build system.

Building from a release source tarball

The basic build and installation of the project can be done from an official release source tarball, in the following way:

  $ wget https://www.freedesktop.org/software/libqmi/libqmi-1.30.0.tar.xz
  $ tar -Jxvf libqmi-1.30.0.tar.xz
  $ cd libqmi-1.30.0
  $ ./configure --prefix=/usr
  $ make

Optional switches

Additional optional switches that may be given to the configure command above would be:

In Debian/Ubuntu systems the default location for libraries depends on the architecture of the build, so instead of the default /usr/lib path that would be in effect due to --prefix=/usr, the user should also give an explicit --libdir path pointing to the correct location. E.g. on a 64bit Ubuntu/Debian build, the user would use --prefix=/usr --libdir=/usr/lib/x86_64-linux-gnu.
If the QMI-over-MBIM feature is required, the additional --enable-mbim-qmux should be given. Omitting this switch will imply auto-detecting whether the feature can be built with the already installed dependencies.
If the QMI-over-QRTR feature is required, the additional --enable-qrtr should be given. Omitting this switch will imply auto-detecting whether the feature can be built with the already installed dependencies.
If the project should build support for only a certain subset of QMI commands, the user can select which collection of commands should be used with the --enable-collection switch:
- --enable-collection=minimal will select the minimum number of QMI commands required to have a data connection up.
- --enable-collection=basic will select the minimum number of QMI commands required by ModemManager.
- --enable-collection=full, or omitting the switch, will select all the available QMI commands.
- --enable-collection=XXXX will select the QMI commands listed in the user-provided data/qmi-collection-XXXX.json file in the project sources.
If the documentation should be rebuilt, the additional --enable-gtk-doc switch should be given. Omitting this switch will imply auto-detecting whether the documentation can be rebuilt with the already installed dependencies.
If the introspection support should be included in the build, the additional --enable-introspection switch should be given. Omitting this switch will imply auto-detecting whether the introspection can be built with the already installed dependencies.
When developing changes to the library or debugging issues, it is recommended to build with debug symbols so that running the program under gdb produces useful backtrace information. This can be achieved by providing user compiler flags like these: CFLAGS="-ggdb -O0"

An example project build using all the above optional switches could be:

  $ ./configure                          \
      --prefix=/usr                      \
      --libdir=/usr/lib/x86_64-linux-gnu \
      --enable-mbim-qmux                 \
      --enable-qrtr                      \
      --enable-collection=basic          \
      --enable-gtk-doc                   \
      --enable-introspection             \
      CFLAGS="-ggdb -O0"
  $ make

Running ./configure --help will show all the possible switches that are supported.

Building from a git checkout

When building from a git checkout, there is one single additional step required to build the project: running the included autogen.sh in order to setup the GNU autotools project and generate a configure script:

  $ git clone https://gitlab.freedesktop.org/mobile-broadband/libqmi.git
  $ cd libqmi
  $ NOCONFIGURE=1 ./autogen.sh
  $ ./configure --prefix=/usr
  $ make

The same optional switches may be given to the configure script when building from a git checkout.

Installing

The installation on the prefix selected during configure can be done with the following command:

  $ sudo make install

Uninstalling

If you have manually installed the project with the steps above, it can be uninstalled in the same way:

  $ sudo make uninstall