1 /** @file
2
3 Utility functions used by virtio device drivers.
4
5 Copyright (C) 2012, Red Hat, Inc.
6 Portion of Copyright (C) 2013, ARM Ltd.
7
8 This program and the accompanying materials are licensed and made available
9 under the terms and conditions of the BSD License which accompanies this
10 distribution. The full text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php
12
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
14 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15
16 **/
17
18 #include <Library/BaseLib.h>
19 #include <Library/BaseMemoryLib.h>
20 #include <Library/DebugLib.h>
21 #include <Library/MemoryAllocationLib.h>
22 #include <Library/UefiBootServicesTableLib.h>
23
24 #include <Library/VirtioLib.h>
25
26
27 /**
28
29 Configure a virtio ring.
30
31 This function sets up internal storage (the guest-host communication area)
32 and lays out several "navigation" (ie. no-ownership) pointers to parts of
33 that storage.
34
35 Relevant sections from the virtio-0.9.5 spec:
36 - 1.1 Virtqueues,
37 - 2.3 Virtqueue Configuration.
38
39 @param[in] The number of descriptors to allocate for the
40 virtio ring, as requested by the host.
41
42 @param[out] Ring The virtio ring to set up.
43
44 @retval EFI_OUT_OF_RESOURCES AllocatePages() failed to allocate contiguous
45 pages for the requested QueueSize. Fields of
46 Ring have indeterminate value.
47
48 @retval EFI_SUCCESS Allocation and setup successful. Ring->Base
49 (and nothing else) is responsible for
50 deallocation.
51
52 **/
53 EFI_STATUS
54 EFIAPI
VirtioRingInit(IN UINT16 QueueSize,OUT VRING * Ring)55 VirtioRingInit (
56 IN UINT16 QueueSize,
57 OUT VRING *Ring
58 )
59 {
60 UINTN RingSize;
61 volatile UINT8 *RingPagesPtr;
62
63 RingSize = ALIGN_VALUE (
64 sizeof *Ring->Desc * QueueSize +
65 sizeof *Ring->Avail.Flags +
66 sizeof *Ring->Avail.Idx +
67 sizeof *Ring->Avail.Ring * QueueSize +
68 sizeof *Ring->Avail.UsedEvent,
69 EFI_PAGE_SIZE);
70
71 RingSize += ALIGN_VALUE (
72 sizeof *Ring->Used.Flags +
73 sizeof *Ring->Used.Idx +
74 sizeof *Ring->Used.UsedElem * QueueSize +
75 sizeof *Ring->Used.AvailEvent,
76 EFI_PAGE_SIZE);
77
78 Ring->NumPages = EFI_SIZE_TO_PAGES (RingSize);
79 Ring->Base = AllocatePages (Ring->NumPages);
80 if (Ring->Base == NULL) {
81 return EFI_OUT_OF_RESOURCES;
82 }
83 SetMem (Ring->Base, RingSize, 0x00);
84 RingPagesPtr = Ring->Base;
85
86 Ring->Desc = (volatile VOID *) RingPagesPtr;
87 RingPagesPtr += sizeof *Ring->Desc * QueueSize;
88
89 Ring->Avail.Flags = (volatile VOID *) RingPagesPtr;
90 RingPagesPtr += sizeof *Ring->Avail.Flags;
91
92 Ring->Avail.Idx = (volatile VOID *) RingPagesPtr;
93 RingPagesPtr += sizeof *Ring->Avail.Idx;
94
95 Ring->Avail.Ring = (volatile VOID *) RingPagesPtr;
96 RingPagesPtr += sizeof *Ring->Avail.Ring * QueueSize;
97
98 Ring->Avail.UsedEvent = (volatile VOID *) RingPagesPtr;
99 RingPagesPtr += sizeof *Ring->Avail.UsedEvent;
100
101 RingPagesPtr = (volatile UINT8 *) Ring->Base +
102 ALIGN_VALUE (RingPagesPtr - (volatile UINT8 *) Ring->Base,
103 EFI_PAGE_SIZE);
104
105 Ring->Used.Flags = (volatile VOID *) RingPagesPtr;
106 RingPagesPtr += sizeof *Ring->Used.Flags;
107
108 Ring->Used.Idx = (volatile VOID *) RingPagesPtr;
109 RingPagesPtr += sizeof *Ring->Used.Idx;
110
111 Ring->Used.UsedElem = (volatile VOID *) RingPagesPtr;
112 RingPagesPtr += sizeof *Ring->Used.UsedElem * QueueSize;
113
114 Ring->Used.AvailEvent = (volatile VOID *) RingPagesPtr;
115 RingPagesPtr += sizeof *Ring->Used.AvailEvent;
116
117 Ring->QueueSize = QueueSize;
118 return EFI_SUCCESS;
119 }
120
121
122 /**
123
124 Tear down the internal resources of a configured virtio ring.
125
126 The caller is responsible to stop the host from using this ring before
127 invoking this function: the VSTAT_DRIVER_OK bit must be clear in
128 VhdrDeviceStatus.
129
130 @param[out] Ring The virtio ring to clean up.
131
132 **/
133 VOID
134 EFIAPI
VirtioRingUninit(IN OUT VRING * Ring)135 VirtioRingUninit (
136 IN OUT VRING *Ring
137 )
138 {
139 FreePages (Ring->Base, Ring->NumPages);
140 SetMem (Ring, sizeof *Ring, 0x00);
141 }
142
143
144 /**
145
146 Turn off interrupt notifications from the host, and prepare for appending
147 multiple descriptors to the virtio ring.
148
149 The calling driver must be in VSTAT_DRIVER_OK state.
150
151 @param[in,out] Ring The virtio ring we intend to append descriptors to.
152
153 @param[out] Indices The DESC_INDICES structure to initialize.
154
155 **/
156 VOID
157 EFIAPI
VirtioPrepare(IN OUT VRING * Ring,OUT DESC_INDICES * Indices)158 VirtioPrepare (
159 IN OUT VRING *Ring,
160 OUT DESC_INDICES *Indices
161 )
162 {
163 //
164 // Prepare for virtio-0.9.5, 2.4.2 Receiving Used Buffers From the Device.
165 // We're going to poll the answer, the host should not send an interrupt.
166 //
167 *Ring->Avail.Flags = (UINT16) VRING_AVAIL_F_NO_INTERRUPT;
168
169 //
170 // Prepare for virtio-0.9.5, 2.4.1 Supplying Buffers to the Device.
171 //
172 // Since we support only one in-flight descriptor chain, we can always build
173 // that chain starting at entry #0 of the descriptor table.
174 //
175 Indices->HeadDescIdx = 0;
176 Indices->NextDescIdx = Indices->HeadDescIdx;
177 }
178
179
180 /**
181
182 Append a contiguous buffer for transmission / reception via the virtio ring.
183
184 This function implements the following section from virtio-0.9.5:
185 - 2.4.1.1 Placing Buffers into the Descriptor Table
186
187 Free space is taken as granted, since the individual drivers support only
188 synchronous requests and host side status is processed in lock-step with
189 request submission. It is the calling driver's responsibility to verify the
190 ring size in advance.
191
192 The caller is responsible for initializing *Indices with VirtioPrepare()
193 first.
194
195 @param[in,out] Ring The virtio ring to append the buffer to, as a
196 descriptor.
197
198 @param[in] BufferPhysAddr (Guest pseudo-physical) start address of the
199 transmit / receive buffer.
200
201 @param[in] BufferSize Number of bytes to transmit or receive.
202
203 @param[in] Flags A bitmask of VRING_DESC_F_* flags. The caller
204 computes this mask dependent on further buffers to
205 append and transfer direction.
206 VRING_DESC_F_INDIRECT is unsupported. The
207 VRING_DESC.Next field is always set, but the host
208 only interprets it dependent on VRING_DESC_F_NEXT.
209
210 @param[in,out] Indices Indices->HeadDescIdx is not accessed.
211 On input, Indices->NextDescIdx identifies the next
212 descriptor to carry the buffer. On output,
213 Indices->NextDescIdx is incremented by one, modulo
214 2^16.
215
216 **/
217 VOID
218 EFIAPI
VirtioAppendDesc(IN OUT VRING * Ring,IN UINTN BufferPhysAddr,IN UINT32 BufferSize,IN UINT16 Flags,IN OUT DESC_INDICES * Indices)219 VirtioAppendDesc (
220 IN OUT VRING *Ring,
221 IN UINTN BufferPhysAddr,
222 IN UINT32 BufferSize,
223 IN UINT16 Flags,
224 IN OUT DESC_INDICES *Indices
225 )
226 {
227 volatile VRING_DESC *Desc;
228
229 Desc = &Ring->Desc[Indices->NextDescIdx++ % Ring->QueueSize];
230 Desc->Addr = BufferPhysAddr;
231 Desc->Len = BufferSize;
232 Desc->Flags = Flags;
233 Desc->Next = Indices->NextDescIdx % Ring->QueueSize;
234 }
235
236
237 /**
238
239 Notify the host about the descriptor chain just built, and wait until the
240 host processes it.
241
242 @param[in] VirtIo The target virtio device to notify.
243
244 @param[in] VirtQueueId Identifies the queue for the target device.
245
246 @param[in,out] Ring The virtio ring with descriptors to submit.
247
248 @param[in] Indices Indices->NextDescIdx is not accessed.
249 Indices->HeadDescIdx identifies the head descriptor
250 of the descriptor chain.
251
252
253 @return Error code from VirtIo->SetQueueNotify() if it fails.
254
255 @retval EFI_SUCCESS Otherwise, the host processed all descriptors.
256
257 **/
258 EFI_STATUS
259 EFIAPI
VirtioFlush(IN VIRTIO_DEVICE_PROTOCOL * VirtIo,IN UINT16 VirtQueueId,IN OUT VRING * Ring,IN DESC_INDICES * Indices)260 VirtioFlush (
261 IN VIRTIO_DEVICE_PROTOCOL *VirtIo,
262 IN UINT16 VirtQueueId,
263 IN OUT VRING *Ring,
264 IN DESC_INDICES *Indices
265 )
266 {
267 UINT16 NextAvailIdx;
268 EFI_STATUS Status;
269 UINTN PollPeriodUsecs;
270
271 //
272 // virtio-0.9.5, 2.4.1.2 Updating the Available Ring
273 //
274 // It is not exactly clear from the wording of the virtio-0.9.5
275 // specification, but each entry in the Available Ring references only the
276 // head descriptor of any given descriptor chain.
277 //
278 NextAvailIdx = *Ring->Avail.Idx;
279 Ring->Avail.Ring[NextAvailIdx++ % Ring->QueueSize] =
280 Indices->HeadDescIdx % Ring->QueueSize;
281
282 //
283 // virtio-0.9.5, 2.4.1.3 Updating the Index Field
284 //
285 MemoryFence();
286 *Ring->Avail.Idx = NextAvailIdx;
287
288 //
289 // virtio-0.9.5, 2.4.1.4 Notifying the Device -- gratuitous notifications are
290 // OK.
291 //
292 MemoryFence();
293 Status = VirtIo->SetQueueNotify (VirtIo, VirtQueueId);
294 if (EFI_ERROR (Status)) {
295 return Status;
296 }
297
298 //
299 // virtio-0.9.5, 2.4.2 Receiving Used Buffers From the Device
300 // Wait until the host processes and acknowledges our descriptor chain. The
301 // condition we use for polling is greatly simplified and relies on the
302 // synchronous, lock-step progress.
303 //
304 // Keep slowing down until we reach a poll period of slightly above 1 ms.
305 //
306 PollPeriodUsecs = 1;
307 MemoryFence();
308 while (*Ring->Used.Idx != NextAvailIdx) {
309 gBS->Stall (PollPeriodUsecs); // calls AcpiTimerLib::MicroSecondDelay
310
311 if (PollPeriodUsecs < 1024) {
312 PollPeriodUsecs *= 2;
313 }
314 MemoryFence();
315 }
316
317 MemoryFence();
318 return EFI_SUCCESS;
319 }
320