hololink::module::HololinkInterfaceV1

Access features on an HSB device.

This is the application’s handle to the device itself: it opens and closes the control plane, drives the device into a known state, reads and writes device registers, and hands out the other services that work on this device – data channels, I2C buses, sequencers and VSYNC sources.

Fetch it with the EnumerationMetadata describing the device, then bring the device up before configuring a sensor on it:

#include <hololink/module/hololink.hpp>

Example

auto& adapter = hololink::module::Adapter::get_adapter();
auto metadata = adapter.wait_for_channel(hololink_ip, discovery_timeout);
auto hololink = hololink::module::HololinkInterfaceV1::get_service(metadata);
// No device I/O works until the control plane is open.
hololink->start();
// The framework leaves device state alone unless the application asks;
// reset() drives the board into a known state.
hololink->reset();
// ... configure sensors, run the pipeline ...
// Close connections to the device.
hololink->stop();

Inherits from: hololink::module::ConfigurableService< HololinkInterfaceV1 > (public), std::enable_shared_from_this< HololinkInterfaceV1 > (public)

Methods

enumeration_metadata

virtual const EnumerationMetadata & hololink::module::HololinkInterfaceV1::enumeration_metadata() const

The enumeration metadata this device was configured with.

Services sharing this device read the configuration metadata from this snapshot rather than keeping a copy of their own, so they are all built from the same values.

start

virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::start()

Open the control plane to the device.

Register access, I2C traffic and anything else that reaches the device works only while the control plane is open, so an application calls this before configuring the device. Calling it again while it is open does nothing.

Returns: HOLOLINK_MODULE_OK or an error status.

stop

virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::stop()

Close the control plane to the device.

Applications call this when they are done with the device; it does nothing if the control plane is already closed.

Returns: HOLOLINK_MODULE_OK or an error status.

reset

virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::reset()

Drive the device into a known state.

Resets the device, waits for it to come back and announce itself, then applies the configuration the control plane needs. Every callback registered through on_reset() fires. Applications reset a device before configuring the sensors on it: the framework changes no device state on its own.

Returns: HOLOLINK_MODULE_OK or an error status.

device_lost

virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::device_lost()

Invalidate the services cached for this device, following loss of contact with it.

Services built for a device accumulate device state, which goes stale when the device is lost. Once an application discovers the loss it calls this, and the framework drops its references to those service objects. When the device comes back and is enumerated again, calls to get_service build new instances, in sync with the recovered device. The application drops its own references to the older objects; calls on those stale instances fail in ways that depend on the service.

Returns: HOLOLINK_MODULE_OK or an error status.

ptp_synchronize

virtual bool hololink::module::HololinkInterfaceV1::ptp_synchronize()

Wait for the device’s clock to synchronize with the PTP grandmaster.

Blocks until the device’s clock is disciplined, so that the timestamps it reports with each frame share the host’s PTP domain. Applications that rely on those timestamps call this after start() or reset().

Returns: True once the clock is synchronized; false if it did not synchronize within a default timeout.

on_reset

virtual std::shared_ptr<ResetRegistration> hololink::module::HololinkInterfaceV1::on_reset(
    std::function<void()> callback
)

Register a callback fired each time this device completes a reset.

The callback runs once per reset(), after the device has rebooted and its HSB configuration has been re-applied. Sensor drivers register here to drop the hardware state they cached, so the next configuration pass writes it to the device again. Any number of callbacks may be registered.

Returns: Handle keeping the callback registered; destroying it unregisters the callback.

Parameters

write_uint32

virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::write_uint32(
    const std::vector<uint32_t> &addresses,
    const std::vector<uint32_t> &values
)

Write to locations within the HSB IP local bus.

Returns: HOLOLINK_MODULE_OK, or HOLOLINK_MODULE_INVALID_PARAMETER when the two lists differ in length.

Parameters

read_uint32

virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::read_uint32(
    const std::vector<uint32_t> &addresses,
    std::vector<uint32_t> &out_values
)

Read locations within the HSB IP local bus.

Returns: HOLOLINK_MODULE_OK or an error status.

Parameters

and_uint32

virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::and_uint32(
    uint32_t address,
    uint32_t mask
)

Clear bits in an HSB IP local bus location.

Reads the register, ANDs the value with mask, and writes it back.

Returns: HOLOLINK_MODULE_OK or an error status.

Parameters

or_uint32

