From patchwork Thu Oct 9 14:08:45 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anders Roxell X-Patchwork-Id: 38507 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-wg0-f70.google.com (mail-wg0-f70.google.com [74.125.82.70]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id D04E9202E7 for ; Thu, 9 Oct 2014 14:09:29 +0000 (UTC) Received: by mail-wg0-f70.google.com with SMTP id a1sf914427wgh.5 for ; Thu, 09 Oct 2014 07:09:29 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:from:to:date:message-id:in-reply-to :references:subject:precedence:list-id:list-unsubscribe:list-archive :list-post:list-help:list-subscribe:mime-version:errors-to:sender :x-original-sender:x-original-authentication-results:mailing-list :content-type:content-transfer-encoding; bh=OOtMehJRf4v+WNnSSk5mEoT0UnpnfvZ9/kdDSBWp6JM=; b=iuYJzxpLfP3YckLi7kYKpEbjTcUF/o6kn7cUozbtoZ15VoqI9WM2XXour/sAZuH6Cq T8tK531hZYN857q7NoaCKdf3TPtQoFCAErKd+q79KlpLtpcST0f3GB6cpC/lydDKXTua Pmk/lW8ct4xhfIYzA6lpFLZnzQTo/pzzbMM0jhIBDzXIAXrp4Z+15aLBoCsD1N4vqRfO XoWKkDuW5SHK2dc2sH3ctPtcJdWSmOW52JKNNwQJZ1Z4vwoEvUElgAuDW5N01AQbgjVA QeJ9WZGWL2I+S/RONcXGXS25gzATwYfZo6LS2trH1v8+6pk+QNeXHvO1JOUmXPdoeqn7 3cpg== X-Gm-Message-State: ALoCoQlvIpEQECkYB/tXnRLEEfG8kED6FEm5w+o3wHlVrA4eR4CYP9h7CAgq+BTqieQo+at+0KFu X-Received: by 10.112.132.37 with SMTP id or5mr2775028lbb.2.1412863768380; Thu, 09 Oct 2014 07:09:28 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.8.169 with SMTP id s9ls156761laa.47.gmail; Thu, 09 Oct 2014 07:09:28 -0700 (PDT) X-Received: by 10.112.199.232 with SMTP id jn8mr17924178lbc.30.1412863768236; Thu, 09 Oct 2014 07:09:28 -0700 (PDT) Received: from mail-lb0-f174.google.com (mail-lb0-f174.google.com [209.85.217.174]) by mx.google.com with ESMTPS id ap3si4556202lbc.33.2014.10.09.07.09.28 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Thu, 09 Oct 2014 07:09:28 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.217.174 as permitted sender) client-ip=209.85.217.174; Received: by mail-lb0-f174.google.com with SMTP id p9so1235807lbv.33 for ; Thu, 09 Oct 2014 07:09:28 -0700 (PDT) X-Received: by 10.112.130.226 with SMTP id oh2mr10387123lbb.100.1412863767955; Thu, 09 Oct 2014 07:09:27 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.112.84.229 with SMTP id c5csp254734lbz; Thu, 9 Oct 2014 07:09:26 -0700 (PDT) X-Received: by 10.224.15.67 with SMTP id j3mr24144922qaa.3.1412863766430; Thu, 09 Oct 2014 07:09:26 -0700 (PDT) Received: from ip-10-35-177-41.ec2.internal (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTPS id c103si5781836qge.56.2014.10.09.07.09.25 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Thu, 09 Oct 2014 07:09:26 -0700 (PDT) Received-SPF: none (google.com: lng-odp-bounces@lists.linaro.org does not designate permitted sender hosts) client-ip=54.225.227.206; Received: from localhost ([127.0.0.1] helo=ip-10-35-177-41.ec2.internal) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1XcEPE-0006x8-Ht; Thu, 09 Oct 2014 14:09:24 +0000 Received: from mail-lb0-f174.google.com ([209.85.217.174]) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1XcEOz-0006u2-GT for lng-odp@lists.linaro.org; Thu, 09 Oct 2014 14:09:09 +0000 Received: by mail-lb0-f174.google.com with SMTP id p9so1218950lbv.5 for ; Thu, 09 Oct 2014 07:09:03 -0700 (PDT) X-Received: by 10.112.129.71 with SMTP id nu7mr4367928lbb.106.1412863742369; Thu, 09 Oct 2014 07:09:02 -0700 (PDT) Received: from localhost (c-853670d5.07-21-73746f28.cust.bredbandsbolaget.se. [213.112.54.133]) by mx.google.com with ESMTPSA id ki7sm992743lac.38.2014.10.09.07.09.01 for (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Thu, 09 Oct 2014 07:09:01 -0700 (PDT) From: Anders Roxell To: lng-odp@lists.linaro.org Date: Thu, 9 Oct 2014 16:08:45 +0200 Message-Id: <1412863729-28176-4-git-send-email-anders.roxell@linaro.org> X-Mailer: git-send-email 2.1.0 In-Reply-To: <1412863729-28176-1-git-send-email-anders.roxell@linaro.org> References: <1412863729-28176-1-git-send-email-anders.roxell@linaro.org> Subject: [lng-odp] [DO NOT REVIEW 3/7] packet_io: add API definitions X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: , List-Help: , List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: lng-odp-bounces@lists.linaro.org X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: anders.roxell@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.217.174 as permitted sender) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 Signed-off-by: Anders Roxell --- packet_io.dox | 255 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) 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 + */