From patchwork Fri Dec 19 14:16:05 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Petri Savolainen X-Patchwork-Id: 42490 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-lb0-f198.google.com (mail-lb0-f198.google.com [209.85.217.198]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id A07CD26C6B for ; Fri, 19 Dec 2014 14:18:11 +0000 (UTC) Received: by mail-lb0-f198.google.com with SMTP id p9sf723975lbv.5 for ; Fri, 19 Dec 2014 06:18:10 -0800 (PST) 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:subject :precedence:list-id:list-unsubscribe:list-archive:list-post :list-help:list-subscribe:mime-version:content-type :content-transfer-encoding:errors-to:sender:x-original-sender :x-original-authentication-results:mailing-list; bh=LCIUi7uEKsZrkqYrxH20LKSSYm4ZcV7KgBLN3XBk0Pw=; b=YX/YB1IX7zlliMCz2ezWBlKnIaV81h4zrGbrN5lS/EEPCfGgBUc5mKpNZwjXYR+yyp J3XanTD1FxAPZrrmOungR5ePlL0nWbcA9laLt2HrAyML0A3F+FFUOO9oDsJ/YXn+5AVf 06kx3vWZSxcC7bcMI1YJKvZUQDeKOIcTMsjRHCr7DSfEYELSUlMJ8WqepNwuxTfZKtaU fA9P6Gd9orCjXt8C6iMVFCy7WptMjjdTeowerR8clhbHWqoTWrEhdRT9QrMXE1jr8bBg 8psn2Vad1nU3SxyGovAUp+xGfaX3yQ165AxHkdf7XAVShIIn31lzDAotiZkfnKsCd9XB MD9g== X-Gm-Message-State: ALoCoQnEL/pOs2tSIpQ9GxYtBWL23hnYdAEbs7BBcEUoBQiqnXJzAEbrqQTst6RqUlUpEH8FWxZ3 X-Received: by 10.112.169.101 with SMTP id ad5mr1143997lbc.1.1418998690536; Fri, 19 Dec 2014 06:18:10 -0800 (PST) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.28.137 with SMTP id b9ls1444509lah.29.gmail; Fri, 19 Dec 2014 06:18:10 -0800 (PST) X-Received: by 10.112.172.162 with SMTP id bd2mr8035717lbc.87.1418998690329; Fri, 19 Dec 2014 06:18:10 -0800 (PST) Received: from mail-lb0-f173.google.com (mail-lb0-f173.google.com. [209.85.217.173]) by mx.google.com with ESMTPS id o8si10044082laj.121.2014.12.19.06.18.10 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Fri, 19 Dec 2014 06:18:10 -0800 (PST) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.217.173 as permitted sender) client-ip=209.85.217.173; Received: by mail-lb0-f173.google.com with SMTP id z12so871193lbi.32 for ; Fri, 19 Dec 2014 06:18:10 -0800 (PST) X-Received: by 10.112.135.6 with SMTP id po6mr8037286lbb.69.1418998690164; Fri, 19 Dec 2014 06:18:10 -0800 (PST) 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.142.69 with SMTP id ru5csp287921lbb; Fri, 19 Dec 2014 06:18:09 -0800 (PST) X-Received: by 10.140.89.176 with SMTP id v45mr3012055qgd.44.1418998688332; Fri, 19 Dec 2014 06:18:08 -0800 (PST) Received: from ip-10-35-177-41.ec2.internal (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTPS id e6si11897629qar.54.2014.12.19.06.18.05 (version=TLSv1 cipher=RC4-SHA bits=128/128); Fri, 19 Dec 2014 06:18:08 -0800 (PST) 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 1Y1yNS-0005hP-Jj; Fri, 19 Dec 2014 14:17:58 +0000 Received: from mail-qa0-f46.google.com ([209.85.216.46]) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1Y1yNL-0005gc-NC for lng-odp@lists.linaro.org; Fri, 19 Dec 2014 14:17:51 +0000 Received: by mail-qa0-f46.google.com with SMTP id w8so654009qac.19 for ; Fri, 19 Dec 2014 06:17:46 -0800 (PST) X-Received: by 10.224.99.3 with SMTP id s3mr13874593qan.79.1418998666464; Fri, 19 Dec 2014 06:17:46 -0800 (PST) Received: from localhost.localdomain (ec2-23-23-178-99.compute-1.amazonaws.com. [23.23.178.99]) by mx.google.com with ESMTPSA id l3sm9565138qav.16.2014.12.19.06.17.43 (version=TLSv1.1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Fri, 19 Dec 2014 06:17:45 -0800 (PST) From: Petri Savolainen To: lng-odp@lists.linaro.org Date: Fri, 19 Dec 2014 16:16:05 +0200 Message-Id: <1418998565-5097-1-git-send-email-petri.savolainen@linaro.org> X-Mailer: git-send-email 2.2.1 X-Topics: patch Subject: [lng-odp] [PATCH] api: config: Separate api spec and linux-generic limits 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: petri.savolainen@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.173 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 Document purpose of configuration options in generic terms and label linux-generic implementation limits with @internal doxygen tag. Signed-off-by: Petri Savolainen Reviewed-by: Bill Fischofer --- platform/linux-generic/include/api/odp_config.h | 83 +++++++++++++------------ 1 file changed, 42 insertions(+), 41 deletions(-) diff --git a/platform/linux-generic/include/api/odp_config.h b/platform/linux-generic/include/api/odp_config.h index 2f839b3..542a719 100644 --- a/platform/linux-generic/include/api/odp_config.h +++ b/platform/linux-generic/include/api/odp_config.h @@ -49,72 +49,73 @@ extern "C" { #define ODP_CONFIG_PKTIO_ENTRIES 64 /** - * Minimum supported buffer alignment - * This defines the minimum buffer alignment request. Requests for - * values below this will be rounded up to this value. + * Minimum buffer alignment + * + * This defines the minimum supported buffer alignment. Requests for values + * below this will be rounded up to this value. */ #define ODP_CONFIG_BUFFER_ALIGN_MIN 8 /** - * Maximum supported buffer alignment - * This defines the maximum supported buffer alignment. Requests for - * values above this will fail. + * Maximum buffer alignment + * + * This defines the maximum supported buffer alignment. Requests for values + * above this will fail. */ - #define ODP_CONFIG_BUFFER_ALIGN_MAX (4*1024) /** * Default packet headroom - * This is default headroom that will be applied to any buffer pool created - * for packets. Note that while headroom serves to reserve space for packet - * header expansion via the odp_packet_push_head() routine, it also serves to - * align packets within the buffer. ODP packet buffers always have a minimum - * of 8 byte alignment, so the headroom can be used to offset packets so that, - * for example, a 14 byte standard Ethernet header ends on a 4 byte boundary - * so that the following IP header begins on a 4 byte alignment. Note also - * that this is the minimum headroom value that the application - * requires. Implementations are free to add to whatever value is specified - * here in multiples of 8 bytes to preserve the implied alignment - * specification. The specific default shown here allows a 1500-byte packet - * to be received into a single segment with Ethernet offset alignment and - * room for some header expansion. + * + * This defines the minimum number of headroom bytes that newly created packets + * have by default. The default apply to both ODP packet input and user + * allocated packets. Implementations may reserve a larger than minimum headroom + * size e.g. due to HW or a protocol specific alignment requirement. + * + * @internal In linux-generic implementation: + * The default value (66) allows a 1500-byte packet to be received into a single + * segment with Ethernet offset alignment and room for some header expansion. */ #define ODP_CONFIG_PACKET_HEADROOM 66 /** * Default packet tailroom - * This is the default tailroom that will be applied to any buffer pool - * created for packets. This specifies the minimum tailroom value that the - * application requires. Implementations are free to add to this as desired + * + * This defines the minimum number of tailroom bytes that newly created packets + * have by default. The default apply to both ODP packet input and user + * allocated packets. Implementations are free to add to this as desired * without restriction. Note that most implementations will automatically * consider any unused portion of the last segment of a packet as tailroom */ #define ODP_CONFIG_PACKET_TAILROOM 0 /** - * Minimum packet segment size - * This defines the minimum allowable size for packet segments. It exists to - * ensure that the application can have a reasonable expectation that all - * packet headers will reside in the first packet segment. Note that this - * value MUST be a multiple of 8. + * Minimum packet segment length + * + * This defines the minimum packet segment length in bytes. The user defined + * buffer size (in odp_buffer_pool_param_t) in buffer pool creation will be + * rounded up into this value. * - * This is the granularity of segmented buffers/packets. Note that this is - * currently only applicable to buffers of type ODP_BUFFER_TYPE_PACKET. It is - * sized for now to be large enough to support 1536-byte packets with the - * default headroom shown above, since the raw socket interface does not - * at present support scatter/gather I/O. This is subject to the - * ODP_CONFIG_PACKET_BUF_MIN_LEN configuration shown above and MUST be a - * multiple of ODP_CACHE_LINE_SIZE. 1664 is used here as a default since it is - * a multiple of both 64 and 128, which are the most common cache line sizes. - * Adjust as needed for your platform. + * @internal In linux-generic implementation: + * - The value MUST be a multiple of 8. + * - The value MUST be a multiple of ODP_CACHE_LINE_SIZE + * - The default value (1664) is large enough to support 1536-byte packets + * with the default headroom shown above and is a multiple of both 64 and 128, + * which are the most common cache line sizes. */ #define ODP_CONFIG_PACKET_BUF_LEN_MIN (1664) /** - * Maximum packet length supported - * MUST be an integral number of segments and SHOULD be large enough to - * accommodate jumbo packets (9K). Attempts to allocate or extend packets to - * sizes larger than this limit will fail. + * Maximum packet buffer length + * + * This defines the maximum number of bytes that can be stored into a packet + * (maximum return value of odp_packet_buf_len()). Attempts to allocate + * (including default head- and tailrooms) or extend packets to sizes larger + * than this limit will fail. + * + * @internal In linux-generic implementation: + * - The value MUST be an integral number of segments + * - The value SHOULD be large enough to accommodate jumbo packets (9K) */ #define ODP_CONFIG_PACKET_BUF_LEN_MAX (ODP_CONFIG_PACKET_BUF_LEN_MIN*6)