1 2VGA Arbiter 3=========== 4 5Graphic devices are accessed through ranges in I/O or memory space. While most 6modern devices allow relocation of such ranges, some "Legacy" VGA devices 7implemented on PCI will typically have the same "hard-decoded" addresses as 8they did on ISA. For more details see "PCI Bus Binding to IEEE Std 1275-1994 9Standard for Boot (Initialization Configuration) Firmware Revision 2.1" 10Section 7, Legacy Devices. 11 12The Resource Access Control (RAC) module inside the X server [0] existed for 13the legacy VGA arbitration task (besides other bus management tasks) when more 14than one legacy device co-exists on the same machine. But the problem happens 15when these devices are trying to be accessed by different userspace clients 16(e.g. two server in parallel). Their address assignments conflict. Moreover, 17ideally, being an userspace application, it is not the role of the the X 18server to control bus resources. Therefore an arbitration scheme outside of 19the X server is needed to control the sharing of these resources. This 20document introduces the operation of the VGA arbiter implemented for Linux 21kernel. 22 23---------------------------------------------------------------------------- 24 25I. Details and Theory of Operation 26 I.1 vgaarb 27 I.2 libpciaccess 28 I.3 xf86VGAArbiter (X server implementation) 29II. Credits 30III.References 31 32 33I. Details and Theory of Operation 34================================== 35 36I.1 vgaarb 37---------- 38 39The vgaarb is a module of the Linux Kernel. When it is initially loaded, it 40scans all PCI devices and adds the VGA ones inside the arbitration. The 41arbiter then enables/disables the decoding on different devices of the VGA 42legacy instructions. Device which do not want/need to use the arbiter may 43explicitly tell it by calling vga_set_legacy_decoding(). 44 45The kernel exports a char device interface (/dev/vga_arbiter) to the clients, 46which has the following semantics: 47 48 open : open user instance of the arbiter. By default, it's attached to 49 the default VGA device of the system. 50 51 close : close user instance. Release locks made by the user 52 53 read : return a string indicating the status of the target like: 54 55 "<card_ID>,decodes=<io_state>,owns=<io_state>,locks=<io_state> (ic,mc)" 56 57 An IO state string is of the form {io,mem,io+mem,none}, mc and 58 ic are respectively mem and io lock counts (for debugging/ 59 diagnostic only). "decodes" indicate what the card currently 60 decodes, "owns" indicates what is currently enabled on it, and 61 "locks" indicates what is locked by this card. If the card is 62 unplugged, we get "invalid" then for card_ID and an -ENODEV 63 error is returned for any command until a new card is targeted. 64 65 66 write : write a command to the arbiter. List of commands: 67 68 target <card_ID> : switch target to card <card_ID> (see below) 69 lock <io_state> : acquires locks on target ("none" is an invalid io_state) 70 trylock <io_state> : non-blocking acquire locks on target (returns EBUSY if 71 unsuccessful) 72 unlock <io_state> : release locks on target 73 unlock all : release all locks on target held by this user (not 74 implemented yet) 75 decodes <io_state> : set the legacy decoding attributes for the card 76 77 poll : event if something changes on any card (not just the 78 target) 79 80 card_ID is of the form "PCI:domain:bus:dev.fn". It can be set to "default" 81 to go back to the system default card (TODO: not implemented yet). Currently, 82 only PCI is supported as a prefix, but the userland API may support other bus 83 types in the future, even if the current kernel implementation doesn't. 84 85Note about locks: 86 87The driver keeps track of which user has which locks on which card. It 88supports stacking, like the kernel one. This complexifies the implementation 89a bit, but makes the arbiter more tolerant to user space problems and able 90to properly cleanup in all cases when a process dies. 91Currently, a max of 16 cards can have locks simultaneously issued from 92user space for a given user (file descriptor instance) of the arbiter. 93 94In the case of devices hot-{un,}plugged, there is a hook - pci_notify() - to 95notify them being added/removed in the system and automatically added/removed 96in the arbiter. 97 98There's also a in-kernel API of the arbiter in the case of DRM, vgacon and 99others which may use the arbiter. 100 101 102I.2 libpciaccess 103---------------- 104 105To use the vga arbiter char device it was implemented an API inside the 106libpciaccess library. One fieldd was added to struct pci_device (each device 107on the system): 108 109 /* the type of resource decoded by the device */ 110 int vgaarb_rsrc; 111 112Besides it, in pci_system were added: 113 114 int vgaarb_fd; 115 int vga_count; 116 struct pci_device *vga_target; 117 struct pci_device *vga_default_dev; 118 119 120The vga_count is usually need to keep informed how many cards are being 121arbitrated, so for instance if there's only one then it can totally escape the 122scheme. 123 124 125These functions below acquire VGA resources for the given card and mark those 126resources as locked. If the resources requested are "normal" (and not legacy) 127resources, the arbiter will first check whether the card is doing legacy 128decoding for that type of resource. If yes, the lock is "converted" into a 129legacy resource lock. The arbiter will first look for all VGA cards that 130might conflict and disable their IOs and/or Memory access, including VGA 131forwarding on P2P bridges if necessary, so that the requested resources can 132be used. Then, the card is marked as locking these resources and the IO and/or 133Memory access is enabled on the card (including VGA forwarding on parent 134P2P bridges if any). In the case of vga_arb_lock(), the function will block 135if some conflicting card is already locking one of the required resources (or 136any resource on a different bus segment, since P2P bridges don't differentiate 137VGA memory and IO afaik). If the card already owns the resources, the function 138succeeds. vga_arb_trylock() will return (-EBUSY) instead of blocking. Nested 139calls are supported (a per-resource counter is maintained). 140 141 142Set the target device of this client. 143 int pci_device_vgaarb_set_target (struct pci_device *dev); 144 145 146For instance, in x86 if two devices on the same bus want to lock different 147resources, both will succeed (lock). If devices are in different buses and 148trying to lock different resources, only the first who tried succeeds. 149 int pci_device_vgaarb_lock (void); 150 int pci_device_vgaarb_trylock (void); 151 152Unlock resources of device. 153 int pci_device_vgaarb_unlock (void); 154 155Indicates to the arbiter if the card decodes legacy VGA IOs, legacy VGA 156Memory, both, or none. All cards default to both, the card driver (fbdev for 157example) should tell the arbiter if it has disabled legacy decoding, so the 158card can be left out of the arbitration process (and can be safe to take 159interrupts at any time. 160 int pci_device_vgaarb_decodes (int new_vgaarb_rsrc); 161 162Connects to the arbiter device, allocates the struct 163 int pci_device_vgaarb_init (void); 164 165Close the connection 166 void pci_device_vgaarb_fini (void); 167 168 169I.3 xf86VGAArbiter (X server implementation) 170-------------------------------------------- 171 172(TODO) 173 174X server basically wraps all the functions that touch VGA registers somehow. 175 176 177II. Credits 178=========== 179 180Benjamin Herrenschmidt (IBM?) started this work when he discussed such design 181with the Xorg community in 2005 [1, 2]. In the end of 2007, Paulo Zanoni and 182Tiago Vignatti (both of C3SL/Federal University of Paraná) proceeded his work 183enhancing the kernel code to adapt as a kernel module and also did the 184implementation of the user space side [3]. Now (2009) Tiago Vignatti and Dave 185Airlie finally put this work in shape and queued to Jesse Barnes' PCI tree. 186 187 188III. References 189============== 190 191[0] http://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347 192[1] http://lists.freedesktop.org/archives/xorg/2005-March/006663.html 193[2] http://lists.freedesktop.org/archives/xorg/2005-March/006745.html 194[3] http://lists.freedesktop.org/archives/xorg/2007-October/029507.html 195