source: multimedia/libdriv/intel-media.xml@ 6354d17

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

<!--<!ENTITY intel-media-driver-version                "23.2.4">-->

  <!ENTITY intel-media-download-http "https://github.com/intel/media-driver/archive/refs/tags/intel-media-&intel-media-version;.tar.gz">
  <!ENTITY intel-media-download-ftp  " ">
  <!ENTITY intel-media-md5sum        "5e2fffaf1c1972b8791c3cfd59cd6a9e">
  <!ENTITY intel-media-size          "25 MB">
  <!ENTITY intel-media-buildsize     "2.1 GB (359 MB installed)">
  <!ENTITY intel-media-time          "6.3 SBU (with parallelism=4)">

]>

  <sect1 id="intel-media" xreflabel="intel-media-&intel-media-version;">
  <?dbhtml filename="intel-media.html"?>

    <sect1info>
      <date>$Date$</date>
    </sect1info>

    <title>intel-media-&intel-media-version;</title>

    <indexterm zone="intel-media">
      <primary sortas="a-intel-media">intel-media</primary>
    </indexterm>

    <sect2 role="package">
      <title>Introduction to intel-media</title>

      <para>
        The <application>intel-media</application> package provides a
        VA API driver for Intel GPUs that are provided with Broadwell CPUs and
        higher. This includes support for a variety of codecs.
      </para>

      &lfs120_checked;

      <bridgehead renderas="sect3">Package Information</bridgehead>
      <itemizedlist spacing="compact">
        <listitem>
          <para>
            Download (HTTP): <ulink url="&intel-media-download-http;"/>
          </para>
        </listitem>
        <listitem>
          <para>
            Download (FTP): <ulink url="&intel-media-download-ftp;"/>
          </para>
        </listitem>
        <listitem>
          <para>
            Download MD5 sum: &intel-media-md5sum;
          </para>
        </listitem>
        <listitem>
          <para>
            Download size: &intel-media-size;
          </para>
        </listitem>
        <listitem>
          <para>
            Estimated disk space required: &intel-media-buildsize;
          </para>
        </listitem>
        <listitem>
          <para>
            Estimated build time: &intel-media-time;
          </para>
        </listitem>
      </itemizedlist>

<!--
      <bridgehead renderas="sect2">Additional Downloads</bridgehead>
      <itemizedlist spacing="compact">
        <listitem>
          <para>
            Required patch:
            <ulink url="&patch-root;/intel-media-&intel-media-version;-upstream_fixes-1.patch"/>
          </para>
        </listitem>
      </itemizedlist>
-->

      <note>
        <para>
          The tarball <filename>intel-media-&intel-media-version;.tar.gz</filename>
          will extract to the directory
          <filename class="directory">media-driver-intel-media-&intel-media-version;</filename>.
        </para>
      </note>

      <bridgehead renderas="sect3">intel-media Dependencies</bridgehead>

      <bridgehead renderas="sect4">Required</bridgehead>
      <para role="required">
        <xref linkend="cmake"/>,
        <xref linkend="intel-gmmlib"/>,
        <xref linkend="libva"/>, and
        <xref linkend="xorg-env"/>
      </para>

    </sect2>

    <sect2 role="kernel" id='intel-media-kernel'>
      <title>Kernel Configuration</title>

      <para>
        Enable the following options in the kernel configuration.
        Recompile the kernel if necessary:
      </para>

      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
        href="intel-media-kernel.xml"/>

      <indexterm zone="intel-media intel-media-kernel">
        <primary sortas="d-intel-media">intel-media</primary>
      </indexterm>
    </sect2>

    <!-- TODO: It's said Gen9+ (Skylake or later) may need some firmware files. -->

    <sect2 role="installation">
      <title>Installation of intel-media</title>

      <note>
        <para>
          This package takes a long time to build because it compiles code
          specific to each individual generation of Intel GPUs and for a
          variety of media codecs.
        </para>

        <!-- This reduce the size of iHD_drv_video.so from 319M to 157M
             for me.  -->
        <!-- It seems ARL depends on MTL.  We need to review once an Arrow
             Lake CPU is launched.  -->
        <!-- Support for ARL is completely broken, needs to be turned off to 
             complete the build -->
        <para>
          If you know the model of your Intel GPU, you can pass the
          <option>-D{GEN{8,9,11,12},MTL,ARL}=OFF</option> option to the
          <command>cmake</command> command but leaving the option for your
          GPU out.  Note that the <quote>GEN</quote> number here is the
          generation of the GPU, not the CPU.  For example, with an Intel
          Core i7-1065G7 CPU shipping a 11th-generation Intel GPU, the
          <option>-D{GEN{8,9,12},MTL,ARL}=OFF</option> option can be used
          so the code specific to the other generations of Intel GPUs won't
          be built.
        </para>

        <para>
          To determine the model of the Intel GPU, run
          <command>lspci -nn | grep -Ei 'VGA|DISPLAY'</command> first.
          It will output some information about the GPU.  If the output
          contains <literal>Meteor Lake</literal>, the GPU model is
          <literal>MTL</literal>.  Otherwise, follow
          <ulink url='https://dgpu-docs.intel.com/devices/hardware-table.html'/>
          to find the entry for your GPU and the model of the GPU should
          be in the <quote>Architecture</quote> column.  The Xe and XeHPG
          architectures are covered by the <literal>GEN12</literal> model.
        </para>
        <!-- TODO: The info about MTL is my best guess, the referred Intel
        page does not contain Meteor Lake GPU PCI devicd ID as at Feb 2024.
        XeHPC is not enabled by default but they are some data center GPUs.
        Not sure if anyone will run LFS in a data center. -->
      </note>

