HAL Architecture

Introduction to HAL

The HAL (Hardware Abstraction Layer) is designed as an API to access event-based camera hardware functionalities in a generic way by defining high-level capability interfaces generalizing these functionalities. The purpose of this generic API is to enable operating different event-based cameras from a unified API. This makes it much easier:

for camera manufacturers to integrate with existing event-based applications

for application developers to support different devices

The dynamic plugin-based architecture of HAL also enables each camera manufacturer to make different system integration choices. For example, the board communication can be implemented using any protocol (USB, MIPI, Ethernet, etc.) as explained in the the Treuzell Protocol page.

HAL Components

The generic access to camera functionalities is achieved using high-level capability interfaces called facilities, which define the standard high-level behavior of each camera functionality. For example, different event-based sensors can implement the concept of Region Of Interest (ROI) in various ways (typically with a series of register accesses) but HAL provides a single I_ROI facility that proposes multiple functions that can be used on those multiple sensors/cameras (Metavision::I_ROI::set_window(), Metavision::I_ROI::enable()…).

When a new camera functionality needs to be supported by the HAL API, a new facility representing it is typically introduced, without impact on other cameras not supporting this functionality.

A given camera is operated using the corresponding HAL plugin, which is maintained and distributed by the device manufacturer.

The plugin is provided in the form of a shared library containing the implementations of the HAL facilities for each hardware feature supported by the device.

The selection of the plugin is done via the HAL Discovery mechanism that will enumerate and select the appropriate plugin for a given device as explained in the next section.

This dynamic plugin-based design enables any application built using Metavision HAL to be compatible, without any modification (compilation or link), with any camera providing its plugin.

The following diagram summarizes the relationships between those different components:

Device Discovery

HAL device discovery mechanism allows to build a Metavision::Device. The discovery entry point is the function DeviceDiscovery::open. This function will go through the following steps involving both the HAL module and the Plugin code:

get the list of the available plugins (plugins loading phase)

find and select the plugin that matches the camera

find a Camera Discovery from the selected plugin capable of opening the camera

build and return the Metavision::Device

This flow is shown in the following diagram depicting the cascade of calls:

Note that, when opening a RAW file, the device discovery behaves almost the same except that compatible plugins are first sorted in order of matching likelihood (priority to matching integrator and plugin names, then matching integrator name and finally any compatible plugin).

HAL Facilities

Facilities provide functions that expose a camera functionality (e.g ROI, biases, digital crop, etc.). The Metavision::I_Facility abstract class is the main class from which all other facilities inherit. A given facility interface exposes a functionality by defining virtual functions, for which plugins supporting this functionality must provide implementations.

From the user point of view, if a facility is available, it is expected that the corresponding camera functionality is available and can be used.

The main facilities are :

Metavision::I_EventsStream: interface that provides streaming control functionality and exposes buffer of raw data payload via the accompanying DataTransfer utility class

Metavision::I_EventsStreamDecoder and Metavision::I_EventFrameDecoder: interfaces that provides functions to convert raw data to events as exposed by the SDK base module by using decoding routines for EVT2.X, EVT3, frame histo/diff, etc. formats

Metavision::I_EventDecoder: interface to register event based callbacks to process decoded events when available

Metavision::I_HW_Identification: interface that provides information on the underlying camera system for identification purposes

Metavision::I_PluginSoftwareInfo: interface that provides information about the HAL version used to compile a specific plugin

Metavision::I_HALSoftwareInfo: interface that provides information about the actual HAL version (which can be different from the one used to build the plugin shared library)

This list is not exhaustive and many other facilities exist (I_LL_Biases, I_Monitoring, etc.). Refer to the facility API documentation for more information.

Next Steps

From here, depending on your interest, you can:

continue to explore the SDK architecture, by:

moving up the stack and checking the architecture of the SDK Stream module built on top of the HAL API

moving down the stack and discovering the Camera Plugin architecture

dive into the HAL API by checking the HAL Code Samples