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