Zephyr Versal SYSMON Driver Implementation

This page provides details on the implementation of the Versal SYSMON Zephyr driver.

Sensor Layer

The sensor driver does not use a subsystem. Instead, the Zephyr sensor framework header (sensor.h) validates the parameters passed and calls the driver API.

https://xilinx-wiki.atlassian.net/wiki/spaces/A/whiteboard/3435855922

Probe Data From Node

In driver we need to assign the compatible string to a zephyr macro, DT_DRV_COMPAT. If the assigned string matches with any one of the DT nodes with status property okay then driver register the Init API to the sensor framework using a framework structure.

Probe

#define DT_DRV_COMPAT xlnx_versal_sysmon

#define VERSAL_SYSMON_INIT(inst)                                                      \
        VERSAL_SYSMON_INTR_CONFIG(inst)                                               \
        static const struct sysmon_chan_data chans_##inst[] = {                       \
                DT_INST_FOREACH_CHILD(inst, SUPPLY_CHAN_DATA_INIT)};                  \
                                                                                      \
        static uint8_t match_idx_##inst[ARRAY_SIZE(chans_##inst)];                    \
        BUILD_ASSERT(DT_INST_PROP(inst, xlnx_numchannels) == ARRAY_SIZE(chans_##inst), \
                     "xlnx,numchannels must equal the number of channel child nodes"); \
                                                                                      \
        const static struct versal_sysmon_cfg sysmon_config_##inst = {                \
                DEVICE_MMIO_ROM_INIT(DT_INST(inst, DT_DRV_COMPAT)),                   \
                .num_channels = DT_INST_PROP(inst, xlnx_numchannels),                 \
                .chan = chans_##inst,                                                 \
                .irq_config_func = versal_sysmon_config_intr##inst};                  \
                                                                                      \
        static struct sysmon_data sysmon_data_##inst = {                              \
                .match_idx = match_idx_##inst,                                        \
        };                                                                            \
                                                                                      \
        SENSOR_DEVICE_DT_INST_DEFINE(inst, versal_sysmon_init, NULL,                  \
                                     &sysmon_data_##inst, &sysmon_config_##inst,      \
                                     POST_KERNEL, CONFIG_SENSOR_INIT_PRIORITY,        \
                                     &versal_sysmon_api);

DT_INST_FOREACH_STATUS_OKAY(VERSAL_SYSMON_INIT)

DT_DRV_COMPAT

  • This macro holds the compatible string of the driver.

DT_INST_FOREACH_STATUS_OKAY

  • This macro calls VERSAL_SYSMON_INIT(inst) on all nodes with compatible DT_DRV_COMPAT and status okay.

DT_INST_FOREACH_CHILD

  • This macro calls SUPPLY_CHAN_DATA_INIT on every child node of the instance. Each child node describes one supply channel with its xlnx,name and xlnx,register properties.

  • BUILD_ASSERT checks at build time that xlnx,numchannels equals the number of child nodes.

SENSOR_DEVICE_DT_INST_DEFINE

  • This macro defines a device structure that is automatically configured by the kernel during system initialization.

  • versal_sysmon_init is run by the kernel during system initialization.

  • device→data is set with the sysmon_data_##inst variable address.

  • device→config is set with the sysmon_config_##inst variable address.

  • POST_KERNEL defines the device initialization level.

  • CONFIG_SENSOR_INIT_PRIORITY defines the device priority within the device initialization level.

  • versal_sysmon_api is a structure where all the APIs that need to be registered to the sensor framework are added.

DT_INST_PROP(inst, property)

  • This macro returns the node property value.

Init

versal_sysmon_init does the following:

  • Maps the register space with DEVICE_MMIO_MAP.

  • Unlocks the NPI register space, disables and clears all interrupts.

  • Initializes the work items used to handle events and to unmask interrupts again after an alarm.

  • Connects the interrupt through the instance specific irq_config_func.

  • Matches each channel name in the device tree to the driver channel table and stores the index. The init fails with -EINVAL for an unknown name.

Sensor Framework

Sensor framework has a structure where drivers need to register their APIs by following the same protocol used in the structure that follows,

Framework Structure

__subsystem struct sensor_driver_api {
    sensor_attr_set_t attr_set;
    sensor_attr_get_t attr_get;
    sensor_trigger_set_t trigger_set;
    sensor_sample_fetch_t sample_fetch;
    sensor_channel_get_t channel_get;
    sensor_get_decoder_t get_decoder;
    sensor_submit_t submit;
};

Functional Implementation

sensor_attr_set_t

Args: const struct device *dev, enum sensor_channel chan, enum sensor_attribute attr, const struct sensor_value *val

  • Set lower/upper thresholds.

  • Enable/disable interrupt and configure interrupt mode.

  • Enable/disable averaging.

sensor_attr_get_t

Args: const struct device *dev, enum sensor_channel chan, enum sensor_attribute attr, const struct sensor_value *val

  • Get lower/upper thresholds, averaging count, Interrupt mode, and interrupt configuration.

sensor_trigger_set_t

Args: const struct device *dev, const struct sensor_trigger *trig, sensor_trigger_handler_t handler

  • Register interrupt handler callback based on trigger types.

    • Trigger types:

      • SENSOR_TRIG_DATA_READY

      • SENSOR_TRIG_THRESHOLD

sensor_sample_fetch_t

Args: const struct device *dev, enum sensor_channel chan

  • Read the raw voltage/temperature values and convert them into actual values.

  • store the data in driver data structure.

    • chan types

      • SENSOR_CHAN_VOLTAGE

      • SENSOR_CHAN_DIE_TEMP

      • SENSOR_CHAN_ALL

sensor_channel_get_t

Args: const struct device *dev, enum sensor_channel chan, struct sensor_value *val

  • Return a useful value for a particular channel, from the driver’s internal data

Testing Using Testsuite

Testing of the driver can be done using the Testsuite subsystem. Test cases are written using the ZTEST macro and are registered with a test suite using the ZTEST_SUITE macro. The test is located in tests/drivers/sensor/versal_sysmon.

ZTEST Example

static const struct device *sysmon_dev = DEVICE_DT_GET(DT_NODELABEL(sysmon0));

static void before(void *fixture)
{
        ARG_UNUSED(fixture);
        zassert_true(device_is_ready(sysmon_dev), "Device %s is not ready.",
                     sysmon_dev->name);
        chan_to_use = (enum sensor_channel)VERSAL_SYSMON_VCCINT;
        k_sem_init(&irq_sem, 0, 1);
        atomic_clear(&trigger_handler_called);
}

ZTEST(sysmon, test_read_supply_channels)
{
        /* sample_fetch, channel_get and attr_get on a supply channel */
}

ZTEST_SUITE(sysmon, NULL, NULL, before, NULL, NULL);
  • before runs before every test case. It checks the device is ready and clears the interrupt semaphore and the trigger flag.

  • The test cases and the suite are matched by the suite name (sysmon).

Test Cases

  • test_read_supply_channels - sample_fetch, channel_get and threshold attr_get on a supply channel.

  • test_th_temp_interrupt - temperature threshold trigger and interrupt.

  • test_ot_temp_interrupt - over temperature (OT) threshold trigger and interrupt.

  • test_supply_chan_interrupts - supply channel threshold interrupts.

Building and Running the Test

west build -p always -b versal_apu tests/drivers/sensor/versal_sysmon

The test is allowed on the versal_apu platform and is selected when a device tree node with the xlnx,versal-sysmon compatible is enabled.