Vmeta

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

Installation and test

Tested on 12.1.0 on XO-1.75.

1. Install gstreamer-plugins-marvell and libvmeta-marvell
2. Download http://techslides.com/demos/sample-videos/small.mp4 and play it in Totem in GNOME

For a beefier test video, try http://archive.org/download/hellmans_mayonnaise_commercial/hellmans_mayonnaise_commercial.mpeg

Note that these packages do include software decoders too (not sure why) so just 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:

vmetadec istance(0x....) found
At finalizing, Gstvmetadec instance(0x....) DecErroOccured is 0x0
Gstvmetadec instance(0x....) is finalized.

Also look in dmesg, check that there are not any vmeta-related complaints there.

For a more direct gstreamer test:

 gst-launch filesrc location=hellmans_mayonnaise_commercial.mpeg ! decodebin ! vmetaxvimagesink

Troubleshooting

Hangs after displaying first frame

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

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.

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.

marvell-ipp

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).

libvmetahal and libcodecvmeta

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.

gst-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.

gst-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).

Current packages

libphycontmem

This 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.

libvmeta

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

marvell-ipp-mmp3

This XO-4 package includes both the IPP codec libraries, and the vmeta "codec" library, libvmetahal, and the supporting libmiscgen. Most libraries are hardfp. 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.

The files here come from the Marvell qseven alpha4 code drop.

marvell-ipp-mmp2

This XO-1.75 package includes both the IPP codec libraries, and the vmeta "codec" library, libvmetahal, and the supporting libmiscgen. Most libraries are softfp, it is puzzling why they seem to work on our hardfp system.

These files come from OLPC's 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.

gstreamer-plugins-marvell-mmp3

This XO-4 package includes the gstreamer pipeline elements to use the IPP codecs and vmeta. It requires the libraries and headers from marvell-ipp-mmp3, making it unsuitable for XO-1.75.

gstreamer-plugins-marvell-mmp2

This XO-1.75 package includes the gstreamer pipeline elements to use the IPP codecs and vmeta. It requires the libraries and headers from marvell-ipp-mmp2.

Previous packages

See /Historical packages