From 95e89f0ede9ed84b5cd0c39b7f68bc08fb120c3b Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Sat, 22 Mar 2014 22:41:28 +0100 Subject: 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 --- lib/intel_mmio.c | 125 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 121 insertions(+), 4 deletions(-) (limited to 'lib/intel_mmio.c') 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; +} -- cgit v1.2.3