vhost

overlay/virtqueue/available_ring.go

@@ -0,0 +1,140 @@
+package virtqueue
+
+import (
+	"fmt"
+	"unsafe"
+)
+
+// availableRingFlag is a flag that describes an [AvailableRing].
+type availableRingFlag uint16
+
+const (
+	// availableRingFlagNoInterrupt is used by the guest to advise the host to
+	// not interrupt it when consuming a buffer. It's unreliable, so it's simply
+	// an optimization.
+	availableRingFlagNoInterrupt availableRingFlag = 1 << iota
+)
+
+// availableRingSize is the number of bytes needed to store an [AvailableRing]
+// with the given queue size in memory.
+func availableRingSize(queueSize int) int {
+	return 6 + 2*queueSize
+}
+
+// availableRingAlignment is the minimum alignment of an [AvailableRing]
+// in memory, as required by the virtio spec.
+const availableRingAlignment = 2
+
+// AvailableRing is used by the driver to offer descriptor chains to the device.
+// Each ring entry refers to the head of a descriptor chain. It is only written
+// to by the driver and read by the device.
+//
+// Because the size of the ring depends on the queue size, we cannot define a
+// Go struct with a static size that maps to the memory of the ring. Instead,
+// this struct only contains pointers to the corresponding memory areas.
+type AvailableRing struct {
+	initialized bool
+
+	// flags that describe this ring.
+	flags *availableRingFlag
+	// ringIndex indicates where the driver would put the next entry into the
+	// ring (modulo the queue size).
+	ringIndex *uint16
+	// ring references buffers using the index of the head of the descriptor
+	// chain in the [DescriptorTable]. It wraps around at queue size.
+	ring []uint16
+	// usedEvent is not used by this implementation, but we reserve it anyway to
+	// avoid issues in case a device may try to access it, contrary to the
+	// virtio specification.
+	usedEvent *uint16
+}
+
+// newAvailableRing creates an available ring that uses the given underlying
+// memory. The length of the memory slice must match the size needed for the
+// ring (see [availableRingSize]) for the given queue size.
+func newAvailableRing(queueSize int, mem []byte) *AvailableRing {
+	ringSize := availableRingSize(queueSize)
+	if len(mem) != ringSize {
+		panic(fmt.Sprintf("memory size (%v) does not match required size "+
+			"for available ring: %v", len(mem), ringSize))
+	}
+
+	return &AvailableRing{
+		initialized: true,
+		flags:       (*availableRingFlag)(unsafe.Pointer(&mem[0])),
+		ringIndex:   (*uint16)(unsafe.Pointer(&mem[2])),
+		ring:        unsafe.Slice((*uint16)(unsafe.Pointer(&mem[4])), queueSize),
+		usedEvent:   (*uint16)(unsafe.Pointer(&mem[ringSize-2])),
+	}
+}
+
+// Address returns the pointer to the beginning of the ring in memory.
+// Do not modify the memory directly to not interfere with this implementation.
+func (r *AvailableRing) Address() uintptr {
+	if !r.initialized {
+		panic("available ring is not initialized")
+	}
+	return uintptr(unsafe.Pointer(r.flags))
+}
+
+// offer adds the given descriptor chain heads to the available ring and
+// advances the ring index accordingly to make the device process the new
+// descriptor chains.
+func (r *AvailableRing) offerElements(chains []UsedElement) {
+	//always called under lock
+	//r.mu.Lock()
+	//defer r.mu.Unlock()
+
+	// Add descriptor chain heads to the ring.
+	for offset, x := range chains {
+		// The 16-bit ring index may overflow. This is expected and is not an
+		// issue because the size of the ring array (which equals the queue
+		// size) is always a power of 2 and smaller than the highest possible
+		// 16-bit value.
+		insertIndex := int(*r.ringIndex+uint16(offset)) % len(r.ring)
+		r.ring[insertIndex] = x.GetHead()
+	}
+
+	// Increase the ring index by the number of descriptor chains added to the
+	// ring.
+	*r.ringIndex += uint16(len(chains))
+}
+
+func (r *AvailableRing) offer(chains []uint16) {
+	//always called under lock
+	//r.mu.Lock()
+	//defer r.mu.Unlock()
+
+	// Add descriptor chain heads to the ring.
+	for offset, x := range chains {
+		// The 16-bit ring index may overflow. This is expected and is not an
+		// issue because the size of the ring array (which equals the queue
+		// size) is always a power of 2 and smaller than the highest possible
+		// 16-bit value.
+		insertIndex := int(*r.ringIndex+uint16(offset)) % len(r.ring)
+		r.ring[insertIndex] = x
+	}
+
+	// Increase the ring index by the number of descriptor chains added to the
+	// ring.
+	*r.ringIndex += uint16(len(chains))
+}
+
+func (r *AvailableRing) offerSingle(x uint16) {
+	//always called under lock
+	//r.mu.Lock()
+	//defer r.mu.Unlock()
+
+	offset := 0
+	// Add descriptor chain heads to the ring.
+
+	// The 16-bit ring index may overflow. This is expected and is not an
+	// issue because the size of the ring array (which equals the queue
+	// size) is always a power of 2 and smaller than the highest possible
+	// 16-bit value.
+	insertIndex := int(*r.ringIndex+uint16(offset)) % len(r.ring)
+	r.ring[insertIndex] = x
+
+	// Increase the ring index by the number of descriptor chains added to the ring.
+	*r.ringIndex += 1
+}