Rules for what you can and can't do with _DSD
by Charles Garcia-Tobin
Hi all
Last week at the ASWG conference call I took the action of defining some
ground rules for _DSD submissions. I have drafted some up here. I¹d be
grateful to know your thoughts.
Cheers
Charles
Introduction
============
The following provides rules for the process of submitting _DSD
properties. This process must be followed by vendors wishing to see their
drivers supported by OS vendors that support ACPI.
What properties can be described by _DSD
========================================
_DSD stands for device specific data, it is an object in ACPI that may be
associated with a device to describe specific device properties that are
not covered by other mechanisms in the ACPI specification. An example may
be a mac address, or phy for an networking device.
What properties must not be described by _DSD
=============================================
_DSD must only be used to describe properties that are specific to a
device, rather than properties of the system as whole. i.e. Generic
properties that are required by generic kernel frameworks must not be
described with _DSD.
_DSD must not be used to describe properties that are already covered in
the ACPI specification.
For a system described with ACPI, it must not a requirement that any of
the following areas need and OS to evaluate _DSD in order to work:
- Support dynamic device configurations (hot add/removal)
- Support hardware abstraction through control methods
- power management
- thermal management
- RAS interfaces
_DSD must not be used to describe properties that are specific to an
operating system. For example properties with OS names in the key
would not allowed.
Submitting a binding
====================
<Insert previous mails from Al Stone on the dsd too and dsd(a)acpica.org>
Becoming a reviewer
===================
Anybody who is member of the dsd(a)acpica.org can be a reviewer.
Becoming a maintainer
=====================
_DSD maintainership is a meritocracy. The process is:
1. You submit a request dsd(a)acpica.org to become maintainer
2. Existing maintainers take a view on teh merit of the request based
on the track record of the person making the request in:
2.1 OS verndors. Eg FreeBSD, RH, or Windows may propose a maintainer
2.2 Existing FW representation technologies: ie person is a known
ACPI contributor or Device Tree contributor or maintainer
<< Other stuff to eventually include >>
========================================
Dsd tool stuff from Al, Rules on what properties look like from Rafael
-- IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
ARM Limited, Registered office 110 Fulbourn Road, Cambridge CB1 9NJ, Registered in England & Wales, Company No: 2557590
ARM Holdings plc, Registered office 110 Fulbourn Road, Cambridge CB1 9NJ, Registered in England & Wales, Company No: 2548782
5 years, 8 months
- 5
- 7
DSD v2
by Charles Garcia-Tobin
Hi all
Sorry it¹s taken a while but here is second version of the DSD process and
rules. Hopefully it has all the feedback incorporated. Thanks to those
that reviewed it. There is also a TODO list that we need to get in place
to get this going:
TODO:
1. Fold these rules into dsd github from Al
2. Provide pointers to these rules in the ACPI documentation:
http://www.uefi.org/sites/default/files/resources/_DSD-device-properti\
es-UUID.pdf
In the same breath use this effort to fix the examples there to remove
linux references
3. Provide pointers to these rules in kernel documentation (for all
kernels that will support _DSD)
4. Retroactively apply the process to the few _DSD instances that have
been created
5. Expand this process to add device specific _OSC
Figured I¹d write this down so we know what we have left to do. Please add
other things in there if you think I missed something out. I guess Al and
I will take most of it on.
Txt for process is below
Cheers
Charles
Introduction
============
This document provides rules that apply to the to the usage of the
Device Properties _DSD, which is covered by the following UUID:
* daffd814-6eba-4d8c-8a91-bc9bbf4aa301
The Device Properties _DSD is described here:
[1]
http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UU
ID.pdf
The rules should be followed by vendors wishing to see drivers that
use the Device Properties _DSD supported by ACPI compliant OS vendors.
What properties can be described by _DSD
========================================
_DSD stands for Device Specific Data. The Device Properties _DSD is an
object in ACPI that may be associated with a device to provide the
Operating System with information on the device and its configuration
that cannot be represented in any other way, in accordance with the
ACPI specification. It is regarded as invalid to use the information
from _DSD instead of the existing ACPI mechanisms. Therefore _DSD may
only be used in addition to existing ACPI mechanisms. An example may a
MAC address, or PHY for a networking device.
What properties must not be described by _DSD
=============================================
As described in [1] the Device Properties _DSD must only be used to
describe properties that are specific to a device, rather than
properties of the system as whole. For this reason, the definition of
each particular set of _DSD properties is only meaningful in
association with a device ID. The interpretation of any _DSD
properties that cannot be related to a specific device ID is
essentially impossible in general and therefore it is invalid to use them.
As described in [1] the Device Properties _DSD must not be used to
provide the OSPM or drivers the same information that is provided by
the _CRS object. Further, the existing interfaces provided to
Operating Systems by the ACPI specification should still work, and not
require
additional parsing of _DSD objects, and therefore kernel changes, in
order to operate correctly. Examples include:
- Support dynamic device configurations (hot add/removal)
- Support hardware abstraction through control methods
- power management
- thermal management
- RAS interfaces
By corollary the Device Properties _DSD should never be used to
describe information that can be described by existing ACPI
methodologies. For example: voltage regulators or clocks that may need
to be turned on or off to manage the power of a device, should use
existing power resource _ON/_OFF methods, or device _PSx methods,
instead of _DSD.
Submitting a binding
====================
<Insert previous mails from Al Stone on the dsd too and dsd(a)acpica.org>
Becoming a reviewer
===================
Anybody who is member of the dsd(a)acpica.org can be a reviewer.
Becoming a maintainer
=====================
The process is for becoming a _DSD maintainer is as follows:
1. You submit a request dsd(a)acpica.org to become maintainer
2. Existing maintainers take a view on the merit of the request based
on the track record of the person making the request in:
2.1 OS verndors. E.g. FreeBSD, RH, or Windows may propose a maintainer
2.2 Existing FW representation technologies: e.g. person is a known
ACPI contributor or Device Tree contributor or maintainer
-- IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
ARM Limited, Registered office 110 Fulbourn Road, Cambridge CB1 9NJ, Registered in England & Wales, Company No: 2557590
ARM Holdings plc, Registered office 110 Fulbourn Road, Cambridge CB1 9NJ, Registered in England & Wales, Company No: 2548782
5 years, 12 months
- 1
- 0
[RFC] Formalizing the description of device properties
by Al Stone
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
-----------------------------------
6 years
- 3
- 11
- ← Newer
- 1
- Older →