View source for Vmeta

vMeta is a hardware-accelerated video encoding and decoding engine included in the XO-1.75 and XO-4.

== Installation ==

To obtain the packages referred to below, contact OLPC support.  You will be given a URL of a directory which contains packages.  In the instructions below, this is represented as $FIXME.

These instructions are for OLPC OS [[14.1.0]]:

For XO-1.75, the base package is ''marvell-ipp-mmp2'' and the gstreamer-0.10 plugin packages are ''gstreamer-plugins-marvell-mmp2'' and ''gstreamer-plugins-vmetaxv''.

For XO-4, the base package is ''marvell-ipp-mmp3'' and the gstreamer-0.10 plugin packages are ''gstreamer-plugins-marvell-mmp3'' and ''gstreamer-plugins-vmetaxv''

These packages may be added to your build, or added after install.

See [[OS_Builder/Add_Restricted|How to add restricted software to build]].

=== Add after Install ===

For XO-1.75:
 cd /etc/yum.repos.d
 sudo wget -q -O restricted.repo $FIXME/restricted.repo
 sudo yum install -y marvell-ipp-mmp2 gstreamer-plugins-marvell-mmp2 gstreamer-plugins-vmetaxv

For XO-4:
 cd /etc/yum.repos.d
 sudo wget -q -O restricted.repo $FIXME/restricted.repo
 sudo yum install -y gstreamer-plugins-marvell-mmp3 gstreamer-plugins-vmetaxv

=== gstreamer-1.0 ===

Install gstreamer1-plugins-vmeta (both laptop models) and gstreamer1-plugins-bad-free (for commonly required container support).

== Testing ==

Test videos:
* http://techslides.com/demos/sample-videos/small.mp4 (403 forbidden, as of 2013-10-01)
* http://download.openbricks.org/sample/H264/SampleClip.m4v
* http://archive.org/download/hellmans_mayonnaise_commercial/hellmans_mayonnaise_commercial.mpeg (might be a [http://dev.laptop.org/ticket/12741 bad sample]?)

You can play these in Totem under GNOME.

In some cases software decoders are available, so seeing the video play back doesn't mean that it is being done by the vmeta hardware engine. The best way to be confident that hardware accel is being used is by looking at totem standard output, which should be limited to:

<pre>
vmetadec istance(0x....) found
At finalizing, Gstvmetadec instance(0x....) DecErrorOccured is 0x0
Gstvmetadec instance(0x....) is finalized.
</pre>

Also look in <tt>dmesg</tt>, check that there are not any vmeta-related complaints there. You can also watch /proc/interrupts contents, the vmeta interrupts should increase while playing back the sample videos.

For a more direct gstreamer-0.10 test:
  gst-launch filesrc location=hellmans_mayonnaise_commercial.mpeg ! decodebin ! vmetaxvimagesink

For the same thing under gstreamer-1.0:
  gst-launch-1.0 filesrc location=hellmans_mayonnaise_commercial.mpeg ! decodebin ! vmetaxvsink

== Troubleshooting ==

=== Hangs after displaying first frame ===

Check that regular audio playback is working (e.g. with <tt>speaker-test</tt>).

=== Video plays back with no audio ===

Check that you have the appropriate audio codecs installed. Note that while the gstreamer-0.10 packages do include some software audio codecs, the gstreamer1 plugins do not include any audio codecs, you have to go and install them from other sources.

== Software component breakdown ==

=== uio_vmeta ===

This is an in-kernel UIO driver that allows the vmeta hardware engine to be driven from userspace (registers and interrupts). Some changes to the UIO core are needed as well.

=== libphycontmem ===

This library provides a userspace API to allocate and deal with a chunk of physically contiguous DMA-capable main memory. The buffer needs to be quite large, at least 32mb, 40mb in order to view higher quality videos.

Marvell code drops include backends for pmem and bmm (Buffer Management Module, probably a special kernel driver that provides such a buffer). An ion backend is also available from OLPC. This remains a sticky area.

* pmem was really designed to deal with fixed memory areas (e.g. graphics memory), but vmeta is something that we see as optional and on-demand; we don't want to hold this allocation even while vmeta is not being used, and we don't even know that vmeta ''will'' be used.
** When OLPC shipped this for 13.1.0 and previous, we unconditionally set up a DMA-coherent allocation in early boot.
** For 13.2.0 and newer, OLPC ships this solution for XO-1.75, but hacked to allocate the buffer only upon first use of pmem.
* ion is a little better, when combined with the DMA backend (which naturally uses CMA), now the allocation is done on-demand. However, ion provides no API to pass physical addresses to userspace, which is a requirement here.
** OLPC ships this for XO-4, plus a hack (a new ioctl) to provide physical addresses to userspace.
* OLPC has not explored the BMM approach (to the best of my knowledge); this does seem to have been abandoned in newer Marvell code drops though.
* An ideal approach would be for UIO to expose on-demand contiguous DMA allocations; while that has been discussed/proposed a few times, no implementation has gone upstream.

