lib/intel_io: api documentation

As usual de-inline functions for gtkdoc to see them.

I've decided to exclude the register map stuff since that's not
terribly interesting.

Aside: gtkdoc falls over when the title of a section contains a slash,
hence why it reads "IO" instead of "I/O". The fun ...

Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

3 files changed, 185 insertions, 16 deletions

diff --git a/lib/intel_io.h b/lib/intel_io.h
index 5ea50cab..d56d061d 100644
--- a/lib/intel_io.h
+++ b/lib/intel_io.h
@@ -34,7 +34,7 @@
 /* register access helpers from intel_mmio.c */
 extern void *mmio;
 void intel_mmio_use_pci_bar(struct pci_device *pci_dev);
-void intel_mmio_use_dump_file(char *);
+void intel_mmio_use_dump_file(char *file);
 
 int intel_register_access_init(struct pci_device *pci_dev, int safe);
 void intel_register_access_fini(void);
@@ -42,17 +42,8 @@ uint32_t intel_register_read(uint32_t reg);
 void intel_register_write(uint32_t reg, uint32_t val);
 int intel_register_access_needs_fakewake(void);
 
-static inline uint32_t
-INREG(uint32_t reg)
-{
-	return *(volatile uint32_t *)((volatile char *)mmio + reg);
-}
-
-static inline void
-OUTREG(uint32_t reg, uint32_t val)
-{
-	*(volatile uint32_t *)((volatile char *)mmio + reg) = val;
-}
+uint32_t INREG(uint32_t reg);
+void OUTREG(uint32_t reg, uint32_t val);
 
 /* sideband access functions from intel_iosf.c */
 uint32_t intel_dpio_reg_read(uint32_t reg, int phy);
@@ -64,6 +55,8 @@ int intel_nc_read(uint8_t addr, uint32_t *val);
 int intel_nc_write(uint8_t addr, uint32_t val);
 
 /* register maps from intel_reg_map.c */
+#ifndef __GTK_DOC_IGNORE__
+
 #define INTEL_RANGE_RSVD	(0<<0) /*  Shouldn't be read or written */
 #define INTEL_RANGE_READ	(1<<0)
 #define INTEL_RANGE_WRITE	(1<<1)
@@ -83,5 +76,6 @@ struct intel_register_map {
 };
 struct intel_register_map intel_get_register_map(uint32_t devid);
 struct intel_register_range *intel_get_register_range(struct intel_register_map map, uint32_t offset, uint32_t mode);
+#endif /* __GTK_DOC_IGNORE__ */
 
 #endif /* INTEL_GPU_TOOLS_H */
diff --git a/lib/intel_iosf.c b/lib/intel_iosf.c
index ea7a320a..7e251599 100644
--- a/lib/intel_iosf.c
+++ b/lib/intel_iosf.c
@@ -55,26 +55,76 @@ static int vlv_sideband_rw(uint32_t port, uint8_t opcode, uint32_t addr,
 	return 0;
 }
 
+/**
+ * intel_punit_read:
+ * @addr: register offset
+ * @val: pointer to starge for the read result
+ *
+ * 32-bit read of the register at @offset through the P-Unit sideband port.
+ *
+ * Returns:
+ * 0 when the register access succeeded, negative errno code on failure.
+ */
 int intel_punit_read(uint8_t addr, uint32_t *val)
 {
 	return vlv_sideband_rw(IOSF_PORT_PUNIT, PUNIT_OPCODE_REG_READ, addr, val);
 }
 
+/**
+ * intel_punit_write:
+ * @addr: register offset
+ * @val: value to write
+ *
+ * 32-bit write of the register at @offset through the P-Unit sideband port.
+ *
+ * Returns:
+ * 0 when the register access succeeded, negative errno code on failure.
+ */
 int intel_punit_write(uint8_t addr, uint32_t val)
 {
 	return vlv_sideband_rw(IOSF_PORT_PUNIT, PUNIT_OPCODE_REG_WRITE, addr, &val);
 }
 
