[Intel-gfx] [PATCH 21/28] lib/intel_io: api documentation
Daniel Vetter
daniel.vetter at ffwll.ch
Sun Mar 23 15:18:55 CET 2014
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 at ffwll.ch>
---
lib/intel_io.h | 18 +++-----
lib/intel_iosf.c | 58 ++++++++++++++++++++++++++
lib/intel_mmio.c | 125 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
3 files changed, 185 insertions(+), 16 deletions(-)
diff --git a/lib/intel_io.h b/lib/intel_io.h
index 5ea50cab472c..d56d061d5b0a 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 ea7a320a5647..7e251599b593 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 97eee5601f91..6666b9e75b12 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;
+}
--
1.8.5.2
More information about the Intel-gfx
mailing list