An operation guide to build and debug open source Media SDK software stack

The Goal

Intel started the Media SDK + associated Linux graphics stack/driver open source project in 2017. Now developers can build the full set of the media software components to run Intel® Media SDK completely from open source repositories with the steps described in this article. Developers can run and debug their media applications with source access to the full stack.

This configuration is not yet officially validated.  However, we are publishing this recipe in the spirit of making the full range of options available.   Please try it and send us the feedback on the Intel® Media SDK forum. We will improve the open source code and documentation based on everyone's feedback.

For the hardware platform coverage, please refer to the supported platforms section of the media driver repository.

Overview of the Media SDK Software Components

Before we start, the following diagram is a map to the components updated:

The open source media stack

 

 

 

 

 

 

 

 

 

The diagram shows the component relationships; the components being built are highlighted; the components not related to the build process are colored gray. Note the i915 driver has a different color. It is included in the kernel, and there are many options to update it. The diagram also shows briefly how the built components related to the kernel, firmware, the Intel processor graphics GPU hardware and user application. 

For the built components, the following table shows the repository and the built library names related to each component:

Component in diagramRepoLibrary names
libVA APIllbva, libva-utilslibva*.so
VAAPI Intel Drivermedia-driver, GMMLibiHD_drv_video.so, igfxcmrt64.so
Media SDK LibraryMediaSDKlibmfxhw64.so and files under /opt/intel/mediasdk

 

 

 

 

 

Note Before the Build

Since each open source code has its own repo, there is no automatic version alignment. Commit IDs used must be managed by the builder.  Since the code in each repository master branch keeps moving forward, builds based on the latest commits might fail occasionally. The specific commit IDs we tested are listed at the end of this guide.

In case of build failure, please read the issue list to check the error reports and solutions.

This article covers Ubuntu 16.04 and CentOS 7.4.1708.  Default library search paths might be different for other Linux distributions.  For example, Ubuntu's convention includes "x86_64-linux-gnu" while CentOS uses "lib64".   As long as path setup and related environment variables are consistent these steps should work in a wide variety of recent Linux environments.

Build Guide

We recommend replacing the default kernel with version 4.14.16 or newer.  In general, newer kernels will have the latest improvements and there is less risk with moving the kernel forward than moving in backward from your validated configuration.

 