+/**
+ * intel_nc_read:
+ * @addr: register offset
+ * @val: pointer to starge for the read result
+ *
+ * 32-bit read of the register at @offset through the NC sideband port.
+ *
+ * Returns:
+ * 0 when the register access succeeded, negative errno code on failure.
+ */
 int intel_nc_read(uint8_t addr, uint32_t *val)
 {
 	return vlv_sideband_rw(IOSF_PORT_NC, PUNIT_OPCODE_REG_READ, addr, val);
 }
 
+/**
+ * intel_nc_write:
+ * @addr: register offset
+ * @val: value to write
+ *
+ * 32-bit write of the register at @offset through the NC sideband port.
+ *
+ * Returns:
+ * 0 when the register access succeeded, negative errno code on failure.
+ */
 int intel_nc_write(uint8_t addr, uint32_t val)
 {
 	return vlv_sideband_rw(IOSF_PORT_NC, PUNIT_OPCODE_REG_WRITE, addr, &val);
 }
 
+/**
+ * intel_dpio_reg_read:
+ * @reg: register offset
+ * @phy: DPIO PHY to use
+ *
+ * 32-bit read of the register at @offset through the DPIO sideband port.
+ *
+ * Returns:
+ * The value read from the register.
+ */
 uint32_t intel_dpio_reg_read(uint32_t reg, int phy)
 {
 	uint32_t val;
@@ -83,6 +133,14 @@ uint32_t intel_dpio_reg_read(uint32_t reg, int phy)
 	return val;
 }
 
