Re: Syntax of files.* configuration

[Mouse <mouse%Rodents-Montreal.ORG@localhost>]

> I want to write an I2C driver [...]

> - In arch/evbarm/conf/GENERIC64, the following line:

> mesonuart*Â Â Â  at fdt? pass 4Â Â Â Â Â Â Â Â Â Â Â  # Amlogic Meson UART

(I feel reasonably sure the line contains spaces, not non-break spaces,
here represented as if the octets were 8859-1, because that's what I
see.  This is probably your MUA "helpfully" ocrrupting your text.  I'll
fix this up manually in further quotes.)

> - In arch/arm/amlogic/files.meson, the following snippet:

> device    mesonuart
> attach    mesonuart at fdt with meson_uart
> file    arch/arm/amlogic/meson_uart.c        meson_uart

> I understand that: [...]

Yes, I too think all of those are correct.

> I don't understand:

Well, here is my understanding.

> - what the ? after 'fdt' and 'pass 4' mean

The ? after fdt means that mesonuart can attach at _any_ fdt.  You
could write a config file that declares, say,

mesonuart* at fdt2 pass 4

which would be the same except it would attach at fdt2 only, not any
other fdt instances.  (This is occasionally useful; for example, it's
used by SPARC configs to get the serial lines and the keyboard/mouse
attached to the UARTs which are connected to the corresponding
back-panel connectors.)

The "pass 4" is what's called a locator.  It is used by attachment
devices that have things which can be considered addresses, to specify
what address the thing is at.  To pick a real example, in files.isa, I
find

device	isa {[port = -1], [size = 0],
	     [iomem = -1], [iosiz = 0],
	     [irq = -1], [drq = -1], [drq2 = -1]}

which says that "at isa" attachments can have port, size, iomem, iosiz,
irq, drq, and drq2 locators.  A config file line

lpt0	at isa? port 0x378 irq 7

then generates data structures so that the lpt device trise to use
those values of port and irq when attaching lpt0 at isa.  (The other
values all default; presumably they aren't relevant to lpt.)

Similarly, pci has locators "dev" and "function", so you'll see things
such as "ex* at pci? dev ? function ?", meaning that the an ex can
attach with any dev and function values.  (What these locators actually
_mean_ depends on the attached-to device.  If you are familiar with ISA
and PCI, you will presumably recognize most or all of those names as
providing things relevant to those buses.)

In this case, well, I don't know fdt, but presumably it has a numeric
value which can reasonably be called "pass", and for which the value 4
is to be used when looking for mesonuart.

> - what the optional 'with meson_uart' means

It means that, conceptually, mesonuart may attach to things other than
fdt, and that there is some fdt-specific glue code used when attaching
it to fdt.  (Whether there actually are any other attachments for it in
any particular case is irrelevant.  Even if no other attachment is
defined anywhere, this may be done to keep the code structure clean,
separating the attachment glue from the "real" driver.)

For example, if a serial-line chip can attach at a PCI device or an ISA
device (to use an example from the i386/amd64 world), you might see
(fictitious names, because I haven't investigated how i386/amd64 serial
ports actually attach)

config file:
	pciserial*	at pci* dev ? function ?
	serial*		at pciserial? unit ?
	isaserial*	at isa*
	serial*		at isaserial? unit ?
files.*:
	attach pciserial at pci
	attach serial at pciserial with com_pci
	attach isaserial at isa
	attach serial at isaserial with com_isa

> - where and how the 'meson_uart' boolean is set

It is set if something which attaches "with meson_uart" is configured.
(This is a config-time thing, not something you'll see in the generated
kernel.)

> - whether there is a relationship between the names in those 
> configuration files and the first argument of the CFATTACH_DECL_NEW
> macro

I'm less sure here, but I _think_ the first arg to CFATTACH_DECL_NEW
needs to match the device name, the name that occurs after "attach" in
files.* or at the beginning of "at" line in the kernel config.

> Is there any documentation explaining this syntax?

There should be.  I don't know whether there is; I've never really gone
looking for any.

/~\ The ASCII				  Mouse
\ / Ribbon Campaign
 X  Against HTML		mouse%rodents-montreal.org@localhost
/ \ Email!	     7D C8 61 52 5D E7 2D 39  4E F1 31 3E E8 B3 27 4B