X-Git-Url: https://gerrit.fd.io/r/gitweb?a=blobdiff_plain;f=src%2Fsvm%2Fsvm_fifo.h;h=93ef006fd48f8418fc51c950edaa1a6ed5d504e9;hb=d68faf8559da72aa6ad0526d5a86fb16587b1508;hp=8d5e48033604e21ef5023846ef0b7fd6a62cc019;hpb=f22f4e562e1b922cff036ef628b77fd2d479d015;p=vpp.git

diff --git a/src/svm/svm_fifo.h b/src/svm/svm_fifo.h
index 8d5e4803360..93ef006fd48 100644
--- a/src/svm/svm_fifo.h
+++ b/src/svm/svm_fifo.h
@@ -200,16 +200,19 @@ void svm_fifo_init (svm_fifo_t * f, u32 size);
  */
 svm_fifo_chunk_t *svm_fifo_chunk_alloc (u32 size);
 /**
- * Grow fifo size by adding chunk to chunk list
+ * Ensure the whole fifo size is writeable
  *
- * If fifos are allocated on a segment, this should be called with
- * the segment's heap pushed.
+ * Allocates enough chunks to cover the whole fifo size.
  *
- * @param f	fifo to be extended
- * @param c 	chunk or linked list of chunks to be added
+ * @param f	fifo
  */
-void svm_fifo_add_chunk (svm_fifo_t * f, svm_fifo_chunk_t * c);
 int svm_fifo_fill_chunk_list (svm_fifo_t * f);
+/**
+ * Initialize rbtrees used for ooo lookups
+ *
+ * @param f		fifo
+ * @param ooo_type	type of ooo operation (0 enqueue, 1 dequeue)
+ */
 void svm_fifo_init_ooo_lookup (svm_fifo_t * f, u8 ooo_type);
 /**
  * Free fifo and associated state
@@ -292,7 +295,7 @@ void svm_fifo_enqueue_nocopy (svm_fifo_t * f, u32 len);
  * Overwrite fifo head with new data
  *
  * This should be typically used by dgram transport protocols that need
- * to update the dgram header after dequeueing a chunk of data. It assumes
+ * to update the dgram header after dequeuing a chunk of data. It assumes
  * that the dgram header is at most spread over two chunks.
  *
  * @param f		fifo
@@ -304,7 +307,9 @@ void svm_fifo_overwrite_head (svm_fifo_t * f, u8 * src, u32 len);
  * Dequeue data from fifo
  *
  * Data is dequeued to consumer provided buffer and head is atomically
- * updated.
+ * updated. This should not be used in combination with ooo lookups. If
+ * ooo peeking of data is needed in combination with dequeuing use @ref
+ * svm_fifo_dequeue_drop.
  *
  * @param f		fifo
  * @param len		length of data to dequeue
@@ -343,8 +348,22 @@ int svm_fifo_dequeue_drop (svm_fifo_t * f, u32 len);
  * @param f		fifo
  */
 void svm_fifo_dequeue_drop_all (svm_fifo_t * f);
-int svm_fifo_segments (svm_fifo_t * f, svm_fifo_seg_t * fs);
-void svm_fifo_segments_free (svm_fifo_t * f, svm_fifo_seg_t * fs);
+/**
+ * Get pointers to fifo chunks data in @ref svm_fifo_seg_t array
+ *
+ * Populates fifo segment array with pointers to fifo chunk data and lengths.
+ * Because this returns pointers to data, it must be paired with
+ * @ref svm_fifo_dequeue_drop to actually release the fifo chunks after the
+ * data is consumed.
+ *
+ * @param f		fifo
+ * @param fs		array of fifo segments allocated by caller
+ * @param n_segs	number of fifo segments in array
+ * @param max_bytes	max bytes to be mapped to fifo segments
+ * @return 		number of bytes in fifo segments or SVM_FIFO_EEMPTY
+ */
+int svm_fifo_segments (svm_fifo_t * f, svm_fifo_seg_t * fs, u32 n_segs,
+		       u32 max_bytes);
 /**
  * Add io events subscriber to list
  *
@@ -380,6 +399,12 @@ ooo_segment_t *svm_fifo_first_ooo_segment (svm_fifo_t * f);
  * @return 	1 if sane, 0 otherwise
  */
 u8 svm_fifo_is_sane (svm_fifo_t * f);
+/**
+ * Number of chunks linked into the fifo
+ *
+ * @param f	fifo
+ * @return 	number of chunks in fifo linked list
+ */
 u32 svm_fifo_n_chunks (svm_fifo_t * f);
 format_function_t format_svm_fifo;
 
@@ -545,12 +570,24 @@ u32 svm_fifo_max_read_chunk (svm_fifo_t * f);
  */
 u32 svm_fifo_max_write_chunk (svm_fifo_t * f);
 
+/**
+ * Fifo head chunk getter
+ *
+ * @param f	fifo
+ * @return	head chunk pointer
+ */
 static inline svm_fifo_chunk_t *
 svm_fifo_head_chunk (svm_fifo_t * f)
 {
   return f->head_chunk;
 }
 
+/**
+ * Fifo head pointer getter
+ *
+ * @param f	fifo
+ * @return	head pointer
+ */
 static inline u8 *
 svm_fifo_head (svm_fifo_t * f)
 {
@@ -560,12 +597,24 @@ svm_fifo_head (svm_fifo_t * f)
   return (f->head_chunk->data + (f->head - f->head_chunk->start_byte));
 }
 
+/**
+ * Fifo tail chunk getter
+ *
+ * @param f	fifo
+ * @return	tail chunk pointer
+ */
 static inline svm_fifo_chunk_t *
 svm_fifo_tail_chunk (svm_fifo_t * f)
 {
   return f->tail_chunk;
 }
 
+/**
+ * Fifo tail pointer getter
+ *
+ * @param f	fifo
+ * @return	tail pointer
+ */
 static inline u8 *
 svm_fifo_tail (svm_fifo_t * f)
 {
@@ -573,6 +622,12 @@ svm_fifo_tail (svm_fifo_t * f)
   return (f->tail_chunk->data + (f->tail - f->tail_chunk->start_byte));
 }
 
+/**
+ * Fifo number of subscribers getter
+ *
+ * @param f	fifo
+ * @return	number of subscribers
+ */
 static inline u8
 svm_fifo_n_subscribers (svm_fifo_t * f)
 {
@@ -630,6 +685,9 @@ svm_fifo_size (svm_fifo_t * f)
 static inline void
 svm_fifo_set_size (svm_fifo_t * f, u32 size)
 {
+  if (size > (1 << f->fs_hdr->max_log2_chunk_size))
+    return;
+  fsh_virtual_mem_update (f->fs_hdr, f->slice_index, (int) f->size - size);
   f->size = size;
 }