From patchwork Thu Jan 4 10:22:13 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Richard Sandiford X-Patchwork-Id: 123401 Delivered-To: patch@linaro.org Received: by 10.80.135.92 with SMTP id 28csp6538107edv; Thu, 4 Jan 2018 02:22:36 -0800 (PST) X-Google-Smtp-Source: ACJfBov42qLQHbM1ngSPWFxHIAa7QB+SdQT5B6RHw1Sx1hmWH029yadqT5MtpZeopo5nUCiZouHi X-Received: by 10.84.230.137 with SMTP id e9mr3995006plk.293.1515061356724; Thu, 04 Jan 2018 02:22:36 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1515061356; cv=none; d=google.com; s=arc-20160816; b=0lXf//NAoboNPwx0IFr+Z63tLxAnzOOHq4c4dTJfyWKRqn8ceNRHCW/+35xUVBbacu XyjCnEqX3ls/r8V656q8ulfL5ImX6qu+JBmWQlFgK7PAg3nwwXrC9UxLadrkcvDlxEQ7 hZc4I+0zYFx8UTT7oj0LqDU2jcYtv7S4Cyfau5+aqoA+5OylJvUpQSpWBwFJSrbEfrsK RitvrGfLzLpF5OExOKwd8alJ3nSZUVQzuGP6MgS1wVdOI/14088GoQHbLRTtP4U4F5D6 LVwTnjkJWaZlfuSb24cj6De/0cJVC5bJXGHH5h+9KeAENHPkJn7xNNAqhMyQOZm2074D k0/w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=mime-version:user-agent:message-id:date:subject:mail-followup-to:to :from:delivered-to:sender:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:mailing-list:dkim-signature :domainkey-signature:arc-authentication-results; bh=JXL7HilS8kNEdD0sgwgJo2Rj2tHOcdLJNqkZErzC4bM=; b=PJYbG5mrmiQUCKBkkkrHmMKg5DImMPxC+Kv0O7bUu2Su11rNwc9K2AMGE83rtF+UVz HiHYVyRNoE+yy1V63vr4vQr6Wcn7qU0a8l9T3nSj/yWNv16yf7rx4hOa+3CrUKRhSO9Q ysrQtaqyMp3EFszMe5GeYo7p3SqaHfv6U8WxuvqtrmR5S54ha/qaUlcAi9L7qdPJ0dE1 jM8qJobOk4329serJdsYPW1akH8jJRxxEEo8Niuacic5dNX0rPK9S01hGDtOfbHRG2ue sxnZf2x3UmCzcp1tIR1Azt6er/SELm3clU0QXyxsH8+nL8UGBEbpv4oL5D2mAai/gHlR wq7Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=SJRpWhtJ; spf=pass (google.com: domain of gcc-patches-return-470129-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) smtp.mailfrom=gcc-patches-return-470129-patch=linaro.org@gcc.gnu.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from sourceware.org (server1.sourceware.org. [209.132.180.131]) by mx.google.com with ESMTPS id j13si1878274pgp.328.2018.01.04.02.22.36 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 04 Jan 2018 02:22:36 -0800 (PST) Received-SPF: pass (google.com: domain of gcc-patches-return-470129-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) client-ip=209.132.180.131; Authentication-Results: mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=SJRpWhtJ; spf=pass (google.com: domain of gcc-patches-return-470129-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) smtp.mailfrom=gcc-patches-return-470129-patch=linaro.org@gcc.gnu.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:from :to:subject:date:message-id:mime-version:content-type; q=dns; s= default; b=eBvdBJUBPVulx2z2iYNVUWL0KPmgHiSAgyMPPE4k/JWsTcX5X+yaB jg2zXAe7Pt+xZcfFL8PkLYskrWohn6lhlEW6VFxtpqXh5VmiOFh6d9OyhJjRast0 UkSmDYvSXn1M22a6zi2oHL4lP5BrVvo+mipw4yPFYo6j051Jxsb5WY= 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:from :to:subject:date:message-id:mime-version:content-type; s= default; bh=qcvhfAfTnJBFSlvGzg/eA3xG64Y=; b=SJRpWhtJ2ojduBB+RRnk ST6aJs0ASaxf5JLAK7w31OYkRZJfYcP+sjztgDpIAiyo0L1zJMFoxo74nVGTzfuT qZYnj76zIKFJOPzJJm3aoJwx8pAiSBwLlCn22SVBAXcs1cV8LpRdQWN3Aj3/jKTk 04At2B9RwVNfTr5B/+4EtoI= Received: (qmail 80593 invoked by alias); 4 Jan 2018 10:22:19 -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 80568 invoked by uid 89); 4 Jan 2018 10:22:19 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-16.6 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, KAM_SHORT, RCVD_IN_DNSWL_NONE, SPF_PASS autolearn=ham version=3.3.2 spammy=UD:is-a.h, is-a.h, isah, Hx-languages-length:5104 X-HELO: mail-wm0-f43.google.com Received: from mail-wm0-f43.google.com (HELO mail-wm0-f43.google.com) (74.125.82.43) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Thu, 04 Jan 2018 10:22:17 +0000 Received: by mail-wm0-f43.google.com with SMTP id a79so2500101wma.0 for ; Thu, 04 Jan 2018 02:22:16 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:mail-followup-to:subject:date:message-id :user-agent:mime-version; bh=JXL7HilS8kNEdD0sgwgJo2Rj2tHOcdLJNqkZErzC4bM=; b=s3PjmIhAnAI4ZJcnj8lsCsSw1Jg0JfW/YEGDzY0OSiASNMwkmOIlf4xdDR/Fu8dvVj uFX+5/xvKfmgZy+NYwrnaRfMCSNbyge3iioZYiOCT2BOIy6502SsikznQrbnmcJcqfbU mj+YfGP8EjUwSC7G2hZma9eAsum3SoJhuIiepDauoUHKA7VYB3g9yWN+5ofvoQRGnszb 2drgRJJVqPdqh0wcvmdfznpsFFIXA3SOyTydowf5qIq8YdlRcepZNW5HAtFX/QOmHpKX P5EIPSWkU9YnZOC0BB+R19LorBGUzih+7q3VSiPvSQrchMlLYwfVx8CZoKeJjV8b0BN7 CA0g== X-Gm-Message-State: AKGB3mLDmrbJq2q2rxtxwC/GHIyWcGbzeJ9waZAAQEFqYgA4ds9vgF3B nAq/hYnk06ZIELYiDGzP+oHO7kmwwPg= X-Received: by 10.28.9.195 with SMTP id 186mr3241326wmj.122.1515061334886; Thu, 04 Jan 2018 02:22:14 -0800 (PST) Received: from localhost ([95.144.14.233]) by smtp.gmail.com with ESMTPSA id k25sm6121890wrk.11.2018.01.04.02.22.13 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 04 Jan 2018 02:22:14 -0800 (PST) From: Richard Sandiford To: gcc-patches@gcc.gnu.org Mail-Followup-To: gcc-patches@gcc.gnu.org, richard.sandiford@linaro.org Subject: Document machine_mode wrapper classes Date: Thu, 04 Jan 2018 10:22:13 +0000 Message-ID: <87a7xtj54a.fsf@linaro.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.3 (gnu/linux) MIME-Version: 1.0 An update of the patch originally posted here, deep in the original 77 machine_mode chain: https://gcc.gnu.org/ml/gcc-patches/2017-07/msg01407.html Tested on aarch64-linux-gnu. OK to install? Richard 2018-01-04 Richard Sandiford gcc/ * doc/rtl.texi: Document machine_mode wrapper classes. Index: gcc/doc/rtl.texi =================================================================== --- gcc/doc/rtl.texi 2018-01-03 21:43:46.010576426 +0000 +++ gcc/doc/rtl.texi 2018-01-04 10:19:10.643966664 +0000 @@ -1414,6 +1414,113 @@ classes. Currently @code{VOIDmode} and @code{MODE_RANDOM}. @end table +@cindex machine mode wrapper classes +@code{machmode.h} also defines various wrapper classes that combine a +@code{machine_mode} with a static assertion that a particular +condition holds. The classes are: + +@table @code +@findex scalar_int_mode +@item scalar_int_mode +A mode that has class @code{MODE_INT} or @code{MODE_PARTIAL_INT}. + +@findex scalar_float_mode +@item scalar_float_mode +A mode that has class @code{MODE_FLOAT} or @code{MODE_DECIMAL_FLOAT}. + +@findex scalar_mode +@item scalar_mode +A mode that holds a single numerical value. In practice this means +that the mode is a @code{scalar_int_mode}, is a @code{scalar_float_mode}, +or has class @code{MODE_FRACT}, @code{MODE_UFRACT}, @code{MODE_ACCUM}, +@code{MODE_UACCUM} or @code{MODE_POINTER_BOUNDS}. + +@findex complex_mode +@item complex_mode +A mode that has class @code{MODE_COMPLEX_INT} or @code{MODE_COMPLEX_FLOAT}. + +@findex fixed_size_mode +@item fixed_size_mode +A mode whose size is known at compile time. +@end table + +Named modes use the most constrained of the available wrapper classes, +if one exists, otherwise they use @code{machine_mode}. For example, +@code{QImode} is a @code{scalar_int_mode}, @code{SFmode} is a +@code{scalar_float_mode} and @code{BLKmode} is a plain +@code{machine_mode}. It is possible to refer to any mode as a raw +@code{machine_mode} by adding the @code{E_} prefix, where @code{E} +stands for ``enumeration''. For example, the raw @code{machine_mode} +names of the modes just mentioned are @code{E_QImode}, @code{E_SFmode} +and @code{E_BLKmode} respectively. + +The wrapper classes implicitly convert to @code{machine_mode} and to any +wrapper class that represents a more general condition; for example +@code{scalar_int_mode} and @code{scalar_float_mode} both convert +to @code{scalar_mode} and all three convert to @code{fixed_size_mode}. +The classes act like @code{machine_mode}s that accept only certain +named modes. + +@findex opt_mode +@file{machmode.h} also defines a template class @code{opt_mode<@var{T}>} +that holds a @code{T} or nothing, where @code{T} can be either +@code{machine_mode} or one of the wrapper classes above. The main +operations on an @code{opt_mode<@var{T}>} @var{x} are as follows: + +@table @samp +@item @var{x}.exists () +Return true if @var{x} holds a mode rather than nothing. + +@item @var{x}.exists (&@var{y}) +Return true if @var{x} holds a mode rather than nothing, storing the +mode in @var{y} if so. @var{y} must be assignment-compatible with @var{T}. + +@item @var{x}.require () +Assert that @var{x} holds a mode rather than nothing and return that mode. + +@item @var{x} = @var{y} +Set @var{x} to @var{y}, where @var{y} is a @var{T} or implicitly converts +to a @var{T}. +@end table + +The default constructor sets an @code{opt_mode<@var{T}>} to nothing. +There is also a constructor that takes an initial value of type @var{T}. + +It is possible to use the @file{is-a.h} accessors on a @code{machine_mode} +or machine mode wrapper @var{x}: + +@table @samp +@findex is_a +@item is_a <@var{T}> (@var{x}) +Return true if @var{x} meets the conditions for wrapper class @var{T}. + +@item is_a <@var{T}> (@var{x}, &@var{y}) +Return true if @var{x} meets the conditions for wrapper class @var{T}, +storing it in @var{y} if so. @var{y} must be assignment-compatible with +@var{T}. + +@item as_a <@var{T}> (@var{x}) +Assert that @var{x} meets the conditions for wrapper class @var{T} +and return it as a @var{T}. + +@item dyn_cast <@var{T}> (@var{x}) +Return an @code{opt_mode<@var{T}>} that holds @var{x} if @var{x} meets +the conditions for wrapper class @var{T} and that holds nothing otherwise. +@end table + +The purpose of these wrapper classes is to give stronger static type +checking. For example, if a function takes a @code{scalar_int_mode}, +a caller that has a general @code{machine_mode} must either check or +assert that the code is indeed a scalar integer first, using one of +the functions above. + +The wrapper classes are normal C++ classes, with user-defined +constructors. Sometimes it is useful to have a POD version of +the same type, particularly if the type appears in a @code{union}. +The template class @code{pod_mode<@var{T}>} provides a POD version +of wrapper class @var{T}. It is assignment-compatible with @var{T} +and implicitly converts to both @code{machine_mode} and @var{T}. + Here are some C macros that relate to machine modes: @table @code