+/**
+ * intel_dpio_reg_write:
+ * @reg: register offset
+ * @val: value to write
+ * @phy: dpio PHY to use
+ *
+ * 32-bit write of the register at @offset through the DPIO sideband port.
+ */
 void intel_dpio_reg_write(uint32_t reg, uint32_t val, int phy)
 {
 	vlv_sideband_rw(IOSF_PORT_DPIO, DPIO_OPCODE_REG_WRITE, reg, &val);
diff --git a/lib/intel_mmio.c b/lib/intel_mmio.c
index 97eee560..6666b9e7 100644
--- a/lib/intel_mmio.c
+++ b/lib/intel_mmio.c
@@ -45,8 +45,30 @@
 #include "igt_debugfs.h"
 #include "intel_chipset.h"
 
+/**
+ * SECTION:intel_io
+ * @short_description: Register access and sideband I/O libraray
+ * @title: intel io
+ *
+ * > #include "intel_io.h"
+ *
+ * This library provides register I/O helpers in both a basic version and a more
+ * fancy version which also handles forcewak and can optionally check registers
+ * against a white-list. All register function are compatible. Hence the same
+ * code can be used to decode registers with either of them, or also from a dump
+ * file using intel_mmio_use_dump_file().
+ *
+ * Futhermore this library also provides helper functions for accessing the
+ * various sideband interfaces found on Valleyview/Baytrail based platforms.
+ */
+
 #define FAKEKEY 0x2468ace0
 
+/**
+ * mmio:
+ *
+ * Pointer to the register range. It is not recommended to use this directly.
+ */
 void *mmio;
 
 static struct _mmio_data {
@@ -57,6 +79,14 @@ static struct _mmio_data {
 	int key;
 } mmio_data;
 
+/**
+ * intel_mmio_use_dump_file:
+ * @file: name of the register dump file to open
+ *
+ * Sets up #mmio to point at the data contained in @file. This allows the same
+ * code to get reused for dumping and decoding from running hardwared as from
+ * register dumps.
+ */
 void
 intel_mmio_use_dump_file(char *file)
 {
@@ -79,6 +109,16 @@ intel_mmio_use_dump_file(char *file)
 	close(fd);
 }
 
+/**
+ * intel_mmio_use_pci_bar:
+ * @pci_dev: intel gracphis pci device
+ *
+ * Sets up #mmio to point at the data contained in @file. This allows the same
+ * code to get reused for dumping and decoding from running hardwared as from
+ * register dumps.
+ *
+ * @pci_dev can be obtained from intel_get_pci_device().
+ */
 void
 intel_mmio_use_pci_bar(struct pci_device *pci_dev)
 {
@@ -119,11 +159,18 @@ release_forcewake_lock(int fd)
 	close(fd);
 }
 
-/*
- * Initialize register access library.
- *
- * @pci_dev: pci device we're mucking with
+/**
+ * intel_register_access_init:
+ * @pci_dev: intel gracphis pci device
  * @safe: use safe register access tables
+ *
+ * This initializes the new register access library, which supports forcewake
+ * handling and also allows register access to be checked with an explicit
+ * whitelist.
+ *
+ * It also initializes #mmio like intel_mmio_use_pci_bar().
+ *
+ * @pci_dev can be obtained from intel_get_pci_device().
  */
 int
 intel_register_access_init(struct pci_device *pci_dev, int safe)
@@ -157,17 +204,30 @@ intel_register_access_init(struct pci_device *pci_dev, int safe)
 	mmio_data.inited++;
 	return 0;
 }
+
 static int
 intel_register_access_needs_wake(void)
 {
 	return mmio_data.key != FAKEKEY;
 }
 
+/**
+ * intel_register_access_needs_fakewake:
+ *
+ * Returns:
+ * Non-zero when forcewake initialization failed.
+ */
 int intel_register_access_needs_fakewake(void)
 {
 	return mmio_data.key == FAKEKEY;
 }
 
+/**
+ * intel_register_access_fini:
+ *
+ * Clean up the register access helper initialized with
+ * intel_register_access_init().
+ */
 void
 intel_register_access_fini(void)
 {
@@ -176,6 +236,19 @@ intel_register_access_fini(void)
 	mmio_data.inited--;
 }
 
+/**
+ * intel_register_read:
+ * @reg: register offset
+ *
+ * 32-bit read of the register at @offset. This function only works when the new
+ * register access helper is initialized with intel_register_access_init().
+ *
+ * Compared to INREG() it can do optional checking with the register access
+ * white lists.
+ *
+ * Returns:
+ * The value read from the register.
+ */
 uint32_t
 intel_register_read(uint32_t reg)
 {
@@ -207,6 +280,17 @@ out:
 	return ret;
 }
 
+/**
+ * intel_register_write:
+ * @reg: register offset
+ * @val: value to write
+ *
+ * 32-bit write to the register at @offset. This function only works when the new
+ * register access helper is initialized with intel_register_access_init().
+ *
+ * Compared to OUTRET() it can do optional checking with the register access
+ * white lists.
+ */
 void
 intel_register_write(uint32_t reg, uint32_t val)
 {
@@ -232,3 +316,36 @@ intel_register_write(uint32_t reg, uint32_t val)
 write_out:
 	*(volatile uint32_t *)((volatile char *)mmio + reg) = val;
 }
+
+
+/**
+ * INREG:
+ * @reg: register offset
+ *
+ * 32-bit read of the register at @offset. This function only works when the new
+ * register access helper is initialized with intel_register_access_init().
+ *
+ * This function directly accesses the #mmio without safety checks.
+ *
+ * Returns:
+ * The value read from the register.
+ */
+uint32_t INREG(uint32_t reg)
+{
+	return *(volatile uint32_t *)((volatile char *)mmio + reg);
+}
+
+/**
+ * OUTRET:
+ * @reg: register offset
+ * @val: value to write
+ *
+ * 32-bit write to the register at @offset. This function only works when the new
+ * register access helper is initialized with intel_register_access_init().
+ *
+ * This function directly accesses the #mmio without safety checks.
+ */
+void OUTREG(uint32_t reg, uint32_t val)
+{
+	*(volatile uint32_t *)((volatile char *)mmio + reg) = val;
+}