libmetal: lib: linux: improve Linux UIO-backed device open and test coverage by bentheredonethat · Pull Request #365 · OpenAMP/libmetal

bentheredonethat · 2026-05-06T16:30:59Z

This series improves the Linux UIO-backed device-open flow in libmetal and
adds test coverage for the new API and Linux-specific helper paths.

The immediate motivation is to support Linux userspace applications that open
UIO-exposed devices through libmetal while keeping the existing bus/device
contract intact. In the current Linux implementation, the basic UIO path is
already present, but the backend is tightly coupled to bus probing, does not
cleanly separate resolved Linux device identities, does not unregister Linux
IRQ device state on close, and does not correctly retain the raw mapping
needed when a UIO map uses a non-zero offset.

This series addresses those gaps in three steps:

1. Add an explicit public helper,                                              
   metal_device_open_from_bus(), for bus/device based open while keeping       
   metal_device_open() as a compatibility wrapper.                             
                                                                               
2. Refactor the Linux UIO backend so it can populate a libmetal device         
   after resolving either a bus device name or a UIO class name, track the  
   resolved Linux identities more clearly, validate UIO map offsets, retain 
   raw mmap pointers for correct unmap, unregister Linux IRQ device state   
   on close, and tolerate Linux bus probe failure during metal_sys_init().  
                                                                               
3. Add cross-platform and Linux-specific tests for the new device-open         
   helper and the Linux UIO/IRQ bookkeeping helpers.

With these changes, downstream Linux host applications can continue to use
libmetal's device-open and IRQ registration model while relying on the
improved Linux UIO device handling in the library.

The public device-open API already takes bus and device names, but the current interface does not make that contract explicit. Add metal_device_open_from_bus() as a named helper for bus/device based open and keep metal_device_open() as a compatibility wrapper. This makes the Linux bus-based device flow easier to reference from downstream code without changing existing callers. Signed-off-by: Ben Levinsky <ben.levinsky@amd.com>

Refactor the Linux UIO device path so the backend can reuse the same population flow after resolving a device from either a platform bus name or a UIO class name. Track the resolved Linux identities separately, validate UIO map offsets, retain the raw mmap pointers for correct unmap, and clear Linux IRQ registration state when a device is closed. Also make metal_sys_init() tolerate Linux bus probe failure so Linux initialization can still complete even when bus-based open is unavailable. This keeps the existing Linux UIO path working while making it easier for downstream host applications to use UIO-exposed devices. Signed-off-by: Ben Levinsky <ben.levinsky@amd.com>

Add a standalone Linux system test for the device-open and Linux helper paths added by the UIO-backed device open work. The new test registers a temporary in-process bus and device to verify metal_device_open_from_bus(), the existing metal_device_open() compatibility wrapper, and expected error handling for invalid arguments, missing buses, missing devices, and buses without dev_open callbacks. It also covers the Linux-specific helper behavior without requiring real UIO hardware by validating UIO map offset checks and exercising IRQ device bookkeeping with an eventfd-backed IRQ. The IRQ coverage verifies that a registered device is visible, enable state is tracked, and unregistering the device clears both the device pointer and enabled state. Only the Linux system test collection is updated so the coverage remains isolated from the existing cross-platform tests. Signed-off-by: Ben Levinsky <ben.levinsky@amd.com>

arnopo · 2026-05-11T13:47:35Z

 #include <metal/utilities.h>
 #include <metal/irq.h>

+#include <stdbool.h>


This commit is quite large and difficult to understand if you are not familiar with the AMD implementation based on UIO, which is my case.

Could you split it into smaller, more readable commits?

Does it make sense to keep UIO support in the Linux subsystem, or is it specific to AMD?

arnopo · 2026-05-11T13:51:07Z

 #include "irq.h"

 #define MAX_DRIVERS	64
+#define METAL_UIO_CLASS_PATH "/sys/class/uio"


Does UIO support is required on the target in order to use OpenAMP in Linux user space?

arnopo · 2026-05-11T13:56:07Z

 void metal_linux_irq_register_dev(struct metal_device *dev, int irq);
+void metal_linux_irq_unregister_dev(int irq);
+struct metal_device *metal_linux_irq_get_dev(int irq);
+int metal_linux_irq_is_enabled(int irq);


APIs should have a doxygen documentation header

arnopo · 2026-05-11T13:56:39Z

-				    void *output, int len);
+int metal_linux_uio_validate_offset(const char *dev_name,
+				    unsigned int index,
+				    unsigned long offset);


doxygen documentation header

arnopo · 2026-05-11T14:53:07Z


