doc/026-device-queues/devif.tex

94 	For example, what happens when a guest accesses a memory buffer that is handed off
104 		\item \textbf{Buffer}: A buffer is a chunk of memory within a region.
106 		\item \textbf{Ownership}: An endpoint can own a buffer and transfer ownership of a buffer to another endpoint or device.
107 		If an endpoint owns a buffer, it can alter it. If an endpoint alters a buffer that is not owned,
114 	A buffer is a variable sized piece of memory within a previously to the \devif interface
121 	queue on the stack can do an arbitrary transformation on the buffer that was enqueued
126 	has to be considered. In certain cases, a write to a buffer might not have been written back
127 	to memory before the buffer is processed by a device.
134 	hardware threads (multi-copy atomic). In most cases this is because of a write buffer
135 	that is introduced to buffer stores and the local request are satisfied by the contents
136 	of the buffer. TSO is still a very strict memory model and only allows limited instruction
202 	To deregister a region, every buffer of the region i.e. the whole region has to be
240 	Enqueues a buffer of a region for ownership transfer. The buffers offset into the memory region
243 	The length of the buffer must be large than 0 and must not
244 	exceed the region size minus the offset of the start address of the buffer within the
245 	region. The valid data offset has to be within the buffer and its length may not exceed
247 	The buffer has to be currently owned by the client i.e. a buffer
249 	Enqueueing a buffer does not directly transfer the ownership, but the client
250 	enqueueing the buffer has given up ownership on the buffer. Eventually the ownership
251 	of the buffer will be transferred but there is no guarantee when this happens.
252 	All the changes to the buffer have to be written back to memory and not only
253 	reside in the cache. Altering a buffer that a client has no ownership over,
255 	the argument \texttt{misc\_flags}. When chaining multiple buffers, the last buffer
275 		\item \texttt{regionid\_t region\_id}: the id of a memory region the enqueued buffer belongs to.
277 		\item \texttt{genoffset\_t length}: the length of the enqueued buffer.
278 		\item \texttt{genoffset\_t valid\_data}: the offset within the buffer where the valid data starts.
279 		\item \texttt{genoffset\_t valid\_length}: the length of the valid data within the buffer.
280 		\item \texttt{uint64\_t flags}: flags of the buffer.
287 		\item The buffer must be owned by the client of the interface
289 		\item The length must not exceed the region size minus the offset of the buffer within the region
292 		\item Changes to the buffer are written back to memory
305 		\item Bounds check for buffer fails
310 	Dequeues a buffer from the queue. After a buffer is dequeued, the client
311 	takes ownership of the buffer. As long as the client owns a buffer, the
312 	client can alter the contents of this buffer. Dequeue can be called any time,
315 	dequeues a buffer, it has to invalidate its cache of the received buffer when
317 	have to represent a valid buffer as well as point to valid data. If nothing
318 	is known about the validity of the data with the buffer, the whole buffer
336 		\item \texttt{regionid\_t* region\_id}: return pointer to the region id of the dequeued buffer.
338 		\item \texttt{genoffset\_t* length}: return pointer to the length of the enqueued buffer.
339 		\item \texttt{genoffset\_t* valid\_data}: return pointer to the offset within the buffer where the valid data starts.
340 		\item \texttt{genoffset\_t* valid\_length}: return pointer to the length of the valid data within the buffer.
341 		\item \texttt{uint64\_t flags}: flags of the buffer.
348 	The returned pointer have to contain valid information about a buffer.
358 		\item \textit{valid\_data} does not exceed the buffer size
359 		\item \textit{valid\_length} does not exceed buffer size minus valid data offset
371 	actually a buffer in the queue. When a buffer is enqueued, there
372 	is no guarantee to when the buffer is processed. Notify ensures, that
404 	define what a buffer is. This means in our model the smallest unit resource we transfer ownership
554 and a small generic library implementing the bookkeeping of region and buffer ids. The backend
664 to check for non valid buffer enqueues/deqeues that might happen and
667 An example of a not valid enqueue of a buffer is when the endpoint that enqueues
668 the buffer does not own the buffer.
675 If a buffer is enqueued, it has to be contained in one of these
676 memory chunks (otherwise the endpoint does not own the buffer).
677 The memory chunk is then altered according how the buffer is contained in the chunk.
679 If the buffer is in the middle of the chunk, we split the memory chunk
680 into two new memory chunks that do not contain the buffer. Simply put, the list contains the
683 If a buffer is dequeued the buffer is added to the existing memory
685 list of chunks. If a buffer is dequeued that is in between two
752 the solarflare card might lead to problems.} To send data using such a buffer, we need to know
753 for a region id the corresponding first entry of the buffer table. Since the buffer id is the
754 offset within the region, we can directly compute the buffer table entry if we store the index
755 of the first entry of the region. Further with the buffer id being the offset in the region, we
756 can compute offsets within a 4k buffer entry (supported by the NIC). If a buffer crosses
757 a 4k buffer entry boundary, the packet has to be fragmented into two descriptors in the ringbuffers.
759 	\caption{Translation from region id + buffer id to buffer table entry of the solarflare card}
765 \texttt{devq\_enqueue()} now, the region and buffer id are translated to an buffer table
767 \texttt{devq\_enqueue()} function are used to define if the buffer we enqueue is a receive
768 or send buffer. Additionally to the descriptor, we also write the buffer id, region id and
770 buffer table index to region and buffer id is not necessary on \texttt{devq\_dequeue()}.
793         // add a memory region to the buffer table
877             // there was an error i.e. retry enqueueing buffer
880            // there was an error i.e. retry enqueueing buffer