[DO,NOT,REVIEW,5/7] packet_io: add Usage examples

Message ID 1412863729-28176-6-git-send-email-anders.roxell@linaro.org
State New
Headers show

Commit Message

Anders Roxell Oct. 9, 2014, 2:08 p.m.
Signed-off-by: Anders Roxell <anders.roxell@linaro.org>
---
 packet_io.dox | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

Patch

diff --git a/packet_io.dox b/packet_io.dox
index 6204159..25de47f 100644
--- a/packet_io.dox
+++ b/packet_io.dox
@@ -475,4 +475,67 @@  This routine returns the output queue for a packet. This is a shorthand
 equivalent of calling odp_packet_get_input() followed by odp_pktio_outq_getdef()
 to determine the output queue based on the interface the packet was received on.
 
+@section examples Usage Examples
+
+This section contains some example code sequences demonstrating expected usage
+of the APIs defined here. This is pseudo-ish code rather than something that
+will actually compile, for real usable examples check the examples in the ODP
+source repository.
+
+Each example has two sections of code, an "Initialisation" section that is
+expected to be run once from a single thread (e.g. the "main" thread) and a
+"Worker" section that would be run from each worker thread.
+
+@subsection exsched Single Interface via Scheduler
+
+@subsubsection Initialisation
+
+@code
+odp_cos_t default_cos = odp_cos_create(..);
+odp_buffer_pool_t pkt_pool = odp_buffer_pool_create(..);
+odp_queue_t inq = odp_queue_create(..);
+odp_cos_set_pool(default_cos, pkt_pool);
+odp_cos_set_queue(default_cos, inq);
+
+odp_pktio_t pktio = odp_pktio_open("eth0", default_cos);
+/* additional pktios could be opened here, passing the same default_cos */
+@endcode
+
+@subsubsection Worker
+
+@code
+while (1) {
+	pkt = odp_schedule();
+	outq = odp_packet_outq(pkt);
+	buf = odp_buffer_from_packet(pkt);
+
+	/* do stuff.. */
+
+	odp_queue_enq(outq, buf);
+}
+@endcode
+
+@subsection exdirect Direct Send/Receive
+
+@subsubsection Initialisation
+
+@code
+odp_pktio_t pktio = odp_pktio_open("eth0", ODP_COS_INVALID);
+@endcode
+
+No buffer pool is associated with the pktio interface as it will only be
+accessed by direct polling, in which case pools and buffers are managed
+within the application.
+
+@subsubsection Worker
+
+@code
+odp_pktio_worker_t io = odp_pktio_open_worker("eth0");
+
+while (1) {
+	num_pkts = odp_pktio_worker_recv(io, pkt_tbl, ARRAY_SIZE(pkt_tbl));
+	odp_pktio_worker_send(io, pkt_tbl, num_pkts);
+}
+@endcode
+
 */