From patchwork Thu Oct 9 14:08:44 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anders Roxell X-Patchwork-Id: 38506 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-wi0-f198.google.com (mail-wi0-f198.google.com [209.85.212.198]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id BDBE0202E7 for ; Thu, 9 Oct 2014 14:09:24 +0000 (UTC) Received: by mail-wi0-f198.google.com with SMTP id hi2sf1026132wib.5 for ; Thu, 09 Oct 2014 07:09:24 -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=KiEuD3iRf7kD6WrQ6fubW0ANBk/L5eLlAR0w/omdyQw=; b=BIFtg7ufnPMTfLeFoEngeMi31RuYaVDc8qn/vpsb5xXtcx/elvSBIPs4oFwuurQP41 tMpUWiqaXZQ/wLKI5kg1Wh9Z9Vy+zo3wdzg39CRGqnIa2ZQKgdpPD8yrFug5xYd3d1g3 571W9ttKKXChVWhAMPfn9zp+J1EhmOrClAxu0qr9exs3fOodvMDHVLkX4A+VHuccjLct /t+ya3+u/pzyY0Wq9lLHxUMEz98vmjVFlxBL0JxPeQbT2tTQdpfL2c1tKRobJJd3IMD8 LQSAxUq9GkoVU9mGXbpdETO90rc+8VVBMlnxb3hBekV3uEdi93kxCWlgG4Fze//ETj9J ZpWw== X-Gm-Message-State: ALoCoQmiM4Ekfg0e41zMgBpCa4tpLV8gVTEs+sSEGTA3MpiY0pn3gzdAZXgTWA3UOiX0z6COVVvY X-Received: by 10.112.140.199 with SMTP id ri7mr253438lbb.17.1412863763905; Thu, 09 Oct 2014 07:09:23 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.36.66 with SMTP id o2ls181939laj.8.gmail; Thu, 09 Oct 2014 07:09:23 -0700 (PDT) X-Received: by 10.112.166.6 with SMTP id zc6mr18272572lbb.31.1412863763727; Thu, 09 Oct 2014 07:09:23 -0700 (PDT) Received: from mail-la0-f43.google.com (mail-la0-f43.google.com [209.85.215.43]) by mx.google.com with ESMTPS id nb4si4551435lbb.35.2014.10.09.07.09.23 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Thu, 09 Oct 2014 07:09:23 -0700 (PDT) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.43 as permitted sender) client-ip=209.85.215.43; Received: by mail-la0-f43.google.com with SMTP id mc6so1291778lab.2 for ; Thu, 09 Oct 2014 07:09:23 -0700 (PDT) X-Received: by 10.112.134.229 with SMTP id pn5mr17925745lbb.22.1412863763623; Thu, 09 Oct 2014 07:09:23 -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 c5csp254715lbz; Thu, 9 Oct 2014 07:09:22 -0700 (PDT) X-Received: by 10.68.162.3 with SMTP id xw3mr41903pbb.142.1412863761921; Thu, 09 Oct 2014 07:09:21 -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 t5si5836767qcs.26.2014.10.09.07.09.21 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Thu, 09 Oct 2014 07:09:21 -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 1XcEPA-0006wt-3r; Thu, 09 Oct 2014 14:09:20 +0000 Received: from mail-lb0-f171.google.com ([209.85.217.171]) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1XcEOw-0006tt-7f for lng-odp@lists.linaro.org; Thu, 09 Oct 2014 14:09:06 +0000 Received: by mail-lb0-f171.google.com with SMTP id z12so1229194lbi.30 for ; Thu, 09 Oct 2014 07:09:00 -0700 (PDT) X-Received: by 10.112.135.230 with SMTP id pv6mr10582624lbb.105.1412863740454; Thu, 09 Oct 2014 07:09:00 -0700 (PDT) Received: from localhost (c-853670d5.07-21-73746f28.cust.bredbandsbolaget.se. [213.112.54.133]) by mx.google.com with ESMTPSA id ug7sm987665lac.48.2014.10.09.07.08.59 for (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Thu, 09 Oct 2014 07:08:59 -0700 (PDT) From: Anders Roxell To: lng-odp@lists.linaro.org Date: Thu, 9 Oct 2014 16:08:44 +0200 Message-Id: <1412863729-28176-3-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 2/7] packet_io: add Fuctional description 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.215.43 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 | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/packet_io.dox b/packet_io.dox index d9d96b4..f47b008 100644 --- a/packet_io.dox +++ b/packet_io.dox @@ -41,4 +41,83 @@ associated with the pktio device over which the packet is to be sent, the implementation is then responsible for taking the packet from the output queue and effecting its transmission. +@section func Functional Description + +The pktio APIs define the following handles to be used to access a pktio +interface; + + - @c odp_pktio_t one per interface, all configuration of the interface is + performed using a handle of this type. There can be only one handle of this + type per interface at any time. + - @c odp_pktio_worker_t one per interface for each worker thread, used for I/O + and read only access to pktio configuration. + +@subsection initialisation_sequence Initialisation sequence + +The following section walks through a simplified example of an initialisation +sequence an ODP application may go through to use a pktio device. + +1. Call @c odp_global_init(), if necessary passing platform specific information + required to configure the pktio interfaces. +2. Call @c odp_cos_create() to create a CoS. +3. Call @c odp_buffer_pool_create() to create pool of buffers of type + @c ODP_BUFFER_TYPE_PACKET and and call @c odp_cos_set_pool() to associate it + with the CoS, so that packets matching this CoS will be allocated from this + pool. +4. Call @c odp_queue_create() to create a queue of type ODP_QUEUE_TYPE_PKTIN + and call @c odp_pktio_set_default_cos() to associate it with the CoS so that + matching packets matching this CoS will be delivered to this queue. +5. Call @c odp_pktio_open() passing the above CoS as the default CoS for the + interface. As there are no L2/L3/PMR rules paired with the pktio interface, + all received packets will be assigned the default class of service. +6. Start calling @c odp_schedule() from each of the worker tasks to begin + receiving packets. +7. For each received packet, call @c odp_packet_outq() to determine which + output queue is to be used for transmission based on which interface the + packet was received on. +8. Call @c odp_queue_enq() to queue the packet for transmission on the selected + output queue. + +Steps 1 to 5 would typically be performed at application startup in the main +thread. The worker tasks at step 7 could be active prior to any of the previous +steps, but packets only start being delivered after the association between the +pktio interface and the input queue is made during the odp_pktio_open() call. + +Further examples showing different ways an application can use the API are +found in the \ref examples section later in the document. + +@subsection ordering Ordering and Atomicity + +There are two methods of receiving or sending packets via a pktio device, +either working directly with the pktio device via odp_pktio_recv/send or +indirectly via queues and the scheduler. The application writer must select +the method that best suits their requirements, using both methods for a single +interface is not supported. + +In ODP, ordering and atomicity are functions of the scheduler, and in many cases +obtaining packets via the scheduler is how the best performance will be achieved, +particularly on platforms that make use of a hardware accelerated scheduler. + +Directly invoking send/recv on the pktio interface avoids the scheduler and +therefore the application is given no guarantees of ordering or atomicity. +There are however some cases where this can offer a performance improvement, for +example if the application maintains order by some other means such as only +accessing and interface from a single core, as it avoids the need to invoke the +scheduler and enqueue/dequeue packets. + +@subsection ifacetypes Supporting multiple interface types + +Some platforms have a number of different types of pktio interface, or at least +a number of different configuration options for a single type of interface. In +order for the ODP API to remain portable these differences must not require the +application to take platform specific code paths. The general mechanism for +coping with this is to assign a unique identifier to each interface (a character +string), this identifier is essentially opaque to the API but it used by the +implementation to determine which underlying interface is being accessed and +therefore the mechanisms used to work with it. + +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. + */