<!--
      <para>
        First, fix a few build failures with GCC-13:
      </para>

 <screen><userinput remap="pre">patch -Np1 -i ../intel-media-&intel-media-version;-upstream_fixes-1.patch</userinput></screen>
-->

      <para>
        Install <application>intel-media</application> by running the
        following commands:
      </para>

<screen><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

cmake -DCMAKE_INSTALL_PREFIX=$XORG_PREFIX \
      -DINSTALL_DRIVER_SYSCONF=OFF        \
      -DBUILD_TYPE=Release                \
      -G Ninja                            \
      -Wno-dev ..                   &amp;&amp;
ninja</userinput></screen>


      <para>
        This package does not come with a test suite.
      </para>

      <para>
        Now, as the <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>ninja install</userinput></screen>

    </sect2>

    <!-- As of Oct 1 2023, the build is broken if MTL and ARL are turned on
         hopefully this is fixed by the time they launch, in which 
         case we can remove the option and this section [rahul] -->
    <!-- As of October 31st, 2023, the build seems to be functional again! This
         is with version 23.4.0. [renodr]
    <sect2 role="commands">
      <title>Command Explanations</title>
       
      <para>
        <parameter>-D{MTL,ARL}=OFF</parameter>: As of October 2023,
        Meteor Lake and Arrow Lake iGPU support is broken but still
        in intel-media. The build fails if support for either iGPU
        is turned on. Since both of these have not been officially
        released yet, it is safe to turn support for them off.
      </para>

     </sect2> 
    -->

    <sect2 role="content">
      <title>Contents</title>

      <segmentedlist>
        <segtitle>Installed Programs</segtitle>
        <segtitle>Installed Libraries</segtitle>
        <segtitle>Installed Drivers</segtitle>
        <segtitle>Installed Directories</segtitle>

        <seglistitem>
          <seg>
            None
          </seg>
          <seg>
            libigfxcmrt.so
          </seg>
          <seg>
            iHD_drv_video.so
          </seg>
          <seg>
            /usr/include/igfxcmrt
          </seg>
        </seglistitem>
      </segmentedlist>

      <variablelist>
        <bridgehead renderas="sect2">Short Descriptions</bridgehead>
        <?dbfo list-presentation="list"?>
        <?dbhtml list-presentation="table"?>

        <varlistentry id="libigfxcmrt">
          <term><filename class="libraryfile">libigfxcmrt.so</filename></term>
          <listitem>
            <para>
              provides API functions which allow running GPU kernels on the
              render engine
            </para>
            <indexterm zone="intel-media libigfxcmrt">
              <primary sortas="c-libigfxcmrt">libigfxcmrt.so</primary>
            </indexterm>
          </listitem>
        </varlistentry>

      </variablelist>

    </sect2>

  </sect1>