acpi: document HETP table

Document struct acpi_gen_regaddr and struct acpi_hpet.

Sphinx requires that the __packed attribute is at the end of the structure
definitions.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>

diff --git a/include/acpi/acpi_table.h b/include/acpi/acpi_table.h
index 8256af6d29e5f620918bfa5ffc4c5b2e1d76ac50..954e3e9503738401eeb3e9ed46c113ef25cfb855 100644 (file)
--- a/include/acpi/acpi_table.h
+++ b/include/acpi/acpi_table.h
@@ -61,13 +61,37 @@ struct __packed acpi_table_header {
        u32 creator_revision;   /* ASL compiler revision number */
 };
 
+/**
+ * struct acpi_gen_regaddr - generic address structure (GAS)
+ */
 struct acpi_gen_regaddr {
-       u8 space_id;    /* Address space ID */
-       u8 bit_width;   /* Register size in bits */
-       u8 bit_offset;  /* Register bit offset */
-       u8 access_size; /* Access size */
-       u32 addrl;      /* Register address, low 32 bits */
-       u32 addrh;      /* Register address, high 32 bits */
+       /**
+        * @space_id: address space ID
+        *
+        * See table "Operation Region Address Space Identifiers" in the ACPI
+        * specification.
+        */
+       u8 space_id;
+       /** @bit_width: size in bits of the register */
+       u8 bit_width;
+       /** @bit_offset: bit offset of the register */
+       u8 bit_offset;
+       /**
+        * @access_size: access size
+        *
+        * * 0 - undefined
+        * * 1 - byte access
+        * * 2 - word (2 bytes) access
+        * * 3 - Dword (4 bytes) access
+        * * 4 - Qword (8 bytes) access
+        *
+        * See ACPI_ACCESS_SIZE_*_ACCESS macros.
+        */
+       u8 access_size;
+       /** @addrl: register address, low 32 bits */
+       u32 addrl;
+       /** @addrh: register address, high 32 bits */
+       u32 addrh;
 };
 
 /* A maximum number of 32 ACPI tables ought to be enough for now */
@@ -85,15 +109,26 @@ struct __packed acpi_xsdt {
        u64 entry[MAX_ACPI_TABLES];
 };
 
-/* HPET timers */
-struct __packed acpi_hpet {
+/**
+ * struct acpi_hpet: High Precision Event Timers (HETP)
+ *
+ * The structure is defined in the
+ * "IA-PC HPET (High Precision Event Timers) Specification", rev 1.0a, Oct 2004
+ */
+struct acpi_hpet {
+       /** @header: table header */
        struct acpi_table_header header;
+       /** @id hardware ID of Event Timer Block */
        u32 id;
+       /** @addr: address of Event Timer Block */
        struct acpi_gen_regaddr addr;
+       /** @number: HPET sequence number */
        u8 number;
+       /** @min_tick: minimum clock ticks without lost interrupts */
        u16 min_tick;
+       /** @attributes: page protection and OEM atttribute */
        u8 attributes;
-};
+} __packed;
 
 struct __packed acpi_tpm2 {
        struct acpi_table_header header;
@@ -364,7 +399,7 @@ enum {
  * This holds information about the Generic Interrupt Controller (GIC) CPU
  * interface. See ACPI Spec v6.3 section 5.2.12.14
  */
-struct __packed acpi_madr_gicc {
+struct acpi_madr_gicc {
        u8 type;
        u8 length;
        u16 reserved;
@@ -383,7 +418,7 @@ struct __packed acpi_madr_gicc {
        u8 efficiency;
        u8 reserved2;
        u16 spi_overflow_irq;
-};
+} __packed;
 
 /**
  * struct __packed acpi_madr_gicc - GIC distributor (type 0xc)
@@ -391,7 +426,7 @@ struct __packed acpi_madr_gicc {
  * This holds information about the Generic Interrupt Controller (GIC)
  * Distributor interface. See ACPI Spec v6.3 section 5.2.12.15
  */
-struct __packed acpi_madr_gicd {
+struct acpi_madr_gicd {
        u8 type;
        u8 length;
        u16 reserved;
@@ -400,7 +435,7 @@ struct __packed acpi_madr_gicd {
        u32 reserved2;
        u8 gic_version;
        u8 reserved3[3];
-};
+} __packed;
 
 /* MCFG (PCI Express MMIO config space BAR description table) */
 struct acpi_mcfg {
@@ -653,7 +688,7 @@ struct __packed acpi_spcr {
  *
  * See ACPI Spec v6.3 section 5.2.24 for details
  */
-struct __packed acpi_gtdt {
+struct acpi_gtdt {
        struct acpi_table_header header;
        u64 cnt_ctrl_base;
        u32 reserved0;
@@ -670,7 +705,7 @@ struct __packed acpi_gtdt {
        u32 plat_timer_offset;
        u32 virt_el2_gsiv;
        u32 virt_el2_flags;
-};
+} __packed;
 
 /**
  * struct acpi_bgrt -  Boot Graphics Resource Table (BGRT)
@@ -680,7 +715,7 @@ struct __packed acpi_gtdt {
  *
  * See ACPI Spec v6.3 section 5.2.22 for details
  */
-struct __packed acpi_bgrt {
+struct acpi_bgrt {
        struct acpi_table_header header;
        u16 version;
        u8 status;
@@ -688,7 +723,7 @@ struct __packed acpi_bgrt {
        u64 addr;
        u32 offset_x;
        u32 offset_y;
-};
+} __packed;
 
 /* Types for PPTT */
 #define ACPI_PPTT_TYPE_PROC            0
@@ -709,22 +744,22 @@ struct __packed acpi_bgrt {
  *
  * See ACPI Spec v6.3 section 5.2.29 for details
  */
-struct __packed acpi_pptt_header {
+struct acpi_pptt_header {
        u8 type;        /* ACPI_PPTT_TYPE_... */
        u8 length;
        u16 reserved;
-};
+} __packed;
 
 /**
  * struct acpi_pptt_proc - a processor as described by PPTT
  */
-struct __packed acpi_pptt_proc {
+struct acpi_pptt_proc {
        struct acpi_pptt_header hdr;
        u32 flags;
        u32 parent;
        u32 proc_id;
        u32 num_resources;
-};
+} __packed;
 
 /* Cache flags for acpi_pptt_cache */
 #define ACPI_PPTT_SIZE_VALID           BIT(0)
@@ -751,7 +786,7 @@ struct __packed acpi_pptt_proc {
 /**
  * struct acpi_pptt_cache - a cache as described by PPTT
  */
-struct __packed acpi_pptt_cache {
+struct acpi_pptt_cache {
        struct acpi_pptt_header hdr;
        u32 flags;
        u32 next_cache_level;
@@ -760,7 +795,7 @@ struct __packed acpi_pptt_cache {
        u8 assoc;
        u8 attributes;
        u16 line_size;
-};
+} __packed;
 
 /* Tables defined/reserved by ACPI and generated by U-Boot */
 enum acpi_tables {