OLPC's version originates from the qseven alpha4 code drop. It has been modified to support ion, in addition to pmem, and to detect which one to use at runtime (we use ion on XO-4 and pmem on XO-1.75). pmem and ion helper code is built directly into the library.

Git repo: http://dev.laptop.org/git/users/dsd/libphycontmem

=== libvmeta ===

This library provides an API for interacting with the low-level vmeta hardware: management of DMA buffers, power, clocks, etc. It uses libphycontmem for memory management and interacts with the uio_vmeta kernel interface for the rest.

OLPC's current version originates from the qseven alpha4 code drop. OLPC's changes are limited to build system tweaks for packaging.

Git repo: http://dev.laptop.org/git/users/dsd/libvmeta

=== marvell-ipp, libvmetahal and libcodecvmetadec ===

:    ''Continuing the tradition that IPP is lumped into the vmeta category...:''

The IPP libraries are a set of proprietary '''software''' encoders/decoders. That makes them unrelated to vmeta, which is a hardware-based engine. There is also an overlap, the IPP codecs support some video formats that vmeta can play without software help. Shipping software codecs alongside a hardware-based decoding/encoding engine sounds odd but there is some basis for it:

* The vmeta specifications place some restrictions on video parameters for the supported formats. Maybe there are some files that vmeta cannot play, even though the base format is (generally) supported.
* vMeta only accelerates video, the audio stream must be decoded in software.
* These decoders are optimized for the hardware; we have versions that use iwMMXt2 and other versions that use NEON.
* While there is some overlap, the IPP codecs do support some video formats that are not supported by the hardware (e.g. wmv).

Further confusing the IPP software vs hardware situation, marvell-ipp (software codec package) ships the libraries required for hardware-accelerated vmeta playback.
libcodecvmeta{dec,enc} link against libvmetahal. These are closed source libraries provided by Marvell.

OLPC provides marvell-ipp-mmp3 (for XO-4) and marvell-ipp-mmp2 (for XO-1.75). These packages include both the IPP codec libraries, and the vmeta "codec" library, libvmetahal, and the supporting libmiscgen.

In marvell-ipp-mmp3, most libraries are hardfp. The files here come from the Marvell qseven alpha4 code drop. There are two incompatibilities with XO-1.75:
* Some IPP libraries are compiled with NEON instructions, XO-1.75/MMP2 does not support this instruction set
* There is some incompatibility between one of the new vmeta libraries (libmiscgen, libvmetahal, and/or libcodecvmetadec) that causes a bus error in libvmeta when used on XO-1.75.

In marvell-ipp-mmp2, most libraries are softfp. It is puzzling why they seem to work on our hardfp system. These files originate from OLPC's previous libvmeta-marvell-005 package. Beyond that, the source of these files is somewhat unknown. Possibly from a mixture of Android code drops and incomplete tarballs posted on symplicity.

Git repo: <tt>/home/dsd/private_git/marvell-ipp</tt> branch (mmp2/mmp3 branches)

=== gstreamer-plugins-marvell ===

This is a set of gstreamer plugins that provide playback via vmeta or with the IPP codecs. libgstvmetadec links against libcodecvmetadec, and the IPP-based elements link against the IPP libraries.

The IPP-based gstreamer plugins are set with a higher priority than default, so that they get preferred (even for existing applications). And the vmeta plugins have an even higher priority for the same reason. This means that existing gstreamer apps automatically use hardware-accelerated or IPP-optimized playback.

OLPC ships two versions:
# <b>gstreamer-plugins-marvell-mmp3</b> for XO-4. It requires the libraries and headers from marvell-ipp-mmp3, making it unsuitable for XO-1.75.
# <b>gstreamer-plugins-marvell-mmp2</b> for XO-1.75. It requires the libraries and headers from marvell-ipp-mmp2.

Git repo: http://dev.laptop.org/git/users/dsd/gst-plugins-marvell (mmp2/mmp3 branches)

=== gstreamer-plugins-vmetaxv ===

This package adds a fork of the xvimagesink plugin. This plugin uses a special hack to detect which buffers have come from the vmeta pipeline. When detected, physical addresses of such buffers can be sent straight to the graphics driver, avoiding a memcpy.

When incoming buffers have not originated from vmeta, the normal Xv display code is used (including a memcpy of the frame data).

Git repo: http://dev.laptop.org/git/users/dsd/gst-plugins-vmetaxv

=== gstreamer1-plugins-vmeta ===

Carlos Rafael Giani has implemented a new vmeta decoder (including the equivalent vmetaxv replacement) for gstreamer-1.0. The decoder is written from scratch and has several advantages over the previous implementation. See https://github.com/dv1/gst-vmeta for more info.

One important difference here is that these plugins do not include support for MPEG container formats and similar, whereas the 0.10 gstreamer plugins did. So you probably want to install gstreamer1-plugins-bad-free from Fedora for the container support.

Another change is that there are no gstreamer plugins included here for access to the IPP audio libraries. So, while the gstreamer-0.10 setup does include some additional audio support, for gstreamer-1.0 you will need to find the required audio codecs (e.g. AAC decoder) from elsewhere.

== Previous packages ==

See [[/Historical packages]]