From patchwork Wed Nov 26 18:05:48 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 41562 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-lb0-f200.google.com (mail-lb0-f200.google.com [209.85.217.200]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 9B16C203C2 for ; Wed, 26 Nov 2014 18:06:17 +0000 (UTC) Received: by mail-lb0-f200.google.com with SMTP id f15sf2152095lbj.7 for ; Wed, 26 Nov 2014 10:06:16 -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=fFatYLElm5Mf79QiaK73rl0ibClFxfW882GhYaW0Cxc=; b=Qmg2E4fGgci057tVA6wad+SeAQfQdO1l2lyTAO04o63AYR6dpDdGLkmFquDuwlVgzc 0agIW0N8ineh+d7/KcK1naBK4ojIIiwrRJQ5OgFOixbKiGxP218Cl068bkzFphjmAv4T LhZtOqLYboUJ3tVYhT562/q1ehss1PSKAS+BjUSiIBArfNj3vuaZiFyJn7s2Qsat12W/ PFR7bOlVJqQCncqMzbRQBNp2sW56nihscIX8waErfIQiZBJb4htKQnG7K6Eda8fwZrYd nVtxlktzlCriy4q5DpQP/piD84JhNJYppmuurZKjYpOdATit51t+S1Sd3XBXbNJFD4Ah pwlQ== X-Gm-Message-State: ALoCoQm5XTLdEoWXFKo8g+34ktqsWRh6jw2bjLDAjvWNt2RlxB4Fzlzh9aj+gxghH97j97gJp0e2 X-Received: by 10.180.206.77 with SMTP id lm13mr1206036wic.4.1417025176606; Wed, 26 Nov 2014 10:06:16 -0800 (PST) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.36.67 with SMTP id o3ls695727laj.86.gmail; Wed, 26 Nov 2014 10:06:16 -0800 (PST) X-Received: by 10.112.73.39 with SMTP id i7mr35190057lbv.8.1417025176393; Wed, 26 Nov 2014 10:06:16 -0800 (PST) Received: from mail-la0-f52.google.com (mail-la0-f52.google.com. [209.85.215.52]) by mx.google.com with ESMTPS id rq10si5061404lbb.136.2014.11.26.10.06.16 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 26 Nov 2014 10:06:16 -0800 (PST) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.52 as permitted sender) client-ip=209.85.215.52; Received: by mail-la0-f52.google.com with SMTP id q1so2972638lam.11 for ; Wed, 26 Nov 2014 10:06:16 -0800 (PST) X-Received: by 10.152.43.103 with SMTP id v7mr11799704lal.29.1417025176253; Wed, 26 Nov 2014 10:06:16 -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.184.201 with SMTP id ew9csp670356lbc; Wed, 26 Nov 2014 10:06:15 -0800 (PST) X-Received: by 10.224.137.68 with SMTP id v4mr47663289qat.46.1417025175010; Wed, 26 Nov 2014 10:06:15 -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 v7si5815414qaf.108.2014.11.26.10.06.11 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Wed, 26 Nov 2014 10:06:14 -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 1Xtgyg-00050W-7d; Wed, 26 Nov 2014 18:06:10 +0000 Received: from mail-qg0-f52.google.com ([209.85.192.52]) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1XtgyY-00050H-F8 for lng-odp@lists.linaro.org; Wed, 26 Nov 2014 18:06:02 +0000 Received: by mail-qg0-f52.google.com with SMTP id a108so2456188qge.11 for ; Wed, 26 Nov 2014 10:05:57 -0800 (PST) X-Received: by 10.140.22.201 with SMTP id 67mr46734947qgn.16.1417025157234; Wed, 26 Nov 2014 10:05:57 -0800 (PST) Received: from fedora1.holmesfamily.ws ([98.221.136.245]) by mx.google.com with ESMTPSA id s3sm4506727qat.4.2014.11.26.10.05.56 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 26 Nov 2014 10:05:56 -0800 (PST) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Wed, 26 Nov 2014 13:05:48 -0500 Message-Id: <1417025148-21535-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.1.0 X-Topics: patch Subject: [lng-odp] [PATCH] api_guide_lines: Update bool, is, has and get rules 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: mike.holmes@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.52 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 The API require guide lines to help it conform to a consistent look and feel. These additional clarifications help promote those guidelines. Signed-off-by: Mike Holmes Reviewed-by: Maxim Uvarov --- api_guide_lines.dox | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/api_guide_lines.dox b/api_guide_lines.dox index 4903961..be23e9a 100644 --- a/api_guide_lines.dox +++ b/api_guide_lines.dox @@ -48,7 +48,7 @@ type | Correct use |---| :--------- void | SHOULD be used for APIs that do not return a value void*| SHOULD be used for APIs that return a pointer intended to be used by the caller. For example, a routine that returns the address of an application context area SHOULD use a void * return type -int | SHOULD be used for APIs that return a boolean value. The values 1 = true, 0 = false are used for this purpose +odp_bool_t | SHOULD be used for APIs that return a @ref boolean value. int | SHOULD be used for success and failure indications, with 0 indicating a success. Errno may be set @subsection parameters Parameter Structure and Validation @@ -79,6 +79,27 @@ Other mechanisms available to the implementer are: - ODP_LOG() is used to direct implementation messages to the application. +@subsection function_name Function Names +Functions must attempt to be so clear in their intent that referencing the documentation is not necessary, the guidelines below should be followed unless a strong case is made for an exception. + +@subsection getters Getting information + +@subsubsection is_has Is / Has +An api with "is" or "has" are both considered @ref boolean questions. They can only return true or false and it reflects the current state of something. + +An example might be a packet interface, you might want to know if it is in promiscuous mode. +@code odp_bool_t state = odp_pktio_is_promiscuous(pktio handle) @endcode + +In addtion you might want to know if it has the ability to be in promiscuous mode. +@code odp_bool_t state = odp_pktio_has_promiscuous(pktio handle) @endcode + +Another case might be if a packet has a vlan flag set +@code odp_bool_t state = odp_packet_has_vlan(packet handle) @endcode + +@subsubsection get Get +Where possible returned information should be an enum if it reflects a finite list of information. +In general get apis drop the actual tag "get" in the function name. + @subsection function_calls Function Calls ODP APIs typically have prototypes of the form: @@ -95,7 +116,7 @@ p2_type | Is the data type of the second parameter, etc. For ODP APIs that return void, results are undefined if the input parameters are invalid. For those that return void *, the value ODP_NULL or ODP_INVALID MAY be used to indicate call failure. -For non-boolean APIs returning int, a return value of 0 indicates success while non-zero indicates failure. +For non-boolean APIs returning int, a return value of 0 indicates success while non-zero indicates failure see @ref success. @subsection errno Use of errno ODP APIs SHOULD make use of the thread-local variable errno, defined in the standard library include file errno.h, to indicate a reason for an API call failure when appropriate. @@ -116,14 +137,13 @@ An example of this might be the number of queues that an application can create. An attempt to allocate more queues than the underlying implementation supports would result in this failure code being returned via errno. @subsection boolean Boolean -For odp booleans are integers (int) -The values 1 = true, 0 = false are used for this purpose. +For odp all booleans are integers. To aid application readability they are defined as the type odp_bool_t. +The values !0 = true, 0 = false are used for this purpose. @subsection success Success and Failure Pass indications are integers (int) and SHOULD also be used for APIs that return a simple success/failure indication to the caller. In this case the return value 0 indicates success while non-zero (typically -1) indicates failure and errno is set to a reason code that indicates the nature of the failure. - @section implementation Implementation Considerations To support application portability and preserve implementation flexibility, ODP APIs MUST be designed with several guiding principles in mind.