From: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
Date: Sun, 21 Jan 2024 13:44:36 +0000 (+0100)
Subject: acpi: document HETP table
X-Git-Url: http://git.dujemihanovic.xyz/?a=commitdiff_plain;h=23f128f55bf9ded7bed136f9b32f81eeacbb9f36;p=u-boot.git

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 8256af6d29..954e3e9503 100644
--- 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 {