Re: General device properties API

[Taylor R Campbell <campbell+netbsd-tech-kern%mumble.net@localhost>]

> Date: Sun, 15 Aug 2021 09:10:48 -0700
> From: Jason Thorpe <thorpej%me.com@localhost>
> 
> > On Aug 15, 2021, at 2:08 AM, Taylor R Campbell <campbell+netbsd-tech-kern%mumble.net@localhost> wrote:
> > 
> > This is a little abstract to follow just from the types.  Can you show
> > examples of:
> > 
> > - code scattered around to reflect device tree properties?
> 
> Great example starts at: sys/arch/sparc64/sparc64/autoconf.c:1248
> and continues to line 1319.

Cool, thanks!  Can you expand on what it would look like instead with
the new API?  Do you have any diffs to particulary compelling messy
drivers or buses to show off how this makes things better?

How do I know what properties are going to be available in a driver?
Is it part of an internal kernel<->kernel interface like device
properties, or just whatever is passed through the OF/FDT or ACPI
firmware?

If the latter, what happens if I want to use the same driver on a
system that might use OF/FDT or ACPI, where OF/FDT or ACPI provide the
same information by different spellings like `mac-address' vs
`ethernet-address' (hypothetical)?  Or is this intended only for
drivers where the binding to a particular type of firmware device tree
is baked into the driver, so this kind of thing won't ever come up?

> > How do clients know they are following the typing rules?  Does the
> > compiler provide any way to detect errors, or can that be detected
> > only at run-time depending on what OF/FDT/ACPI data the firmware
> > provides?
> 
> Code needs to check at run-time, which has been the case for a long
> time already, and honestly I don't see any problem with that at all.

Well, there's two possibilities and I wasn't sure which one was
intended in your proposal:

1. This is an internal kernel<->kernel interface, where one part of
   the kernel (like sparc64/autoconf.c) provides properties and
   another part of the kernel consumes them.

   => In this case, it would be reasonable to expect a typed
      definition in a .h file that the provider.c and consumer.c files
      use so the compiler can detect typos and verify the types match
      at compile-time.

2. This is a driver<->firmware interface, where we have compile-time
   type-checking only on the driver side and there's nothing the
   compiler can do to detect typos or prevent disagreement with
   firmware that the driver might encounter.

   => In this case, the best we can hope for is that the firmware
      provides tagged data so that, say, device_getprop_uint64 can
      return failure if the firmware actually has a string and not a
      uint64.

It sounds like the answer is (2) but I wanted to make sure I
understood correctly.

For device_properties, in contrast, the answer is (1), and by removing
a non-type-checkable intermediary (the device_properties dictionary)
we might improve the situation by reducing the number of places for
undetectable errors to creep in.

> > What's the advantage of creating a new API with many of essentially
> > the same functions prop_* (prop_dictionary_get_string, &c.), vs just
> > mapping the entire tree recursively into a proplib dictionary and
> > having drivers use the existing prop_* API to query it?
> 
> Mainly because recursively mapping the entire device tree into a
> dictionary would be wasteful (there are plenty of properties nobody
> cares about, so why allocate objects for them?).  Also, the
> structure of the underlying device tree does not necessarily map
> directly to how we structure our representation of it with
> device_t's.  My approach coerces it into our logical format by
> virtue of assigning the correct dev handles to the device_t's when
> things are enumerated (we do a good chunk of this in the tree now
> using CFARGS() and there is more of this in the pipeline in the
> thorpej-i2c-spi-conf2 branch).

Thanks, that sounds reasonable.  Can you expand on what device handles
are and how they are assigned, maybe with a couple of examples of
machines that use some combination of PCI, OF/FDT, and ACPI?  Might be
nice to have for a man page EXAMPLES section later on!