From patchwork Fri Dec 11 19:52:36 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 58309 Delivered-To: patch@linaro.org Received: by 10.112.73.68 with SMTP id j4csp93890lbv; Fri, 11 Dec 2015 11:52:54 -0800 (PST) X-Received: by 10.140.17.213 with SMTP id 79mr25956110qgd.49.1449863574606; Fri, 11 Dec 2015 11:52:54 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id c187si21613310qhd.24.2015.12.11.11.52.53; Fri, 11 Dec 2015 11:52:54 -0800 (PST) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dkim=neutral (body hash did not verify) header.i=@linaro-org.20150623.gappssmtp.com Received: by lists.linaro.org (Postfix, from userid 109) id DD0B962024; Fri, 11 Dec 2015 19:52:53 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-2.5 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, T_DKIM_INVALID, URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 4FAF861973; Fri, 11 Dec 2015 19:52:48 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 73B7362016; Fri, 11 Dec 2015 19:52:45 +0000 (UTC) Received: from mail-qk0-f179.google.com (mail-qk0-f179.google.com [209.85.220.179]) by lists.linaro.org (Postfix) with ESMTPS id 41D5B61D23 for ; Fri, 11 Dec 2015 19:52:44 +0000 (UTC) Received: by qkht125 with SMTP id t125so54567749qkh.3 for ; Fri, 11 Dec 2015 11:52:44 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro-org.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:mime-version:content-type :content-transfer-encoding; bh=m2qh95bomGpQ8A1VI0k5/8I1cWBJLBHNzmdHhjxye38=; b=T6fzidOnDxhEy1XD58v25++pzE3ky8AriTarL4WZrPpM2Q8G5ORDfIwWIfWGkngpHT VneZK+q1BHPsGjoqEGJFwMZctNhXTM9IwzgR0Rxi6xua3y1PB/sNdBlnK/CFXl21V97q E4PD0EeCXFcd+C85Ua+saSEGWqNjLROpFkcK+zo9YyjvbPlkeBMg7UPRjaikOqrTG3X3 oHz42r7c/mNvKiMWT4+sYkpmV/LyJTYUsQNRnms49zXGJj6bgvWs8DbBCFzfZQ6RP5/+ TWt0eVTLnIG7m0ShHYWkmNMGIacd5J01DFX8On3qYPCwVsFk74+a5t55UYdZCgf3/9HM mA3A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-type:content-transfer-encoding; bh=m2qh95bomGpQ8A1VI0k5/8I1cWBJLBHNzmdHhjxye38=; b=cPXv4vCkjOD1HZsS7aA63kB2BujB+Gxde7gIhMXGHP+o6lhdt/ldqgv/MLZjAGVQlr YixNNSld9XGvNMfwLdNnbZuCc/mTZkOjJYhN+YbdJaXK6XFReenAvNJSISJculRrTnoo EOyFc3LjzvvC5OBm1+Vac2FRHB9c22mf+InHvicwBze/nkaquwRJIwwlMiJFmyj9lzTL A7JTHAFIJwWwi6qiR/wfF99tVKZ+fQpn5k4oM7Fpu3K5JSgYM3/YDmFVNq5aB4JVAXHU Y/GZsvtBPVlYm+KhzxWviZL4pO+2JRiEO/LBWsMAsbfxLtshj0Ja6UBawzsug0VSYV4u huVA== X-Gm-Message-State: ALoCoQnQELdFj9Lsp4DD6V0nCDcJ3/ciXdKTfRXbL3ik6a+Ujx8pNpt9XtEkSl1xAJkp7v6mc9ibRPBAdAKSLP2Fym5+R4pxSw== X-Received: by 10.55.195.90 with SMTP id a87mr25623001qkj.12.1449863563957; Fri, 11 Dec 2015 11:52:43 -0800 (PST) Received: from localhost.localdomain (c-98-221-136-245.hsd1.nj.comcast.net. [98.221.136.245]) by smtp.gmail.com with ESMTPSA id d130sm8794878qkb.33.2015.12.11.11.52.42 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 11 Dec 2015 11:52:43 -0800 (PST) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Fri, 11 Dec 2015 14:52:36 -0500 Message-Id: <1449863556-31260-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.5.0 MIME-Version: 1.0 X-Topics: patch Subject: [lng-odp] [PATCH] doc/users-guide: add helpers section X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Signed-off-by: Mike Holmes --- doc/users-guide/users-guide.adoc | 161 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index cf77fa0..d2e1a16 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -431,6 +431,167 @@ Applications only include the 'include/odp.h file which includes the 'platform/< The doxygen documentation defining the behavior of the ODP API is all contained in the public API files, and the actual definitions for an implementation will be found in the per platform directories. Per-platform data that might normally be a #define can be recovered via the appropriate access function if the #define is not directly visible to the application. +== Helpers +Many small helper functions and definitions are needed to enable ODP +applications to be hardware optimized but not tied to a particular hardware or +execution environment. These are typically implemented with inline functions, +preprocessor macros, or compiler built­in features. Thus API definitions are +normally inline when possible. + +=== Core enumeration +Application or middleware need to handle physical and/or logical core IDs, core +counts and core masks quite often. Core enumeration has to remain consistent +even when core deployment may change during application execution (e.g., due to +adaptation to changing traffic profile, etc). + +* +odp_cpumask_from_str()+ +* +odp_cpumask_to_str()+ +* +odp_cpumask_zero()+ +* +odp_cpumask_set()+ +* +odp_cpumask_setall()+ +* +odp_cpumask_clr()+ +* +odp_cpumask_isset()+ +* +odp_cpumask_count()+ +* +odp_cpumask_and()+ +* +odp_cpumask_or()+ +* +odp_cpumask_xor()+ +* +odp_cpumask_equal()+ +* +odp_cpumask_copy()+ +* +odp_cpumask_first()+ +* +odp_cpumask_last()+ +* +odp_cpumask_next()+ +* +odp_cpumask_default_worker()+ +* +odp_cpumask_default_control()+ + +=== Memory alignments +For optimal performance and scalability (e.g., to avoid false sharing and cache +line aliasing), some application data structures need to be aligned to cache +(cache line) and/or memory subsystem (page, DRAM burst) alignments. NUMA +systems also support location­awareness and potentially different cache line +sizes on a per­memory basis. Static memory allocation Serves application needs +for portable definitions for global and core/thread local data. + +* +ODP_ALIGNED+ +* +ODP_PACKED+ +* +ODP_OFFSETOF+ +* +ODP_FIELD_SIZEOF+ +* +ODP_CACHE_LINE_SIZE+ +* +ODP_PAGE_SIZE+ +* +ODP_ALIGNED_CACHE+ +* +ODP_ALIGNED_PAGE+ + +=== Compiler hints +The compiler and linker can do better optimizations if code includes hints on +expected application behavior. Examples of these are classification of +branches with likely/unlikely hints, or marking code with hot (optimize for +speed) or cold (optimize for size) tags. + +* +odp_likely()+ +* +odp_unlikely()+ +* +odp_prefetch()+ +* +odp_prefetch_store()+ + +=== Atomic operations +Modern ISAs offers various atomic instructions to access/manipulate data +concurrently from multiple cores. Well scalable multicore software is possible +only through correct usage (and combination) of hardware acceleration and +atomic instructions. Applications use atomic operations to update global +statistics, sequence counters, quotas, etc., and to build concurrent data +structures. + +* +odp_atomic_init_u64()+ +* +odp_atomic_load_u64()+ +* +odp_atomic_store_u64()+ +* +odp_atomic_fetch_add_u64()+ +* +odp_atomic_add_u64()+ +* +odp_atomic_fetch_sub_u64()+ +* +odp_atomic_sub_u64()+ +* +odp_atomic_fetch_inc_u64()+ +* +odp_atomic_inc_u64()+ +* +odp_atomic_fetch_dec_u64()+ +* +odp_atomic_dec_u64()+ + +=== Memory synchronization barriers +Application (or middleware) needs a portable way to synchronize data +modifications into main memory before messaging other cores or hardware +acceleration about the changes. The nature of the synchronization needs are +cache coherence protocol specific. + +* +odp_barrier_t()+ +* +odp_rwlock_t()+ +* +odp_ticketlock_t()+ +* +odp_barrier_init()+ +* +odp_barrier_wait()+ +* +odp_rwlock_init()+ +* +odp_rwlock_read_lock()+ +* +odp_rwlock_read_unlock()+ +* +odp_rwlock_write_lock()+ +* +odp_rwlock_write_unlock()+ +* +odp_sync_stores()+ +* +odp_ticketlock_init()+ +* +odp_ticketlock_lock()+ +* +odp_ticketlock_trylock()+ +* +odp_ticketlock_unlock()+ +* +odp_ticketlock_is_locked()+ + +=== Execution barriers and spinlocks +Although software locking should be avoided (especially in fast path code), at +times there is no practical way to synchronize cores other than using execution +barriers or spinlocks. For example, the application initialization phase +typically is not performance critical and may be much simpler with synchronous +interfaces and locking. + +* +odp_spinlock_t()+ +* +odp_spinlock_init()+ +* +odp_spinlock_lock()+ +* +odp_spinlock_trylock()+ +* +odp_spinlock_unlock()+ +* +odp_spinlock_is_locked()+ + +=== Profiling and debugging +Although there are (external) tools for profiling and debugging, some level of +application code instrumentation is typically needed (e.g., for on field +debug/profiling). Typically an SoC supports CPU level (e.g., cycle count, cache +misses, branch prediction misses) and SoC level (system cache misses, +interconnect/DRAM utilization) performance counters. + +* +odp_errno()+ +* +odp_errno_zero()+ +* +odp_errno_print()+ +* +odp_errno_str()+ + +* +odp_override_log()+ +* +odp_override_abort()+ + +=== SoC Hardware info +The application may be interested in generic performance characteristics of the +SoC it is running on to have optimal adaption to the system. + +* +odp_cpu_id()+ +* +odp_cpu_count()+ +* +odp_cpu_cycles()+ +* +odp_cpu_cycles_diff()+ +* +odp_cpu_cycles_max()+ +* +odp_cpu_cycles_resolution()+ + +=== Data manipulation +There are some data manipulation operations that are typical to networking +applications. Examples of these are byte order swap for big/little­endian +conversion, various checksum algorithms, and bit shuffling/shifting. + +* +odp_be_to_cpu_16()+ +* +odp_be_to_cpu_32()+ +* +odp_be_to_cpu_64()+ +* +odp_cpu_to_be_16()+ +* +odp_cpu_to_be_32()+ +* +odp_cpu_to_be_64()+ +* +odp_le_to_cpu_16()+ +* +odp_le_to_cpu_32()+ +* +odp_le_to_cpu_64()+ +* +odp_cpu_to_le_16()+ +* +odp_cpu_to_le_32()+ +* +odp_cpu_to_le_64()+ + .Users include structure ---- ./