From patchwork Wed Apr 16 10:36:19 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 28453 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-pb0-f72.google.com (mail-pb0-f72.google.com [209.85.160.72]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 077322036A for ; Wed, 16 Apr 2014 10:37:01 +0000 (UTC) Received: by mail-pb0-f72.google.com with SMTP id jt11sf40290512pbb.3 for ; Wed, 16 Apr 2014 03:37:01 -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:mime-version:subject:precedence:list-id:list-unsubscribe :list-archive:list-post:list-help:list-subscribe:errors-to:sender :x-original-sender:x-original-authentication-results:mailing-list :content-type:content-transfer-encoding; bh=JVuHVpwuQWfBd2vJiBsWGLg/N4oQAXk2MhxjvPuqKqY=; b=SoIQhlvRX/F09z8qvnh1WCRsFeaQJF8pJYO0TuTw45qT8VkS9409Fn14Ey8YRR9dhi zLeXm8P2PGA7tlTPQpx1F0MYDdIsX/OarbGMwn5Wp1XaGnW4Di2BbPuBxdVEnjk1iZCA YHiZ6tDNecOUqCK3vsmkr7AZhQXAAkr2y4sXBxrA3ZM34L/Se/vT6+LgUaMdC5u+xvjL vdpXWn0xQnZnwa0vCwkjhllhcVfxTVE8aPTgDZinRIFvr5Yih95WdgTxvpE0Ls2nYCiJ D0+t0qhHQH1py1pO5+1CgGrV16yYUXvF+RDd3BkbeREMKeg0PZFomcq9TqXUGdVvtZQH Q1yg== X-Gm-Message-State: ALoCoQl7fFv6iG1oi2Hwh7oBi0eq9P5x/geUoCR/brhlWWBV+Ht4NvlcgnPwh037wpLAwWagAkwe X-Received: by 10.68.216.230 with SMTP id ot6mr3557619pbc.3.1397644621300; Wed, 16 Apr 2014 03:37:01 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.140.47.197 with SMTP id m63ls535603qga.58.gmail; Wed, 16 Apr 2014 03:37:01 -0700 (PDT) X-Received: by 10.220.167.2 with SMTP id o2mr2371165vcy.8.1397644621159; Wed, 16 Apr 2014 03:37:01 -0700 (PDT) Received: from mail-ve0-f171.google.com (mail-ve0-f171.google.com [209.85.128.171]) by mx.google.com with ESMTPS id sc7si3805860vdc.175.2014.04.16.03.37.01 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 16 Apr 2014 03:37:01 -0700 (PDT) Received-SPF: neutral (google.com: 209.85.128.171 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) client-ip=209.85.128.171; Received: by mail-ve0-f171.google.com with SMTP id jy13so10824768veb.30 for ; Wed, 16 Apr 2014 03:37:01 -0700 (PDT) X-Received: by 10.53.1.69 with SMTP id be5mr1220328vdd.27.1397644621061; Wed, 16 Apr 2014 03:37:01 -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.220.221.72 with SMTP id ib8csp301407vcb; Wed, 16 Apr 2014 03:37:00 -0700 (PDT) X-Received: by 10.224.66.4 with SMTP id l4mr1786594qai.70.1397644620525; Wed, 16 Apr 2014 03:37:00 -0700 (PDT) Received: from ip-10-141-164-156.ec2.internal (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTPS id u89si9031709qga.83.2014.04.16.03.36.59 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Wed, 16 Apr 2014 03:37:00 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Received: from localhost ([127.0.0.1] helo=ip-10-141-164-156.ec2.internal) by ip-10-141-164-156.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1WaNCz-0006pc-B0; Wed, 16 Apr 2014 10:36:49 +0000 Received: from mail-qa0-f49.google.com ([209.85.216.49]) by ip-10-141-164-156.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1WaNCo-0006p6-FI for lng-odp@lists.linaro.org; Wed, 16 Apr 2014 10:36:38 +0000 Received: by mail-qa0-f49.google.com with SMTP id j7so10314816qaq.22 for ; Wed, 16 Apr 2014 03:36:43 -0700 (PDT) X-Received: by 10.140.103.74 with SMTP id x68mr1686865qge.82.1397644603601; Wed, 16 Apr 2014 03:36:43 -0700 (PDT) Received: from fedora1.holmesfamily.ws (c-98-221-136-245.hsd1.nj.comcast.net. [98.221.136.245]) by mx.google.com with ESMTPSA id 1sm14746906qal.29.2014.04.16.03.36.42 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 16 Apr 2014 03:36:43 -0700 (PDT) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Wed, 16 Apr 2014 06:36:19 -0400 Message-Id: <1397644580-5709-2-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1397644580-5709-1-git-send-email-mike.holmes@linaro.org> References: <1397644580-5709-1-git-send-email-mike.holmes@linaro.org> MIME-Version: 1.0 Subject: [lng-odp] [PATCH v2 1/2] exception handling 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: , 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=neutral (google.com: 209.85.128.171 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) 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: Mike Holmes --- exception_handling.dox | 119 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 exception_handling.dox diff --git a/exception_handling.dox b/exception_handling.dox new file mode 100644 index 0000000..2645caa --- /dev/null +++ b/exception_handling.dox @@ -0,0 +1,119 @@ +/* +Copyright (c) 2014, Linaro Limited +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or + other materials provided with the distribution. + + * Neither the name of Linaro Limited nor the names of its contributors may be + used to endorse or promote products derived from this software without specific + prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +*/ + +/** +@page exception_handling Exception handling in the ODP API +@tableofcontents + +For the implimentation of the exception handling please see @ref odp_debug.h + +@section requirements Requirements +- Minimal overhead in a finished running system. +- Minimizing the propagation of an error from its point of origin +- Identifying what is a programming error +- Identifying a legitimate infield exception +- We only specify what happens inside the ODP library, not in a calling application + +There are two kinds of exceptional behaviour, +-# Run time exceptions, those that are unusual but foreseeable cases in a running system (out of memory) +-# Programming exceptions, those introduced as bugs (null pointers, out of bounds). + +@section run_time Run time exceptions +These are characterized by the following rules in order of importance +-# These must gracefully leave the system in a known stable state. +-# These checks must remain unconditionally in the code base. +-# These should return the error state to the caller. +-# They may emit an error message via \ref ODP_ERR which can be redefined or disabled. + +@subsection run_time_examples Examples +- Being "too late" to cancel a timer that's already popped, or exceeding some implementation-defined limit +- Backpressure due to resource limits (corner case that is error-prone) +- Checks for any condition that could arise in the field, e.g. running out of buffers or failure to allocate memory +@code + +if (unrecoverable_out_of_foos == 1) +{ + ODP_ERR("Completely unable to proceed, no foos available"); + tidy_op_for_exit(); + ... +} + +@endcode +@note ODP does not trap segfaults, it may not be checking for NULL pointers etc to improve the execution speed. The application should trap segfaults. + +@section programming_exceptions Programming exceptions +There are two classes of programming error +-# Compile time, these can be caught by compile time assertions in the preprocessor +-# Run Time, these are run time assertions + +@section compile_time Compile time programming exceptions +These have the following rules +-# Zero overhead at run time, they never need to be turned off (undefined) +-# Use @#error which will break the build, or @#warning which may not break the build unless -Werror is defined. +-# Can be done for any static evaluation case. + +@subsection compile_time_examples Examples +Checking size and alignment of a struct with offsetof + +@code +typedef struct timer timer;} +struct timer +{ + uint8_t MODE; + uint32_t DATA; + uint32_t COUNT; +}; + + +#if (offsetof(timer, DATA) != 4)} +#error DATA must be at offset 4 in timer +#endif +@endcode + +@section compile_run_time Run time programming exceptions +There are two rules +-# These must be capable of being turned off by defining -DNODP_DEBUG +-# They must use ODP_ASSERT so that the output may be redirected on systems without stderr. +-# ODP_ASSERT will call abort() as its final operation. + +@note ODP_ASSERT is defined to make it easier to redirect output from stderr. For example +an in memory text buffer may be in use if stderr has no meaning on a bare metal implimentation + +@subsection compile_run_time_examples Examples +Checks that the API function arguments are within the permitted value range (e.g. handle validation + +@code +void odp_foo(char *pointer) +{ + ODP_ASSERT(pointer != NULL); + … +} +@endcode +*/