drivers: Move API driver structs to an iterable section

[pdgendt]

Introduction

This PR demonstrates how iterable sections can be used to validate type safety of device API calls.

Problem description

Type safety using void * typically requires us to either perform additional build steps, or add overhead data.

Proposed change

Putting each device API in their dedicated linker section allows us to check if calling an API using a void * is located within that section.
Calling invalid device API functions with CONFIG_ASSERT enabled would cause an assertion panic, helping users during development to track issues with devices.

/* A function that is called from network/shell/... */
static int some_function(const char *dev_name)
{
	const struct device *dev = device_get_binding(dev_name);

	if (dev == NULL) {
		return -ENODEV;
	}

	if (!DEVICE_API_IS(adc, dev)) {
		return -EINVAL;
	}

	/* do something with ADC device */
	return 0;
}

Detailed RFC

The following macro definitions are added:

/** @brief Expands to the full type. */
#define Z_DEVICE_API_TYPE(_class) _CONCAT(_class, _driver_api)

/** @endcond */

/**
 * @brief Wrapper macro for declaring device API structs inside iterable sections.
 *
 * @param _class The device API class.
 * @param _name The API instance name.
 */
#define DEVICE_API(_class, _name) const STRUCT_SECTION_ITERABLE(Z_DEVICE_API_TYPE(_class), _name)

/**
 * @brief Expands to the pointer of a device's API for a given class.
 *
 * @param _class The device API class.
 * @param _dev The device instance pointer.
 *
 * @return the pointer to the device API.
 */
#define DEVICE_API_GET(_class, _dev) ((const struct Z_DEVICE_API_TYPE(_class) *)_dev->api)

/**
 * @brief Macro that evaluates to a boolean that can be used to check if an
 *        API pointer is located in the iterable section.
 *
 * @param _class The device API class.
 * @param _dev The device instance pointer.
 *
 * @return true if the API pointer is located in the type's iterable section.
 */
#define DEVICE_API_IS(_class, _dev)                                                                \
	({                                                                                         \
		STRUCT_SECTION_START_EXTERN(Z_DEVICE_API_TYPE(_class));                            \
		STRUCT_SECTION_END_EXTERN(Z_DEVICE_API_TYPE(_class));                              \
		(DEVICE_API_GET(_class, _dev) < STRUCT_SECTION_END(Z_DEVICE_API_TYPE(_class)) &&   \
		 DEVICE_API_GET(_class, _dev) >= STRUCT_SECTION_START(Z_DEVICE_API_TYPE(_class))); \
	})

A python script scripts/build/gen_iter_sections.py is added (written by @bjarki-trackunit) to translate all __subsystem struct definitions to linker sections.

Requirements (for each API type)

Instances create the API struct using DEVICE_API (which forces const), for example:

static DEVICE_API(adc, api) = {
	.channel_setup = ads1112_channel_setup,
	.read = ads1112_read,
	.ref_internal = ADS1112_REF_INTERNAL,
};

The API calls evaluate the void *, for example:

static inline int z_impl_adc_read(const struct device *dev,
				  const struct adc_sequence *sequence)
{
	__ASSERT_NO_MSG(DEVICE_API_IS(adc, dev));

	return DEVICE_API_GET(adc, dev)->read(dev, sequence);
}

Dependencies

None that I can think of.

Concerns and Unresolved Questions

• __ASSERT vs CHECKIF
• CONFIG_CMAKE_LINKER_GENERATOR can't rely on the gen_iter_sections.py script to generate sections for iterable structs
• All out-of-tree drivers need to migrate to use driver API macros
• Should we create a post-linker script that validates if all device's api pointers are located in the correct section?
• Naming; type vs class
• Is the _driver_api a required suffix? And should we shorten/hide this part using the macros?

Tasks

After approval to go forward, we can start moving other drivers too.

[bjarki-andreasen]

The other half of the issue is that we also need the actual device, the API on its own is not of much use :) The proposal I made here #58112 uses elf parsing to tie the API to a device, and generates header files from it. It's a bit complex, requiring multi stage building to work, building drivers before subsystem/app.

I still prefer the simplest (but a bit costly) generating additional arrays of dev + api in ROM like SENSOR_DEVICE_DT_DEFINE_...

[fabiobaltieri]

The other half of the issue is that we also need the actual device

You could scan through the (existing) device iterable section and match all devices who's api pointer is within the boundaries of the API category you care about.

[bjarki-andreasen]

The other half of the issue is that we also need the actual device

You could scan through the (existing) device iterable section and match all devices who's api pointer is within the boundaries of the API category you care about.

Yes, but that's a runtime scan, ew :D

[fabiobaltieri]

Yes, but that's a runtime scan, ew :D

Should be quick though.

[pdgendt]

Yes, but that's a runtime scan, ew :D

Should be quick though.

That's why I think #67698 and this PR can solve different issues, and both can coexist.

[Laczen]

Wouldn't this method force the api to be included in ROM even if the device is not used?

[bjarki-andreasen]

Wouldn't this method force the api to be included in ROM even if the device is not used?

The APIs are only included if the drivers are included, so there should be no difference in ROM usage, only where in ROM the API structs are placed :)

[pdgendt]

Update:

• Change CHECKIF to __ASSERT_NO_MSG

[fabiobaltieri]

Dropping the RFC and DNM tags since this has been commented and it appears like there's consensus that it can go in.

[pdgendt]

Dropping the RFC and DNM tags since this has been commented and it appears like there's consensus that it can go in.

Also removed the arch meeting label as this prevents merging, and unassigned @gmarull