From patchwork Tue Feb 16 03:18:54 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Martin Sebor X-Patchwork-Id: 583131 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 53138140557 for ; Tue, 16 Feb 2016 14:19:17 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.b=vadpmKox; dkim-atps=neutral DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender :subject:to:references:cc:from:message-id:date:mime-version :in-reply-to:content-type; q=dns; s=default; b=LKIuWpso3cqHPoYJU ouIgTZE8zm35AUA9J1q2Ngh2K0kzAc6SbiFwk2xfRYeg37Vaz+Qbhr4lAOQqLIYi HupV6OW+Mcnz27sUpCh/PO5YicP+hgry8UaNt15PWwPnWJtj+DsUFjQvYh8Qemo4 FW5++cEpueKkyT6ymrUu35TMuY= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender :subject:to:references:cc:from:message-id:date:mime-version :in-reply-to:content-type; s=default; bh=LR7qM3AfqRXOW2H3rUv57Vk Tifs=; b=vadpmKox56+2WmJFGdJ4IuGB/706A1QHSVVwn/eF7pZ+7WjuUlOmWnY yIpXmPGPye+BQtjLHTOervhXFF8Pt7NwH+VaxDm6Bso2dmQpK0hOnER5GokQX8zG D0Bh7oQNq640+EUtEmfsqIaAiZ/g9/S8Sks8KpzlOAO9b3t4Efc8= Received: (qmail 78300 invoked by alias); 16 Feb 2016 03:19:09 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 78229 invoked by uid 89); 16 Feb 2016 03:19:03 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.6 required=5.0 tests=BAYES_00, FREEMAIL_FROM, RCVD_IN_DNSWL_LOW, SPF_PASS autolearn=ham version=3.3.2 spammy=anticipate, msebor@redhat.com, mseborredhatcom, GLIBC X-HELO: mail-qg0-f52.google.com Received: from mail-qg0-f52.google.com (HELO mail-qg0-f52.google.com) (209.85.192.52) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES128-GCM-SHA256 encrypted) ESMTPS; Tue, 16 Feb 2016 03:19:01 +0000 Received: by mail-qg0-f52.google.com with SMTP id b35so124150464qge.0 for ; Mon, 15 Feb 2016 19:18:59 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:subject:to:references:cc:from:message-id:date :user-agent:mime-version:in-reply-to:content-type; bh=W01YGpbR109ELbE4Pxa2NWZv77QwWvTpOFJo93XRSgI=; b=RYYy1a+NnT0nudce+E8YzqTpG7HmKr0yanBWuXAZVZ8GKWG6SPp0TIUykwI7mwXEJH 2Xp1CnJITg960Q/HZFLRafpVF26cG40byEh5gbTEll8z64vA6667WP980cWV5ONQ36q1 FOeIG3TDqaMPMEO2eCZFClKArJEoyRz5AZmmaUYlFTIOhjXWV9em9NioRo6WwNwDyx1h uZRhPyBw/JJo6bIHvoPYyTQH9NhiSW5AmAlFvhMil7TCmjOp/pcGpxQ4c4gG971Rthiv +ZU0Ky/C27BHGMHi629DMpC58WN2DDOVpwd88jnBYpveGMiZiTw4OHuSoTCbGjIPVUuO 64WA== X-Gm-Message-State: AG10YOT8/cuGMR58NqpSHToVsfVmwlaFr3gJbHW1ESmmRLw5mGw5r3G5pbLK7kh+AB+45A== X-Received: by 10.140.133.133 with SMTP id 127mr25880459qhf.42.1455592737803; Mon, 15 Feb 2016 19:18:57 -0800 (PST) Received: from [192.168.0.26] (71-215-88-205.hlrn.qwest.net. [71.215.88.205]) by smtp.gmail.com with ESMTPSA id l20sm3531270qhc.24.2016.02.15.19.18.55 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 15 Feb 2016 19:18:56 -0800 (PST) Subject: Re: [PATCH] 69759 - document __builtin_alloca and __builtin_alloca_with_align To: Joseph Myers References: <56BF8976.3080907@gmail.com> Cc: Gcc Patch List From: Martin Sebor Message-ID: <56C2951E.1040304@gmail.com> Date: Mon, 15 Feb 2016 20:18:54 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.1.0 MIME-Version: 1.0 In-Reply-To: X-IsSubscribed: yes On 02/15/2016 04:18 PM, Joseph Myers wrote: > The description here is self-contradictory; __BIGGEST_ALIGNMENT__ bytes is > often different from the greatest fundamental alignment (fundamental > alignments and max_align_t only consider standard C types, > __BIGGEST_ALIGNMENT__ can allow for e.g. vector type extensions). Thank you for reviewing the patch. You're right that I conflated fundamental alignment with the strictest alignment. I've adjusted the description to make a distinction between __BIGGEST_ALIGNMENT__ and _Alignof(max_align_t) since they, as you point out, need not be the same (for example on i386 Linux with GLIBC I see that the former is 16 while the latter 8, which is correct because on GLIBC's malloc returns 8-byte aligned pointers). I've also fixed a few typos and made additional adjustments to reflect the fixes in my patch for bug 69780 that I anticipate committing later this week. That said, I think it's worth pointing out that max_align_t has nothing to do with standard C types. The intent of the type is to expose a type with the strictest alignment supported by an implementation for an object of any type and with any storage duration, not the alignment of the most strictly aligned basic (or fundamental) type. Martin PR c/69759 - __builtin_alloca and __builtin_alloca_with_align undocumented gcc/ChangeLog: 2016-02-15 Martin Sebor PR c/69759 * doc/extend.texi (Other Builtins): Document __builtin_alloca and __builtin_alloca_with_align. Index: gcc/doc/extend.texi =================================================================== --- gcc/doc/extend.texi (revision 233367) +++ gcc/doc/extend.texi (working copy) @@ -10144,6 +10144,8 @@ in the Cilk Plus language manual which c @node Other Builtins @section Other Built-in Functions Provided by GCC @cindex built-in functions +@findex __builtin_alloca +@findex __builtin_alloca_with_align @findex __builtin_call_with_static_chain @findex __builtin_fpclassify @findex __builtin_isfinite @@ -10690,6 +10692,93 @@ In the same fashion, GCC provides @code{ @code{__builtin_} prefixed. The @code{isinf} and @code{isnan} built-in functions appear both with and without the @code{__builtin_} prefix. +@deftypefn {Built-in Function} void* __builtin_alloca (size_t size) +The @code{__builtin_alloca} function must be called at block scope. +The function allocates an object @var{size} bytes large on the stack of +the calling function. The object is aligned at the greatest supported +alignment boundary for the target. The greatest supported alignment +is the value of the @code{__BIGGEST_ALIGNMENT__} macro. Portable C11 +and C++11 (or later) programs can obtain a similar value by evaluating +the @code{_Alignof (max_align_t)} and @code{alignof (std::max_align_t)} +expressions, respectively, which yield an alignment suitable for any +standard type in each language. @code{__builtin_alloca} returns a pointer +to the first byte of the allocated object. The lifetime of the allocated +object ends just before the calling function returns to its caller. This +is so even when @code{__builtin_alloca_with_align} is called within a nested +block. + +For example, the following function allocates eight objects of @code{n} +bytes each on the stack, storing a pointer to each in consecutive elements +of the array @code{a}. It then passes the array to function @code{g()} +which can safely use the storage pointed to by each of the array elements. + +@smallexample +void f (unsigned n) +@{ + void *a [8]; + for (int i = 0; i != 8; ++i) + a [i] = __builtin_alloca (n); + + g (a, n); // safe +@} +@end smallexample + +Since the @code{__builtin_alloca} function doesn't validate its arguments +it is the responsibility of its caller to make sure the argument doesn't +cause it doesn't exceed the stack size limit. +The @code{__builtin_alloca} function is provided to make it possible to +allocate arrays with a runtime bound on the stack. Since C99 variable +length arrays offer similar functionality under a portable, more convenient, +and safer interface they are recommended instead, in both C99 and C++ +programs where GCC provides them as an extension. + +@end deftypefn + +@deftypefn {Built-in Function} void* __builtin_alloca_with_align (size_t size, size_t align) +The @code{__builtin_alloca_with_align} function must be called at block +scope. The function allocates an object @var{size} bytes large on +the stack of the calling function. The allocated object is aligned on +the boundary specified by the argument @var{align} whose unit is given +in bits (not bytes). @var{size} must be positive and not exceed the stack +size limit. @var{align} must be a constant integer expression that +evaluates to a power of 2 greater than or equal to @code{__CHAR_BIT__}. +Invocations with other values are rejected with an error. The function +returns a pointer to the first byte of the allocated object. The lifetime +of the allocated object ends at the end of the block in which the function +was called. The allocated storage is released no later than just before +the calling function returns to its caller, but may be released as early +as when control leaves the block in which the function was called. + +For example, in the following function the call to @code{g()} is unsafe +because when @code{overalign} is non-zero, the space allocated by +@code{__builtin_alloca_with_align} may have been released at the end +of the @code{if} statement in which it was called. + +@smallexample +void f (unsigned n, bool overalign) +@{ + void *p; + if (overalign) + p = __builtin_alloca_with_align (n, 64); + else + p = __builtin_alloc (n); + + g (p, n); // unsafe +@} +@end smallexample + +Since the @code{__builtin_alloca_with_align} function doesn't validate +the @code{size} argument it is the responsibility of its caller to make +sure the argument doesn't cause it to exceed the stack size limit. +The @code{__builtin_alloca_with_align} function is provided to make +it possible to allocate overaligned arrays with a runtime bound on +the stack. Since C99 variable length arrays offer the same functionality +under a portable, more convenient, and safer interface they are recommended +instead, in both C99 and C++ programs where GCC provides them as +an extension. + +@end deftypefn + @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) You can use the built-in function @code{__builtin_types_compatible_p} to