8:05 a.m.
I thought I would pass on some of the discussion that's going on around
the use and definition of _DSD device properties. There seems to be some
basic agreement that (a) we should send things to a common forum for
review and documentation, and that (b) the forum needs to be easily visible
and usable by Linux folks, MS people, and firmware developers, and that
(c) there is a dsd(a)acpica.org mailing list set up for that, but has not
been used at all (nor has the ASWG process, for that matter).
Darren Hart of Intel has proposed some of these, and has volunteered to
try to get this going. And, I agree with him on where we need to go with
all of this. So, I would encourage people to start submitting things to
the dsd(a)acpica.org mailing list -- like this RFC, for example.
But, that begs the question of *what* to submit. I haven't been very vocal
about this just because I was fiddling around with the ideas but I think
they're solid enough to get moving.
I thought I would pass on some of the discussion that's going on around
the use and definition of _DSD device properties. There seems to be some
basic agreement that (a) we should send things to a common forum for
review and documentation, and that (b) the forum needs to be easily visible
and usable by Linux folks, MS people, and firmware developers, and that
(c) there is a dsd(a)acpica.org mailing list set up for that, but has not
been used at all (nor has the ASWG process, for that matter).
Darren Hart of Intel has proposed some of these, and has volunteered to
try to get this going. And, I agree with him on where we need to go with
all of this. So, I would encourage people to start submitting things to
the dsd(a)acpica.org mailing list.
But, that begs the question of *what* to submit. I haven't been very vocal
about this just because I was fiddling around with the ideas but I think
they're solid enough to get moving.
Please see the git tree at https://github.com/ahs3/dsd. This may or may not
be the right long term place to host it, but the README describes the idea --
I've written a tool that uses simple YAML to describe device properties. The
tool can verify that all the right things are documented, and allows one to
build a data base -- of plain human-readable ASCII YAML -- that anyone can
visit, peruse, or offer updates to.
The YAML is probably not complete; however, the key thing is that this is
completely open source, under a very permissive license, and easily seen or
used by developers of any OS or any bit of firmware -- the neutral location
and open license means equal use and access for Microsoft, Linux, and the
firmware writers. Patches are of course welcome -- to the tool, or even the
data base of device property descriptions.
So, if one sends the type of YAML expected to dsd(a)acpica.org, I can easily
pull it in, verify it, and push it back out to github, assuming it's reasonably
correct and usable. If we can agree that all discussions about the
acceptability of any particular device property occurs on dsd(a)acpica.org, we
can get this process moving and documented, and change the discussion to
be about specific device properties instead.
I'm attaching the README from https://github.com/ahs3/dsd for those that are
as lazy as I am about following links :).....
README
------
dsd -- a command line tool for _DSD device property registrations
-----------------------------------------------------------------
A simple 'make' will produce a command line tool to help in the collection,
registration and maintenance of entries describing the device properties
allowed via the _DSD method in ACPI [0] -- and in Device Tree (DT).
The issue is that there is a desire to share device properties not only
across devices (e.g., is more than one "mac-address" really needed?), but
between the users of ACPI via _DSD, and possibly the users of Device Tree
(DT), where the key-value model is used extensively.
While DT documentation seems to be reasonably well cared for (at least in
the Linux kernel documentation) and there is a process for maintaining the
device property definitions, the same is not true of ACPI. In fact, device
properties as used by _DSD are maintained completely outside of the
specification, and there is no history of maintaining -- or registering --
them as there is for DT, since this is all relatively new to ACPI.
However, regardless of its quality, keeping documentatation in the Linux
kernel does present some problems. For one, firmware developers are not
likely to look at the Linux source for information on the device properties
they might want to use or need to define. The OS is not really where their
focus lies. For two, sharing device properties with the Windows OS becomes
very difficult; asking Microsoft engineers to go use the Linux source code
as reference material puts them in an untenable position.
What this tool -- dsd -- is attempting to do is provide a standard, neutral
location and format for the definition of these properties, so that anyone
that needs to can easily get to them, register new ones, or share existing
properties.
Each device property is described in YAML (examples below, with details in
the file called YAML). At present, a directory contains the YAML, with one
file per device property, one file per device using those properties, and
acts as a very crude "data base" for all of the entries. The dsd command
provides several functions for dealing with this "data base" of device
properties:
-- initialize the data base
-- verify the YAML is correct
-- add the device property to the data base in a consistent format
-- remove a device property from the data base
-- list all known device property names
-- output the info from a given device property
-- output a basic text description of the property for use in Linux
documentation (or elsewhere)
Additional functions can be added (all the source is provided), and should
this project work out, more will be -- for example, summaries of all of
the properties for a given device, or analysis indicating whether or not
a property is needed and by what devices, or perhaps even more clever things.
Building the tool
-----------------
The dsd command requires that libyaml for C be installed [1]. Then, just
do:
% make
There is no install target at present. Run the command:
% ./dsd help
to show what options are available.
YAML
----
The dsd command uses basic YAML formatting (so, spaces for indentation, then
indentation for indicating structure) and currently recognizes the following
keywords:
property: <name>
owner: <string>
type: integer |
hexadecimal-integer |
hexadecimal-address-package |
string |
<type> <value-list>
description: <free text>
example: <free text>
For example:
property: phy-mode
owner: Al Stone <ahs3(a)redhat.com>
type: string
values:
- token: na
description: none available
- token: mii
description: media independent interface (MII)
- token: gmii
description: gigabit MII
- token: sgmii
description: serial gigabit MII
- token: tbi
description: ten bit interface
- token: revmii
description: reverse MII
- token: rmii
description: reduced MII
- token: rgmii
description: reduced gigabit MII (RGMII)
- token: rgmii-id
description: RGMII with internal delay
- token: rgmii-rxid
description: RGMII with receive delay only
- token: rgmii-txid
description: RGMII with transmit delay only
- token: rtbi
description: reduced ten bit interface
- token: smii
description: serial MII
- token: xgmii
description: 10 gigabit MII
- token: moca
description: multimedia over coax
- token: qsgmii
description: quad serial gigabit MII
description: |
Defines the PHY mode to be used for this device.
example: |
Package (2) { "phy-mode", "xgmii" }
Please use '---' to separate device property definitions if several are
included in a single file of text (dsd will separate them into unique
entries in the "data base").
References
----------
[0] For a description of _DSD, see:
http://www.uefi.org/sites/default/files/resources/_DSD-implementation-gui...
For the device properties UUID of _DSD, see:
http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-...
[1] On Debian: apt-get install libyaml-dev
On Fedora: dnf install libyaml-devel
Please see the git tree at https://github.com/ahs3/dsd. This may or may not
be the right long term place to host it, but the README describes the idea --
I've written a tool that uses simple YAML to describe device properties. The
tool can verify that all the right things are documented, and allows one to
build a data base -- of plain human-readable ASCII YAML -- that anyone can
visit, peruse, or offer updates to.
The YAML is probably not complete; however, the key thing is that this is
completely open source, under a very permissive license, and easily seen or
used by developers of any OS or any bit of firmware -- the neutral location
and open license means equal use and access for Microsoft, Linux, and the
firmware writers. Patches are of course welcome -- to the tool, or even the
data base of device property descriptions.
So, if one sends the type of YAML expected to dsd(a)acpica.org, I can easily
pull it in, verify it, and push it back out to github, assuming it's reasonably
correct and usable. If we can agree that all discussions about the
acceptability of any particular device property occurs on dsd(a)acpica.org, we
can get this process moving and documented, and change the discussion to
be about specific device properties instead.
I'm attaching the README from https://github.com/ahs3/dsd for those that are
as lazy as I am about following links :).....
README
------
dsd -- a command line tool for _DSD device property registrations
-----------------------------------------------------------------
A simple 'make' will produce a command line tool to help in the collection,
registration and maintenance of entries describing the device properties
allowed via the _DSD method in ACPI [0] -- and in Device Tree (DT).
The issue is that there is a desire to share device properties not only
across devices (e.g., is more than one "mac-address" really needed?), but
between the users of ACPI via _DSD, and possibly the users of Device Tree
(DT), where the key-value model is used extensively.
While DT documentation seems to be reasonably well cared for (at least in
the Linux kernel documentation) and there is a process for maintaining the
device property definitions, the same is not true of ACPI. In fact, device
properties as used by _DSD are maintained completely outside of the
specification, and there is no history of maintaining -- or registering --
them as there is for DT, since this is all relatively new to ACPI.
However, regardless of its quality, keeping documentatation in the Linux
kernel does present some problems. For one, firmware developers are not
likely to look at the Linux source for information on the device properties
they might want to use or need to define. The OS is not really where their
focus lies. For two, sharing device properties with the Windows OS becomes
very difficult; asking Microsoft engineers to go use the Linux source code
as reference material puts them in an untenable position.
What this tool -- dsd -- is attempting to do is provide a standard, neutral
location and format for the definition of these properties, so that anyone
that needs to can easily get to them, register new ones, or share existing
properties.
Each device property is described in YAML (examples below, with details in
the file called YAML). At present, a directory contains the YAML, with one
file per device property, one file per device using those properties, and
acts as a very crude "data base" for all of the entries. The dsd command
provides several functions for dealing with this "data base" of device
properties:
-- initialize the data base
-- verify the YAML is correct
-- add the device property to the data base in a consistent format
-- remove a device property from the data base
-- list all known device property names
-- output the info from a given device property
-- output a basic text description of the property for use in Linux
documentation (or elsewhere)
Additional functions can be added (all the source is provided), and should
this project work out, more will be -- for example, summaries of all of
the properties for a given device, or analysis indicating whether or not
a property is needed and by what devices, or perhaps even more clever things.
Building the tool
-----------------
The dsd command requires that libyaml for C be installed [1]. Then, just
do:
% make
There is no install target at present. Run the command:
% ./dsd help
to show what options are available.
YAML
----
The dsd command uses basic YAML formatting (so, spaces for indentation, then
indentation for indicating structure) and currently recognizes the following
keywords:
property: <name>
owner: <string>
type: integer |
hexadecimal-integer |
hexadecimal-address-package |
string |
<type> <value-list>
description: <free text>
example: <free text>
For example:
property: phy-mode
owner: Al Stone <ahs3(a)redhat.com>
type: string
values:
- token: na
description: none available
- token: mii
description: media independent interface (MII)
- token: gmii
description: gigabit MII
- token: sgmii
description: serial gigabit MII
- token: tbi
description: ten bit interface
- token: revmii
description: reverse MII
- token: rmii
description: reduced MII
- token: rgmii
description: reduced gigabit MII (RGMII)
- token: rgmii-id
description: RGMII with internal delay
- token: rgmii-rxid
description: RGMII with receive delay only
- token: rgmii-txid
description: RGMII with transmit delay only
- token: rtbi
description: reduced ten bit interface
- token: smii
description: serial MII
- token: xgmii
description: 10 gigabit MII
- token: moca
description: multimedia over coax
- token: qsgmii
description: quad serial gigabit MII
description: |
Defines the PHY mode to be used for this device.
example: |
Package (2) { "phy-mode", "xgmii" }
Please use '---' to separate device property definitions if several are
included in a single file of text (dsd will separate them into unique
entries in the "data base").
References
----------
[0] For a description of _DSD, see:
http://www.uefi.org/sites/default/files/resources/_DSD-implementation-gui...
For the device properties UUID of _DSD, see:
http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-...
[1] On Debian: apt-get install libyaml-dev
On Fedora: dnf install libyaml-devel
--
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3(a)redhat.com
-----------------------------------
9:44 a.m.
Hi,
On 8/28/2015 12:05 AM, Al Stone wrote:
[cut]
README
------
dsd -- a command line tool for _DSD device property registrations
-----------------------------------------------------------------
A simple 'make' will produce a command line tool to help in the collection,
registration and maintenance of entries describing the device properties
allowed via the _DSD method in ACPI [0] -- and in Device Tree (DT).
The issue is that there is a desire to share device properties not only
across devices (e.g., is more than one "mac-address" really needed?), but
between the users of ACPI via _DSD, and possibly the users of Device Tree
(DT), where the key-value model is used extensively.
While DT documentation seems to be reasonably well cared for (at least in
the Linux kernel documentation) and there is a process for maintaining the
device property definitions, the same is not true of ACPI. In fact, device
properties as used by _DSD are maintained completely outside of the
specification, and there is no history of maintaining -- or registering --
them as there is for DT, since this is all relatively new to ACPI.
However, regardless of its quality, keeping documentatation in the Linux
kernel does present some problems. For one, firmware developers are not
likely to look at the Linux source for information on the device properties
they might want to use or need to define. The OS is not really where their
focus lies. For two, sharing device properties with the Windows OS becomes
very difficult; asking Microsoft engineers to go use the Linux source code
as reference material puts them in an untenable position.
What this tool -- dsd -- is attempting to do is provide a standard, neutral
location and format for the definition of these properties, so that anyone
that needs to can easily get to them, register new ones, or share existing
properties.
Each device property is described in YAML (examples below, with details in
the file called YAML). At present, a directory contains the YAML, with one
file per device property, one file per device using those properties, and
acts as a very crude "data base" for all of the entries. The dsd command
provides several functions for dealing with this "data base" of device
properties:
-- initialize the data base
-- verify the YAML is correct
-- add the device property to the data base in a consistent format
-- remove a device property from the data base
-- list all known device property names
-- output the info from a given device property
-- output a basic text description of the property for use in Linux
documentation (or elsewhere)
Additional functions can be added (all the source is provided), and should
this project work out, more will be -- for example, summaries of all of
the properties for a given device, or analysis indicating whether or not
a property is needed and by what devices, or perhaps even more clever things.
Building the tool
-----------------
The dsd command requires that libyaml for C be installed [1]. Then, just
do:
% make
There is no install target at present. Run the command:
% ./dsd help
to show what options are available.
YAML
----
The dsd command uses basic YAML formatting (so, spaces for indentation, then
indentation for indicating structure) and currently recognizes the following
keywords:
property: <name>
owner: <string>
type: integer |
hexadecimal-integer |
hexadecimal-address-package |
string |
<type> <value-list>
description: <free text>
example: <free text>
This looks good to me in general, although I'd replace "owner" with
something like "submitter" to avoid IP connotations.
Also there needs to be a way to connect the properties to the entities
they are supposed to apply to. Like in your example below the
"phy-mode" property will be applicable to NICs, but not necessarily to
other types of hardware.
For example:
property: phy-mode
owner: Al Stone <ahs3(a)redhat.com>
type: string
values:
- token: na
description: none available
- token: mii
description: media independent interface (MII)
- token: gmii
description: gigabit MII
- token: sgmii
description: serial gigabit MII
- token: tbi
description: ten bit interface
- token: revmii
description: reverse MII
- token: rmii
description: reduced MII
- token: rgmii
description: reduced gigabit MII (RGMII)
- token: rgmii-id
description: RGMII with internal delay
- token: rgmii-rxid
description: RGMII with receive delay only
- token: rgmii-txid
description: RGMII with transmit delay only
- token: rtbi
description: reduced ten bit interface
- token: smii
description: serial MII
- token: xgmii
description: 10 gigabit MII
- token: moca
description: multimedia over coax
- token: qsgmii
description: quad serial gigabit MII
description: |
Defines the PHY mode to be used for this device.
example: |
Package (2) { "phy-mode", "xgmii" }
Please use '---' to separate device property definitions if several are
included in a single file of text (dsd will separate them into unique
entries in the "data base").
Thanks,
Rafael
5:28 a.m.
On 08/27/2015 05:44 PM, Rafael J. Wysocki wrote:
Hi,
On 8/28/2015 12:05 AM, Al Stone wrote:
[cut]
Thanks for the feedback, Rafael.
> README
> ------
>
> dsd -- a command line tool for _DSD device property registrations
> -----------------------------------------------------------------
>
> A simple 'make' will produce a command line tool to help in the collection,
> registration and maintenance of entries describing the device properties
> allowed via the _DSD method in ACPI [0] -- and in Device Tree (DT).
>
> The issue is that there is a desire to share device properties not only
> across devices (e.g., is more than one "mac-address" really needed?), but
> between the users of ACPI via _DSD, and possibly the users of Device Tree
> (DT), where the key-value model is used extensively.
>
> While DT documentation seems to be reasonably well cared for (at least in
> the Linux kernel documentation) and there is a process for maintaining the
> device property definitions, the same is not true of ACPI. In fact, device
> properties as used by _DSD are maintained completely outside of the
> specification, and there is no history of maintaining -- or registering --
> them as there is for DT, since this is all relatively new to ACPI.
>
> However, regardless of its quality, keeping documentatation in the Linux
> kernel does present some problems. For one, firmware developers are not
> likely to look at the Linux source for information on the device properties
> they might want to use or need to define. The OS is not really where their
> focus lies. For two, sharing device properties with the Windows OS becomes
> very difficult; asking Microsoft engineers to go use the Linux source code
> as reference material puts them in an untenable position.
>
> What this tool -- dsd -- is attempting to do is provide a standard, neutral
> location and format for the definition of these properties, so that anyone
> that needs to can easily get to them, register new ones, or share existing
> properties.
>
> Each device property is described in YAML (examples below, with details in
> the file called YAML). At present, a directory contains the YAML, with one
> file per device property, one file per device using those properties, and
> acts as a very crude "data base" for all of the entries. The dsd command
> provides several functions for dealing with this "data base" of device
> properties:
>
> -- initialize the data base
> -- verify the YAML is correct
> -- add the device property to the data base in a consistent format
> -- remove a device property from the data base
> -- list all known device property names
> -- output the info from a given device property
> -- output a basic text description of the property for use in Linux
> documentation (or elsewhere)
>
> Additional functions can be added (all the source is provided), and should
> this project work out, more will be -- for example, summaries of all of
> the properties for a given device, or analysis indicating whether or not
> a property is needed and by what devices, or perhaps even more clever things.
>
> Building the tool
> -----------------
> The dsd command requires that libyaml for C be installed [1]. Then, just
> do:
>
> % make
>
> There is no install target at present. Run the command:
>
> % ./dsd help
>
> to show what options are available.
>
> YAML
> ----
> The dsd command uses basic YAML formatting (so, spaces for indentation, then
> indentation for indicating structure) and currently recognizes the following
> keywords:
>
> property: <name>
>
> owner: <string>
>
> type: integer |
> hexadecimal-integer |
> hexadecimal-address-package |
> string |
> <type> <value-list>
>
> description: <free text>
>
> example: <free text>
This looks good to me in general, although I'd replace "owner" with
something
like "submitter" to avoid IP connotations.
Ah. Easily done; "maintainer" was the other thought -- just like in the
kernel, I want to know who to bother when there are problems so that might
be more meaningful than "submitter."
Also there needs to be a way to connect the properties to the
entities they are
supposed to apply to. Like in your example below the "phy-mode" property will
be applicable to NICs, but not necessarily to other types of hardware.
Right. There is, but it was not in the example, and is in the YAML text file
in the git repo; my bad. So, for a property, one might write:
property: phy-mode
devices:
- generic-nic
- my-specific-nic
...
and for a device, one can write:
device: generic-nic
properties:
- phy-mode
- max-speed
...
The 'dsd add' command will check those and emit warnings when something is
referred to that doesn't exist in the db or in the YAML being added. The
'dsd verify' command checks that the references are complete; i.e., if a
refers to b, then b points back to a, also. This should make it fairly easy
to check at least some aspects of correctness.
> For example:
>
> property: phy-mode
> owner: Al Stone <ahs3(a)redhat.com>
> type: string
> values:
> - token: na
> description: none available
> - token: mii
> description: media independent interface (MII)
> - token: gmii
> description: gigabit MII
> - token: sgmii
> description: serial gigabit MII
> - token: tbi
> description: ten bit interface
> - token: revmii
> description: reverse MII
> - token: rmii
> description: reduced MII
> - token: rgmii
> description: reduced gigabit MII (RGMII)
> - token: rgmii-id
> description: RGMII with internal delay
> - token: rgmii-rxid
> description: RGMII with receive delay only
> - token: rgmii-txid
> description: RGMII with transmit delay only
> - token: rtbi
> description: reduced ten bit interface
> - token: smii
> description: serial MII
> - token: xgmii
> description: 10 gigabit MII
> - token: moca
> description: multimedia over coax
> - token: qsgmii
> description: quad serial gigabit MII
> description: |
> Defines the PHY mode to be used for this device.
> example: |
> Package (2) { "phy-mode", "xgmii" }
>
> Please use '---' to separate device property definitions if several are
> included in a single file of text (dsd will separate them into unique
> entries in the "data base").
>
Thanks,
Rafael
--
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3(a)redhat.com
-----------------------------------
10:28 a.m.
On 8/28/2015 9:28 PM, Al Stone wrote:
On 08/27/2015 05:44 PM, Rafael J. Wysocki wrote:
> Hi,
>
> On 8/28/2015 12:05 AM, Al Stone wrote:
>
> [cut]
Thanks for the feedback, Rafael.
>> README
>> ------
>>
>> dsd -- a command line tool for _DSD device property registrations
>> -----------------------------------------------------------------
>>
>> A simple 'make' will produce a command line tool to help in the
collection,
>> registration and maintenance of entries describing the device properties
>> allowed via the _DSD method in ACPI [0] -- and in Device Tree (DT).
>>
>> The issue is that there is a desire to share device properties not only
>> across devices (e.g., is more than one "mac-address" really needed?),
but
>> between the users of ACPI via _DSD, and possibly the users of Device Tree
>> (DT), where the key-value model is used extensively.
>>
>> While DT documentation seems to be reasonably well cared for (at least in
>> the Linux kernel documentation) and there is a process for maintaining the
>> device property definitions, the same is not true of ACPI. In fact, device
>> properties as used by _DSD are maintained completely outside of the
>> specification, and there is no history of maintaining -- or registering --
>> them as there is for DT, since this is all relatively new to ACPI.
>>
>> However, regardless of its quality, keeping documentatation in the Linux
>> kernel does present some problems. For one, firmware developers are not
>> likely to look at the Linux source for information on the device properties
>> they might want to use or need to define. The OS is not really where their
>> focus lies. For two, sharing device properties with the Windows OS becomes
>> very difficult; asking Microsoft engineers to go use the Linux source code
>> as reference material puts them in an untenable position.
>>
>> What this tool -- dsd -- is attempting to do is provide a standard, neutral
>> location and format for the definition of these properties, so that anyone
>> that needs to can easily get to them, register new ones, or share existing
>> properties.
>>
>> Each device property is described in YAML (examples below, with details in
>> the file called YAML). At present, a directory contains the YAML, with one
>> file per device property, one file per device using those properties, and
>> acts as a very crude "data base" for all of the entries. The dsd
command
>> provides several functions for dealing with this "data base" of device
>> properties:
>>
>> -- initialize the data base
>> -- verify the YAML is correct
>> -- add the device property to the data base in a consistent format
>> -- remove a device property from the data base
>> -- list all known device property names
>> -- output the info from a given device property
>> -- output a basic text description of the property for use in Linux
>> documentation (or elsewhere)
>>
>> Additional functions can be added (all the source is provided), and should
>> this project work out, more will be -- for example, summaries of all of
>> the properties for a given device, or analysis indicating whether or not
>> a property is needed and by what devices, or perhaps even more clever things.
>>
>> Building the tool
>> -----------------
>> The dsd command requires that libyaml for C be installed [1]. Then, just
>> do:
>>
>> % make
>>
>> There is no install target at present. Run the command:
>>
>> % ./dsd help
>>
>> to show what options are available.
>>
>> YAML
>> ----
>> The dsd command uses basic YAML formatting (so, spaces for indentation, then
>> indentation for indicating structure) and currently recognizes the following
>> keywords:
>>
>> property: <name>
>>
>> owner: <string>
>>
>> type: integer |
>> hexadecimal-integer |
>> hexadecimal-address-package |
>> string |
>> <type> <value-list>
>>
>> description: <free text>
>>
>> example: <free text>
> This looks good to me in general, although I'd replace "owner" with
something
> like "submitter" to avoid IP connotations.
Ah. Easily done; "maintainer" was the other thought -- just like in the
kernel, I want to know who to bother when there are problems so that might
be more meaningful than "submitter."
Realistically, what can they do to fix the problem if any?
Also, if those are supposed to be "maintainers" or "contacts" or
whatever similar, the entries would need to be updated every time these
people change employers or move to other projects etc. Experience shows
that it is not particularly realistic to expect things like that to
happen ...
> Also there needs to be a way to connect the properties to the
entities they are
> supposed to apply to. Like in your example below the "phy-mode" property
will
> be applicable to NICs, but not necessarily to other types of hardware.
Right. There is, but it was not in the example, and is in the YAML text file
in the git repo; my bad. So, for a property, one might write:
property: phy-mode
devices:
- generic-nic
- my-specific-nic
...
Where "my-specific-nic" would be a device ID I suppose?
and for a device, one can write:
device: generic-nic
properties:
- phy-mode
- max-speed
...
Well, so that gets slightly complicated, because you need to specify
what is covered by "generic-nic" somehow. That is, what devices may or
should be expected to inherit the properties from "generic-nic".
Honestly, at this point I need to ask people internally for opinions.
The 'dsd add' command will check those and emit warnings when
something is
referred to that doesn't exist in the db or in the YAML being added. The
'dsd verify' command checks that the references are complete; i.e., if a
refers to b, then b points back to a, also. This should make it fairly easy
to check at least some aspects of correctness.
That is useful functionality, but we need to agree on the basics to
start with IMO.
Thanks,
Rafael
4:21 a.m.
On 08/28/2015 06:28 PM, Rafael J. Wysocki wrote:
On 8/28/2015 9:28 PM, Al Stone wrote:
> On 08/27/2015 05:44 PM, Rafael J. Wysocki wrote:
>> Hi,
>>
>> On 8/28/2015 12:05 AM, Al Stone wrote:
>>
>> [cut]
> Thanks for the feedback, Rafael.
>
>>> README
>>> ------
>>>
>>> dsd -- a command line tool for _DSD device property registrations
>>> -----------------------------------------------------------------
>>>
>>> A simple 'make' will produce a command line tool to help in the
collection,
>>> registration and maintenance of entries describing the device properties
>>> allowed via the _DSD method in ACPI [0] -- and in Device Tree (DT).
>>>
>>> The issue is that there is a desire to share device properties not only
>>> across devices (e.g., is more than one "mac-address" really
needed?), but
>>> between the users of ACPI via _DSD, and possibly the users of Device Tree
>>> (DT), where the key-value model is used extensively.
>>>
>>> While DT documentation seems to be reasonably well cared for (at least in
>>> the Linux kernel documentation) and there is a process for maintaining the
>>> device property definitions, the same is not true of ACPI. In fact, device
>>> properties as used by _DSD are maintained completely outside of the
>>> specification, and there is no history of maintaining -- or registering --
>>> them as there is for DT, since this is all relatively new to ACPI.
>>>
>>> However, regardless of its quality, keeping documentatation in the Linux
>>> kernel does present some problems. For one, firmware developers are not
>>> likely to look at the Linux source for information on the device properties
>>> they might want to use or need to define. The OS is not really where their
>>> focus lies. For two, sharing device properties with the Windows OS becomes
>>> very difficult; asking Microsoft engineers to go use the Linux source code
>>> as reference material puts them in an untenable position.
>>>
>>> What this tool -- dsd -- is attempting to do is provide a standard, neutral
>>> location and format for the definition of these properties, so that anyone
>>> that needs to can easily get to them, register new ones, or share existing
>>> properties.
>>>
>>> Each device property is described in YAML (examples below, with details in
>>> the file called YAML). At present, a directory contains the YAML, with one
>>> file per device property, one file per device using those properties, and
>>> acts as a very crude "data base" for all of the entries. The dsd
command
>>> provides several functions for dealing with this "data base" of
device
>>> properties:
>>>
>>> -- initialize the data base
>>> -- verify the YAML is correct
>>> -- add the device property to the data base in a consistent format
>>> -- remove a device property from the data base
>>> -- list all known device property names
>>> -- output the info from a given device property
>>> -- output a basic text description of the property for use in Linux
>>> documentation (or elsewhere)
>>>
>>> Additional functions can be added (all the source is provided), and should
>>> this project work out, more will be -- for example, summaries of all of
>>> the properties for a given device, or analysis indicating whether or not
>>> a property is needed and by what devices, or perhaps even more clever
things.
>>>
>>> Building the tool
>>> -----------------
>>> The dsd command requires that libyaml for C be installed [1]. Then, just
>>> do:
>>>
>>> % make
>>>
>>> There is no install target at present. Run the command:
>>>
>>> % ./dsd help
>>>
>>> to show what options are available.
>>>
>>> YAML
>>> ----
>>> The dsd command uses basic YAML formatting (so, spaces for indentation, then
>>> indentation for indicating structure) and currently recognizes the following
>>> keywords:
>>>
>>> property: <name>
>>>
>>> owner: <string>
>>>
>>> type: integer |
>>> hexadecimal-integer |
>>> hexadecimal-address-package |
>>> string |
>>> <type> <value-list>
>>>
>>> description: <free text>
>>>
>>> example: <free text>
>> This looks good to me in general, although I'd replace "owner" with
something
>> like "submitter" to avoid IP connotations.
> Ah. Easily done; "maintainer" was the other thought -- just like in the
> kernel, I want to know who to bother when there are problems so that might
> be more meaningful than "submitter."
Realistically, what can they do to fix the problem if any?
Also, if those are supposed to be "maintainers" or "contacts" or
whatever
similar, the entries would need to be updated every time these people change
employers or move to other projects etc. Experience shows that it is not
particularly realistic to expect things like that to happen ...
My intent is to capture a starting point -- from that standpoint, "submitter"
is probably more accurate. I agree -- it's completely unclear if people could
fix a problem, or would stick around. OTOH, having *some place* to start when
an issue occurs is better than what we have today.
>> Also there needs to be a way to connect the properties to the
entities they are
>> supposed to apply to. Like in your example below the "phy-mode"
property will
>> be applicable to NICs, but not necessarily to other types of hardware.
> Right. There is, but it was not in the example, and is in the YAML text file
> in the git repo; my bad. So, for a property, one might write:
>
> property: phy-mode
> devices:
> - generic-nic
> - my-specific-nic
> ...
>
Where "my-specific-nic" would be a device ID I suppose?
Semantically, I was thinking that would be whatever name made sense to
the submitter, but something human readable as the name for this device
in the db. I was debating how to add in _HID (or _CID or whatever the
driver writer chose) and could perhaps just use those keywords, but would
prefer a more neutral name -- "device-id", "numeric-id", ... ?
> and for a device, one can write:
>
> device: generic-nic
> properties:
> - phy-mode
> - max-speed
> ...
Well, so that gets slightly complicated, because you need to specify what is
covered by "generic-nic" somehow. That is, what devices may or should be
expected to inherit the properties from "generic-nic".
Honestly, at this point I need to ask people internally for opinions.
That's fine, but please keep the discussion on the mailing list. IMO, it
is absolutely essential this entire process stay completely transparent to
everyone involved. I can see no absolutely no reason for any of it to be
hidden.
> The 'dsd add' command will check those and emit warnings
when something is
> referred to that doesn't exist in the db or in the YAML being added. The
> 'dsd verify' command checks that the references are complete; i.e., if a
> refers to b, then b points back to a, also. This should make it fairly easy
> to check at least some aspects of correctness.
>
That is useful functionality, but we need to agree on the basics to start with IMO.
Thanks,
Rafael
Sure. It's just a simple matter of changing software :). We needed to start
somewhere and get something moving so that's what this is -- a starting point.
People have to get products shipped and nothing had been happening, so there's
a pressing need to start somewhere, anywhere...
--
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3(a)redhat.com
-----------------------------------
10:13 a.m.
On 8/31/2015 8:21 PM, Al Stone wrote:
On 08/28/2015 06:28 PM, Rafael J. Wysocki wrote:
> On 8/28/2015 9:28 PM, Al Stone wrote:
>> On 08/27/2015 05:44 PM, Rafael J. Wysocki wrote:
>>> Hi,
>>>
>>> On 8/28/2015 12:05 AM, Al Stone wrote:
>>>
>>> [cut]
>> Thanks for the feedback, Rafael.
>>
>>>> README
>>>> ------
>>>>
>>>> dsd -- a command line tool for _DSD device property registrations
>>>> -----------------------------------------------------------------
>>>>
>>>> A simple 'make' will produce a command line tool to help in the
collection,
>>>> registration and maintenance of entries describing the device properties
>>>> allowed via the _DSD method in ACPI [0] -- and in Device Tree (DT).
>>>>
>>>> The issue is that there is a desire to share device properties not only
>>>> across devices (e.g., is more than one "mac-address" really
needed?), but
>>>> between the users of ACPI via _DSD, and possibly the users of Device
Tree
>>>> (DT), where the key-value model is used extensively.
>>>>
>>>> While DT documentation seems to be reasonably well cared for (at least
in
>>>> the Linux kernel documentation) and there is a process for maintaining
the
>>>> device property definitions, the same is not true of ACPI. In fact,
device
>>>> properties as used by _DSD are maintained completely outside of the
>>>> specification, and there is no history of maintaining -- or registering
--
>>>> them as there is for DT, since this is all relatively new to ACPI.
>>>>
>>>> However, regardless of its quality, keeping documentatation in the Linux
>>>> kernel does present some problems. For one, firmware developers are not
>>>> likely to look at the Linux source for information on the device
properties
>>>> they might want to use or need to define. The OS is not really where
their
>>>> focus lies. For two, sharing device properties with the Windows OS
becomes
>>>> very difficult; asking Microsoft engineers to go use the Linux source
code
>>>> as reference material puts them in an untenable position.
>>>>
>>>> What this tool -- dsd -- is attempting to do is provide a standard,
neutral
>>>> location and format for the definition of these properties, so that
anyone
>>>> that needs to can easily get to them, register new ones, or share
existing
>>>> properties.
>>>>
>>>> Each device property is described in YAML (examples below, with details
in
>>>> the file called YAML). At present, a directory contains the YAML, with
one
>>>> file per device property, one file per device using those properties,
and
>>>> acts as a very crude "data base" for all of the entries. The
dsd command
>>>> provides several functions for dealing with this "data base" of
device
>>>> properties:
>>>>
>>>> -- initialize the data base
>>>> -- verify the YAML is correct
>>>> -- add the device property to the data base in a consistent format
>>>> -- remove a device property from the data base
>>>> -- list all known device property names
>>>> -- output the info from a given device property
>>>> -- output a basic text description of the property for use in
Linux
>>>> documentation (or elsewhere)
>>>>
>>>> Additional functions can be added (all the source is provided), and
should
>>>> this project work out, more will be -- for example, summaries of all of
>>>> the properties for a given device, or analysis indicating whether or not
>>>> a property is needed and by what devices, or perhaps even more clever
things.
>>>>
>>>> Building the tool
>>>> -----------------
>>>> The dsd command requires that libyaml for C be installed [1]. Then,
just
>>>> do:
>>>>
>>>> % make
>>>>
>>>> There is no install target at present. Run the command:
>>>>
>>>> % ./dsd help
>>>>
>>>> to show what options are available.
>>>>
>>>> YAML
>>>> ----
>>>> The dsd command uses basic YAML formatting (so, spaces for indentation,
then
>>>> indentation for indicating structure) and currently recognizes the
following
>>>> keywords:
>>>>
>>>> property: <name>
>>>>
>>>> owner: <string>
>>>>
>>>> type: integer |
>>>> hexadecimal-integer |
>>>> hexadecimal-address-package |
>>>> string |
>>>> <type> <value-list>
>>>>
>>>> description: <free text>
>>>>
>>>> example: <free text>
>>> This looks good to me in general, although I'd replace "owner"
with something
>>> like "submitter" to avoid IP connotations.
>> Ah. Easily done; "maintainer" was the other thought -- just like in
the
>> kernel, I want to know who to bother when there are problems so that might
>> be more meaningful than "submitter."
> Realistically, what can they do to fix the problem if any?
>
> Also, if those are supposed to be "maintainers" or "contacts" or
whatever
> similar, the entries would need to be updated every time these people change
> employers or move to other projects etc. Experience shows that it is not
> particularly realistic to expect things like that to happen ...
My intent is to capture a starting point -- from that standpoint, "submitter"
is probably more accurate. I agree -- it's completely unclear if people could
fix a problem, or would stick around. OTOH, having *some place* to start when
an issue occurs is better than what we have today.
Actually, "submitter" might be as good as it gets.
>>> Also there needs to be a way to connect the properties to
the entities they are
>>> supposed to apply to. Like in your example below the "phy-mode"
property will
>>> be applicable to NICs, but not necessarily to other types of hardware.
>> Right. There is, but it was not in the example, and is in the YAML text file
>> in the git repo; my bad. So, for a property, one might write:
>>
>> property: phy-mode
>> devices:
>> - generic-nic
>> - my-specific-nic
>> ...
>>
> Where "my-specific-nic" would be a device ID I suppose?
Semantically, I was thinking that would be whatever name made sense to
the submitter, but something human readable as the name for this device
in the db. I was debating how to add in _HID (or _CID or whatever the
driver writer chose) and could perhaps just use those keywords, but would
prefer a more neutral name -- "device-id", "numeric-id", ... ?
In my view the whole database structure needs to be based on defining
"property sets" or "classes" of things.
A property definition by itself is meaningless until you tie it to a
specific "property set" which then may be used to describe a physical
entity, like a device. The generic-nic thing in your example below is
something like that.
I personally would like the following to be basic principles of the design:
(1) A property set (or a class) is a collection of properties (possibly
nested, by no recursion) that may be used to describe an entity like a
device.
(2) It has a single parent set (base class). All of the properties from
the parent set are inherited by its descendants.
(3) It may be based on multiple base sets (in addition to the parent
set) and will inherit their properties in that case.
The, the database may be easily represented in the form of a directory
structure where property sets are represented by directories and
properties - by files in them.
Now, which property set to use will depend on the given device ID (a
_HID or a _CID). IOW, given a device ID, a device driver should know
which property set is applicable to it and that doesn't have to be
specified in the database.
We'll probably need a special "propertty-set-version" property for that
to be able to extend property sets by adding more properties to them
over time.
>> and for a device, one can write:
>>
>> device: generic-nic
>> properties:
>> - phy-mode
>> - max-speed
>> ...
> Well, so that gets slightly complicated, because you need to specify what is
> covered by "generic-nic" somehow. That is, what devices may or should be
> expected to inherit the properties from "generic-nic".
>
> Honestly, at this point I need to ask people internally for opinions.
That's fine, but please keep the discussion on the mailing list. IMO, it
is absolutely essential this entire process stay completely transparent to
everyone involved. I can see no absolutely no reason for any of it to be
hidden.
It is not about hiding things, but about talking to people who may not
be subscribed to this mailing lists simply to get their input.
>> The 'dsd add' command will check those and emit
warnings when something is
>> referred to that doesn't exist in the db or in the YAML being added. The
>> 'dsd verify' command checks that the references are complete; i.e., if a
>> refers to b, then b points back to a, also. This should make it fairly easy
>> to check at least some aspects of correctness.
>>
> That is useful functionality, but we need to agree on the basics to start with IMO.
>
> Thanks,
> Rafael
>
Sure. It's just a simple matter of changing software :). We needed to start
somewhere and get something moving so that's what this is -- a starting point.
People have to get products shipped and nothing had been happening, so there's
a pressing need to start somewhere, anywhere...
Sure.
Thanks,
Rafael
2:47 a.m.
On 08/31/2015 06:13 PM, Rafael J. Wysocki wrote:
On 8/31/2015 8:21 PM, Al Stone wrote:
> On 08/28/2015 06:28 PM, Rafael J. Wysocki wrote:
>> On 8/28/2015 9:28 PM, Al Stone wrote:
>>> On 08/27/2015 05:44 PM, Rafael J. Wysocki wrote:
>>>> Hi,
>>>>[snip....]
>>>>> YAML
>>>>> ----
>>>>> The dsd command uses basic YAML formatting (so, spaces for
indentation, then
>>>>> indentation for indicating structure) and currently recognizes the
following
>>>>> keywords:
>>>>>
>>>>> property: <name>
>>>>>
>>>>> owner: <string>
>>>>>
>>>>> type: integer |
>>>>> hexadecimal-integer |
>>>>> hexadecimal-address-package |
>>>>> string |
>>>>> <type> <value-list>
>>>>>
>>>>> description: <free text>
>>>>>
>>>>> example: <free text>
>>>> This looks good to me in general, although I'd replace
"owner" with something
>>>> like "submitter" to avoid IP connotations.
>>> Ah. Easily done; "maintainer" was the other thought -- just like
in the
>>> kernel, I want to know who to bother when there are problems so that might
>>> be more meaningful than "submitter."
>> Realistically, what can they do to fix the problem if any?
>>
>> Also, if those are supposed to be "maintainers" or "contacts"
or whatever
>> similar, the entries would need to be updated every time these people change
>> employers or move to other projects etc. Experience shows that it is not
>> particularly realistic to expect things like that to happen ...
> My intent is to capture a starting point -- from that standpoint,
"submitter"
> is probably more accurate. I agree -- it's completely unclear if people could
> fix a problem, or would stick around. OTOH, having *some place* to start when
> an issue occurs is better than what we have today.
Actually, "submitter" might be as good as it gets.
Ack. The more I think about it, the more I agree. I'll make that change.
>>>> Also there needs to be a way to connect the
properties to the entities they
>>>> are
>>>> supposed to apply to. Like in your example below the
"phy-mode" property will
>>>> be applicable to NICs, but not necessarily to other types of hardware.
>>> Right. There is, but it was not in the example, and is in the YAML text
file
>>> in the git repo; my bad. So, for a property, one might write:
>>>
>>> property: phy-mode
>>> devices:
>>> - generic-nic
>>> - my-specific-nic
>>> ...
>>>
>> Where "my-specific-nic" would be a device ID I suppose?
> Semantically, I was thinking that would be whatever name made sense to
> the submitter, but something human readable as the name for this device
> in the db. I was debating how to add in _HID (or _CID or whatever the
> driver writer chose) and could perhaps just use those keywords, but would
> prefer a more neutral name -- "device-id", "numeric-id", ... ?
In my view the whole database structure needs to be based on defining "property
sets" or "classes" of things.
A property definition by itself is meaningless until you tie it to a specific
"property set" which then may be used to describe a physical entity, like a
device. The generic-nic thing in your example below is something like that.
Ah, okay. I see what you're getting at now.
I personally would like the following to be basic principles of the
design:
(1) A property set (or a class) is a collection of properties (possibly nested,
by no recursion) that may be used to describe an entity like a device.
Agreed, no recursion. This would imply that we have at least two first class
objects in the language: a "class" and a "property", with a class
being defined
as a container for properties. Okay; I can live with that -- it makes sense.
(2) It has a single parent set (base class). All of the properties
from the
parent set are inherited by its descendants.
Right. Had you thought about the name space for each class? I see there being
two choices: (1) a single name space for a class and all children, such that
each name in a child class must be different from all other names in that
hierarchy, or (2) a single independent name space for each class with a way to
refer to parent properties.
An example might look like this with option (1):
class: foo
property: a
property: b
class: bar # inherits from foo
property: a # illegal, 'a' is defined in foo
property: c # legal, no other use of the name
default: b # ...the parent property
For option (2):
class: foo
property: a # full name is /foo/a
property: b
class: bar # inherits from foo
property: a # legal since this is /foo/bar/a
property: b # this is /foo/bar/a
default: /foo/b # ...the parent property
The second option I find more elegant and intuitive, but it may also be
completely unnecessary. I tried to come up with compelling examples one
way or the other and got nowhere. So, my inclination is to go with the
latter unless there are major objections.
(3) It may be based on multiple base sets (in addition to the parent
set) and
will inherit their properties in that case.
...which also leads me to a single name space per class with syntax for any
disambiguation of references to parent properties as more straightforward. I
agree that multiple inheritance is useful, though.
The, the database may be easily represented in the form of a
directory structure
where property sets are represented by directories and properties - by files in
them.
Right. I'd really like to maintain that usage model -- i.e., one can send a
patch to a text file -- so yeah, I think the db would end up looking as you say.
Now, which property set to use will depend on the given device ID (a
_HID or a
_CID). IOW, given a device ID, a device driver should know which property set
is applicable to it and that doesn't have to be specified in the database.
I agree with the conclusion -- the device does not have to be specified in the
db. However, like in double-entry accounting, it gives me a cross-check for
correctness. For example, if we had something like this:
class: foo
device: my-device
property: a
...
device: my-device
_HID: ACPI0000
dt-id: vendor,my-device
property-class: foo
linux-driver: my_device
windows-driver: MyDevice
bsd-driver: my_device
....
This might give us a fighting chance of finding someone to talk to when
something breaks in a binding, and I can check the db content to ensure
that (a) every class or its parent has a device, and (b) that every device
has a property class.
OTOH, getting people to provide the device info, and keep it up-to-date, may
be very difficult, making it useless quickly, or making it costly to maintain
without a significant return.
We'll probably need a special "propertty-set-version"
property for that to be
able to extend property sets by adding more properties to them over time.
Nod. It's almost a special form of sub-classing...perhaps that's the way to
treat it as well....
Let me try a round 2 here and see what we think.
--
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3(a)redhat.com
-----------------------------------
9:26 a.m.
On 9/8/2015 6:47 PM, Al Stone wrote:
On 08/31/2015 06:13 PM, Rafael J. Wysocki wrote:
> On 8/31/2015 8:21 PM, Al Stone wrote:
>> On 08/28/2015 06:28 PM, Rafael J. Wysocki wrote:
>>> On 8/28/2015 9:28 PM, Al Stone wrote:
>>>> On 08/27/2015 05:44 PM, Rafael J. Wysocki wrote:
>>>>> Hi,
>>>>> [snip....]
>>>>>> YAML
>>>>>> ----
>>>>>> The dsd command uses basic YAML formatting (so, spaces for
indentation, then
>>>>>> indentation for indicating structure) and currently recognizes
the following
>>>>>> keywords:
>>>>>>
>>>>>> property: <name>
>>>>>>
>>>>>> owner: <string>
>>>>>>
>>>>>> type: integer |
>>>>>> hexadecimal-integer |
>>>>>> hexadecimal-address-package |
>>>>>> string |
>>>>>> <type> <value-list>
>>>>>>
>>>>>> description: <free text>
>>>>>>
>>>>>> example: <free text>
>>>>> This looks good to me in general, although I'd replace
"owner" with something
>>>>> like "submitter" to avoid IP connotations.
>>>> Ah. Easily done; "maintainer" was the other thought -- just
like in the
>>>> kernel, I want to know who to bother when there are problems so that
might
>>>> be more meaningful than "submitter."
>>> Realistically, what can they do to fix the problem if any?
>>>
>>> Also, if those are supposed to be "maintainers" or
"contacts" or whatever
>>> similar, the entries would need to be updated every time these people change
>>> employers or move to other projects etc. Experience shows that it is not
>>> particularly realistic to expect things like that to happen ...
>> My intent is to capture a starting point -- from that standpoint,
"submitter"
>> is probably more accurate. I agree -- it's completely unclear if people
could
>> fix a problem, or would stick around. OTOH, having *some place* to start when
>> an issue occurs is better than what we have today.
> Actually, "submitter" might be as good as it gets.
Ack. The more I think about it, the more I agree. I'll make that change.
>>>>> Also there needs to be a way to connect the properties to the
entities they
>>>>> are
>>>>> supposed to apply to. Like in your example below the
"phy-mode" property will
>>>>> be applicable to NICs, but not necessarily to other types of
hardware.
>>>> Right. There is, but it was not in the example, and is in the YAML text
file
>>>> in the git repo; my bad. So, for a property, one might write:
>>>>
>>>> property: phy-mode
>>>> devices:
>>>> - generic-nic
>>>> - my-specific-nic
>>>> ...
>>>>
>>> Where "my-specific-nic" would be a device ID I suppose?
>> Semantically, I was thinking that would be whatever name made sense to
>> the submitter, but something human readable as the name for this device
>> in the db. I was debating how to add in _HID (or _CID or whatever the
>> driver writer chose) and could perhaps just use those keywords, but would
>> prefer a more neutral name -- "device-id", "numeric-id", ...
?
> In my view the whole database structure needs to be based on defining "property
> sets" or "classes" of things.
>
> A property definition by itself is meaningless until you tie it to a specific
> "property set" which then may be used to describe a physical entity, like
a
> device. The generic-nic thing in your example below is something like that.
Ah, okay. I see what you're getting at now.
> I personally would like the following to be basic principles of the design:
> (1) A property set (or a class) is a collection of properties (possibly nested,
> by no recursion) that may be used to describe an entity like a device.
Agreed, no recursion. This would imply that we have at least two first class
objects in the language: a "class" and a "property", with a class
being defined
as a container for properties. Okay; I can live with that -- it makes sense.
> (2) It has a single parent set (base class). All of the properties from the
> parent set are inherited by its descendants.
Right.
In the meantime I changed my mind on this one a bit.
I realized that the structure resulting from that would be to rigid and
the database directory tree would grow horizontally and not vertically,
so it would get difficult to manage over time.
I'm now thinking that tying inheritance to the directory structure is
not a good idea.
I'm still thinking that property sets (classes) should be represented by
directories and properties by files, but I would also allow directories
that did not represent property sets to be present in the database for
purely organizational purposes.
Had you thought about the name space for each class? I see there
being
two choices: (1) a single name space for a class and all children, such that
each name in a child class must be different from all other names in that
hierarchy, or (2) a single independent name space for each class with a way to
refer to parent properties.
I think that (2) is more flexible and more useful.
One example of that is when one set might be superseded by another
derived set and there should be a way to override the "old" properties
in that case.
An example might look like this with option (1):
class: foo
property: a
property: b
class: bar # inherits from foo
property: a # illegal, 'a' is defined in foo
property: c # legal, no other use of the name
default: b # ...the parent property
For option (2):
class: foo
property: a # full name is /foo/a
property: b
class: bar # inherits from foo
property: a # legal since this is /foo/bar/a
property: b # this is /foo/bar/a
default: /foo/b # ...the parent property
The second option I find more elegant and intuitive, but it may also be
completely unnecessary. I tried to come up with compelling examples one
way or the other and got nowhere. So, my inclination is to go with the
latter unless there are major objections.
No objections from me. As I said, it is more flexible IMO.
> (3) It may be based on multiple base sets (in addition to the
parent set) and
> will inherit their properties in that case.
...which also leads me to a single name space per class with syntax for any
disambiguation of references to parent properties as more straightforward. I
agree that multiple inheritance is useful, though.
> The, the database may be easily represented in the form of a directory structure
> where property sets are represented by directories and properties - by files in
> them.
Right. I'd really like to maintain that usage model -- i.e., one can send a
patch to a text file -- so yeah, I think the db would end up looking as you say.
> Now, which property set to use will depend on the given device ID (a _HID or a
> _CID). IOW, given a device ID, a device driver should know which property set
> is applicable to it and that doesn't have to be specified in the database.
I agree with the conclusion -- the device does not have to be specified in the
db. However, like in double-entry accounting, it gives me a cross-check for
correctness. For example, if we had something like this:
class: foo
device: my-device
property: a
...
device: my-device
_HID: ACPI0000
dt-id: vendor,my-device
property-class: foo
linux-driver: my_device
windows-driver: MyDevice
bsd-driver: my_device
....
This might give us a fighting chance of finding someone to talk to when
something breaks in a binding, and I can check the db content to ensure
that (a) every class or its parent has a device, and (b) that every device
has a property class.
OTOH, getting people to provide the device info, and keep it up-to-date, may
be very difficult, making it useless quickly, or making it costly to maintain
without a significant return.
> We'll probably need a special "propertty-set-version" property for that
to be
> able to extend property sets by adding more properties to them over time.
Nod. It's almost a special form of sub-classing...perhaps that's the way to
treat it as well....
I'm actually not sure about that any more.
As I said in the previous message (which apparently didn't make it to
dsd(a)acpica.org, because I sent it from an unsubscribed account, sorry
about that), the version can be easily inferred by the OS from what
properties are present and the firmware developers only need to know if
the property set has been superseded by another one and by which one if so.
Let me try a round 2 here and see what we think.
OK, so below is a list of design principles that don't seem to be
objectionable. I wonder if we can agree on them and continue from there:
1. The design of the database is based on the property set concept.
A property set is a collection of property items that may be
applicable to a hardware entity like a device.
There are two types of property items, properties and property
subsets.
The concept of a property is defined in the "Device Properties
UUID" document at
http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-...
Property subsets are nested collections of properties. Each
of them is associated with an additional key (name) allowing
the subset to be referred to as a whole (and to be treated as
a separate entity). The canonical representation of property
subsets is via the mechanism defined in the "Hierarchical
Properties Extension UUID" document at
http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-...
2. Inheritance should be possible.
To facilitate re-use of existing definitions of properties and
property subsets, the database is designed to allow new property
sets to be built on top of existing ones and to inherit property
items from them.
A property set whose property items are inherited is referred to
as a base set. A property set inheriting property items is
referred to as a derived set.
A property set may be derived from multiple base sets.
A subset of one property set may be derived from another
property set. The set it is derived from is then referred to as
a template of it.
Property sets whose only purpose is to serve as base sets for
other property sets (that can be used by platform firmware to
represent hardware properties) or as templates for property
subsets are referred to as abstract property sets.
3. Non-abstract property sets must be associated with device IDs.
For every non-abstract property set in the database there must
be at least one device ID associated with it. The property set
must be sufficient for representing all properties of the device
with that ID.
For every abstract property set in the database there must be
at least one non-abstract property set derived from it or at
least one property subset using it as a template.
4. Property sets represented as directories.
To allow easy identification of property sets for the purpose of
inheritance (among other things) the database is organized in the
form of a directory tree and property sets are represented as
directories.
For the purpose of identification within the database, each property
set has a name (arbitrary string) not containing a /.
Each property set is uniquely identified by the path from the
top-most directory of the database (database root) to its location,
including its name.
11:46 p.m.
Hi
[snip]
OK, so below is a list of design principles that don't seem to be
objectionable. I wonder if we can agree on them and continue from there:
1. The design of the database is based on the property set concept.
A property set is a collection of property items that may be
applicable to a hardware entity like a device.
There are two types of property items, properties and property
subsets.
The concept of a property is defined in the "Device Properties
UUID" document at
http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-U
UID.pdf
Property subsets are nested collections of properties. Each
of them is associated with an additional key (name) allowing
the subset to be referred to as a whole (and to be treated as
a separate entity). The canonical representation of property
subsets is via the mechanism defined in the "Hierarchical
Properties Extension UUID" document at
http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-e
xtension-UUID-v1.pdf
2. Inheritance should be possible.
To facilitate re-use of existing definitions of properties and
property subsets, the database is designed to allow new property
sets to be built on top of existing ones and to inherit property
items from them.
A property set whose property items are inherited is referred to
as a base set. A property set inheriting property items is
referred to as a derived set.
A property set may be derived from multiple base sets.
A subset of one property set may be derived from another
property set. The set it is derived from is then referred to as
a template of it.
Property sets whose only purpose is to serve as base sets for
other property sets (that can be used by platform firmware to
represent hardware properties) or as templates for property
subsets are referred to as abstract property sets.
3. Non-abstract property sets must be associated with device IDs.
For every non-abstract property set in the database there must
be at least one device ID associated with it. The property set
must be sufficient for representing all properties of the device
with that ID.
For every abstract property set in the database there must be
at least one non-abstract property set derived from it or at
least one property subset using it as a template.
4. Property sets represented as directories.
To allow easy identification of property sets for the purpose of
inheritance (among other things) the database is organized in the
form of a directory tree and property sets are represented as
directories.
For the purpose of identification within the database, each property
set has a name (arbitrary string) not containing a /.
[nit on my OS-agnostic radar]
Replace "/" with "directory separator character e.g / or \."
Each property set is uniquely identified by the path from the
top-most directory of the database (database root) to its location,
including its name.
So to me all of the above seems sane. However, I think we should also have
rules to state what kinds of properties should be provided by this
mechanism. In particular, this mechanism should not be used to provide
alternative implementations to paradigms that are already provided via
ACPI. For example:
- Using these properties to represent power resources such as voltage
supplies or clocks, in such a way that to power manage a device a device
driver using these properties instead of D states or ACPI Power resources
- Using this approach to represent performance states in such a way that
custom drivers in the OS manage CPU performance through these properties
instead of P-states or CPPC
The above is probably the biggest concern that has been coming from the
ARM camp, which incidentally is very well versed in what has gone well and
what hasn¹t gone well with DT, and has been hurt by then having to
maintain bindings that we would rather had not been created. The rule here
is probably pretty obvious, because of the maintenance contract implied by
accepting a property into the database, but I think it is still worth
stating.
Cheers
Charles
_______________________________________________
DSD mailing list
DSD(a)acpica.org
https://lists.acpica.org/mailman/listinfo/dsd
9:20 a.m.
On 9/9/2015 3:46 PM, Charles Garcia-Tobin wrote:
Hi
[snip]
> OK, so below is a list of design principles that don't seem to be
> objectionable. I wonder if we can agree on them and continue from there:
>
> 1. The design of the database is based on the property set concept.
>
> A property set is a collection of property items that may be
> applicable to a hardware entity like a device.
>
> There are two types of property items, properties and property
> subsets.
>
> The concept of a property is defined in the "Device Properties
> UUID" document at
>
> http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-U
> UID.pdf
>
> Property subsets are nested collections of properties. Each
> of them is associated with an additional key (name) allowing
> the subset to be referred to as a whole (and to be treated as
> a separate entity). The canonical representation of property
> subsets is via the mechanism defined in the "Hierarchical
> Properties Extension UUID" document at
>
> http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-e
> xtension-UUID-v1.pdf
>
> 2. Inheritance should be possible.
>
> To facilitate re-use of existing definitions of properties and
> property subsets, the database is designed to allow new property
> sets to be built on top of existing ones and to inherit property
> items from them.
>
> A property set whose property items are inherited is referred to
> as a base set. A property set inheriting property items is
> referred to as a derived set.
>
> A property set may be derived from multiple base sets.
>
> A subset of one property set may be derived from another
> property set. The set it is derived from is then referred to as
> a template of it.
>
> Property sets whose only purpose is to serve as base sets for
> other property sets (that can be used by platform firmware to
> represent hardware properties) or as templates for property
> subsets are referred to as abstract property sets.
>
> 3. Non-abstract property sets must be associated with device IDs.
>
> For every non-abstract property set in the database there must
> be at least one device ID associated with it. The property set
> must be sufficient for representing all properties of the device
> with that ID.
>
> For every abstract property set in the database there must be
> at least one non-abstract property set derived from it or at
> least one property subset using it as a template.
>
> 4. Property sets represented as directories.
>
> To allow easy identification of property sets for the purpose of
> inheritance (among other things) the database is organized in the
> form of a directory tree and property sets are represented as
> directories.
>
> For the purpose of identification within the database, each property
> set has a name (arbitrary string) not containing a /.
[nit on my OS-agnostic radar]
Replace "/" with "directory separator character e.g / or \."
OK, "directory separator character" should be clear enough.
> Each property set is uniquely identified by the path from
the
> top-most directory of the database (database root) to its location,
> including its name.
So to me all of the above seems sane. However, I think we should also have
rules to state what kinds of properties should be provided by this
mechanism. In particular, this mechanism should not be used to provide
alternative implementations to paradigms that are already provided via
ACPI. For example:
- Using these properties to represent power resources such as voltage
supplies or clocks, in such a way that to power manage a device a device
driver using these properties instead of D states or ACPI Power resources
- Using this approach to represent performance states in such a way that
custom drivers in the OS manage CPU performance through these properties
instead of P-states or CPPC
Right.
This has been our position since the introduction of _DSD.
The above is probably the biggest concern that has been coming from
the
ARM camp, which incidentally is very well versed in what has gone well and
what hasn¹t gone well with DT, and has been hurt by then having to
maintain bindings that we would rather had not been created. The rule here
is probably pretty obvious, because of the maintenance contract implied by
accepting a property into the database, but I think it is still worth
stating.
Agreed.
Thanks,
Rafael
> _______________________________________________
> DSD mailing list
> DSD(a)acpica.org
> https://lists.acpica.org/mailman/listinfo/dsd
>
7:44 a.m.
Hi
I agree with the submitter/maintainer comments from Rafael, but in my head
the model for this is one where there is an agreed set of maintainers at
any one time who own the reviewing process of DSD. Folk that take on this
role would be ones that get contacted when a binding shows problems.
Actually the list in general would presumably be the first port of call.
Relating to that, I do wonder whether the general property that should be
present in every binding is a version. This would cater for some of
Jonathan¹s concerns. Though I agree with Rafael that once a binding goes
into the database it should be supported. We may over long term want to
cater for a deprecation strategy too, emphasis on long term.
Finally, a general comment on the dsd tool, which Al, your are gonna hate
me for. It doesn¹t look very OS agnostic. Ie if I wanted to build it, and
use it, from a windows machine it¹d be a bit of a pain unless you had
cygwin or mingw etc. Wondered whether writing in python, which is way
easier for OS agnostic code and has yaml support, would be better. I am
guessing what your answer is going to be :-)
Cheers
Charles
On 28/08/2015 20:28, "DSD on behalf of ahs3(a)redhat.com"
<dsd-bounces(a)acpica.org on behalf of ahs3(a)redhat.com> wrote:
On 08/27/2015 05:44 PM, Rafael J. Wysocki wrote:
> Hi,
>
> On 8/28/2015 12:05 AM, Al Stone wrote:
>
> [cut]
Thanks for the feedback, Rafael.
>> README
>> ------
>>
>> dsd -- a command line tool for _DSD device property registrations
>> -----------------------------------------------------------------
>>
>> A simple 'make' will produce a command line tool to help in the
>>collection,
>> registration and maintenance of entries describing the device
>>properties
>> allowed via the _DSD method in ACPI [0] -- and in Device Tree (DT).
>>
>> The issue is that there is a desire to share device properties not only
>> across devices (e.g., is more than one "mac-address" really needed?),
>>but
>> between the users of ACPI via _DSD, and possibly the users of Device
>>Tree
>> (DT), where the key-value model is used extensively.
>>
>> While DT documentation seems to be reasonably well cared for (at least
>>in
>> the Linux kernel documentation) and there is a process for maintaining
>>the
>> device property definitions, the same is not true of ACPI. In fact,
>>device
>> properties as used by _DSD are maintained completely outside of the
>> specification, and there is no history of maintaining -- or
>>registering --
>> them as there is for DT, since this is all relatively new to ACPI.
>>
>> However, regardless of its quality, keeping documentatation in the
>>Linux
>> kernel does present some problems. For one, firmware developers are
>>not
>> likely to look at the Linux source for information on the device
>>properties
>> they might want to use or need to define. The OS is not really where
>>their
>> focus lies. For two, sharing device properties with the Windows OS
>>becomes
>> very difficult; asking Microsoft engineers to go use the Linux source
>>code
>> as reference material puts them in an untenable position.
>>
>> What this tool -- dsd -- is attempting to do is provide a standard,
>>neutral
>> location and format for the definition of these properties, so that
>>anyone
>> that needs to can easily get to them, register new ones, or share
>>existing
>> properties.
>>
>> Each device property is described in YAML (examples below, with
>>details in
>> the file called YAML). At present, a directory contains the YAML,
>>with one
>> file per device property, one file per device using those properties,
>>and
>> acts as a very crude "data base" for all of the entries. The dsd
>>command
>> provides several functions for dealing with this "data base" of device
>> properties:
>>
>> -- initialize the data base
>> -- verify the YAML is correct
>> -- add the device property to the data base in a consistent format
>> -- remove a device property from the data base
>> -- list all known device property names
>> -- output the info from a given device property
>> -- output a basic text description of the property for use in Linux
>> documentation (or elsewhere)
>>
>> Additional functions can be added (all the source is provided), and
>>should
>> this project work out, more will be -- for example, summaries of all of
>> the properties for a given device, or analysis indicating whether or
>>not
>> a property is needed and by what devices, or perhaps even more clever
>>things.
>>
>> Building the tool
>> -----------------
>> The dsd command requires that libyaml for C be installed [1]. Then,
>>just
>> do:
>>
>> % make
>>
>> There is no install target at present. Run the command:
>>
>> % ./dsd help
>>
>> to show what options are available.
>>
>> YAML
>> ----
>> The dsd command uses basic YAML formatting (so, spaces for
>>indentation, then
>> indentation for indicating structure) and currently recognizes the
>>following
>> keywords:
>>
>> property: <name>
>>
>> owner: <string>
>>
>> type: integer |
>> hexadecimal-integer |
>> hexadecimal-address-package |
>> string |
>> <type> <value-list>
>>
>> description: <free text>
>>
>> example: <free text>
>
> This looks good to me in general, although I'd replace "owner" with
>something
> like "submitter" to avoid IP connotations.
Ah. Easily done; "maintainer" was the other thought -- just like in the
kernel, I want to know who to bother when there are problems so that might
be more meaningful than "submitter."
> Also there needs to be a way to connect the properties to the entities
>they are
> supposed to apply to. Like in your example below the "phy-mode"
>property will
> be applicable to NICs, but not necessarily to other types of hardware.
Right. There is, but it was not in the example, and is in the YAML text
file
in the git repo; my bad. So, for a property, one might write:
property: phy-mode
devices:
- generic-nic
- my-specific-nic
...
and for a device, one can write:
device: generic-nic
properties:
- phy-mode
- max-speed
...
The 'dsd add' command will check those and emit warnings when something is
referred to that doesn't exist in the db or in the YAML being added. The
'dsd verify' command checks that the references are complete; i.e., if a
refers to b, then b points back to a, also. This should make it fairly
easy
to check at least some aspects of correctness.
>> For example:
>>
>> property: phy-mode
>> owner: Al Stone <ahs3(a)redhat.com>
>> type: string
>> values:
>> - token: na
>> description: none available
>> - token: mii
>> description: media independent interface (MII)
>> - token: gmii
>> description: gigabit MII
>> - token: sgmii
>> description: serial gigabit MII
>> - token: tbi
>> description: ten bit interface
>> - token: revmii
>> description: reverse MII
>> - token: rmii
>> description: reduced MII
>> - token: rgmii
>> description: reduced gigabit MII (RGMII)
>> - token: rgmii-id
>> description: RGMII with internal delay
>> - token: rgmii-rxid
>> description: RGMII with receive delay only
>> - token: rgmii-txid
>> description: RGMII with transmit delay only
>> - token: rtbi
>> description: reduced ten bit interface
>> - token: smii
>> description: serial MII
>> - token: xgmii
>> description: 10 gigabit MII
>> - token: moca
>> description: multimedia over coax
>> - token: qsgmii
>> description: quad serial gigabit MII
>> description: |
>> Defines the PHY mode to be used for this device.
>> example: |
>> Package (2) { "phy-mode", "xgmii" }
>>
>> Please use '---' to separate device property definitions if several are
>> included in a single file of text (dsd will separate them into unique
>> entries in the "data base").
>>
>
> Thanks,
> Rafael
>
--
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3(a)redhat.com
-----------------------------------
_______________________________________________
DSD mailing list
DSD(a)acpica.org
https://lists.acpica.org/mailman/listinfo/dsd
1:47 a.m.
On 09/07/2015 03:44 PM, Charles Garcia-Tobin wrote:
Hi
I agree with the submitter/maintainer comments from Rafael, but in my head
the model for this is one where there is an agreed set of maintainers at
any one time who own the reviewing process of DSD. Folk that take on this
role would be ones that get contacted when a binding shows problems.
Actually the list in general would presumably be the first port of call.
Relating to that, I do wonder whether the general property that should be
present in every binding is a version. This would cater for some of
Jonathan¹s concerns. Though I agree with Rafael that once a binding goes
into the database it should be supported. We may over long term want to
cater for a deprecation strategy too, emphasis on long term.
I think we're in agreement, actually. There are the maintainers of this
amorphous data base we're creating, but then there are the submitters of
the device properties -- preferably not the same people. And as a practical
matter, I suspect you're right: folks will contact the maintainers first,
who may then try to send them off to a submitter, should there be problems.
My internal thinking over versioning goes something like this:
1. If a binding is in the data base, it needs to be supported. Plain
and simple.
2. Rule #1 implies some sort of clean-up process. In reality, though,
this may be painful, given that we have no idea how long any given
OS will be in use (personally, I have seen 25 year support contracts
for a specific version). Simplistically, if the driver gets
deprecated, so does the binding, and perhaps that is sufficient.
3. If a submitter wants to version a binding, so be it, with proper
oversight by the db maintainers. That is, the formalism allows it,
but the db is controlled by Rule #1, and the details are the domain
of the driver writers.
Finally, a general comment on the dsd tool, which Al, your are gonna
hate
me for. It doesn¹t look very OS agnostic. Ie if I wanted to build it, and
use it, from a windows machine it¹d be a bit of a pain unless you had
cygwin or mingw etc. Wondered whether writing in python, which is way
easier for OS agnostic code and has yaml support, would be better. I am
guessing what your answer is going to be :-)
Cheers
Charles
Hehehe. No worries. It's only code :-).
Yeah, being portable was way down on the list of attributes when I started
to bash this together. I have no objection to Python; I just happened to
be thinking primarily in C at the time. I'll take a look at that -- I've
been trying to think through all of Rafael's suggestions, too, and was
debating bodging together a Python version just for speed of experimentation
sake.
On 28/08/2015 20:28, "DSD on behalf of ahs3(a)redhat.com"
<dsd-bounces(a)acpica.org on behalf of ahs3(a)redhat.com> wrote:
> On 08/27/2015 05:44 PM, Rafael J. Wysocki wrote:
>> Hi,
>>
>> On 8/28/2015 12:05 AM, Al Stone wrote:
>>
>> [cut]
>
> Thanks for the feedback, Rafael.
>
>>> README
>>> ------
>>>
>>> dsd -- a command line tool for _DSD device property registrations
>>> -----------------------------------------------------------------
>>>
>>> A simple 'make' will produce a command line tool to help in the
>>> collection,
>>> registration and maintenance of entries describing the device
>>> properties
>>> allowed via the _DSD method in ACPI [0] -- and in Device Tree (DT).
>>>
>>> The issue is that there is a desire to share device properties not only
>>> across devices (e.g., is more than one "mac-address" really
needed?),
>>> but
>>> between the users of ACPI via _DSD, and possibly the users of Device
>>> Tree
>>> (DT), where the key-value model is used extensively.
>>>
>>> While DT documentation seems to be reasonably well cared for (at least
>>> in
>>> the Linux kernel documentation) and there is a process for maintaining
>>> the
>>> device property definitions, the same is not true of ACPI. In fact,
>>> device
>>> properties as used by _DSD are maintained completely outside of the
>>> specification, and there is no history of maintaining -- or
>>> registering --
>>> them as there is for DT, since this is all relatively new to ACPI.
>>>
>>> However, regardless of its quality, keeping documentatation in the
>>> Linux
>>> kernel does present some problems. For one, firmware developers are
>>> not
>>> likely to look at the Linux source for information on the device
>>> properties
>>> they might want to use or need to define. The OS is not really where
>>> their
>>> focus lies. For two, sharing device properties with the Windows OS
>>> becomes
>>> very difficult; asking Microsoft engineers to go use the Linux source
>>> code
>>> as reference material puts them in an untenable position.
>>>
>>> What this tool -- dsd -- is attempting to do is provide a standard,
>>> neutral
>>> location and format for the definition of these properties, so that
>>> anyone
>>> that needs to can easily get to them, register new ones, or share
>>> existing
>>> properties.
>>>
>>> Each device property is described in YAML (examples below, with
>>> details in
>>> the file called YAML). At present, a directory contains the YAML,
>>> with one
>>> file per device property, one file per device using those properties,
>>> and
>>> acts as a very crude "data base" for all of the entries. The dsd
>>> command
>>> provides several functions for dealing with this "data base" of
device
>>> properties:
>>>
>>> -- initialize the data base
>>> -- verify the YAML is correct
>>> -- add the device property to the data base in a consistent format
>>> -- remove a device property from the data base
>>> -- list all known device property names
>>> -- output the info from a given device property
>>> -- output a basic text description of the property for use in Linux
>>> documentation (or elsewhere)
>>>
>>> Additional functions can be added (all the source is provided), and
>>> should
>>> this project work out, more will be -- for example, summaries of all of
>>> the properties for a given device, or analysis indicating whether or
>>> not
>>> a property is needed and by what devices, or perhaps even more clever
>>> things.
>>>
>>> Building the tool
>>> -----------------
>>> The dsd command requires that libyaml for C be installed [1]. Then,
>>> just
>>> do:
>>>
>>> % make
>>>
>>> There is no install target at present. Run the command:
>>>
>>> % ./dsd help
>>>
>>> to show what options are available.
>>>
>>> YAML
>>> ----
>>> The dsd command uses basic YAML formatting (so, spaces for
>>> indentation, then
>>> indentation for indicating structure) and currently recognizes the
>>> following
>>> keywords:
>>>
>>> property: <name>
>>>
>>> owner: <string>
>>>
>>> type: integer |
>>> hexadecimal-integer |
>>> hexadecimal-address-package |
>>> string |
>>> <type> <value-list>
>>>
>>> description: <free text>
>>>
>>> example: <free text>
>>
>> This looks good to me in general, although I'd replace "owner"
with
>> something
>> like "submitter" to avoid IP connotations.
>
> Ah. Easily done; "maintainer" was the other thought -- just like in the
> kernel, I want to know who to bother when there are problems so that might
> be more meaningful than "submitter."
>
>> Also there needs to be a way to connect the properties to the entities
>> they are
>> supposed to apply to. Like in your example below the "phy-mode"
>> property will
>> be applicable to NICs, but not necessarily to other types of hardware.
>
> Right. There is, but it was not in the example, and is in the YAML text
> file
> in the git repo; my bad. So, for a property, one might write:
>
> property: phy-mode
> devices:
> - generic-nic
> - my-specific-nic
> ...
>
>
> and for a device, one can write:
>
> device: generic-nic
> properties:
> - phy-mode
> - max-speed
> ...
>
> The 'dsd add' command will check those and emit warnings when something is
> referred to that doesn't exist in the db or in the YAML being added. The
> 'dsd verify' command checks that the references are complete; i.e., if a
> refers to b, then b points back to a, also. This should make it fairly
> easy
> to check at least some aspects of correctness.
>
>
>>> For example:
>>>
>>> property: phy-mode
>>> owner: Al Stone <ahs3(a)redhat.com>
>>> type: string
>>> values:
>>> - token: na
>>> description: none available
>>> - token: mii
>>> description: media independent interface (MII)
>>> - token: gmii
>>> description: gigabit MII
>>> - token: sgmii
>>> description: serial gigabit MII
>>> - token: tbi
>>> description: ten bit interface
>>> - token: revmii
>>> description: reverse MII
>>> - token: rmii
>>> description: reduced MII
>>> - token: rgmii
>>> description: reduced gigabit MII (RGMII)
>>> - token: rgmii-id
>>> description: RGMII with internal delay
>>> - token: rgmii-rxid
>>> description: RGMII with receive delay only
>>> - token: rgmii-txid
>>> description: RGMII with transmit delay only
>>> - token: rtbi
>>> description: reduced ten bit interface
>>> - token: smii
>>> description: serial MII
>>> - token: xgmii
>>> description: 10 gigabit MII
>>> - token: moca
>>> description: multimedia over coax
>>> - token: qsgmii
>>> description: quad serial gigabit MII
>>> description: |
>>> Defines the PHY mode to be used for this device.
>>> example: |
>>> Package (2) { "phy-mode", "xgmii" }
>>>
>>> Please use '---' to separate device property definitions if several
are
>>> included in a single file of text (dsd will separate them into unique
>>> entries in the "data base").
>>>
>>
>> Thanks,
>> Rafael
>>
>
>
> --
> ciao,
> al
> -----------------------------------
> Al Stone
> Software Engineer
> Red Hat, Inc.
> ahs3(a)redhat.com
> -----------------------------------
> _______________________________________________
> DSD mailing list
> DSD(a)acpica.org
> https://lists.acpica.org/mailman/listinfo/dsd
>
--
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3(a)redhat.com
-----------------------------------
2566
days inactive
2579
days old
11 comments
3 participants
participants (3)
-
Al Stone -
Charles Garcia-Tobin -
Rafael J. Wysocki