From: Daniel Vetter Date: Sat, 22 Mar 2014 21:41:28 +0000 (+0100) Subject: lib/intel_io: api documentation X-Git-Tag: intel-gpu-tools-1.7~220 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=95e89f0ede9ed84b5cd0c39b7f68bc08fb120c3b;p=platform%2Fupstream%2Fintel-gpu-tools.git 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 --- diff --git a/lib/intel_io.h b/lib/intel_io.h index 5ea50ca..d56d061 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 ea7a320..7e25159 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 97eee56..6666b9e 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; +}