virtual hololink_module_status_t hololink::module::HololinkInterfaceV1::or_uint32(
    uint32_t address,
    uint32_t mask
)

Set bits in an HSB IP local bus location.

Reads the register, ORs the value with mask, and writes it back.

Returns: HOLOLINK_MODULE_OK or an error status.

Parameters

get_i2c

template <typename T = I2cInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::get_i2c(
    uint32_t bus,
    uint32_t address,
    bool allow_null = false
)

Fetch a I2C driver object.

The bus reaches every peripheral on it; each transaction names the peripheral it addresses.

Returns: The I2C interface for that bus.

Template parameters

Parameters

software_sequencer

template <typename T = SequencerInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::software_sequencer(
    bool allow_null = false
)

Sequencer for use with immediately triggered sequences.

Sequencers are implemented within the HSB IP to trigger sets of HSB IP local bus transactions (e.g. to execute an I2C transaction) on a specific flag (e.g. a GPIO or frame-done event). Use this sequencer when you want a sequence to run immediately.

Returns: The sequencer.

Template parameters

Parameters

gpio0_sequencer

template <typename T = SequencerInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::gpio0_sequencer(
    bool allow_null = false
)

Sequencer to trigger a sequence when GPIO0 is active.

Returns: The sequencer.

Template parameters

Parameters

gpio1_sequencer

template <typename T = SequencerInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::gpio1_sequencer(
    bool allow_null = false
)

Sequencer to trigger a sequence when GPIO1 is active.

Returns: The sequencer.

Template parameters

Parameters

sif0_frame_start_sequencer

template <typename T = SequencerInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::sif0_frame_start_sequencer(
    bool allow_null = false
)

Sequencer to trigger a sequence when SIF0 (sensor interface 0) receives the first data from a sensor following a frame end condition.

Returns: The sequencer.

Template parameters

Parameters

sif1_frame_start_sequencer

template <typename T = SequencerInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::sif1_frame_start_sequencer(
    bool allow_null = false
)

Sequencer to trigger a sequence when SIF1 (sensor interface 1) receives the first data from a sensor following a frame end condition.

Returns: The sequencer.

Template parameters

Parameters

ptp_pps_output

template <typename T = PtpPpsOutputInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::ptp_pps_output(
    bool allow_null = false
)

Fetch a PTP-based PPS output controller, for use with sensors that can be triggered externally (e.g.

cameras with VSYNC inputs).

One PTP PPS output serves the whole device, driven by the PPS the device’s PTP-disciplined clock produces. Use the object returned here to configure the PPS rate; this same object is usually passed in to a device driver to ask it to use that as the sample trigger input.

Returns: the PPS controller based on PTP

Template parameters

Parameters

null_vsync

template <typename T = VsyncInterfaceV1>
std::shared_ptr<T> hololink::module::HololinkInterfaceV1::null_vsync(
    bool allow_null = false
)

When a sensor takes a PPS sync input, use this instance to configure the device for free-running (unsynchronized) operation.

Returns: The VSYNC source.

Template parameters

Parameters

configure

virtual void hololink::module::ConfigurableService<HololinkInterfaceV1>::configure(
    const EnumerationMetadata &
)

Use metadata contents to initialize this instance.

This routine is guaranteed to be called the first time a call to get_service(metadata) is called on a specific service instance.

module

std::shared_ptr<Module> hololink::module::ServiceBase::module() const

The Module that this service was published from.

The service holds no strong reference to its Module, so this does not extend the Module’s lifetime.

Returns: The owning Module, or an empty pointer if the service has not been published or its Module no longer exists.

Static methods

get_service

static std::shared_ptr<HololinkInterfaceV1> hololink::module::ConfigurableService<HololinkInterfaceV1>::get_service(
    const EnumerationMetadata &metadata,
    bool allow_null = false
)

for_each_type_id

static bool hololink::module::Service<HololinkInterfaceV1>::for_each_type_id(
    Callback &&cb
)

Iterate over every type_id supported by this instance.

The callback signature is bool(const char*) — returning false halts the walk; true continues. Iteration is depth-first, so you’ll see the most specific implementation types first.

Inner classes

ResetRegistration

class hololink::module::HololinkInterfaceV1::ResetRegistration

Handle to a callback registered with on_reset().

The callback fires while the handle is held, and is unregistered when the handle is destroyed. Hold it for as long as the callback should fire.