[Intel-gfx] [PATCH 04/28] lib/intel_chipset: api docs

[Daniel Vetter]

Unfortunately gtkdoc doesn't pick up the intel_pch enum.

Signed-off-by: Daniel Vetter <daniel.vetter at ffwll.ch>
---
 lib/intel_chipset.c | 50 +++++++++++++++++++++++++++++++++++++++++++++++++-
 lib/intel_chipset.h |  5 +++++
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/lib/intel_chipset.c b/lib/intel_chipset.c
index 8c440cc9c8ba..5ac90d1b8ed2 100644
--- a/lib/intel_chipset.c
+++ b/lib/intel_chipset.c
@@ -40,8 +40,32 @@
 
 #include "intel_chipset.h"
 
+/**
+ * SECTION:intel_chipset
+ * @short_description: Feature macros and chipset helpers
+ * @title: intel chipset
+ *
+ * This library mostly provides feature macros which use raw pci device ids. It
+ * also provides a few more helper functions to handle pci devices, chipset
+ * detection and related issues.
+ */
+
+/**
+ * intel_pch:
+ *
+ * Global variable to keep track of the pch type. Can either be set manually or
+ * detected at runtime with intel_check_pch().
+ */
 enum pch_type intel_pch;
 
+/**
+ * intel_get_pci_device:
+ *
+ * Looks up the main graphics pci device using libpciaccess.
+ *
+ * Returns:
+ * The pci_device, exits the program on any failures.
+ */
 struct pci_device *
 intel_get_pci_device(void)
 {
@@ -92,6 +116,16 @@ intel_get_pci_device(void)
 	return pci_dev;
 }
 
+/**
+ * intel_get_drm_devid:
+ * @fd: open i915 drm file descriptor
+ *
+ * Queries the kernel for the pci device id corresponding to the drm file
+ * descriptor.
+ *
+ * Returns:
+ * The devid, exits the program on any failures.
+ */
 uint32_t
 intel_get_drm_devid(int fd)
 {
@@ -114,6 +148,15 @@ intel_get_drm_devid(int fd)
 	return devid;
 }
 
+/**
+ * intel_gen:
+ * @devid: pci device id
+ *
+ * Computes the Intel GFX generation for the give device id.
+ *
+ * Returns:
+ * The GFX generation on successful lookup, -1 on failure.
+ */
 int intel_gen(uint32_t devid)
 {
 	if (IS_GEN2(devid))
@@ -134,6 +177,12 @@ int intel_gen(uint32_t devid)
 	return -1;
 }
 
+/**
+ * intel_check_pch:
+ *
+ * Detects the PCH chipset type of the running systems and fills in the results
+ * into the global #intel_pch varaible.
+ */
 void
 intel_check_pch(void)
 {
@@ -163,4 +212,3 @@ intel_check_pch(void)
 		return;
 	}
 }
-
diff --git a/lib/intel_chipset.h b/lib/intel_chipset.h
index 24dfe9455663..2f3077881dd4 100644
--- a/lib/intel_chipset.h
+++ b/lib/intel_chipset.h
@@ -49,6 +49,9 @@ void intel_check_pch(void);
 #define HAS_CPT (intel_pch == PCH_CPT)
 #define HAS_LPT (intel_pch == PCH_LPT)
 
+/* Exclude chipset #defines, they just add noise */
+#ifndef __GTK_DOC_IGNORE__
+
 #define PCI_CHIP_I810			0x7121
 #define PCI_CHIP_I810_DC100		0x7123
 #define PCI_CHIP_I810_E			0x7125
@@ -181,6 +184,8 @@ void intel_check_pch(void);
 #define PCI_CHIP_VALLEYVIEW_2		0x0f32
 #define PCI_CHIP_VALLEYVIEW_3		0x0f33
 
+#endif /* __GTK_DOC_IGNORE__ */
+
 #define IS_MOBILE(devid)	((devid) == PCI_CHIP_I855_GM || \
 				 (devid) == PCI_CHIP_I915_GM || \
 				 (devid) == PCI_CHIP_I945_GM || \
-- 
1.8.5.2