Build instruction for Ubuntu 16.04.3

  1. Install the OS
    This build guide assumes the new installation of Ubuntu 16.04.3 LTS. As the first step, please install the system and update with the latest OS updates.
  2. Prepare the system with the system tools/library
    Note: If you don't want to replace the kernel, you can jump to step #5 to use the script to complete the build process.
    These tools and library dependencies are required for the build process. The installation of "libgl1-mesa-dev" dependencies makes sure the full configuration of the required components to build libVA is available.
    # sudo apt-get -y install git libssl-dev dh-autoreconf cmake libgl1-mesa-dev libpciaccess-dev
    # mkdir <path-to-working-directory>
    # export WORKING_DIR=<path-to-working-directory>
  3. Firmware Check and update
    There are 3 kinds of graphics firmware, GUC, HUC and DMC. Please check the i915 kernel mode driver for the required firmware version, then use the following command to check the current firmware version:
    # ls -al /lib/firmware/i915/ | grep skl_dmc
    -rw-r--r--  1 root root   8824 Dec  1  2016 skl_dmc_ver1_23.bin
    -rw-r--r--  1 root root   8928 Dec  1  2016 skl_dmc_ver1_26.bin
    lrwxrwxrwx  1 root root     19 Dec  1  2016 skl_dmc_ver1.bin -> skl_dmc_ver1_26.bin

    DMC v1.26 is required on the SkyLake platform with Kernel 4.14.16. Install it as follows:

    # cd WORKING_DIR
    # git clone https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git
    # sudo cp linux-firmware/i915/skl_dmc_ver1_26.bin /lib/firmware/i915/.

    Note: the "kbl" and "bxt" firmware may not be necessary; but missing them will cause some warnings in the following steps.

  4. Install Kernel 4.14.16 with Ubuntu Kernel Update Utility(Ukuu), skip this step if you want to build kernel manually
    Ukuu is a Ubuntu utility to download and install the prebuilt kernel automatically, it makes it easier to migrate new kernels.
    Note: Kernel 4.14.16 must be used in this article, later version should work but was not tested.
    # sudo add-apt-repository ppa:teejee2008/ppa
    # sudo apt-get update
    # sudo apt-get -y install ukuu
    # ukuu-gtk
    

    "ukuu-gtk" command launches graphic interface, select the kernel version 4.14.16 to install.
    Note: After the kernel installed, reboot the system and use command "uname -r" to make sure the system is running on kernel 4.14.16. If not, update GRUB manually.

  5. Build the 4.14.16 kernel, this can be skipped if choosing #4.
    Note: Kernel 4.14.16 must be used in this article, later version should work but was not tested.
    # cd $WORKING_DIR
    # git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
    # cd linux-stable/
    # git checkout -b my_v4.14.16 v4.14.16
    # cp /boot/config-`uname -r` .config
    # make olddefconfig
    # make -j8 
    # sudo make modules_install
    # sudo make install
    Note: After the kernel build, reboot the system and use command "uname -r" to make sure the system is running on kernel 4.14.16. If not, update GRUB manually.
  6. Run operation 7~9 with script, skip this step if you want to build manually
    • Download the attached script build_msdk_ubuntu.sh
    • Unzip it to any local folder, for example, "Downloads", run it as a normal user.
    • The script is using a working directory, you can either create one either or generate automatically.
    • The script has two version options, either the master with the latest version or the tested commit ID (listed at the bottom of this article). We recommend the master version since it is synced with the latest changes; the tested commit ID works as a fallback if the master version failed, it was created earlier and has the rendering issue when running the sample code.
    • The script doesn't clean up automatically when running back-to-back, please manually remove the working directory with command "rm -rf <working directory>" any time before re-run it.
  7. Build the libVA libraries, please skip this if run script in #6.
    Note:
    - If you want to use the latest version, skip the commands "git checkout <commit id>" in the following instructions.
    - If you want to use the test version, please find the commit ID of libva and libva-utils in the configurations table at the end of this guide.
    # cd $WORKING_DIR
    # git clone https://github.com/intel/libva.git
    # git clone https://github.com/intel/libva-utils.git
    # cd $WORKING_DIR/libva
    # git checkout <libva commit id>
    # ./autogen.sh --prefix=/usr --libdir=/usr/lib/x86_64-linux-gnu
    # make -j4
    # sudo make install
    # cd $WORKING_DIR/libva-utils
    # git checkout <libva-utils commit id>
    # ./autogen.sh --prefix=/usr --libdir=/usr/lib/x86_64-linux-gnu
    # make -j4
    # sudo make install
    Note: At the end of the autogen.sh command, check and make sure the drm, x11 and glx components are configured.
    # ./autogen.sh --prefix=/usr --libdir=/usr/lib/x86_64-linux-gnu
    ......
    libva - 2.0.1.pre1 (VA-API 1.0.0)
    
    Installation prefix .............. : /usr
    Default driver path .............. : /usr/lib/x86_64-linux-gnu/dri
    Extra window systems ............. : drm x11 glx
    Build documentation .............. : no
    Build with messaging ............. : yes
    
    Now type 'make' to compile libva.
    
  8. Build the media driver, please skip this if run script in #6.
    Note
    - If you want to use the latest version, skip the commands "git checkout <commit id>" in the following instructions.
    - If you want to use the test version, please find the commit ID of gmmlib and media-driver in the configurations table at the end of this guide.
    # cd $WORKING_DIR
    # git clone https://github.com/intel/media-driver.git
    # git clone https://github.com/intel/gmmlib.git
    # cd $WORKING_DIR/gmmlib
    # git checkout <gmmlib commit id>
    # cd $WORKING_DIR/media-driver
    # git checkout <media-driver commit id>
    # cd $WORKING_DIR
    # mkdir -p build
    # cd $WORKING_DIR/build
    # cmake ../media-driver \
    -DMEDIA_VERSION="2.0.0" \
    -DBUILD_ALONG_WITH_CMRTLIB=1 \
    -DBS_DIR_GMMLIB=`pwd`/../gmmlib/Source/GmmLib/ \
    -DBS_DIR_COMMON=`pwd`/../gmmlib/Source/Common/ \
    -DBS_DIR_INC=`pwd`/../gmmlib/Source/inc/ \
    -DBS_DIR_MEDIA=`pwd`/../media-driver \
    -DCMAKE_INSTALL_PREFIX=/usr \
    -DCMAKE_INSTALL_LIBDIR=/usr/lib/x86_64-linux-gnu \
    -DINSTALL_DRIVERS_SYSCONF=OFF \
    -DLIBVA_DRIVERS_PATH=/usr/lib/x86_64-linux-gnu/dri
    # make -j8
    # sudo make install
    # export LIBVA_DRIVER_NAME=iHD
    # export LIBVA_DRIVERS_PATH=/usr/lib/x86_64-linux-gnu/dri
    # vainfo
    Note: The "libva-utils" module is used to build the "vainfo" utility, which is a helpful diagnostic tool to check your libVA environment.
    Here is the expected result of "vainfo" after a successful built.
    # vainfo
    libva info: VA-API version 1.0.0
    libva info: va_getDriverName() returns 0
    libva info: User requested driver 'iHD'
    libva info: Trying to open /usr/lib/x86_64-linux-gnu/dri/iHD_drv_video.so
    libva info: Found init function __vaDriverInit_1_0
    libva info: va_openDriver() returns 0
    vainfo: VA-API version: 1.0 (libva 2.0.1.pre1)
    vainfo: Driver version: Intel iHD driver - 2.0.0
    vainfo: Supported profile and entrypoints
          VAProfileNone                   :	VAEntrypointVideoProc
          VAProfileNone                   :	VAEntrypointStats
          VAProfileMPEG2Simple            :	VAEntrypointVLD
          VAProfileMPEG2Simple            :	VAEntrypointEncSlice
          VAProfileMPEG2Main              :	VAEntrypointVLD
          VAProfileMPEG2Main              :	VAEntrypointEncSlice
          VAProfileH264Main               :	VAEntrypointVLD
          VAProfileH264Main               :	VAEntrypointEncSlice
          VAProfileH264Main               :	VAEntrypointFEI
          VAProfileH264Main               :	VAEntrypointEncSliceLP
          VAProfileH264High               :	VAEntrypointVLD
          VAProfileH264High               :	VAEntrypointEncSlice
          VAProfileH264High               :	VAEntrypointFEI
          VAProfileH264High               :	VAEntrypointEncSliceLP
          VAProfileVC1Simple              :	VAEntrypointVLD
          VAProfileVC1Main                :	VAEntrypointVLD
          VAProfileVC1Advanced            :	VAEntrypointVLD
          VAProfileJPEGBaseline           :	VAEntrypointVLD
          VAProfileJPEGBaseline           :	VAEntrypointEncPicture
          VAProfileH264ConstrainedBaseline:	VAEntrypointVLD
          VAProfileH264ConstrainedBaseline:	VAEntrypointEncSlice
          VAProfileH264ConstrainedBaseline:	VAEntrypointFEI
          VAProfileH264ConstrainedBaseline:	VAEntrypointEncSliceLP
          VAProfileVP8Version0_3          :	VAEntrypointVLD
          VAProfileHEVCMain               :	VAEntrypointVLD
          VAProfileHEVCMain               :	VAEntrypointEncSlice
          VAProfileHEVCMain               :	VAEntrypointFEI
    
  9. Build the Media SDK library, please skip this if run script in #6.
    Note
    - If you want to use the latest version, skip the commands "git checkout <commit id>" in the following instructions.
    - If you want to use the test version, please find the commit ID of MediaSDK in the configurations table at the end of this guide.
    - For Apollo Lake platform support, add "--target=BXT" to the end of the cmake command, so "perl tools/builder/build_mfx.pl --cmake=intel64.make.release --target=BXT"
    # cd $WORKING_DIR
    # git clone https://github.com/Intel-Media-SDK/MediaSDK.git
    # cd MediaSDK
    # git checkout <Media SDK commit id>
    # export MFX_HOME=`pwd`
    # perl tools/builder/build_mfx.pl --cmake=intel64.make.release
    # make -C __cmake/intel64.make.release/ -j4
    # cd __cmake/intel64.make.release
    # sudo make install
  10. Brief validate the build
    To run the sample code under the built libraries, it must use the sample binary built in the Media SDK library source tree. Currently, the sample code intended for the released version of Media SDK will fail because of the different environment requirements.
    The following instructions assume starting in a new terminal so he has to set all the required environment variables must be set.
    # cd $WORKING_DIR
    # cd MediaSDK/__cmake/intel64.make.release/__bin/release
    # export MFX_HOME=/opt/intel/mediasdk
    # export LIBVA_DRIVERS_PATH=/usr/lib/x86_64-linux-gnu/dri
    # export LIBVA_DRIVER_NAME=iHD
    # ./sample_multi_transcode -i::h264 input.264 -o::h264 out.264
    Note: the input and output file extension here is the format of the elementary stream. Media SDK  processes video elementary streams only. If you don't have easy access to an input video file in elementary stream format, you can download the sample package from the sample code page. After extracting the sample package, the test content files can be found at the directory "~/samples/_bin/content".

