From patchwork Thu Feb 19 16:16:10 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 441679 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 C3969140151 for ; Fri, 20 Feb 2015 03:16:59 +1100 (AEDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender :message-id:date:from:mime-version:to:subject:content-type; q= dns; s=default; b=LifkYweIOlqKJKviFyq+/+aYt8S9h1Y0QU+IYPN47i7xBD Vobfm7W/3LEt8wDYuEbGbnRsv6BXB1ANQvJsLyeuSExhX+KyYIbm1G5zYRRZxakb r7G8vqbWoawdRfd0/MVdzZpFIIgt57aG6UULQd1w0oPFU9l9FEsWnItGUpw18= 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 :message-id:date:from:mime-version:to:subject:content-type; s= default; bh=kJ/vngkx64t2ld8h+yT03ocWU+s=; b=C9fGY84kFC0bjTCVaPxS IMAp1p3h7HFOJ3vgt9oQL8KLRq54DBsHq0n6Puy3Glqv2hhj+oysYhUQJmzVSPHU EQ97Rh8bfVPK/tKCIjf3AGDssQwvxHpdtHHGJmBVvZwHwjpE0rQcOG4tDOEWMyr+ iUBeits36TM4k2AHTM0sAVg= Received: (qmail 12924 invoked by alias); 19 Feb 2015 16:16:37 -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 12839 invoked by uid 89); 19 Feb 2015 16:16:36 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.1 required=5.0 tests=AWL, BAYES_00, RCVD_IN_DNSWL_LOW, SPF_PASS autolearn=ham version=3.3.2 X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Thu, 19 Feb 2015 16:16:35 +0000 Received: from svr-orw-fem-03.mgc.mentorg.com ([147.34.97.39]) by relay1.mentorg.com with esmtp id 1YOTmA-00050I-Kf from Sandra_Loosemore@mentor.com for gcc-patches@gcc.gnu.org; Thu, 19 Feb 2015 08:16:30 -0800 Received: from [IPv6:::1] (147.34.91.1) by svr-orw-fem-03.mgc.mentorg.com (147.34.97.39) with Microsoft SMTP Server id 14.3.224.2; Thu, 19 Feb 2015 08:16:30 -0800 Message-ID: <54E60C4A.9050800@codesourcery.com> Date: Thu, 19 Feb 2015 09:16:10 -0700 From: Sandra Loosemore User-Agent: Mozilla/5.0 (X11; Linux i686; rv:17.0) Gecko/20130329 Thunderbird/17.0.5 MIME-Version: 1.0 To: GCC Patches Subject: [doc, committed] copy-edit x86 transactional memory intrinsics section A while ago when I was doing some other work on extend.texi, I noticed that the section on x86 transactional memory intrinsics was in need of cleanup. I've checked in this patch to do some content-free copy-editing -- fixing typos and markup, rephrasing some awkward sentences, etc. To tell the truth I don't think the documentation in this section is useful to anyone who doesn't already know how to use the feature, so it could still use more content-full editing as well. But, at least this is an incremental improvement. -Sandra Index: gcc/doc/extend.texi =================================================================== --- gcc/doc/extend.texi (revision 220818) +++ gcc/doc/extend.texi (working copy) @@ -17257,10 +17257,11 @@ int __builtin_ia32_xtest () @node x86 transactional memory intrinsics @subsection x86 Transactional Memory Intrinsics -Hardware transactional memory intrinsics for x86. These allow to use +These hardware transactional memory intrinsics for x86 allow you to use memory transactions with RTM (Restricted Transactional Memory). -For using HLE (Hardware Lock Elision) see @ref{x86 specific memory model extensions for transactional memory} instead. This support is enabled with the @option{-mrtm} option. +For using HLE (Hardware Lock Elision) see +@ref{x86 specific memory model extensions for transactional memory} instead. A memory transaction commits all changes to memory in an atomic way, as visible to other threads. If the transaction fails it is rolled back @@ -17271,12 +17272,12 @@ and suitable fallback code always needs @deftypefn {RTM Function} {unsigned} _xbegin () Start a RTM (Restricted Transactional Memory) transaction. -Returns _XBEGIN_STARTED when the transaction +Returns @code{_XBEGIN_STARTED} when the transaction started successfully (note this is not 0, so the constant has to be -explicitely tested). When the transaction aborts all side effects +explicitly tested). If the transaction aborts, all side-effects are undone and an abort code is returned. There is no guarantee any transaction ever succeeds, so there always needs to be a valid -tested fallback path. +fallback path. @end deftypefn @smallexample @@ -17290,38 +17291,38 @@ if ((status = _xbegin ()) == _XBEGIN_STA @} @end smallexample -Valid abort status bits (when the value is not @code{_XBEGIN_STARTED}) are: +If the transaction aborts, the return value is one of: @table @code @item _XABORT_EXPLICIT -Transaction explicitely aborted with @code{_xabort}. The parameter passed -to @code{_xabort} is available with @code{_XABORT_CODE(status)} +Transaction was explicitly aborted with @code{_xabort}. The parameter passed +to @code{_xabort} is available with @code{_XABORT_CODE(status)}. @item _XABORT_RETRY Transaction retry is possible. @item _XABORT_CONFLICT -Transaction abort due to a memory conflict with another thread +Transaction abort due to a memory conflict with another thread. @item _XABORT_CAPACITY -Transaction abort due to the transaction using too much memory +Transaction abort due to the transaction using too much memory. @item _XABORT_DEBUG -Transaction abort due to a debug trap +Transaction abort due to a debug trap. @item _XABORT_NESTED -Transaction abort in a inner nested transaction +Transaction abort in an inner nested transaction. @end table @deftypefn {RTM Function} {void} _xend () -Commit the current transaction. When no transaction is active this will -fault. All memory side effects of the transactions will become visible -to other threads in an atomic matter. +Commit the current transaction. When no transaction is active this faults. +All memory side-effects of the transaction become visible +to other threads in an atomic manner. @end deftypefn @deftypefn {RTM Function} {int} _xtest () -Return a value not zero when a transaction is currently active, otherwise 0. +Return a nonzero value if a transaction is currently active, otherwise 0. @end deftypefn @deftypefn {RTM Function} {void} _xabort (status) Abort the current transaction. When no transaction is active this is a no-op. -status must be a 8bit constant, that is included in the status code returned -by @code{_xbegin} +The @var{status} is an 8-bit constant; its value is encoded in the return +value from @code{_xbegin}. @end deftypefn @node Target Format Checks