-int metal_device_open(const char *bus_name, const char *dev_name,
-		      struct metal_device **device)
+int metal_device_open_from_bus(const char *bus_name, const char *dev_name,


I do not understand the need to create a new API. It looks to me like this introduces confusion by duplicating APIs instead of making things more obvious.

Having a single system-agnostic API makes more sense to me.

bentheredonethat · 2026-05-11T16:03:43Z

Hi @arnopo

Thanks for the review. I agree the Linux change is too large as posted, and I can split it into smaller commits before respinning.

The main problem I am trying to solve is narrower than the current series makes it look. Linux userspace libmetal already opens platform/PCI devices through the existing Linux UIO-backed path.
Today applications have to pass the Linux bus device name, for example "ff360000.ipi". That name comes from the platform device/unit-address naming and is not a stable logical name across SoCs or
even across different instances.

For demos and portable userspace applications, we would like to use a logical name such as "demo-ipi". On systems using UIO, that logical name can be exposed by the kernel as the UIO class name,
for example:

  /sys/class/uio/uioX/name = demo-ipi

The Linux libmetal backend can then resolve that UIO class name back to the real bus device:

  demo-ipi
    -> /sys/class/uio/uioX/name
    -> /sys/class/uio/uioX/device
    -> /sys/bus/platform/devices/ff360000.ipi

and continue through the existing Linux bus open/bind/map/IRQ/close flow.

So the intended direction is not to make UIO mandatory for OpenAMP generally, and not to introduce a new Linux device model. It is only to let the existing Linux UIO backend accept the UIO class
name as an alias for the native bus device name.

I also agree with your comment about the new public API. The UIO-name use case does not require adding metal_device_open_from_bus(). I can drop that patch and keep the existing system-agnostic
API:

  metal_device_open("platform", "demo-ipi", &dev);

The Linux backend would interpret the device argument as either:

the native bus device name, preserving existing behavior, or
a UIO class-name alias, resolved internally to the native platform/PCI device.

Internally I plan to keep both identities clear, e.g. requested name / resolved bus device name / UIO name. For minimum behavior change, the returned device->name can remain the resolved native
bus device name; the UIO name is just an open-time alias.

For the respin, does the following direction sound acceptable?

Drop the new metal_device_open_from_bus() public API.
Split the Linux changes into smaller commits, likely:
- UIO mmap offset validation and correct raw-pointer unmap tracking.
- IRQ bookkeeping cleanup on device close.
- UIO class-name alias resolution for the existing Linux UIO backend.
- Tests and documentation updates.
Include Doxygen comments in the same commits that introduce new internal Linux helpers.
Clarify in the commit messages that UIO-name lookup is optional alias resolution for the existing Linux backend, not a requirement for OpenAMP Linux userspace in general.

If this direction makes sense, I will rework the series around that.

arnopo · 2026-05-12T08:15:11Z

Hi @arnopo

Thanks for the review. I agree the Linux change is too large as posted, and I can split it into smaller commits before respinning.

The main problem I am trying to solve is narrower than the current series makes it look. Linux userspace libmetal already opens platform/PCI devices through the existing Linux UIO-backed path. Today applications have to pass the Linux bus device name, for example "ff360000.ipi". That name comes from the platform device/unit-address naming and is not a stable logical name across SoCs or even across different instances.

For demos and portable userspace applications, we would like to use a logical name such as "demo-ipi". On systems using UIO, that logical name can be exposed by the kernel as the UIO class name, for example:
  /sys/class/uio/uioX/name = demo-ipi
The Linux libmetal backend can then resolve that UIO class name back to the real bus device:
  demo-ipi
    -> /sys/class/uio/uioX/name
    -> /sys/class/uio/uioX/device
    -> /sys/bus/platform/devices/ff360000.ipi
and continue through the existing Linux bus open/bind/map/IRQ/close flow.

What about using symbolic link for that, as proposed by @tnmysh in OpenAMP/openamp-system-reference#101.
That would avoid resolution by /sys/class/uio/uioX/name if a /sys/class/uio/<name>/device symbolic is created with a udev rule.
Would it work in your case?

So the intended direction is not to make UIO mandatory for OpenAMP generally, and not to introduce a new Linux device model. It is only to let the existing Linux UIO backend accept the UIO class name as an alias for the native bus device name.

I also agree with your comment about the new public API. The UIO-name use case does not require adding metal_device_open_from_bus(). I can drop that patch and keep the existing system-agnostic API:
  metal_device_open("platform", "demo-ipi", &dev);
The Linux backend would interpret the device argument as either:

the native bus device name, preserving existing behavior, or

a UIO class-name alias, resolved internally to the native platform/PCI device.

Internally I plan to keep both identities clear, e.g. requested name / resolved bus device name / UIO name. For minimum behavior change, the returned device->name can remain the resolved native bus device name; the UIO name is just an open-time alias.

For the respin, does the following direction sound acceptable?

Drop the new metal_device_open_from_bus() public API.

Split the Linux changes into smaller commits, likely:

UIO mmap offset validation and correct raw-pointer unmap tracking.

IRQ bookkeeping cleanup on device close.

UIO class-name alias resolution for the existing Linux UIO backend.

Tests and documentation updates.

Include Doxygen comments in the same commits that introduce new internal Linux helpers.

Clarify in the commit messages that UIO-name lookup is optional alias resolution for the existing Linux backend, not a requirement for OpenAMP Linux userspace in general.

Sound good.

Thanks
arnaud

If this direction makes sense, I will rework the series around that.

bentheredonethat · 2026-05-12T14:03:20Z

Thanks @arnopo, this is a good point.

Using a udev-created symlink such as:

/sys/class/uio/<logical-name>/device
would work in our use case and is a nice optimization when present, since it avoids scanning uioX/name.

For upstream libmetal, I would prefer to treat this as optional platform integration rather than a hard dependency, because not all deployments guarantee custom udev rules. So my plan is:

keep the generic fallback that resolves via /sys/class/uio/uioX/name,
optionally try the symlink path first when it exists.

That keeps behavior portable out of the box while allowing integrators to use the symlink approach for faster/cleaner lookup.

If you agree, I will document this in the commit message as “optional udev optimization, generic fallback preserved”.

arnopo · 2026-05-12T17:00:08Z

Thanks @arnopo, this is a good point.

Using a udev-created symlink such as:

/sys/class/uio/<logical-name>/device would work in our use case and is a nice optimization when present, since it avoids scanning uioX/name.

For upstream libmetal, I would prefer to treat this as optional platform integration rather than a hard dependency, because not all deployments guarantee custom udev rules. So my plan is:

keep the generic fallback that resolves via /sys/class/uio/uioX/name,

optionally try the symlink path first when it exists.

That keeps behavior portable out of the box while allowing integrators to use the symlink approach for faster/cleaner lookup.

If you agree, I will document this in the commit message as “optional udev optimization, generic fallback preserved”.

I would prefer that we handle this in the same way we manage /dev/rpmsgX or /sys/class/remoteproc/remoteprocX devices, rather than adding it to libmetal.

I propose adding this PR to the agenda for the next OpenAMP meeting so we can discuss it further.

bentheredonethat mentioned this pull request May 6, 2026

examples: libmetal: amd_rpu: Fix dynamic config setup OpenAMP/openamp-system-reference#102

Open

bentheredonethat added 3 commits May 6, 2026 09:36

bentheredonethat force-pushed the uio-update branch from 6dbafca to 758f084 Compare May 6, 2026 16:40

arnopo requested review from arnopo, edmooring and tnmysh May 11, 2026 12:59

arnopo requested changes May 11, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

libmetal: lib: linux: improve Linux UIO-backed device open and test coverage#365

libmetal: lib: linux: improve Linux UIO-backed device open and test coverage#365
bentheredonethat wants to merge 3 commits into
OpenAMP:mainfrom
bentheredonethat:uio-update

bentheredonethat commented May 6, 2026

Uh oh!

arnopo May 11, 2026

Uh oh!

arnopo May 11, 2026

Uh oh!

arnopo May 11, 2026

Uh oh!

arnopo May 11, 2026

Uh oh!

arnopo May 11, 2026

Uh oh!

bentheredonethat commented May 11, 2026

Uh oh!

arnopo commented May 12, 2026

Uh oh!

bentheredonethat commented May 12, 2026

Uh oh!

arnopo commented May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

bentheredonethat commented May 6, 2026

Uh oh!

arnopo May 11, 2026

Choose a reason for hiding this comment

Uh oh!

arnopo May 11, 2026

Choose a reason for hiding this comment

Uh oh!

arnopo May 11, 2026

Choose a reason for hiding this comment

Uh oh!

arnopo May 11, 2026

Choose a reason for hiding this comment

Uh oh!

arnopo May 11, 2026

Choose a reason for hiding this comment

Uh oh!

bentheredonethat commented May 11, 2026

Uh oh!

arnopo commented May 12, 2026

Uh oh!

bentheredonethat commented May 12, 2026

Uh oh!

arnopo commented May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants