[DO,NOT,REVIEW,3/7] packet_io: add API definitions

diff --git a/packet_io.dox b/packet_io.dox
index f47b008..2a90c98 100644
--- a/packet_io.dox
+++ b/packet_io.dox
@@ -120,4 +120,259 @@  In addition to this the application can provide platform specific
 initialisation data to odp_global_init() which can be used to configure
 non-portable properties of the interface implementation.
 
+@section apidef API Definitions
+
+@subsection datatypescfg Data Types
+
+The following data types are referenced in the API descriptions described
+below. The names are part of the ODP API and MUST be present in any conforming
+implementation, however the type values shown here are illustrative and
+implementations SHOULD either use these or substitute their own type values
+that are appropriate to the underlying platform.
+
+@code
+/* ODP packet IO handle, one per interface */
+typedef uint32_t odp_pktio_t;
+
+/* Invalid packet IO handle */
+#define ODP_PKTIO_INVALID 0
+
+/* ODP packet IO worker handle, one per interface for each worker thread */
+typedef uint32_t odp_pktio_worker_t;
+
+/* Invalid packet IO worker handle */
+#define ODP_PKTIO_WORKER_INVALID 0
+@endcode
+
+@subsection odp_pktio_open odp_pktio_open
+
+@code
+/*
+ * Open an ODP packet IO instance.
+ *
+ * @param iface       Packet IO interface name.
+ * @param default_cos Class-of-service to be assigned to packets received on
+ *                    this instance if no other class-of-service is matched.
+ *
+ * @return ODP packet IO handle or ODP_PKTIO_INVALID on error.
+ */
+odp_pktio_t odp_pktio_open(const char *iface, odp_cos_t default_cos);
+@endcode
+
+Open the specified interface and return an @c odp_pktio_t handle to be used to
+refer to this pktio instance in subsequent API calls. A return value of
+@c ODP_PKTIO_INVALID indicates failure and the caller should inspect errno to
+determine the cause.
+
+This routine would typically be called during application startup for each
+interface the application intends to use. Each interface can be opened only once.
+
+The interface name is a NULL terminated string containing a human readable name
+for the interface, used by the implementation to identify the underlying pktio
+interface.
+
+The default class-of-service is used to define how received packets should be
+dealt with if they don't match any other class-of-service. A value of
+@c ODP_COS_INVALID causes all such packets to be discarded. Immediately
+following the odp_pktio_open() call all incoming packets will match the default
+class-of-service until additional header based rules (either PMR or L2/L3
+priority) have been configured. The default class-of-service can be modified at
+any time by calling odp_pktio_set_default_cos().
+
+@subsection odp_pktio_close odp_pktio_close
+
+@code
+/*
+ * Close an ODP packet IO instance.
+ *
+ * @param id ODP packet IO handle.
+ *
+ * @return 0 on success, -1 on error.
+ */
+int odp_pktio_close(odp_pktio_t id);
+@endcode
+
+Close a pktio instance and free any internal resources associated with it. It
+is the responsibility of the application to ensure that any resources that have
+been associated with this instance are freed, for example the default CoS.
+
+@subsection odp_pktio_outq_getdef odp_pktio_outq_getdef
+
+@code
+/*
+ * Query default output queue associated with a pktio handle.
+ *
+ * @param id ODP packet IO handle.
+ *
+ * @return Default output queue or ODP_QUEUE_INVALID on error.
+ */
+odp_queue_t odp_pktio_outq_getdef(odp_pktio_t id);
+@endcode
+
+This routine returns the output queue associated with a pktio handle, packets
+enqueued to this queue are queued for tranmission over the interface. The
+output queue is assigned by the implementation during the open call.
+
+@subsection odp_pktio_set_default_cos odp_pktio_set_default_cos
+
+@code
+/*
+ * Setup default class-of-service for a packet IO interface.
+ *
+ * @param id  ODP packet IO handle.
+ * @param cos class-of-service set to assign to all packets arriving at the
+ *            pktio interface, unless overridden by subsequent header-based
+ *            filters.
+ *
+ * @return 0 on success, -1 on error.
+ */
+int odp_pktio_set_default_cos(odp_pktio_t id, odp_cos_t cos);
+@endcode
+
+@subsection odp_pktio_set_error_cos odp_pktio_set_error_cos
+@code
+/*
+ * Setup error class-of-service for a packet IO interface.
+ *
+ * @param id  ODP packet IO handle.
+ * @param cos class-of-service set to all packets arriving the specified
+ *            interface that contain an error.
+ *
+ * @return 0 on success, -1 on error.
+ */
+int odp_pktio_set_error_cos(odp_pktio_t id, odp_cos_t cos);
+@endcode
+
+This OPTIONAL routine assigns a class-of-service, which may be used to discard
+such packets or deliver them to the application via a prescribed queue for
+further processing. The specific errors types include L2 FCS and optionally
+L3/L4 checksum errors, malformed headers etc. depending on platform
+capabilities.
+
+@subsection odp_pktio_set_input odp_pktio_set_input
+
+@code
+/*
+ * Store packet input handle into packet
+ *
+ * @param pkt  ODP packet buffer handle
+ * @param id   ODP packet IO handle
+ *
+ * @return
+ */
+void odp_pktio_set_input(odp_packet_t pkt, odp_pktio_t id);
+@endcode
+
+@subsection odp_pktio_get_input odp_pktio_get_input
+
+@code
+/*
+ * Get stored packet input handle from packet
+ *
+ * @param pkt  ODP packet buffer handle
+ *
+ * @return Packet IO handle
+ */
+odp_pktio_t odp_pktio_get_input(odp_packet_t pkt);
+@endcode
+
+@subsection odp_pktio_set_mac_addr odp_pktio_set_mac_addr
+
+@code
+/*
+ * Set the default MAC address of a packet IO interface.
+ *
+ * @param id         ODP packet IO handle.
+ * @param mac_addr   MAC address to be assigned to the interface.
+ * @param addr_size  Size of the address in bytes.
+ *
+ * @return 0 on success, -1 on error.
+ */
+int odp_pktio_set_mac_addr(odp_pktio_t id, unsigned char *mac_addr,
+                           size_t addr_size);
+@endcode
+
+@subsection odp_pktio_mac_addr odp_pktio_mac_addr
+
+@code
+/*
+ * Get the default MAC address of a packet IO interface.
+ *
+ * @param      id        ODP packet IO handle.
+ * @param[out] mac_addr  Storage for MAC address of the packet IO interface.
+ * @param[out] addr_size Size of the MAC address.
+ *
+ * @return 0 on success, -1 on error.
+ */
+int odp_pktio_mac_addr(odp_pktio_t id, unsigned char *mac_addr,
+                       size_t *addr_size);
+@endcode
+
+@subsection odp_pktio_set_mtu odp_pktio_set_mtu
+
+@code
+/*
+ * Configure the MTU for a packet IO interface.
+ *
+ * @param id   ODP packet IO handle.
+ * @param mtu  The MTU to be applied.
+ *
+ * @return 0 on success, -1 on error.
+ */
+int odp_pktio_set_mtu(odp_pktio_t id, uint16_t mtu);
+@endcode
+
+@subsection odp_pktio_mtu odp_pktio_mtu
+
+@code
+/*
+ * Get the currently configured MTU of a packet IO interface.
+ *
+ * @param      id   ODP packet IO handle.
+ * @param[out] mtu  Pointer to location in which to store the MTU value.
+ *
+ * @return 0 on success, -1 on error.
+ */
+int odp_pktio_mtu(odp_pktio_t id, uint16_t *mtu);
+@endcode
+
+@subsection odp_pktio_promisc_enable odp_pktio_promisc_enable
+
+@code
+/*
+ * Enable promiscuous mode on a packet IO interface.
+ *
+ * @param id ODP packet IO handle.
+ *
+ * @return 0 on success, -1 on failure.
+ */
+int odp_pktio_promisc_enable(odp_pktio_t id);
+@endcode
+
+@subsection odp_pktio_promisc_disable odp_pktio_promisc_disable
+
+@code
+/*
+ * Disable promiscuous mode on a packet IO interface.
+ *
+ * @param id ODP packet IO handle.
+ *
+ * @return 0 on success, -1 on failure.
+ */
+int odp_pktio_promisc_disable(odp_pktio_t id);
+@endcode
+
+@subsection odp_pktio_promisc odp_pktio_promisc
+
+@code
+/*
+ * Determine if promiscuous mode is enabled for a packet IO interface.
+ *
+ * @param id ODP packet IO handle.
+ *
+ * @return 0 if promiscuous mode is disabled, 1 if enabled.
+ */
+int odp_pktio_promisc(odp_pktio_t id);
+@endcode
+
 */