September 2015 - DSD - Ml01.01.Org

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, 4 months

5
7
0 / 0

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, 8 months

1
0
0 / 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 -----------------------------------

5 years, 9 months

3
11
0 / 0

2021

2020

2019

2018

2017

2016

2015

DSD September 2015