An Operation Guide to Build, Install and Debug Media SDK Software Stack in Legacy Linux OS

ID 672356
Updated 1/4/2018
Version Latest
Public

author-image

By

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 diagram Repo Library names
libVA API llbva, libva-utils libva*.so
VAAPI Intel Driver media-driver, GMMLib iHD_drv_video.so, igfxcmrt64.so
Media SDK Library MediaSDK libmfxhw64.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 primary 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

For this guide, the default kernel should be replaced with version 4.14.16 or newer.  The newer kernels include the latest Intel graphic driver to enable the function required by the media stack. I this article, we tested with kernel 4.14.16 and 4.14.20. For Media SDK, we tested with release Media SDK 20.2.1

 

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
    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 libelf-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. Although it makes it easier to migrate new kernels, it became a paid tool recently.
    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 and install the kernel, this can be skipped if choosing #4.
    Note: Kernel version 4.14.16/4.14.20 can 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
# sudo update-grub
# sudo reboot now
    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.
    - After reboot, some system components, for example, WiFi might be disabled; this is observed during the test and doesn't block the following steps.
  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 primary with the latest version or the tested commit ID (listed at the bottom of this article). We recommend the primary version since it is synced with the latest changes; the tested commit ID works as a fallback if the primary 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.
    By checking the release note, we learned the tag of libVA libraries is "2.8.0"
    Note:
    - If you want to use the latest version, skip the commands "git checkout -b 2.8.0" 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 -b 2.8.0
# ./autogen.sh --prefix=/usr --libdir=/usr/lib/x86_64-linux-gnu
# make -j4
# sudo make install
# cd $WORKING_DIR/libva-utils
# git checkout -b 2.8.0
# ./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.8.0 (VA-API 1.8.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 step if run script in #6.
    By checking the release note, we learned the tag of media driver is "intel-media-20.2.0"
    Note: 
    - If you want to use the latest version, skip the commands "git checkout -b intel-media-20.2.0" 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 -b intel-gmmlib-20.2.2
# cd $WORKING_DIR/media-driver
# git checkout -b intel-media-20.2.0
# cd $WORKING_DIR
# mkdir -p build
# cd $WORKING_DIR/build
# cmake ../media-driver
# 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.8.0
libva info: Trying to open /usr/lib/x86_64-linux-gnu/dri/iHD_drv_video.so
libva info: Found init function __vaDriverInit_1_8
libva info: va_openDriver() returns 0
vainfo: VA-API version: 1.8 (libva 2.8.0)
vainfo: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 20.2.0 (97e2ea9)
vainfo: Supported profile and entrypoints
      VAProfileNone                   :	VAEntrypointVideoProc
      VAProfileNone                   :	VAEntrypointStats
      VAProfileMPEG2Simple            :	VAEntrypointVLD
      VAProfileMPEG2Simple            :	VAEntrypointEncSlice
      VAProfileMPEG2Main              :	VAEntrypointVLD
      VAProfileMPEG2Main              :	VAEntrypointEncSlice
      VAProfileH264Main               :	VAEntrypointVLD
      VAProfileH264Main               :	VAEntrypointEncSlice
      VAProfileH264Main               :	VAEntrypointFEI
      VAProfileH264High               :	VAEntrypointVLD
      VAProfileH264High               :	VAEntrypointEncSlice
      VAProfileH264High               :	VAEntrypointFEI
      VAProfileVC1Simple              :	VAEntrypointVLD
      VAProfileVC1Main                :	VAEntrypointVLD
      VAProfileVC1Advanced            :	VAEntrypointVLD
      VAProfileJPEGBaseline           :	VAEntrypointVLD
      VAProfileH264ConstrainedBaseline:	VAEntrypointVLD
      VAProfileH264ConstrainedBaseline:	VAEntrypointEncSlice
      VAProfileH264ConstrainedBaseline:	VAEntrypointFEI
      VAProfileVP8Version0_3          :	VAEntrypointVLD
  9. Build the Media SDK library, please skip this if run script in #6.
    By checking the release note, we learned the tag of media driver is "intel-mediasdk-20.2.1"
    Note: 
    - If you want to use the latest version, skip the commands "git checkout -b intel-mediasdk-20.2.1" 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 -b intel-mediasdk-20.2.1
# mkdir build && cd build
# cmake ..
# make -j8
# 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/build/__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 primary with the latest version or the tested commit ID (listed at the bottom of this article). We recommend the primary version since it is synced with the latest changes; the tested commit ID works as a fallback if the primary 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 Releases

For the validated source code, please go to the following release tags:

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

 

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.