_DSD (Device Specific Data) Implementation Guide

 

 

October 2018

 

Revision 1.2

 

 

 

The material contained herein is not a license, either expressly or impliedly, to any intellectual property owned or controlled by any of the authors or developers of this material or to any contribution thereto. The material contained herein is provided on an "AS IS" basis and, to the maximum extent permitted by applicable law, this information is provided AS IS AND WITH ALL FAULTS, and the authors and developers of this material hereby disclaim all other warranties and conditions, either express, implied or statutory, including, but not limited to, any (if any) implied warranties, duties or conditions of merchantability, of fitness for a particular purpose, of accuracy or completeness of responses, of results, of workmanlike effort, of lack of viruses and of lack of negligence, all with regard to this material and any contribution thereto. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." The Unified EFI Forum, Inc. reserves any features or instructions so marked for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. ALSO, THERE IS NO WARRANTY OR CONDITION OF TITLE, QUIET ENJOYMENT, QUIET POSSESSION, CORRESPONDENCE TO DESCRIPTION OR NON-INFRINGEMENT WITH REGARD TO THE SPECIFICATION AND ANY CONTRIBUTION THERETO.

IN NO EVENT WILL ANY AUTHOR OR DEVELOPER OF THIS MATERIAL OR ANY CONTRIBUTION THERETO BE LIABLE TO ANY OTHER PARTY FOR THE COST OF PROCURING SUBSTITUTE GOODS OR SERVICES, LOST PROFITS, LOSS OF USE, LOSS OF DATA, OR ANY INCIDENTAL, CONSEQUENTIAL, DIRECT, INDIRECT, OR SPECIAL DAMAGES WHETHER UNDER CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING IN ANY WAY OUT OF THIS OR ANY OTHER AGREEMENT RELATING TO THIS DOCUMENT, WHETHER OR NOT SUCH PARTY HAD ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.

 

Copyright 2018 Unified EFI, Inc. All Rights Reserved.

 

 

image

Table of Contents

1.     Introduction. 2

1.     Terms. 2

2.     Conventions used in this document. 3

1.2.1 Typographic conventions. 3

2.     General Recommendations. 3

1.     _DSD and _DSM... 3

2.     General _DSD Definition Template. 4

3.     Well Known _DSD UUIDs and Data Structure Formats. 4

1.     Device Properties UUID.. 4

2.     Hierarchical Properties Extension UUID.. 5

3.     Device Graphs UUID.. 5

 

 

 

 

image

 

 

Description

Revision Date

First revision

July 16, 2014

New Section 3.2 Hierarchical Properties Extension UUID

August 8, 2015

 

New Section 3.3 For _DSD graphs

October 26, 2018

 

 

§ Document Number: XXXXXX

 

image

 

This document gives recommendations on the use of the _DSD (Device Specific Data) ACPI device configuration object. It is intended for firmware and software engineers implementing _DSD or designing software that will use information supplied by it.

 

The _DSD, as defined by the ACPI Specification, returns a Package the first and every odd element of which is a Universal Unique Identifier (UUID) and every even element of which is a Package (Data Structure), where each of the UUIDs determines the format of the Data Structure immediately following it. The well-known UUIDs to use in the _DSD output and the Data Structure formats associated with them are also specified in this document.

 

1.      Introduction

 

image

This document gives recommendations on the use of the _DSD (Device Specific Data) ACPI device configuration object. It is intended for firmware and software engineers implementing _DSD or designing software that will use information supplied by it.

 

The _DSD, as defined by the ACPI Specification, returns a Package the first and every odd element of which is a Universal Unique Identifier (UUID) and every even element of which is a Package (Data Structure), where each of the UUIDs determines the format of the Data Structure immediately following it. The well-known UUIDs to use in the _DSD output and the Data Structure formats associated with them are also specified in this document.

 

1.        Terms

The following terms are used throughout this document to describe varying aspects of input localization:

ACPI

Advanced Configuration and Power Interface specification.

Device

Hardware component or set of interrelated hardware registers.

Device ID

Plug and Play ID or ACPI ID of a device.

GUID

Globally Unique Identifier. A 128-bit value used to uniquely name entities. A unique GUID can be generated by an individual without the help of a centralized authority. This allows the generation of names that will never conflict, even among multiple, unrelated parties.

UUID

Universal Unique Identifier, GUID.

 

 

2.        Conventions used in this document

 

1.2.1 Typographic conventions

  This document uses the typographic and illustrative conventions described below:

 

Plain text

The normal text typeface is used for the vast majority of the descriptive text in a specification.

BOLD Monospace

Computer code, example code segments, and all prototype code segments use a BOLD Monospace typeface with a dark red color.  These code listings normally appear in one or more separate paragraphs, though words or segments can also be embedded in a normal text paragraph.

 

image

 

2.      General Recommendations

image

1.  _DSD and _DSM

Although in principle _DSM (Device Specific Method) may be used to implement the functionality provided by _DSD, it is not recommended to do so. Since _DSD is better suited for providing device configuration data, it should be used for this purpose where applicable. However, there are situations in which where using _DSM instead of it _DSD needs to be considered. Generally, all situations in which it would be necessary to implement _DSD as a method for technical reasons fall into this category, but in particular _DSD should not write into device registers in addition to returning the data. In addition to that, _DSD must return the same data every time it is evaluated, so if that cannot be guaranteed, _DSM has to be used instead of it.

 

2.        General _DSD Definition Template

Wherever possible, it is recommended to implement _DSD as a Name, as opposed to a Method, so as to avoid programmatic errors and computational overhead associated with the execution of AML code. In that case the definition of _DSD should follow the common template below.

 

Name (_DSD, Package () { ToUUID("UUID1"),

Package () {

...

}, ToUUID("UUID2"),

Package () {

...

},

...

ToUUID("UUIDn"),

Package () {

...

}

})

 

image

 

3.      Well Known _DSD UUIDs and Data Structure Formats

 

image

1.        Device Properties UUID

http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf

 

2.        Hierarchical Properties Extension UUID

http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf

3.        Device Graphs UUID

http://www.uefi.org/sites/default/files/resources/Device%20graphs%20UUID%20v6%20final.pdf