Network EMAC DSD property documentation
by Timur Tabi
I need help with this.
This is the network DSD description for our on-chip NIC. The DSD
doesn't have any DSDs specific to the EMAC. Most of the complication in
the ACPI node for the EMAC is in the presence of the child node
(QCOM8071) and a other nodes, like INIT, _STA, _CRS, a bunch of _DSMs
(that I'm trying to get rid of).
Shouldn't we be documenting the addresses and interrupts in the _CRS
nodes as well?
property-set: Network Device Properties
set-type: definition
vendor: Qualcomm Technologies, Inc.
bus: acpi
device-id: QCOM8070
revision: 0
derived-from: /Qualcomm/acpi/QCOM8070/0
property: phy-channel
type: integer
description:
If present, defines the PHY channel number
to be used by this device.
values:
integer: 0..31
description: device address
example:
Package (2) {"phy-channel", 4}
property: phy-mode
type: string
description:
Defines the PHY mode to be used for this device.
values:
token: sgmii
description serial gigabit MII
example:
Package (2) {"phy-mode", "sgmii"}
property: mac-address
type: "reference" or "package", I don't know
description:
The 6-byte MAC address to use for this interface
values:
????
example:
Name (MACA, Package (6) {0x10,0xDE,0xAD,0xBE,0xEF,0x10})
...
Package (2) {"mac-address", \_SB.MAC0.MACA},
submitted-by: Timur Tabi <timur(a)codeaurora.org>
--
Qualcomm Datacenter Technologies, Inc. as an affiliate of Qualcomm
Technologies, Inc. Qualcomm Technologies, Inc. is a member of the
Code Aurora Forum, a Linux Foundation Collaborative Project.
5 years, 6 months
Acceptable Use Guidelines
by Al Stone
The first submittal of DSD device properties has been a bit rocky. I really
appreciate Austin and CodeAurora willing to be the first to try. Thank you.
What I see is that there is a difference of opinion on what device properties
are acceptable in _DSD. It seems we have a full spectrum of possibilities: on
one end is allowing almost anything the vendor wants, up to and including just
cloning DT bindings; on the other end is using a _DSD device property as almost
a last resort -- use it if and only if there is no other way to describe
something in ACPI that a device must have to function.
I don't see either extreme as practical. There will always be an exception, by
definition. Neither the kernel nor hardware technology are static.
The problem is, this difference of opinion now presents a stumbling block to
getting _DSD device properties registered.
So, let me suggest the following guidelines -- not rules, but guides -- that I
have been using when thinking about an acceptable use of _DSD device properties;
perhaps we can start from these to reach consensus:
1. If the set of device properties is a cut-and-paste from DT bindings, that's
not acceptable. If you need an ACPI driver, make one. Assuming the DT
driver can be re-used this way may be wrong, and may not be maintainable.
2. If a device property defines something that should have been set by UEFI,
don't take it. Initial frequencies and PHYs are a good example; the SBSA
and SBBR on arm64 defines such things.
3. If a device property duplicates an existing ACPI object or method, it's not
acceptable. Power management is handled quite well by D-states, so use them
instead of providing a table of frequencies for adjusting power usage. The
_CRS defines available registers; use that, not a device property.
4. Under no circumstances should a device property provide information that
can be retrieved from the hardware.
5. There are always exceptions; what is most practical?
This is where I start from. Do you have other guidelines? Are these too
restrictive? Too lax?
Let me know. I'd like to see if we can get to consensus. We've discussed
this briefly at the Linaro Connect firmware mini-conf, and we can of course
discuss it further at Linux Plumbers. But, let's come to some sort of an
agreement so that people can get their work done.
Thanks.
--
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3(a)redhat.com
-----------------------------------
5 years, 10 months