From patchwork Sun Mar 23 14:18:55 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 3879191 Return-Path: X-Original-To: patchwork-intel-gfx@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork1.web.kernel.org (Postfix) with ESMTP id B1C309F391 for ; Sun, 23 Mar 2014 14:19:53 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 8A60F201B4 for ; Sun, 23 Mar 2014 14:19:52 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id D06D720265 for ; Sun, 23 Mar 2014 14:19:49 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 66D746E6AB; Sun, 23 Mar 2014 07:19:49 -0700 (PDT) X-Original-To: intel-gfx@lists.freedesktop.org Delivered-To: intel-gfx@lists.freedesktop.org Received: from mail-ee0-f46.google.com (mail-ee0-f46.google.com [74.125.83.46]) by gabe.freedesktop.org (Postfix) with ESMTP id F0CEC6E6A5 for ; Sun, 23 Mar 2014 07:19:42 -0700 (PDT) Received: by mail-ee0-f46.google.com with SMTP id t10so3496272eei.33 for ; Sun, 23 Mar 2014 07:19:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ffwll.ch; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=n5STI3tMdqX7ENvsxP1L3E35ByrKeQf2gJsdPNS1jUQ=; b=Bu8Ami+9GMXq0l5eOuBkdK8LGscMDHYTqNQSUArVBjbJrWk2IKyAr6XyGMBL2euVcB IsVGLgMcryr+NhmT+tIeV3OUnCekNcL+LP8OQEKeSht9FZJ2RmACgHdL3SHOmWIVhEar E8W36mcdRpPLNoz8ouMyyqX3wZfJyrceBqHcY= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=n5STI3tMdqX7ENvsxP1L3E35ByrKeQf2gJsdPNS1jUQ=; b=lML1DYyQiB5N+INnjLvqWLdx/cTM27PH3t+J2dEBjkvyMohvj6klwS8tUuReYQOTBQ nBXwS6HNEdMRcyU+DPDHEBgoJFVV2/Nn2Xq92gv9dMfCWF7E1chwY7S0TlBbYeJW9x1U KcKYGr6kqFatPHs4GvUe29kSL6GZAy55l/KW2VTRUCFH9xUUwDOjFVJiDr7PPihSpjfs pkgdfelkO/qQE7O1RAgJ0YFMkYJu5vfsy+SSHPJBhtoD3vxFmvoFd5oSCsLGEb7Tflpw 3aZ5zIZlW6pbVp9RKpRhaxfNCGUr4n90GuUGydljBdiolkln+pLT94gQOUoLi52TFiDK ZFoA== X-Gm-Message-State: ALoCoQk9TBpkx0f2FPkPMTvvulIa/meZ4axiWhwB0h1ti+bF6SfBguFAaBDRGlugAH8KFb9lJLFU X-Received: by 10.14.88.7 with SMTP id z7mr51815eee.90.1395584382136; Sun, 23 Mar 2014 07:19:42 -0700 (PDT) Received: from phenom.ffwll.local (84-73-67-144.dclient.hispeed.ch. [84.73.67.144]) by mx.google.com with ESMTPSA id cb5sm26392589eeb.18.2014.03.23.07.19.40 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Sun, 23 Mar 2014 07:19:41 -0700 (PDT) From: Daniel Vetter To: Intel Graphics Development Date: Sun, 23 Mar 2014 15:18:55 +0100 Message-Id: <1395584342-11812-22-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 1.8.5.2 In-Reply-To: <1395584342-11812-1-git-send-email-daniel.vetter@ffwll.ch> References: <1395584342-11812-1-git-send-email-daniel.vetter@ffwll.ch> Cc: Daniel Vetter Subject: [Intel-gfx] [PATCH 21/28] lib/intel_io: api documentation X-BeenThere: intel-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Intel graphics driver community testing & development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" X-Spam-Status: No, score=-4.6 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED,RP_MATCHES_RCVD,T_DKIM_INVALID,UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP 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_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; +}