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 compatibleDT_DRV_COMPATand statusokay.
DT_INST_FOREACH_CHILD
This macro calls
SUPPLY_CHAN_DATA_INITon every child node of the instance. Each child node describes one supply channel with itsxlnx,nameandxlnx,registerproperties.BUILD_ASSERTchecks at build time thatxlnx,numchannelsequals 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_initis run by the kernel during system initialization.device→data is set with the
sysmon_data_##instvariable address.device→config is set with the
sysmon_config_##instvariable address.POST_KERNELdefines the device initialization level.CONFIG_SENSOR_INIT_PRIORITYdefines the device priority within the device initialization level.versal_sysmon_apiis 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
-EINVALfor 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);
beforeruns 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_getand thresholdattr_geton 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.