1607ca46eSDavid Howells #ifndef _UAPI_LINUX_VIRTIO_RING_H
2607ca46eSDavid Howells #define _UAPI_LINUX_VIRTIO_RING_H
3ecda85e7SJuergen Gross /* An interface for efficient virtio implementation, currently for use by KVM,
4ecda85e7SJuergen Gross * but hopefully others soon. Do NOT change this since it will
5607ca46eSDavid Howells * break existing servers and clients.
6607ca46eSDavid Howells *
7607ca46eSDavid Howells * This header is BSD licensed so anyone can use the definitions to implement
8607ca46eSDavid Howells * compatible drivers/servers.
9607ca46eSDavid Howells *
10607ca46eSDavid Howells * Redistribution and use in source and binary forms, with or without
11607ca46eSDavid Howells * modification, are permitted provided that the following conditions
12607ca46eSDavid Howells * are met:
13607ca46eSDavid Howells * 1. Redistributions of source code must retain the above copyright
14607ca46eSDavid Howells * notice, this list of conditions and the following disclaimer.
15607ca46eSDavid Howells * 2. Redistributions in binary form must reproduce the above copyright
16607ca46eSDavid Howells * notice, this list of conditions and the following disclaimer in the
17607ca46eSDavid Howells * documentation and/or other materials provided with the distribution.
18607ca46eSDavid Howells * 3. Neither the name of IBM nor the names of its contributors
19607ca46eSDavid Howells * may be used to endorse or promote products derived from this software
20607ca46eSDavid Howells * without specific prior written permission.
21607ca46eSDavid Howells * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND
22607ca46eSDavid Howells * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23607ca46eSDavid Howells * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24607ca46eSDavid Howells * ARE DISCLAIMED. IN NO EVENT SHALL IBM OR CONTRIBUTORS BE LIABLE
25607ca46eSDavid Howells * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26607ca46eSDavid Howells * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27607ca46eSDavid Howells * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28607ca46eSDavid Howells * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29607ca46eSDavid Howells * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30607ca46eSDavid Howells * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31607ca46eSDavid Howells * SUCH DAMAGE.
32607ca46eSDavid Howells *
33607ca46eSDavid Howells * Copyright Rusty Russell IBM Corporation 2007. */
34d768f32aSThomas Huth #ifndef __KERNEL__
35d768f32aSThomas Huth #include <stdint.h>
36d768f32aSThomas Huth #endif
37607ca46eSDavid Howells #include <linux/types.h>
38eef960a0SMichael S. Tsirkin #include <linux/virtio_types.h>
39607ca46eSDavid Howells
40607ca46eSDavid Howells /* This marks a buffer as continuing via the next field. */
41607ca46eSDavid Howells #define VRING_DESC_F_NEXT 1
42607ca46eSDavid Howells /* This marks a buffer as write-only (otherwise read-only). */
43607ca46eSDavid Howells #define VRING_DESC_F_WRITE 2
44607ca46eSDavid Howells /* This means the buffer contains a list of buffer descriptors. */
45607ca46eSDavid Howells #define VRING_DESC_F_INDIRECT 4
46607ca46eSDavid Howells
4789a9157eSTiwei Bie /*
4889a9157eSTiwei Bie * Mark a descriptor as available or used in packed ring.
4989a9157eSTiwei Bie * Notice: they are defined as shifts instead of shifted values.
5089a9157eSTiwei Bie */
5189a9157eSTiwei Bie #define VRING_PACKED_DESC_F_AVAIL 7
5289a9157eSTiwei Bie #define VRING_PACKED_DESC_F_USED 15
5389a9157eSTiwei Bie
54607ca46eSDavid Howells /* The Host uses this in used->flags to advise the Guest: don't kick me when
55607ca46eSDavid Howells * you add a buffer. It's unreliable, so it's simply an optimization. Guest
56607ca46eSDavid Howells * will still kick if it's out of buffers. */
57607ca46eSDavid Howells #define VRING_USED_F_NO_NOTIFY 1
58607ca46eSDavid Howells /* The Guest uses this in avail->flags to advise the Host: don't interrupt me
59607ca46eSDavid Howells * when you consume a buffer. It's unreliable, so it's simply an
60607ca46eSDavid Howells * optimization. */
61607ca46eSDavid Howells #define VRING_AVAIL_F_NO_INTERRUPT 1
62607ca46eSDavid Howells
6389a9157eSTiwei Bie /* Enable events in packed ring. */
6489a9157eSTiwei Bie #define VRING_PACKED_EVENT_FLAG_ENABLE 0x0
6589a9157eSTiwei Bie /* Disable events in packed ring. */
6689a9157eSTiwei Bie #define VRING_PACKED_EVENT_FLAG_DISABLE 0x1
6789a9157eSTiwei Bie /*
6889a9157eSTiwei Bie * Enable events for a specific descriptor in packed ring.
6989a9157eSTiwei Bie * (as specified by Descriptor Ring Change Event Offset/Wrap Counter).
7089a9157eSTiwei Bie * Only valid if VIRTIO_RING_F_EVENT_IDX has been negotiated.
7189a9157eSTiwei Bie */
7289a9157eSTiwei Bie #define VRING_PACKED_EVENT_FLAG_DESC 0x2
7389a9157eSTiwei Bie
7489a9157eSTiwei Bie /*
7589a9157eSTiwei Bie * Wrap counter bit shift in event suppression structure
7689a9157eSTiwei Bie * of packed ring.
7789a9157eSTiwei Bie */
7889a9157eSTiwei Bie #define VRING_PACKED_EVENT_F_WRAP_CTR 15
7989a9157eSTiwei Bie
80607ca46eSDavid Howells /* We support indirect buffer descriptors */
81607ca46eSDavid Howells #define VIRTIO_RING_F_INDIRECT_DESC 28
82607ca46eSDavid Howells
83607ca46eSDavid Howells /* The Guest publishes the used index for which it expects an interrupt
84607ca46eSDavid Howells * at the end of the avail ring. Host should ignore the avail->flags field. */
85607ca46eSDavid Howells /* The Host publishes the avail index for which it expects a kick
86607ca46eSDavid Howells * at the end of the used ring. Guest should ignore the used->flags field. */
87607ca46eSDavid Howells #define VIRTIO_RING_F_EVENT_IDX 29
88607ca46eSDavid Howells
89a865e420SMichael S. Tsirkin /* Alignment requirements for vring elements.
90a865e420SMichael S. Tsirkin * When using pre-virtio 1.0 layout, these fall out naturally.
91a865e420SMichael S. Tsirkin */
92a865e420SMichael S. Tsirkin #define VRING_AVAIL_ALIGN_SIZE 2
93a865e420SMichael S. Tsirkin #define VRING_USED_ALIGN_SIZE 4
94a865e420SMichael S. Tsirkin #define VRING_DESC_ALIGN_SIZE 16
95a865e420SMichael S. Tsirkin
96*5c669c4aSRicardo Cañuelo /**
97*5c669c4aSRicardo Cañuelo * struct vring_desc - Virtio ring descriptors,
98*5c669c4aSRicardo Cañuelo * 16 bytes long. These can chain together via @next.
99*5c669c4aSRicardo Cañuelo *
100*5c669c4aSRicardo Cañuelo * @addr: buffer address (guest-physical)
101*5c669c4aSRicardo Cañuelo * @len: buffer length
102*5c669c4aSRicardo Cañuelo * @flags: descriptor flags
103*5c669c4aSRicardo Cañuelo * @next: index of the next descriptor in the chain,
104*5c669c4aSRicardo Cañuelo * if the VRING_DESC_F_NEXT flag is set. We chain unused
105*5c669c4aSRicardo Cañuelo * descriptors via this, too.
106*5c669c4aSRicardo Cañuelo */
107607ca46eSDavid Howells struct vring_desc {
108eef960a0SMichael S. Tsirkin __virtio64 addr;
109eef960a0SMichael S. Tsirkin __virtio32 len;
110eef960a0SMichael S. Tsirkin __virtio16 flags;
111eef960a0SMichael S. Tsirkin __virtio16 next;
112607ca46eSDavid Howells };
113607ca46eSDavid Howells
114607ca46eSDavid Howells struct vring_avail {
115eef960a0SMichael S. Tsirkin __virtio16 flags;
116eef960a0SMichael S. Tsirkin __virtio16 idx;
117eef960a0SMichael S. Tsirkin __virtio16 ring[];
118607ca46eSDavid Howells };
119607ca46eSDavid Howells
120607ca46eSDavid Howells /* u32 is used here for ids for padding reasons. */
121607ca46eSDavid Howells struct vring_used_elem {
122607ca46eSDavid Howells /* Index of start of used descriptor chain. */
123eef960a0SMichael S. Tsirkin __virtio32 id;
124607ca46eSDavid Howells /* Total length of the descriptor chain which was used (written to) */
125eef960a0SMichael S. Tsirkin __virtio32 len;
126607ca46eSDavid Howells };
127607ca46eSDavid Howells
128a865e420SMichael S. Tsirkin typedef struct vring_used_elem __attribute__((aligned(VRING_USED_ALIGN_SIZE)))
129a865e420SMichael S. Tsirkin vring_used_elem_t;
130a865e420SMichael S. Tsirkin
131607ca46eSDavid Howells struct vring_used {
132eef960a0SMichael S. Tsirkin __virtio16 flags;
133eef960a0SMichael S. Tsirkin __virtio16 idx;
134a865e420SMichael S. Tsirkin vring_used_elem_t ring[];
135607ca46eSDavid Howells };
136607ca46eSDavid Howells
137a865e420SMichael S. Tsirkin /*
138a865e420SMichael S. Tsirkin * The ring element addresses are passed between components with different
139a865e420SMichael S. Tsirkin * alignments assumptions. Thus, we might need to decrease the compiler-selected
140a865e420SMichael S. Tsirkin * alignment, and so must use a typedef to make sure the aligned attribute
141a865e420SMichael S. Tsirkin * actually takes hold:
142a865e420SMichael S. Tsirkin *
143a865e420SMichael S. Tsirkin * https://gcc.gnu.org/onlinedocs//gcc/Common-Type-Attributes.html#Common-Type-Attributes
144a865e420SMichael S. Tsirkin *
145a865e420SMichael S. Tsirkin * When used on a struct, or struct member, the aligned attribute can only
146a865e420SMichael S. Tsirkin * increase the alignment; in order to decrease it, the packed attribute must
147a865e420SMichael S. Tsirkin * be specified as well. When used as part of a typedef, the aligned attribute
148a865e420SMichael S. Tsirkin * can both increase and decrease alignment, and specifying the packed
149a865e420SMichael S. Tsirkin * attribute generates a warning.
150a865e420SMichael S. Tsirkin */
151a865e420SMichael S. Tsirkin typedef struct vring_desc __attribute__((aligned(VRING_DESC_ALIGN_SIZE)))
152a865e420SMichael S. Tsirkin vring_desc_t;
153a865e420SMichael S. Tsirkin typedef struct vring_avail __attribute__((aligned(VRING_AVAIL_ALIGN_SIZE)))
154a865e420SMichael S. Tsirkin vring_avail_t;
155a865e420SMichael S. Tsirkin typedef struct vring_used __attribute__((aligned(VRING_USED_ALIGN_SIZE)))
156a865e420SMichael S. Tsirkin vring_used_t;
157a865e420SMichael S. Tsirkin
158607ca46eSDavid Howells struct vring {
159607ca46eSDavid Howells unsigned int num;
160607ca46eSDavid Howells
161a865e420SMichael S. Tsirkin vring_desc_t *desc;
162607ca46eSDavid Howells
163a865e420SMichael S. Tsirkin vring_avail_t *avail;
164607ca46eSDavid Howells
165a865e420SMichael S. Tsirkin vring_used_t *used;
166607ca46eSDavid Howells };
167607ca46eSDavid Howells
168e7c8cc35SMatej Genci #ifndef VIRTIO_RING_NO_LEGACY
169e7c8cc35SMatej Genci
170607ca46eSDavid Howells /* The standard layout for the ring is a continuous chunk of memory which looks
171607ca46eSDavid Howells * like this. We assume num is a power of 2.
172607ca46eSDavid Howells *
173607ca46eSDavid Howells * struct vring
174607ca46eSDavid Howells * {
175607ca46eSDavid Howells * // The actual descriptors (16 bytes each)
176607ca46eSDavid Howells * struct vring_desc desc[num];
177607ca46eSDavid Howells *
178607ca46eSDavid Howells * // A ring of available descriptor heads with free-running index.
179eef960a0SMichael S. Tsirkin * __virtio16 avail_flags;
180eef960a0SMichael S. Tsirkin * __virtio16 avail_idx;
181eef960a0SMichael S. Tsirkin * __virtio16 available[num];
182eef960a0SMichael S. Tsirkin * __virtio16 used_event_idx;
183607ca46eSDavid Howells *
184607ca46eSDavid Howells * // Padding to the next align boundary.
185607ca46eSDavid Howells * char pad[];
186607ca46eSDavid Howells *
187607ca46eSDavid Howells * // A ring of used descriptor heads with free-running index.
188eef960a0SMichael S. Tsirkin * __virtio16 used_flags;
189eef960a0SMichael S. Tsirkin * __virtio16 used_idx;
190607ca46eSDavid Howells * struct vring_used_elem used[num];
191eef960a0SMichael S. Tsirkin * __virtio16 avail_event_idx;
192607ca46eSDavid Howells * };
193607ca46eSDavid Howells */
194607ca46eSDavid Howells /* We publish the used event index at the end of the available ring, and vice
195607ca46eSDavid Howells * versa. They are at the end for backwards compatibility. */
196607ca46eSDavid Howells #define vring_used_event(vr) ((vr)->avail->ring[(vr)->num])
197eef960a0SMichael S. Tsirkin #define vring_avail_event(vr) (*(__virtio16 *)&(vr)->used->ring[(vr)->num])
198607ca46eSDavid Howells
vring_init(struct vring * vr,unsigned int num,void * p,unsigned long align)199607ca46eSDavid Howells static inline void vring_init(struct vring *vr, unsigned int num, void *p,
200607ca46eSDavid Howells unsigned long align)
201607ca46eSDavid Howells {
202607ca46eSDavid Howells vr->num = num;
203607ca46eSDavid Howells vr->desc = p;
204d6547f2aSAlexey Dobriyan vr->avail = (struct vring_avail *)((char *)p + num * sizeof(struct vring_desc));
205d768f32aSThomas Huth vr->used = (void *)(((uintptr_t)&vr->avail->ring[num] + sizeof(__virtio16)
206607ca46eSDavid Howells + align-1) & ~(align - 1));
207607ca46eSDavid Howells }
208607ca46eSDavid Howells
vring_size(unsigned int num,unsigned long align)209607ca46eSDavid Howells static inline unsigned vring_size(unsigned int num, unsigned long align)
210607ca46eSDavid Howells {
211eef960a0SMichael S. Tsirkin return ((sizeof(struct vring_desc) * num + sizeof(__virtio16) * (3 + num)
212607ca46eSDavid Howells + align - 1) & ~(align - 1))
213eef960a0SMichael S. Tsirkin + sizeof(__virtio16) * 3 + sizeof(struct vring_used_elem) * num;
214607ca46eSDavid Howells }
215607ca46eSDavid Howells
216e7c8cc35SMatej Genci #endif /* VIRTIO_RING_NO_LEGACY */
217e7c8cc35SMatej Genci
218607ca46eSDavid Howells /* The following is used with USED_EVENT_IDX and AVAIL_EVENT_IDX */
219e412d3a3SStefan Hajnoczi /* Assuming a given event_idx value from the other side, if
220607ca46eSDavid Howells * we have just incremented index from old to new_idx,
221607ca46eSDavid Howells * should we trigger an event? */
vring_need_event(__u16 event_idx,__u16 new_idx,__u16 old)222607ca46eSDavid Howells static inline int vring_need_event(__u16 event_idx, __u16 new_idx, __u16 old)
223607ca46eSDavid Howells {
224607ca46eSDavid Howells /* Note: Xen has similar logic for notification hold-off
225607ca46eSDavid Howells * in include/xen/interface/io/ring.h with req_event and req_prod
226607ca46eSDavid Howells * corresponding to event_idx + 1 and new_idx respectively.
227607ca46eSDavid Howells * Note also that req_event and req_prod in Xen start at 1,
228607ca46eSDavid Howells * event indexes in virtio start at 0. */
229607ca46eSDavid Howells return (__u16)(new_idx - event_idx - 1) < (__u16)(new_idx - old);
230607ca46eSDavid Howells }
231607ca46eSDavid Howells
23289a9157eSTiwei Bie struct vring_packed_desc_event {
23389a9157eSTiwei Bie /* Descriptor Ring Change Event Offset/Wrap Counter. */
23489a9157eSTiwei Bie __le16 off_wrap;
23589a9157eSTiwei Bie /* Descriptor Ring Change Event Flags. */
23689a9157eSTiwei Bie __le16 flags;
23789a9157eSTiwei Bie };
23889a9157eSTiwei Bie
23989a9157eSTiwei Bie struct vring_packed_desc {
24089a9157eSTiwei Bie /* Buffer Address. */
24189a9157eSTiwei Bie __le64 addr;
24289a9157eSTiwei Bie /* Buffer Length. */
24389a9157eSTiwei Bie __le32 len;
24489a9157eSTiwei Bie /* Buffer ID. */
24589a9157eSTiwei Bie __le16 id;
24689a9157eSTiwei Bie /* The flags depending on descriptor type. */
24789a9157eSTiwei Bie __le16 flags;
24889a9157eSTiwei Bie };
24989a9157eSTiwei Bie
250607ca46eSDavid Howells #endif /* _UAPI_LINUX_VIRTIO_RING_H */
251