From patchwork Tue Aug 9 13:50:28 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 9271265 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id BC8F860754 for ; Tue, 9 Aug 2016 13:50:43 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A9D2328358 for ; Tue, 9 Aug 2016 13:50:43 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 9E6A828391; Tue, 9 Aug 2016 13:50:43 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.1 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED, T_DKIM_INVALID autolearn=unavailable version=3.3.1 Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 1AF832835A for ; Tue, 9 Aug 2016 13:50:41 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 0D0736E5B2; Tue, 9 Aug 2016 13:50:39 +0000 (UTC) X-Original-To: intel-gfx@lists.freedesktop.org Delivered-To: intel-gfx@lists.freedesktop.org Received: from mail-wm0-x241.google.com (mail-wm0-x241.google.com [IPv6:2a00:1450:400c:c09::241]) by gabe.freedesktop.org (Postfix) with ESMTPS id 433396E57A for ; Tue, 9 Aug 2016 13:50:37 +0000 (UTC) Received: by mail-wm0-x241.google.com with SMTP id o80so3242645wme.0 for ; Tue, 09 Aug 2016 06:50:37 -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 :mime-version:content-transfer-encoding; bh=jIDNwOPY+Idr09gJTwttfYInGBw1CALssIh04NF3bzE=; b=hKpDfvnf3C61Bek1tpnE1q6oEk1WAFZXyMmJohzx1FGIqHWIYCnl3sZkE48ou+tPwQ nrYloBcJk2RkAzqx3wCWiiw2wg0pYvfHwSkTrghizONIcSSmReYkifY0IYbMn/ZYmgKE kaW/dTxvT+bSBFzPwY2DbLX//8U2mAfTmCSWg= 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:mime-version:content-transfer-encoding; bh=jIDNwOPY+Idr09gJTwttfYInGBw1CALssIh04NF3bzE=; b=bVHOPKjg5uix82W5nDQSC2LnQTmZ7HdtRYN+NAO1vDVwrlJpFNmOLqTTi2VFOuu8WY ZcC1anl5KOJONTLAkjh/nKsBHiGXykrOECKjV7LUn0riSuiFYS9j+wrFhJxDiPZyfpH1 IpnvtparitfE8+sTvlvFDzkgAujW8puSWbBMIpDQ3akfmbd0Tem4bZpfHgT4G9IhUzZd qnhvLtUK1xo2QHjZ0XRDdFWgXCmphPL5lpQwMs5fqldAkkuxeOfoCtU00MedgwomI1ED phg6opxEgt8LfWz5TRO7Ft88igEeBMC2IVpcEl6zynEWm0vH0Oe0FkpGPlcUI9H+DyvI in6A== X-Gm-Message-State: AEkooutO1S7l6RrQHf0eJE8bkV+0BhQ+mT5nKjhK1D2LXsRfT2Y+Y9gOpRL9m6+gfZ7yNQ== X-Received: by 10.194.153.5 with SMTP id vc5mr89867449wjb.75.1470750634993; Tue, 09 Aug 2016 06:50:34 -0700 (PDT) Received: from phenom.ffwll.local ([2a02:168:56b5:0:ac27:b86c:7764:9429]) by smtp.gmail.com with ESMTPSA id za2sm38093831wjb.34.2016.08.09.06.50.33 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 09 Aug 2016 06:50:34 -0700 (PDT) From: Daniel Vetter To: DRI Development Date: Tue, 9 Aug 2016 15:50:28 +0200 Message-Id: <1470750628-17276-1-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.8.1 In-Reply-To: <1470750091-16627-21-git-send-email-daniel.vetter@ffwll.ch> References: <1470750091-16627-21-git-send-email-daniel.vetter@ffwll.ch> MIME-Version: 1.0 Cc: Daniel Vetter , Daniel Vetter , Intel Graphics Development , linux-doc@vger.kernel.org, Jonathan Corbet Subject: [Intel-gfx] [PATCH] vgaarbiter: rst-ifiy and polish kerneldoc X-BeenThere: intel-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Intel graphics driver community testing & development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" X-Virus-Scanned: ClamAV using ClamSMTP Move the documentation into Documentation/gpu, link it up and pull in the kernel doc. No actual text changes except that I did polish the kerneldoc a bit, especially for vga_client_register(). v2: Remove some rst from vga-switcheroo.rst that I don't understand, but which seems to be the reason why the new vgaarbiter.rst sometimes drops out of the sidebar index. v3: Drop one level of headings and clarify the vgaarb one a bit. Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter --- Documentation/gpu/index.rst | 1 + Documentation/gpu/vga-switcheroo.rst | 2 - Documentation/gpu/vgaarbiter.rst | 191 ++++++++++++++++++++++++++++++++++ Documentation/vgaarbiter.txt | 192 ----------------------------------- drivers/gpu/vga/vgaarb.c | 103 ++++++++++++++++++- include/linux/vgaarb.h | 128 +++-------------------- 6 files changed, 309 insertions(+), 308 deletions(-) create mode 100644 Documentation/gpu/vgaarbiter.rst delete mode 100644 Documentation/vgaarbiter.txt diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index fcac0fa72056..ba92f45abb76 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -12,3 +12,4 @@ Linux GPU Driver Developer's Guide drm-uapi i915 vga-switcheroo + vgaarbiter diff --git a/Documentation/gpu/vga-switcheroo.rst b/Documentation/gpu/vga-switcheroo.rst index cbbdb994f1dd..463a74fc40d1 100644 --- a/Documentation/gpu/vga-switcheroo.rst +++ b/Documentation/gpu/vga-switcheroo.rst @@ -1,5 +1,3 @@ -.. _vga_switcheroo: - ============== VGA Switcheroo ============== diff --git a/Documentation/gpu/vgaarbiter.rst b/Documentation/gpu/vgaarbiter.rst new file mode 100644 index 000000000000..0b41b051d021 --- /dev/null +++ b/Documentation/gpu/vgaarbiter.rst @@ -0,0 +1,191 @@ +=========== +VGA Arbiter +=========== + +Graphic devices are accessed through ranges in I/O or memory space. While most +modern devices allow relocation of such ranges, some "Legacy" VGA devices +implemented on PCI will typically have the same "hard-decoded" addresses as +they did on ISA. For more details see "PCI Bus Binding to IEEE Std 1275-1994 +Standard for Boot (Initialization Configuration) Firmware Revision 2.1" +Section 7, Legacy Devices. + +The Resource Access Control (RAC) module inside the X server [0] existed for +the legacy VGA arbitration task (besides other bus management tasks) when more +than one legacy device co-exists on the same machine. But the problem happens +when these devices are trying to be accessed by different userspace clients +(e.g. two server in parallel). Their address assignments conflict. Moreover, +ideally, being a userspace application, it is not the role of the X server to +control bus resources. Therefore an arbitration scheme outside of the X server +is needed to control the sharing of these resources. This document introduces +the operation of the VGA arbiter implemented for the Linux kernel. + +vgaarb kernel/userspace ABI +--------------------------- + +The vgaarb is a module of the Linux Kernel. When it is initially loaded, it +scans all PCI devices and adds the VGA ones inside the arbitration. The +arbiter then enables/disables the decoding on different devices of the VGA +legacy instructions. Devices which do not want/need to use the arbiter may +explicitly tell it by calling vga_set_legacy_decoding(). + +The kernel exports a char device interface (/dev/vga_arbiter) to the clients, +which has the following semantics: + +open + Opens a user instance of the arbiter. By default, it's attached to the + default VGA device of the system. + +close + Close a user instance. Release locks made by the user + +read + Return a string indicating the status of the target like: + + ",decodes=,owns=,locks= (ic,mc)" + + An IO state string is of the form {io,mem,io+mem,none}, mc and + ic are respectively mem and io lock counts (for debugging/ + diagnostic only). "decodes" indicate what the card currently + decodes, "owns" indicates what is currently enabled on it, and + "locks" indicates what is locked by this card. If the card is + unplugged, we get "invalid" then for card_ID and an -ENODEV + error is returned for any command until a new card is targeted. + + +write + Write a command to the arbiter. List of commands: + + target + switch target to card (see below) + lock + acquires locks on target ("none" is an invalid io_state) + trylock + non-blocking acquire locks on target (returns EBUSY if + unsuccessful) + unlock + release locks on target + unlock all + release all locks on target held by this user (not implemented + yet) + decodes + set the legacy decoding attributes for the card + + poll + event if something changes on any card (not just the target) + + card_ID is of the form "PCI:domain:bus:dev.fn". It can be set to "default" + to go back to the system default card (TODO: not implemented yet). Currently, + only PCI is supported as a prefix, but the userland API may support other bus + types in the future, even if the current kernel implementation doesn't. + +Note about locks: + +The driver keeps track of which user has which locks on which card. It +supports stacking, like the kernel one. This complexifies the implementation +a bit, but makes the arbiter more tolerant to user space problems and able +to properly cleanup in all cases when a process dies. +Currently, a max of 16 cards can have locks simultaneously issued from +user space for a given user (file descriptor instance) of the arbiter. + +In the case of devices hot-{un,}plugged, there is a hook - pci_notify() - to +notify them being added/removed in the system and automatically added/removed +in the arbiter. + +There is also an in-kernel API of the arbiter in case DRM, vgacon, or other +drivers want to use it. + +In-kernel interface +------------------- + +.. kernel-doc:: include/linux/vgaarb.h + :internal: + +.. kernel-doc:: drivers/gpu/vga/vgaarb.c + :export: + +libpciaccess +------------ + +To use the vga arbiter char device it was implemented an API inside the +libpciaccess library. One field was added to struct pci_device (each device +on the system):: + + /* the type of resource decoded by the device */ + int vgaarb_rsrc; + +Besides it, in pci_system were added:: + + int vgaarb_fd; + int vga_count; + struct pci_device *vga_target; + struct pci_device *vga_default_dev; + +The vga_count is used to track how many cards are being arbitrated, so for +instance, if there is only one card, then it can completely escape arbitration. + +These functions below acquire VGA resources for the given card and mark those +resources as locked. If the resources requested are "normal" (and not legacy) +resources, the arbiter will first check whether the card is doing legacy +decoding for that type of resource. If yes, the lock is "converted" into a +legacy resource lock. The arbiter will first look for all VGA cards that +might conflict and disable their IOs and/or Memory access, including VGA +forwarding on P2P bridges if necessary, so that the requested resources can +be used. Then, the card is marked as locking these resources and the IO and/or +Memory access is enabled on the card (including VGA forwarding on parent +P2P bridges if any). In the case of vga_arb_lock(), the function will block +if some conflicting card is already locking one of the required resources (or +any resource on a different bus segment, since P2P bridges don't differentiate +VGA memory and IO afaik). If the card already owns the resources, the function +succeeds. vga_arb_trylock() will return (-EBUSY) instead of blocking. Nested +calls are supported (a per-resource counter is maintained). + +Set the target device of this client. :: + + int pci_device_vgaarb_set_target (struct pci_device *dev); + +For instance, in x86 if two devices on the same bus want to lock different +resources, both will succeed (lock). If devices are in different buses and +trying to lock different resources, only the first who tried succeeds. :: + + int pci_device_vgaarb_lock (void); + int pci_device_vgaarb_trylock (void); + +Unlock resources of device. :: + + int pci_device_vgaarb_unlock (void); + +Indicates to the arbiter if the card decodes legacy VGA IOs, legacy VGA +Memory, both, or none. All cards default to both, the card driver (fbdev for +example) should tell the arbiter if it has disabled legacy decoding, so the +card can be left out of the arbitration process (and can be safe to take +interrupts at any time. :: + + int pci_device_vgaarb_decodes (int new_vgaarb_rsrc); + +Connects to the arbiter device, allocates the struct :: + + int pci_device_vgaarb_init (void); + +Close the connection :: + + void pci_device_vgaarb_fini (void); + +xf86VGAArbiter (X server implementation) +---------------------------------------- + +X server basically wraps all the functions that touch VGA registers somehow. + +References +---------- + +Benjamin Herrenschmidt (IBM?) started this work when he discussed such design +with the Xorg community in 2005 [1, 2]. In the end of 2007, Paulo Zanoni and +Tiago Vignatti (both of C3SL/Federal University of Paraná) proceeded his work +enhancing the kernel code to adapt as a kernel module and also did the +implementation of the user space side [3]. Now (2009) Tiago Vignatti and Dave +Airlie finally put this work in shape and queued to Jesse Barnes' PCI tree. + +0) http://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347 +1) http://lists.freedesktop.org/archives/xorg/2005-March/006663.html +2) http://lists.freedesktop.org/archives/xorg/2005-March/006745.html +3) http://lists.freedesktop.org/archives/xorg/2007-October/029507.html diff --git a/Documentation/vgaarbiter.txt b/Documentation/vgaarbiter.txt deleted file mode 100644 index 014423e2824c..000000000000 --- a/Documentation/vgaarbiter.txt +++ /dev/null @@ -1,192 +0,0 @@ - -VGA Arbiter -=========== - -Graphic devices are accessed through ranges in I/O or memory space. While most -modern devices allow relocation of such ranges, some "Legacy" VGA devices -implemented on PCI will typically have the same "hard-decoded" addresses as -they did on ISA. For more details see "PCI Bus Binding to IEEE Std 1275-1994 -Standard for Boot (Initialization Configuration) Firmware Revision 2.1" -Section 7, Legacy Devices. - -The Resource Access Control (RAC) module inside the X server [0] existed for -the legacy VGA arbitration task (besides other bus management tasks) when more -than one legacy device co-exists on the same machine. But the problem happens -when these devices are trying to be accessed by different userspace clients -(e.g. two server in parallel). Their address assignments conflict. Moreover, -ideally, being a userspace application, it is not the role of the X server to -control bus resources. Therefore an arbitration scheme outside of the X server -is needed to control the sharing of these resources. This document introduces -the operation of the VGA arbiter implemented for the Linux kernel. - ----------------------------------------------------------------------------- - -I. Details and Theory of Operation - I.1 vgaarb - I.2 libpciaccess - I.3 xf86VGAArbiter (X server implementation) -II. Credits -III.References - - -I. Details and Theory of Operation -================================== - -I.1 vgaarb ----------- - -The vgaarb is a module of the Linux Kernel. When it is initially loaded, it -scans all PCI devices and adds the VGA ones inside the arbitration. The -arbiter then enables/disables the decoding on different devices of the VGA -legacy instructions. Devices which do not want/need to use the arbiter may -explicitly tell it by calling vga_set_legacy_decoding(). - -The kernel exports a char device interface (/dev/vga_arbiter) to the clients, -which has the following semantics: - - open : open user instance of the arbiter. By default, it's attached to - the default VGA device of the system. - - close : close user instance. Release locks made by the user - - read : return a string indicating the status of the target like: - - ",decodes=,owns=,locks= (ic,mc)" - - An IO state string is of the form {io,mem,io+mem,none}, mc and - ic are respectively mem and io lock counts (for debugging/ - diagnostic only). "decodes" indicate what the card currently - decodes, "owns" indicates what is currently enabled on it, and - "locks" indicates what is locked by this card. If the card is - unplugged, we get "invalid" then for card_ID and an -ENODEV - error is returned for any command until a new card is targeted. - - - write : write a command to the arbiter. List of commands: - - target : switch target to card (see below) - lock : acquires locks on target ("none" is an invalid io_state) - trylock : non-blocking acquire locks on target (returns EBUSY if - unsuccessful) - unlock : release locks on target - unlock all : release all locks on target held by this user (not - implemented yet) - decodes : set the legacy decoding attributes for the card - - poll : event if something changes on any card (not just the - target) - - card_ID is of the form "PCI:domain:bus:dev.fn". It can be set to "default" - to go back to the system default card (TODO: not implemented yet). Currently, - only PCI is supported as a prefix, but the userland API may support other bus - types in the future, even if the current kernel implementation doesn't. - -Note about locks: - -The driver keeps track of which user has which locks on which card. It -supports stacking, like the kernel one. This complexifies the implementation -a bit, but makes the arbiter more tolerant to user space problems and able -to properly cleanup in all cases when a process dies. -Currently, a max of 16 cards can have locks simultaneously issued from -user space for a given user (file descriptor instance) of the arbiter. - -In the case of devices hot-{un,}plugged, there is a hook - pci_notify() - to -notify them being added/removed in the system and automatically added/removed -in the arbiter. - -There is also an in-kernel API of the arbiter in case DRM, vgacon, or other -drivers want to use it. - - -I.2 libpciaccess ----------------- - -To use the vga arbiter char device it was implemented an API inside the -libpciaccess library. One field was added to struct pci_device (each device -on the system): - - /* the type of resource decoded by the device */ - int vgaarb_rsrc; - -Besides it, in pci_system were added: - - int vgaarb_fd; - int vga_count; - struct pci_device *vga_target; - struct pci_device *vga_default_dev; - - -The vga_count is used to track how many cards are being arbitrated, so for -instance, if there is only one card, then it can completely escape arbitration. - - -These functions below acquire VGA resources for the given card and mark those -resources as locked. If the resources requested are "normal" (and not legacy) -resources, the arbiter will first check whether the card is doing legacy -decoding for that type of resource. If yes, the lock is "converted" into a -legacy resource lock. The arbiter will first look for all VGA cards that -might conflict and disable their IOs and/or Memory access, including VGA -forwarding on P2P bridges if necessary, so that the requested resources can -be used. Then, the card is marked as locking these resources and the IO and/or -Memory access is enabled on the card (including VGA forwarding on parent -P2P bridges if any). In the case of vga_arb_lock(), the function will block -if some conflicting card is already locking one of the required resources (or -any resource on a different bus segment, since P2P bridges don't differentiate -VGA memory and IO afaik). If the card already owns the resources, the function -succeeds. vga_arb_trylock() will return (-EBUSY) instead of blocking. Nested -calls are supported (a per-resource counter is maintained). - - -Set the target device of this client. - int pci_device_vgaarb_set_target (struct pci_device *dev); - - -For instance, in x86 if two devices on the same bus want to lock different -resources, both will succeed (lock). If devices are in different buses and -trying to lock different resources, only the first who tried succeeds. - int pci_device_vgaarb_lock (void); - int pci_device_vgaarb_trylock (void); - -Unlock resources of device. - int pci_device_vgaarb_unlock (void); - -Indicates to the arbiter if the card decodes legacy VGA IOs, legacy VGA -Memory, both, or none. All cards default to both, the card driver (fbdev for -example) should tell the arbiter if it has disabled legacy decoding, so the -card can be left out of the arbitration process (and can be safe to take -interrupts at any time. - int pci_device_vgaarb_decodes (int new_vgaarb_rsrc); - -Connects to the arbiter device, allocates the struct - int pci_device_vgaarb_init (void); - -Close the connection - void pci_device_vgaarb_fini (void); - - -I.3 xf86VGAArbiter (X server implementation) --------------------------------------------- - -(TODO) - -X server basically wraps all the functions that touch VGA registers somehow. - - -II. Credits -=========== - -Benjamin Herrenschmidt (IBM?) started this work when he discussed such design -with the Xorg community in 2005 [1, 2]. In the end of 2007, Paulo Zanoni and -Tiago Vignatti (both of C3SL/Federal University of Paraná) proceeded his work -enhancing the kernel code to adapt as a kernel module and also did the -implementation of the user space side [3]. Now (2009) Tiago Vignatti and Dave -Airlie finally put this work in shape and queued to Jesse Barnes' PCI tree. - - -III. References -============== - -[0] http://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347 -[1] http://lists.freedesktop.org/archives/xorg/2005-March/006663.html -[2] http://lists.freedesktop.org/archives/xorg/2005-March/006745.html -[3] http://lists.freedesktop.org/archives/xorg/2007-October/029507.html diff --git a/drivers/gpu/vga/vgaarb.c b/drivers/gpu/vga/vgaarb.c index f17cb0431833..92787f20b7f7 100644 --- a/drivers/gpu/vga/vgaarb.c +++ b/drivers/gpu/vga/vgaarb.c @@ -131,7 +131,24 @@ static struct vga_device *vgadev_find(struct pci_dev *pdev) return NULL; } -/* Returns the default VGA device (vgacon's babe) */ +/** + * vga_default_device - return the default VGA device, for vgacon + * + * This can be defined by the platform. The default implementation + * is rather dumb and will probably only work properly on single + * vga card setups and/or x86 platforms. + * + * If your VGA default device is not PCI, you'll have to return + * NULL here. In this case, I assume it will not conflict with + * any PCI card. If this is not true, I'll have to define two archs + * hooks for enabling/disabling the VGA default device if that is + * possible. This may be a problem with real _ISA_ VGA cards, in + * addition to a PCI one. I don't know at this point how to deal + * with that card. Can theirs IOs be disabled at all ? If not, then + * I suppose it's a matter of having the proper arch hook telling + * us about it, so we basically never allow anybody to succeed a + * vga_get()... + */ struct pci_dev *vga_default_device(void) { return vga_default; @@ -356,6 +373,36 @@ static void __vga_put(struct vga_device *vgadev, unsigned int rsrc) wake_up_all(&vga_wait_queue); } +/** + * vga_get - acquire & locks VGA resources + * @pdev: pci device of the VGA card or NULL for the system default + * @rsrc: bit mask of resources to acquire and lock + * @interruptible: blocking should be interruptible by signals ? + * + * This function acquires VGA resources for the given card and mark those + * resources locked. If the resource requested are "normal" (and not legacy) + * resources, the arbiter will first check whether the card is doing legacy + * decoding for that type of resource. If yes, the lock is "converted" into a + * legacy resource lock. + * + * The arbiter will first look for all VGA cards that might conflict and disable + * their IOs and/or Memory access, including VGA forwarding on P2P bridges if + * necessary, so that the requested resources can be used. Then, the card is + * marked as locking these resources and the IO and/or Memory accesse are + * enabled on the card (including VGA forwarding on parent P2P bridges if any). + * + * This function will block if some conflicting card is already locking one of + * the required resources (or any resource on a different bus segment, since P2P + * bridges don't differenciate VGA memory and IO afaik). You can indicate + * whether this blocking should be interruptible by a signal (for userland + * interface) or not. + * + * Must not be called at interrupt time or in atomic context. If the card + * already owns the resources, the function succeeds. Nested calls are + * supported (a per-resource counter is maintained) + * + * On success, release the VGA resource again with vga_put(). + */ int vga_get(struct pci_dev *pdev, unsigned int rsrc, int interruptible) { struct vga_device *vgadev, *conflict; @@ -408,6 +455,17 @@ int vga_get(struct pci_dev *pdev, unsigned int rsrc, int interruptible) } EXPORT_SYMBOL(vga_get); +/** + * vga_tryget - try to acquire & lock legacy VGA resources + * @pdev: pci devivce of VGA card or NULL for system default + * @rsrc: bit mask of resources to acquire and lock + * + * This function performs the same operation as vga_get(), but will return an + * error (-EBUSY) instead of blocking if the resources are already locked by + * another card. It can be called in any context + * + * On success, release the VGA resource again with vga_put(). + */ int vga_tryget(struct pci_dev *pdev, unsigned int rsrc) { struct vga_device *vgadev; @@ -435,6 +493,16 @@ bail: } EXPORT_SYMBOL(vga_tryget); +/** + * vga_put - release lock on legacy VGA resources + * @pdev: pci device of VGA card or NULL for system default + * @rsrc: but mask of resource to release + * + * This fuction releases resources previously locked by vga_get() or + * vga_tryget(). The resources aren't disabled right away, so that a subsequence + * vga_get() on the same card will succeed immediately. Resources have a + * counter, so locks are only released if the counter reaches 0. + */ void vga_put(struct pci_dev *pdev, unsigned int rsrc) { struct vga_device *vgadev; @@ -716,7 +784,38 @@ void vga_set_legacy_decoding(struct pci_dev *pdev, unsigned int decodes) } EXPORT_SYMBOL(vga_set_legacy_decoding); -/* call with NULL to unregister */ +/** + * vga_client_register - register or unregister a VGA arbitration client + * @pdev: pci device of the VGA client + * @cookie: client cookie to be used in callbacks + * @irq_set_state: irq state change callback + * @set_vga_decode: vga decode change callback + * + * Clients have two callback mechanisms they can use. + * + * @irq_set_state callback: If a client can't disable its GPUs VGA + * resources, then we need to be able to ask it to turn off its irqs when we + * turn off its mem and io decoding. + * + * @set_vga_decode callback: If a client can disable its GPU VGA resource, it + * will get a callback from this to set the encode/decode state. + * + * Rationale: we cannot disable VGA decode resources unconditionally + * some single GPU laptops seem to require ACPI or BIOS access to the + * VGA registers to control things like backlights etc. + * Hopefully newer multi-GPU laptops do something saner, and desktops + * won't have any special ACPI for this. + * They driver will get a callback when VGA arbitration is first used + * by userspace since we some older X servers have issues. + * + * This function does not check whether a client for @pdev has been registered + * already. + * + * To unregister just call this function with @irq_set_state and @set_vga_decode + * both set to NULL for the same @pdev as originally used to register them. + * + * Returns: 0 on success, -1 on failure + */ int vga_client_register(struct pci_dev *pdev, void *cookie, void (*irq_set_state)(void *cookie, bool state), unsigned int (*set_vga_decode)(void *cookie, diff --git a/include/linux/vgaarb.h b/include/linux/vgaarb.h index 8c3b412d84df..ee162e3e879b 100644 --- a/include/linux/vgaarb.h +++ b/include/linux/vgaarb.h @@ -73,34 +73,6 @@ static inline void vga_set_legacy_decoding(struct pci_dev *pdev, unsigned int decodes) { }; #endif -/** - * vga_get - acquire & locks VGA resources - * - * @pdev: pci device of the VGA card or NULL for the system default - * @rsrc: bit mask of resources to acquire and lock - * @interruptible: blocking should be interruptible by signals ? - * - * This function acquires VGA resources for the given - * card and mark those resources locked. If the resource requested - * are "normal" (and not legacy) resources, the arbiter will first check - * whether the card is doing legacy decoding for that type of resource. If - * yes, the lock is "converted" into a legacy resource lock. - * The arbiter will first look for all VGA cards that might conflict - * and disable their IOs and/or Memory access, including VGA forwarding - * on P2P bridges if necessary, so that the requested resources can - * be used. Then, the card is marked as locking these resources and - * the IO and/or Memory accesse are enabled on the card (including - * VGA forwarding on parent P2P bridges if any). - * This function will block if some conflicting card is already locking - * one of the required resources (or any resource on a different bus - * segment, since P2P bridges don't differenciate VGA memory and IO - * afaik). You can indicate whether this blocking should be interruptible - * by a signal (for userland interface) or not. - * Must not be called at interrupt time or in atomic context. - * If the card already owns the resources, the function succeeds. - * Nested calls are supported (a per-resource counter is maintained) - */ - #if defined(CONFIG_VGA_ARB) extern int vga_get(struct pci_dev *pdev, unsigned int rsrc, int interruptible); #else @@ -108,11 +80,14 @@ static inline int vga_get(struct pci_dev *pdev, unsigned int rsrc, int interrupt #endif /** - * vga_get_interruptible + * vga_get_interruptible + * @pdev: pci device of the VGA card or NULL for the system default + * @rsrc: bit mask of resources to acquire and lock * - * Shortcut to vga_get + * Shortcut to vga_get with interruptible set to true. + * + * On success, release the VGA resource again with vga_put(). */ - static inline int vga_get_interruptible(struct pci_dev *pdev, unsigned int rsrc) { @@ -120,47 +95,26 @@ static inline int vga_get_interruptible(struct pci_dev *pdev, } /** - * vga_get_uninterruptible + * vga_get_uninterruptible - shortcut to vga_get() + * @pdev: pci device of the VGA card or NULL for the system default + * @rsrc: bit mask of resources to acquire and lock * - * Shortcut to vga_get + * Shortcut to vga_get with interruptible set to false. + * + * On success, release the VGA resource again with vga_put(). */ - static inline int vga_get_uninterruptible(struct pci_dev *pdev, unsigned int rsrc) { return vga_get(pdev, rsrc, 0); } -/** - * vga_tryget - try to acquire & lock legacy VGA resources - * - * @pdev: pci devivce of VGA card or NULL for system default - * @rsrc: bit mask of resources to acquire and lock - * - * This function performs the same operation as vga_get(), but - * will return an error (-EBUSY) instead of blocking if the resources - * are already locked by another card. It can be called in any context - */ - #if defined(CONFIG_VGA_ARB) extern int vga_tryget(struct pci_dev *pdev, unsigned int rsrc); #else static inline int vga_tryget(struct pci_dev *pdev, unsigned int rsrc) { return 0; } #endif -/** - * vga_put - release lock on legacy VGA resources - * - * @pdev: pci device of VGA card or NULL for system default - * @rsrc: but mask of resource to release - * - * This function releases resources previously locked by vga_get() - * or vga_tryget(). The resources aren't disabled right away, so - * that a subsequence vga_get() on the same card will succeed - * immediately. Resources have a counter, so locks are only - * released if the counter reaches 0. - */ - #if defined(CONFIG_VGA_ARB) extern void vga_put(struct pci_dev *pdev, unsigned int rsrc); #else @@ -168,25 +122,6 @@ extern void vga_put(struct pci_dev *pdev, unsigned int rsrc); #endif -/** - * vga_default_device - * - * This can be defined by the platform. The default implementation - * is rather dumb and will probably only work properly on single - * vga card setups and/or x86 platforms. - * - * If your VGA default device is not PCI, you'll have to return - * NULL here. In this case, I assume it will not conflict with - * any PCI card. If this is not true, I'll have to define two archs - * hooks for enabling/disabling the VGA default device if that is - * possible. This may be a problem with real _ISA_ VGA cards, in - * addition to a PCI one. I don't know at this point how to deal - * with that card. Can theirs IOs be disabled at all ? If not, then - * I suppose it's a matter of having the proper arch hook telling - * us about it, so we basically never allow anybody to succeed a - * vga_get()... - */ - #ifdef CONFIG_VGA_ARB extern struct pci_dev *vga_default_device(void); extern void vga_set_default_device(struct pci_dev *pdev); @@ -195,14 +130,11 @@ static inline struct pci_dev *vga_default_device(void) { return NULL; }; static inline void vga_set_default_device(struct pci_dev *pdev) { }; #endif -/** - * vga_conflicts - * - * Architectures should define this if they have several - * independent PCI domains that can afford concurrent VGA - * decoding +/* + * Architectures should define this if they have several + * independent PCI domains that can afford concurrent VGA + * decoding */ - #ifndef __ARCH_HAS_VGA_CONFLICT static inline int vga_conflicts(struct pci_dev *p1, struct pci_dev *p2) { @@ -210,34 +142,6 @@ static inline int vga_conflicts(struct pci_dev *p1, struct pci_dev *p2) } #endif -/** - * vga_client_register - * - * @pdev: pci device of the VGA client - * @cookie: client cookie to be used in callbacks - * @irq_set_state: irq state change callback - * @set_vga_decode: vga decode change callback - * - * return value: 0 on success, -1 on failure - * Register a client with the VGA arbitration logic - * - * Clients have two callback mechanisms they can use. - * irq enable/disable callback - - * If a client can't disable its GPUs VGA resources, then we - * need to be able to ask it to turn off its irqs when we - * turn off its mem and io decoding. - * set_vga_decode - * If a client can disable its GPU VGA resource, it will - * get a callback from this to set the encode/decode state - * - * Rationale: we cannot disable VGA decode resources unconditionally - * some single GPU laptops seem to require ACPI or BIOS access to the - * VGA registers to control things like backlights etc. - * Hopefully newer multi-GPU laptops do something saner, and desktops - * won't have any special ACPI for this. - * They driver will get a callback when VGA arbitration is first used - * by userspace since we some older X servers have issues. - */ #if defined(CONFIG_VGA_ARB) int vga_client_register(struct pci_dev *pdev, void *cookie, void (*irq_set_state)(void *cookie, bool state),