Build Instruction for CentOS 7.4.1708

  1. Install OS
    This build guide assumes a new installation of CentOS 7.4. First install the system with the minimal package and then install and enable GNOME desktop environment. Update with the latest OS updates.
    #  yum update
    #  reboot
    #  yum group list
    #  yum groupinstall "GNOME Desktop"
    #  systemctl set-default graphical.target
    #  reboot
    #  visudo
    

    Note: Run these commands under "root", then add the sudoer to the system

  2. Prepare the system with the system tools/library
    These tools and library dependencies are required for the build process.  The installation of "mesa-libGL-devel" dependencies makes sure the full configuration required to build libVA is available.
    Note: If you don't want to replace the kernel, you can jump to step #5 to use the script to complete the build process.
    # sudo yum install -y git gcc gcc-c++ openssl-devel elfutils-libelf-devel automake autoconf libtool mesa-libGL-devel libpciaccess-devel
    # mkdir <path-to-working-directory>
    # export WORKING_DIR=<path-to-working-directory>

    Download and install cmake by following the instructions at the cmake installation page:

    # cd WORKING_DIR
    # wget https://cmake.org/files/v3.10/cmake-3.10.1.tar.gz
    # tar xvzf cmake-3.10.1.tar.gz
    # cd WORKING_DIR/cmake-3.10.1
    # ./bootstrap --prefix=/usr
    # make
    # sudo make install
    
  3. Firmware Check and update
    There are 3 kinds of graphics firmware, GUC, HUC and DMC. Please check i915 kernel mode driver for the required firmware version, then use the following command to check the firmware version:
    # ls -al /lib/firmware/i915/ | grep skl_dmc
    -rw-r--r--.  1 root root   8824 Jan  3 18:52 skl_dmc_ver1_23.bin
    -rw-r--r--.  1 root root   8928 Jan  3 18:52 skl_dmc_ver1_26.bin
    lrwxrwxrwx.  1 root root     19 Jan 16 19:58 skl_dmc_ver1.bin -> skl_dmc_ver1_26.bin

    DMC v1.26 is required on the SkyLake platform with Kernel 4.14.16. Install it as follows:

    # cd WORKING_DIR
    # git clone https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git
    # sudo cp linux-firmware/i915/skl_dmc_ver1_26.bin /lib/firmware/i915/.
  4. Build the Kernel 4.14.16
    Note: Kernel 4.14.16 must be used in this article, later version should work but was not tested.
    # cd $WORKING_DIR
    # uname -r
    3.10.0-693.11.6.el7.x86_64
    # git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
    # cd linux-stable/
    # git checkout -b my_v4.14.16 v4.14.16
    # cp /boot/config-`uname -r` .config
    # make olddefconfig
    # make -j8 
    # sudo make modules_install
    # sudo make install

    Note:
    - After the kernel build, reboot the system; at the start options menu, select "Kernel 4.14.16" to start the system
    - After login to the system, use command "uname -r" to make sure the system is running on kernel 4.14.16; if not, update GRUB manually.

  5. Run operation 6~8 with script, skip this step if you want to build manually
    • Download the attached script build_msdk_centos.sh.
    • Unzip to any local folder, for example, "Downloads", run it as a normal user.
    • The script is using a working directory, you can either create one either or generate automatically.
    • The script has two version options, either the master with the latest version or the tested commit ID (listed at the bottom of this article). We recommend the master version since it is synced with the latest changes; the tested commit ID works as a fallback if the master version failed, it was created earlier and has the rendering issue when running the sample code.
    • The script doesn't clean up automatically when running back-to-back, please manually remove the working directory with command "rm -rf <working directory>" any time before re-run it.
  6. Build the libVA libraries, please skip this if run script in #5.
    Note:
    - If you want to use the latest version, skip the commands "git checkout <commit id>" in the following instructions.
    - If you want to use the test version, please find the commit ID of libva and libva-utils in the configurations table at the end of this guide.
    # cd $WORKING_DIR
    # git clone https://github.com/intel/libva.git
    # git clone https://github.com/intel/libva-utils.git
    # cd $WORKING_DIR/libva
    # git checkout <libva commit id>
    # ./autogen.sh --prefix=/usr --libdir=/usr/lib64
    # make -j4
    # sudo make install
    # cd $WORKING_DIR/libva-utils
    # git checkout <libva-utils commit id>
    # ./autogen.sh --prefix=/usr --libdir=/usr/lib64
    # make -j4
    # sudo make install
    Note: At the end of the autogen.sh command, check and make sure the drm, x11 and glx components are configured, the expected output is the same as the Ubuntu instructions above.
  7. Build the media driver, please skip this if run script in #5.
    Note
    - If you want to use the latest version, skip the commands "git checkout <commit id>" in the following instructions.
    - If you want to use the test version, please find the commit ID of gmmlib and media-driver in the configurations table at the end of this guide.
    # cd $WORKING_DIR
    # git clone https://github.com/intel/media-driver.git
    # git clone https://github.com/intel/gmmlib.git
    # cd $WORKING_DIR/gmmlib
    # git checkout <gmmlib commit id>
    # cd $WORKING_DIR/media-driver
    # git checkout <media-driver commit id>
    # cd $WORKING_DIR
    # mkdir -p build
    # cd $WORKING_DIR/build
    # cmake ../media-driver \
    -DMEDIA_VERSION="2.0.0" \
    -DBUILD_ALONG_WITH_CMRTLIB=1 \
    -DBS_DIR_GMMLIB=`pwd`/../gmmlib/Source/GmmLib/ \
    -DBS_DIR_COMMON=`pwd`/../gmmlib/Source/Common/ \
    -DBS_DIR_INC=`pwd`/../gmmlib/Source/inc/ \
    -DBS_DIR_MEDIA=`pwd`/../media-driver \
    -DCMAKE_INSTALL_PREFIX=/usr \
    -DCMAKE_INSTALL_LIBDIR=/usr/lib64 \
    -DINSTALL_DRIVER_SYSCONF=OFF \
    -DLIBVA_DRIVERS_PATH=/usr/lib64/dri
    # make -j8
    # sudo make install
    # export LIBVA_DRIVER_NAME=iHD
    # export LIBVA_DRIVERS_PATH=/usr/lib64/dri
    # vainfo

    Note: The "libva-utils" module is used to build the "vainfo" utility, which is a helpful diagnostic tool to check your libVA environment.
    "vainfo" expected output is the same as in Ubuntu instructions above.

  8. Build the Media SDK Library, please skip this if run script in #5.
    Note
    - If you want to use the latest version, skip the commands "git checkout <commit id>" in the following instructions.
    - If you want to use the test version, please find the commit ID of MediaSDK in the configurations table at the end of this guide.
    - For Apollo Lake platform support, add "--target=BXT" to the end of the cmake command, so "perl tools/builder/build_mfx.pl --cmake=intel64.make.release --target=BXT"
    # cd $WORKING_DIR
    # git clone https://github.com/Intel-Media-SDK/MediaSDK.git
    # cd MediaSDK
    # git checkout <Media SDK commit id>
    # export MFX_HOME=`pwd`
    # perl tools/builder/build_mfx.pl --cmake=intel64.make.release
    # make -C __cmake/intel64.make.release/ -j4
    # cd __cmake/intel64.make.release
    # sudo make install
  9. Brief validate the build
    To run the sample code under the built libraries, you must use the sample binaries built in the Media SDK library source tree. Currently, The released sample code will fail because of the different environment requirements.
    The following instructions assume starting a new terminal. You must set all the require environment variables.
    # cd $WORKING_DIR
    # cd MediaSDK/__cmake/intel64.make.release/__bin/release
    # export MFX_HOME=/opt/intel/mediasdk
    # export LIBVA_DRIVERS_PATH=/usr/lib64/dri
    # export LIBVA_DRIVER_NAME=iHD
    # ./sample_multi_transcode -i::h264 input.264 -o::h264 out.264

    Note: the input and output file extension here is the format of the elementary stream. Media SDK processes video elementary streams only. If you don't have easy access to an input video file in elementary stream format, you can download the sample package from the sample code page. After extracting the sample package, the test content files can be found at the directory "~/samples/_bin/content".

