| Message ID | 1470750628-17276-1-git-send-email-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Tue, Aug 9, 2016 at 9:50 AM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote: > 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 <corbet@lwn.net> > Cc: linux-doc@vger.kernel.org > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> > --- > 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: > + > + "<card_ID>,decodes=<io_state>,owns=<io_state>,locks=<io_state> (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 <card_ID> > + switch target to card <card_ID> (see below) > + lock <io_state> > + acquires locks on target ("none" is an invalid io_state) > + trylock <io_state> > + non-blocking acquire locks on target (returns EBUSY if > + unsuccessful) > + unlock <io_state> > + release locks on target > + unlock all > + release all locks on target held by this user (not implemented > + yet) > + decodes <io_state> > + 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: > - > - "<card_ID>,decodes=<io_state>,owns=<io_state>,locks=<io_state> (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 <card_ID> : switch target to card <card_ID> (see below) > - lock <io_state> : acquires locks on target ("none" is an invalid io_state) > - trylock <io_state> : non-blocking acquire locks on target (returns EBUSY if > - unsuccessful) > - unlock <io_state> : release locks on target > - unlock all : release all locks on target held by this user (not > - implemented yet) > - decodes <io_state> : 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 s/accesse/accesses/ > + * 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 s/differenciate/differentiate/ > + * 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(). Returns: ? > + */ > 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 s/They/The/ > + * by userspace since we some older X servers have issues. s/since we/since/ > + * > + * 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), > -- > 2.8.1 > > _______________________________________________ > dri-devel mailing list > dri-devel@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/dri-devel
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: + + "<card_ID>,decodes=<io_state>,owns=<io_state>,locks=<io_state> (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 <card_ID> + switch target to card <card_ID> (see below) + lock <io_state> + acquires locks on target ("none" is an invalid io_state) + trylock <io_state> + non-blocking acquire locks on target (returns EBUSY if + unsuccessful) + unlock <io_state> + release locks on target + unlock all + release all locks on target held by this user (not implemented + yet) + decodes <io_state> + 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: - - "<card_ID>,decodes=<io_state>,owns=<io_state>,locks=<io_state> (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 <card_ID> : switch target to card <card_ID> (see below) - lock <io_state> : acquires locks on target ("none" is an invalid io_state) - trylock <io_state> : non-blocking acquire locks on target (returns EBUSY if - unsuccessful) - unlock <io_state> : release locks on target - unlock all : release all locks on target held by this user (not - implemented yet) - decodes <io_state> : 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),
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 <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> --- 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