api: ipsec: change semantics of odp_ipsec_result function

Message ID 20170509002222.2438-1-dmitry.ereminsolenikov@linaro.org
State New
Headers show

Commit Message

Dmitry Eremin-Solenikov May 9, 2017, 12:22 a.m.
- Move packets from the event instead of copying them. This simplifies
   event handling/freeing code, which now does not have to track, which
   packets were copied from the event and which packets should be freed.

 - Do not require to free the event before processing packets. This
   allows one to copy packets from the event in small batches and
   process them accordingly.

 - Freeing the event in odp_ipsec_result() leaves space for optimized
   implementations, where an event is actually a packet with additional
   metadata.

Signed-off-by: Dmitry Eremin-Solenikov <dmitry.ereminsolenikov@linaro.org>

---
 include/odp/api/spec/ipsec.h | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

-- 
2.11.0

Patch hide | download patch | download mbox

diff --git a/include/odp/api/spec/ipsec.h b/include/odp/api/spec/ipsec.h
index a0ceb11a..78645567 100644
--- a/include/odp/api/spec/ipsec.h
+++ b/include/odp/api/spec/ipsec.h
@@ -1278,17 +1278,23 @@  int odp_ipsec_out_inline(const odp_ipsec_op_param_t *op_param,
  * Get IPSEC results from an ODP_EVENT_IPSEC_RESULT event
  *
  * Copies IPSEC operation results from an event. The event must be of
- * type ODP_EVENT_IPSEC_RESULT. It must be freed before the application passes
- * any resulting packet handles to other ODP calls.
+ * type ODP_EVENT_IPSEC_RESULT. The event will be freed automatically if
+ * odp_ipsec_result() returns 0.  In all other case it must be freed via
+ * odp_event_free().
  *
- * @param[out]    result  Pointer to operation result for output. Maybe NULL, if
- *                        application is interested only on the number of
- *                        packets.
+ * @param[out]    result  Pointer to operation result for output. May be
+ *                        NULL, if application is interested only on the
+ *                        number of packets.
  * @param         event   An ODP_EVENT_IPSEC_RESULT event
  *
- * @return Number of packets in the event. If this is larger than
- *         'result.num_pkt', all packets did not fit into result struct and
- *         application must call the function again with a larger result struct.
+ * @return Number of packets remaining in the event.
+ * @retval > 0    All packets did not fit into result struct and
+ *                application must call the function again. Packets
+ *                returned during previous calls will not be returned
+ *                again in subsequent calls.
+ * @retval 0      All packets were returned. The event was freed during
+ *                this call. Application should not access the event
+ *                afterwards.
  * @retval <0     On failure
  *
  * @see odp_ipsec_in_enq(), odp_ipsec_out_enq()