1 ===========
2 VGA Arbiter
3 ===========
4
5 Graphic devices are accessed through ranges in
6 modern devices allow relocation of such ranges
7 implemented on PCI will typically have the sam
8 they did on ISA. For more details see "PCI Bus
9 Standard for Boot (Initialization Configuratio
10 Section 7, Legacy Devices.
11
12 The Resource Access Control (RAC) module insid
13 the legacy VGA arbitration task (besides other
14 than one legacy device co-exists on the same m
15 when these devices are trying to be accessed b
16 (e.g. two server in parallel). Their address a
17 ideally, being a userspace application, it is
18 control bus resources. Therefore an arbitratio
19 is needed to control the sharing of these reso
20 the operation of the VGA arbiter implemented f
21
22 vgaarb kernel/userspace ABI
23 ---------------------------
24
25 The vgaarb is a module of the Linux Kernel. Wh
26 scans all PCI devices and adds the VGA ones in
27 arbiter then enables/disables the decoding on
28 legacy instructions. Devices which do not want
29 explicitly tell it by calling vga_set_legacy_d
30
31 The kernel exports a char device interface (/d
32 which has the following semantics:
33
34 open
35 Opens a user instance of the arbiter.
36 default VGA device of the system.
37
38 close
39 Close a user instance. Release locks m
40
41 read
42 Return a string indicating the status
43
44 "<card_ID>,decodes=<io_state>,owns=<io
45
46 An IO state string is of the form {io,
47 ic are respectively mem and io lock co
48 diagnostic only). "decodes" indicate w
49 decodes, "owns" indicates what is curr
50 "locks" indicates what is locked by th
51 unplugged, we get "invalid" then for c
52 error is returned for any command unti
53
54
55 write
56 Write a command to the arbiter. List o
57
58 target <card_ID>
59 switch target to card <card_ID
60 lock <io_state>
61 acquires locks on target ("non
62 trylock <io_state>
63 non-blocking acquire locks on
64 unsuccessful)
65 unlock <io_state>
66 release locks on target
67 unlock all
68 release all locks on target he
69 yet)
70 decodes <io_state>
71 set the legacy decoding attrib
72
73 poll
74 event if something changes on
75
76 card_ID is of the form "PCI:domain:bus
77 to go back to the system default card
78 only PCI is supported as a prefix, but
79 types in the future, even if the curre
80
81 Note about locks:
82
83 The driver keeps track of which user has which
84 supports stacking, like the kernel one. This c
85 a bit, but makes the arbiter more tolerant to
86 to properly cleanup in all cases when a proces
87 Currently, a max of 16 cards can have locks si
88 user space for a given user (file descriptor i
89
90 In the case of devices hot-{un,}plugged, there
91 notify them being added/removed in the system
92 in the arbiter.
93
94 There is also an in-kernel API of the arbiter
95 drivers want to use it.
96
97 In-kernel interface
98 -------------------
99
100 .. kernel-doc:: include/linux/vgaarb.h
101 :internal:
102
103 .. kernel-doc:: drivers/pci/vgaarb.c
104 :export:
105
106 libpciaccess
107 ------------
108
109 To use the vga arbiter char device it was impl
110 libpciaccess library. One field was added to s
111 on the system)::
112
113 /* the type of resource decoded by the dev
114 int vgaarb_rsrc;
115
116 Besides it, in pci_system were added::
117
118 int vgaarb_fd;
119 int vga_count;
120 struct pci_device *vga_target;
121 struct pci_device *vga_default_dev;
122
123 The vga_count is used to track how many cards
124 instance, if there is only one card, then it c
125
126 These functions below acquire VGA resources fo
127 resources as locked. If the resources requeste
128 resources, the arbiter will first check whethe
129 decoding for that type of resource. If yes, th
130 legacy resource lock. The arbiter will first l
131 might conflict and disable their IOs and/or Me
132 forwarding on P2P bridges if necessary, so tha
133 be used. Then, the card is marked as locking t
134 Memory access is enabled on the card (includin
135 P2P bridges if any). In the case of vga_arb_lo
136 if some conflicting card is already locking on
137 any resource on a different bus segment, since
138 VGA memory and IO afaik). If the card already
139 succeeds. vga_arb_trylock() will return (-EBU
140 calls are supported (a per-resource counter is
141
142 Set the target device of this client. ::
143
144 int pci_device_vgaarb_set_target (struc
145
146 For instance, in x86 if two devices on the sam
147 resources, both will succeed (lock). If device
148 trying to lock different resources, only the f
149
150 int pci_device_vgaarb_lock (void)
151 int pci_device_vgaarb_trylock (void)
152
153 Unlock resources of device. ::
154
155 int pci_device_vgaarb_unlock (void)
156
157 Indicates to the arbiter if the card decodes l
158 Memory, both, or none. All cards default to bo
159 example) should tell the arbiter if it has dis
160 card can be left out of the arbitration proces
161 interrupts at any time. ::
162
163 int pci_device_vgaarb_decodes (int n
164
165 Connects to the arbiter device, allocates the
166
167 int pci_device_vgaarb_init (void)
168
169 Close the connection ::
170
171 void pci_device_vgaarb_fini (void)
172
173 xf86VGAArbiter (X server implementation)
174 ----------------------------------------
175
176 X server basically wraps all the functions tha
177
178 References
179 ----------
180
181 Benjamin Herrenschmidt (IBM?) started this wor
182 with the Xorg community in 2005 [1, 2]. In the
183 Tiago Vignatti (both of C3SL/Federal Universit
184 enhancing the kernel code to adapt as a kernel
185 implementation of the user space side [3]. Now
186 Airlie finally put this work in shape and queu
187
188 0) https://cgit.freedesktop.org/xorg/xserver/c
189 1) https://lists.freedesktop.org/archives/xorg
190 2) https://lists.freedesktop.org/archives/xorg
191 3) https://lists.freedesktop.org/archives/xorg
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.