Debug the Media SDK library

To debug the Media SDK library, the binaries must be built in the debug mode. You can run your application with GDB command or other Linux debuggers as with any standard application/library code. The following instructions assume you have successfully built the media stack on Ubuntu 16.04.3 and are starting a new terminal.

# cd $WORKING_DIR/build
# cmake ../media-driver \
-DMEDIA_VERSION="2.0.0" \
-DBUILD_ALONG_WITH_CMRTLIB=1 \
-DBS_DIR_GMMLIB=`pwd`/../gmmlib/Source/GmmLib/ \
-DBS_DIR_COMMON=`pwd`/../gmmlib/Source/Common/ \
-DBS_DIR_INC=`pwd`/../gmmlib/Source/inc/ \
-DBS_DIR_MEDIA=`pwd`/../media-driver \
-DCMAKE_INSTALL_PREFIX=/usr \
-DCMAKE_INSTALL_LIBDIR=/usr/lib/x86_64-linux-gnu \
-DINSTALL_DRIVER_SYSCONF=OFF \
-DLIBVA_DRIVERS_PATH=/usr/lib/x86_64-linux-gnu/dri \
-DBUILD_TYPE=Debug
# make -j8
# sudo make install
# cd $WORKING_DIR/MediaSDK
# export MFX_HOME=`pwd`
# export LIBVA_DRIVER_NAME=iHD
# export LIBVA_DRIVERS_PATH=/usr/lib/x86_64-linux-gnu/dri
# perl tools/builder/build_mfx.pl --cmake=intel64.make.debug
# make -C __cmake/intel64.make.debug/ -j4
# cd __cmake/intel64.make.debug
# sudo make install
# cd __cmake/intel64.make.debug/__bin/debug
# export MFX_HOME=/opt/intel/mediasdk
# gdb --args ./sample_multi_transcode -i::h264 input.264 -o::h264 out.264

