pipeline: add new functions for action handlers

[dpdk.git] / lib / librte_pipeline / rte_pipeline.h

diff --git a/lib/librte_pipeline/rte_pipeline.h b/lib/librte_pipeline/rte_pipeline.h
index 0b02969..84d1802 100644 (file)
--- a/lib/librte_pipeline/rte_pipeline.h
+++ b/lib/librte_pipeline/rte_pipeline.h
@@ -759,14 +759,38 @@ int rte_pipeline_port_out_create(struct rte_pipeline *p,
        uint32_t *port_id);
 
 /**
- * Pipeline output port packet insert
+ * Read pipeline port out stats.
+ *
+ * This function reads port out statistics identified by *port_id* of given
+ * pipeline *p*.
+ *
+ * @param p
+ *   Handle to pipeline instance.
+ * @param port_id
+ *   Port ID what stats will be returned.
+ * @param stats
+ *   Statistics buffer.
+ * @param clear
+ *   If not 0 clear stats after reading.
+ * @return
+ *   0 on success, error code otherwise
+ */
+int rte_pipeline_port_out_stats_read(struct rte_pipeline *p, uint32_t port_id,
+       struct rte_pipeline_port_out_stats *stats, int clear);
+
+/*
+ * Functions to be called as part of the port IN/OUT or table action handlers
  *
- * This function is called by the table action handler whenever it generates a
- * new packet to be sent out though one of the pipeline output ports. This
- * packet is not part of the burst of input packets read from any of the
- * pipeline input ports, so it is not an element of the pkts array input
- * parameter of the table action handler. This packet can be dropped by the
- * output port action handler.
+ */
+/**
+ * Action handler packet insert to output port
+ *
+ * This function can be called by any input/output port or table action handler
+ * to send a packet out through one of the pipeline output ports. This packet is
+ * generated by the action handler, i.e. this packet is not part of the burst of
+ * packets read from one of the pipeline input ports and currently processed by
+ * the pipeline (this packet is not an element of the pkts array input parameter
+ * of the action handler).
  *
  * @param p
  *   Handle to pipeline instance
@@ -774,7 +798,7 @@ int rte_pipeline_port_out_create(struct rte_pipeline *p,
  *   Output port ID (returned by previous invocation of pipeline output port
  *   create) to send the packet specified by pkt
  * @param pkt
- *   New packet generated by the table action handler
+ *   New packet generated by the action handler
  * @return
  *   0 on success, error code otherwise
  */
@@ -782,25 +806,68 @@ int rte_pipeline_port_out_packet_insert(struct rte_pipeline *p,
        uint32_t port_id,
        struct rte_mbuf *pkt);
 
+#define rte_pipeline_ah_port_out_packet_insert \
+       rte_pipeline_port_out_packet_insert
+
 /**
- * Read pipeline port out stats.
+ * Action handler packet hijack
  *
- * This function reads port out statistics identified by *port_id* of given
- * pipeline *p*.
+ * This function can be called by any input/output port or table action handler
+ * to hijack selected packets from the burst of packets read from one of the
+ * pipeline input ports and currently processed by the pipeline. The hijacked
+ * packets are removed from any further pipeline processing, with the action
+ * handler now having the full ownership for these packets.
+ *
+ * The action handler can further send the hijacked packets out through any
+ * pipeline output port by calling the rte_pipeline_ah_port_out_packet_insert()
+ * function. The action handler can also drop these packets by calling the
+ * rte_pktmbuf_free() function, although a better alternative is provided by
+ * the action handler using the rte_pipeline_ah_packet_drop() function.
  *
  * @param p
- *   Handle to pipeline instance.
- * @param port_id
- *   Port ID what stats will be returned.
- * @param stats
- *   Statistics buffer.
- * @param clear
- *   If not 0 clear stats after reading.
+ *   Handle to pipeline instance
+ * @param pkts_mask
+ *   64-bit bitmask specifying which of the packets handed over for processing
+ *   to the action handler is to be hijacked by the action handler. When
+ *   pkts_mask bit n is set, then element n of the pkts array (input argument to
+ *   the action handler) is hijacked.
  * @return
  *   0 on success, error code otherwise
  */
-int rte_pipeline_port_out_stats_read(struct rte_pipeline *p, uint32_t port_id,
-       struct rte_pipeline_port_out_stats *stats, int clear);
+int rte_pipeline_ah_packet_hijack(struct rte_pipeline *p,
+       uint64_t pkts_mask);
+
+/**
+ * Action handler packet drop
+ *
+ * This function is called by the pipeline action handlers (port in/out, table)
+ * to drop the packets selected using packet mask.
+ *
+ * This function can be called by any input/output port or table action handler
+ * to drop selected packets from the burst of packets read from one of the
+ * pipeline input ports and currently processed by the pipeline. The dropped
+ * packets are removed from any further pipeline processing and the packet
+ * buffers are eventually freed to their buffer pool.
+ *
+ * This function updates the drop statistics counters correctly, therefore the
+ * recommended approach for dropping packets by the action handlers is to call
+ * this function as opposed to the action handler hijacking the packets first
+ * and then dropping them invisibly to the pipeline (by using the
+ * rte_pktmbuf_free() function).
+ *
+ * @param p
+ *   Handle to pipeline instance
+ * @param pkts_mask
+ *   64-bit bitmask specifying which of the packets handed over for processing
+ *   to the action handler is to be dropped by the action handler. When
+ *   pkts_mask bit n is set, then element n of the pkts array (input argument to
+ *   the action handler) is dropped.
+ * @return
+ *   0 on success, error code otherwise
+ */
+int rte_pipeline_ah_packet_drop(struct rte_pipeline *p,
+       uint64_t pkts_mask);
+
 #ifdef __cplusplus
 }
 #endif