Note: the debug tool is GDB--The GNU debugger

Validated configuration

OSUbuntu 16.04.3CentOS 7.4.1708
ProcessorCore i7-6770HQCore i7-6770HQ
Kernel4.14.164.14.16
CompilerGCC 5.4gcc 4.8.5
libvafbf7138389f7d6adb6ca743d0ddf2dbc232895f6c88000b75602ded8ec24e6ea032f4841a4437049
libva-utils7b85ff442d99c233fb901a6fe3407d53089716457b85ff442d99c233fb901a6fe3407d5308971645
GMMLibb1451bbe4c506f17ddc819f12b4b448fc08698c5b1451bbe4c506f17ddc819f12b4b448fc08698c5
media-driver2eab2e248c5787ceaebd76be791e60e28e56fbf3170673341a3da890336d5774702929e2fb346239
MediaSDKe54022c1dbdcbd93b502f0da37352c9e9d103180c3ba904ccee661aac8a7af08d714ed36369f1de0

Hardware Platform: Skull Canyon NUC

Reference

Intel® Linux Graphics Firmware

The GNU Project Debugger

Ubuntu Desktop

The CentOS Project

Ukuu Kernel Update Utility

Ukuu Makes it Easy to Install Mainline Linux Kernels on Ubuntu

 

For more complete information about compiler optimizations, see our Optimization Notice.