From patchwork Fri Mar 3 13:05:36 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jan Beulich X-Patchwork-Id: 63906 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:5915:0:0:0:0:0 with SMTP id v21csp398004wrd; Fri, 3 Mar 2023 05:08:23 -0800 (PST) X-Google-Smtp-Source: AK7set+JjZ7BtODejVGNJzO5pD74eDCdyL1tABC0Zt6wWSiXVC5VUbJdYbZ7xbQKhCe97e/Ma9+P X-Received: by 2002:a05:6402:1212:b0:4ab:f47:c6e8 with SMTP id c18-20020a056402121200b004ab0f47c6e8mr1288922edw.21.1677848902914; Fri, 03 Mar 2023 05:08:22 -0800 (PST) Received: from sourceware.org (server2.sourceware.org. [8.43.85.97]) by mx.google.com with ESMTPS id bi23-20020a170906a25700b008c7abe01745si2134684ejb.492.2023.03.03.05.08.22 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 03 Mar 2023 05:08:22 -0800 (PST) Received-SPF: pass (google.com: domain of binutils-bounces+ouuuleilei=gmail.com@sourceware.org designates 8.43.85.97 as permitted sender) client-ip=8.43.85.97; Authentication-Results: mx.google.com; dkim=pass header.i=@sourceware.org header.s=default header.b=JGwtG+7Z; arc=fail (signature failed); spf=pass (google.com: domain of binutils-bounces+ouuuleilei=gmail.com@sourceware.org designates 8.43.85.97 as permitted sender) smtp.mailfrom="binutils-bounces+ouuuleilei=gmail.com@sourceware.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 255B0383EC71 for ; Fri, 3 Mar 2023 13:05:48 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 255B0383EC71 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1677848748; bh=ecRg+UpfJLPz4vQ2LE2hEAzMiKLz2PPb5oT+mkmLkY8=; h=Date:Subject:To:Cc:References:In-Reply-To:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From:Reply-To:From; b=JGwtG+7ZEb3JdK9TwOM6OZtICwPiGepGXyV20qCrFgOAkAvdEQFcggsuT6V7ff6XB RHOXCl0902s4yXCkFhuZG8KOB2DflusKNUmHeF7/TKwoTkk+JDAZnlCc5ne7+/DglL lysyan4/lFg6AMKmJm8xr7XNEILZGAJ5pZCNUQVQ= X-Original-To: binutils@sourceware.org Delivered-To: binutils@sourceware.org Received: from EUR05-VI1-obe.outbound.protection.outlook.com (mail-vi1eur05on2058.outbound.protection.outlook.com [40.107.21.58]) by sourceware.org (Postfix) with ESMTPS id 9A1C63857C4F for ; Fri, 3 Mar 2023 13:05:39 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 9A1C63857C4F ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=cQ/QoGAiD+DSGAzZMMEgPd8JC52scGQGck0OLxBemT8I0/At9QYUi5+xFazjhspKwXsTNmYC4q1FMqtbMtIHgMjIEjUfJjOaBRX9p9kIByG0d18B668TQR4GoxVQkIpdSJfr3OSXKqJfH8756gIOEzs+w4DR/rUItTA8V51cSjJmIY4Erk2y6A83rDMSSVhpOZ6WSM84rt4gk0bWkuxXJpA+PvStS7BeolXbTjWI3grnuLSpujKZpdcjhlTkgwe3wMSkzi2zR1uQWxX8Tt+fVTcLFlYnQYxXtspOiPSKA/8CfK5aiomeORboavUFibDTccSU9ceU1I+6Kp4xNHYRrg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=ecRg+UpfJLPz4vQ2LE2hEAzMiKLz2PPb5oT+mkmLkY8=; b=UJdhT7J1sj1bqnrY/YFONneC4dUI7Hwccn0vpCvWSKF6Ze7QJnre5evVuniWzvFatEYMyWkF0M/C/D7cNmfL8yGpg0Y1/6kqQElpCc2AY2LWim3OT2Ru4EjSMiZ15ByU82xy7rnT8xcRtmqIHyJ907JpISJJG8cVoeolUreZTy2q1RLBATqUIdjz3LVm+ZQ6G7wjDnSgl5VR92RHW6/2l6f0POsAKuMeGSSzr+nxJpOPJ/NUmrkHW3x8hXm1vJSmQmZnYX4gq8tkJebSbOLxYgesBZ0NWmkDOFPI1u5U0sT1JdbTSI8PxK2CfKPL6shWUAnNgqwK6RHo6arm2snFAw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=suse.com; dmarc=pass action=none header.from=suse.com; dkim=pass header.d=suse.com; arc=none Received: from VE1PR04MB6560.eurprd04.prod.outlook.com (2603:10a6:803:122::25) by DBBPR04MB7513.eurprd04.prod.outlook.com (2603:10a6:10:20a::21) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6156.21; Fri, 3 Mar 2023 13:05:37 +0000 Received: from VE1PR04MB6560.eurprd04.prod.outlook.com ([fe80::154e:166d:ec25:531b]) by VE1PR04MB6560.eurprd04.prod.outlook.com ([fe80::154e:166d:ec25:531b%7]) with mapi id 15.20.6156.019; Fri, 3 Mar 2023 13:05:37 +0000 Message-ID: <14ee4656-f39a-59c4-48d0-c397b77ad969@suse.com> Date: Fri, 3 Mar 2023 14:05:36 +0100 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Thunderbird/102.8.0 Subject: [PATCH 16/18] x86: document .insn Content-Language: en-US To: Binutils Cc: "H.J. Lu" , "Jiang, Haochen" References: <764b9e03-18bd-6945-692f-a250522196ca@suse.com> In-Reply-To: <764b9e03-18bd-6945-692f-a250522196ca@suse.com> X-ClientProxiedBy: FR3P281CA0049.DEUP281.PROD.OUTLOOK.COM (2603:10a6:d10:4a::22) To VE1PR04MB6560.eurprd04.prod.outlook.com (2603:10a6:803:122::25) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: VE1PR04MB6560:EE_|DBBPR04MB7513:EE_ X-MS-Office365-Filtering-Correlation-Id: 8ef6a380-2f14-4644-ad38-08db1be7fba4 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: sN0br8ijwtrk4qgQlE/yDHDTptLjqHuCYUQfSGklgS80UDD4+3lkH037gKcGIPEF1MnqHpxAc/8ld7KiDJ31dNsOIXBAPQp0aOXcb6xuGq5Q9jkYM2OZCJ0JrcmQy2tV/QWhQVwLSWjtE7O7JuNoNMxw+83OY7f8VF0NC9fAiaYgmT/MSNMtGm/SvNOR9XDm+1+i2tUUezASLKc25VeKe/1USurAOYl2YpTP1IaT0duurZNBXx+bKDMmbF9e3m4fJXyCOh7RB6K3Nf5OYPmLwIJYoB1b9W93lrhxUeagwv7XSCZ9G9sM1o3BRBqg0MWRxadvxXCTN/Bbsz38OXUZjhRCiSZRaO8bSc3py5UU/novRf4URfzYmXbzYIgzOkuyLt2BCnw8kPYn+6ASji24eEYo9NtgTJUf0MPezsAOGXv1K2Val/btI7XdQL97mjesXR0zvjwM3FR6Kyno+W9YthvuJhwqb0CQRAdM1vnRMTqF5b0ZxrbpGSNnb1V9BeXuUsPmBeXieaVP6BUGXqNaLf1zptEXtgUFnnoZYDElxVGkggEhRmCQRKYPEv/iD3TR1B3QTlt36Y++A3yqPGUcUI8KSJEFBmL9u+kwwAA/AfzQxBc7TWDkmjNd7V/F/2KYXjc9VwCEM1Yua9tI44B5iGpX7lVjNOfPF2AKpZlfwsJuuDr0y/KkOL/BURFOhacPyrIAUXsNZJ4ka3pw0VtisG4Uvy+q3CyfK0yfTDCHwogje8fqpywJ8+tylZEV8+xTIr8a99VgIlGqINQ6pTQAow== X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:VE1PR04MB6560.eurprd04.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230025)(376002)(136003)(39860400002)(346002)(366004)(396003)(451199018)(36756003)(31696002)(6506007)(6486002)(6512007)(2616005)(26005)(186003)(41300700001)(316002)(4326008)(54906003)(8676002)(66556008)(66476007)(6916009)(2906002)(5660300002)(86362001)(478600001)(38100700002)(66946007)(83380400001)(31686004)(8936002)(142923001)(43740500002)(45980500001); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?q?7X9nABf6vfKmVq2bOKzMEKfCSWAa?= =?utf-8?q?qJBy+8pnCxPz9d2nBrJGwFPVQ+VsZJMnhxyCUWCycDpIRIWjYj/PSns960pvCZtPD?= =?utf-8?q?JbODdmx9NHO1QwfPNG5wP4B1qtSzCYkihdnlts1aPv8W+sU8nMZZwp/NXry6ztHNc?= =?utf-8?q?/PY5AJ6nZce6G6czQNUbPiEXrx0BGV0f/gMg6Xelg7xM5FLVpzKax0XLNqkoh0n+8?= =?utf-8?q?XvQdSnsHxfqCiddTxSRHbgA2RGNO+yhCBQWzmq5p2oZMBgmuc5+3wY0L8I6pINcNF?= =?utf-8?q?a1cUQoUA2swGgnetbtv0f2g6FWVvrc2IwYE8DbLK+4mVZkfu7yjYRWlBXgx4+SmZe?= =?utf-8?q?W+1hqlGn6BrTHkX0njlBoJY6apnDJH26KaWZXhGLmbcNH/cVIcNWXhUIPGVVRJ8FZ?= =?utf-8?q?OZUGrmdc11oXnNSmuVV+yEfqBPtWa/YpArL6XLbKI7oekDNx9OjlxsuOBirw1PC3L?= =?utf-8?q?+7PuwphNHO3oYPCbuleg8MSKlXgstD19/b+k5qd8IWKAyKttJ5hHnn7RDoGc0oqLn?= =?utf-8?q?9XRyz/zFzQwTGurpDWLoG0EBrnID/wM/pDbLC7OVQrcGH/y4Rx8jsCkphFElKp3BJ?= =?utf-8?q?IjtsJXj3HoczwXswqI26arFlni3ZtiNOfROn/a81uhcjIE4OitagvickuSEbqoGj7?= =?utf-8?q?eVnX/jr/9CG+xJIyjhdWgdGIYdsuERXcB61uZ3BqfojXZG0OpBKXv6XfwVL6mYtb+?= =?utf-8?q?W2d21Gg3/+kwfk3I1iMNh6u3mWJEfI1PqabMclkuCkyiYHCBHlKSol7RlPxc4ZnzE?= =?utf-8?q?iRjik6ZHEx65Od4dgmAvdJXD9l5AYEq+66uu1PCiIWwzbw7bySlr63+KxTXGfYGaz?= =?utf-8?q?Z65uTec5zsv7tqDT2yjLcEzaKX4djt3N48nobqBcXimu6UpDtVomwvNlY9zBpaHDP?= =?utf-8?q?jkxNNBTxiAQ6WNdQ6baTrCVepSfVIAvBnM9sqF/08k9a0J1XmZ8ouetMHgCoPwkVo?= =?utf-8?q?3zzZB/OIAvnKC7aQoO6grrsd3XDoN25KkSSvYR28rt6UeiotDtkBXdGDe6bybeJhd?= =?utf-8?q?0k5ZfSrlBtAjzNL1IvmTmrQ6WtcT+5Sfg4FEd1OhhmBsWVMWtdkwW04rKYDUqJY7K?= =?utf-8?q?yoKpYiUGK76VuQzEzC+sTDXwTvVdR7Y6WAnrVrRWSt9ZHeM2+9BdwmJcKofmM/82m?= =?utf-8?q?t1Ikig0j+Y2CGFGEv8PVnz35AIEhFXhbUn7yeFTBWt1snkeHuR4zZW5juRt4eAHa0?= =?utf-8?q?cPVWOpTPb2rjZm2S0ADdt4z4SHLhvHOq6d44/COH4OW4xGZYA6ioY3pzFdiDKEEzp?= =?utf-8?q?D7xF8dsmn5D4gR+3qRPTKxyrAQg+F/32MGiEQfBw4L2GEnfE6FqHx+xbCKRDkXEHF?= =?utf-8?q?qU36W4uQu7djxUrrMCLektg61QSguO7eakMCvC9IAaGc4hCzjLCRGdhPwmE3R6vh5?= =?utf-8?q?KQoP7RM7r1O3mnJumBXb/Jnx/ql/UfrvcGKGtQzC1ncCCkXKxoTKsWoeunvYOI8mX?= =?utf-8?q?UrPzUi1q3gtBB9UtwR5JJQ6jZOmKFHc1TVbOZ/tcsxXQ6gj24L6+efGqyRY3GwKX/?= =?utf-8?q?pP6odrJt93Bd?= X-OriginatorOrg: suse.com X-MS-Exchange-CrossTenant-Network-Message-Id: 8ef6a380-2f14-4644-ad38-08db1be7fba4 X-MS-Exchange-CrossTenant-AuthSource: VE1PR04MB6560.eurprd04.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 03 Mar 2023 13:05:37.7575 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: f7a17af6-1c5c-4a36-aa8b-f5be247aa4ba X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: yuiN2DrSFL2V851KMGhPU9rybidL+xQsqGfzdN0uHfTnGGsM120rSI6k+qLMEpGWX2G/wfnmbAsqwECHRSVoAw== X-MS-Exchange-Transport-CrossTenantHeadersStamped: DBBPR04MB7513 X-Spam-Status: No, score=-3028.3 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: binutils@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Binutils mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jan Beulich via Binutils From: Jan Beulich Reply-To: Jan Beulich Errors-To: binutils-bounces+ouuuleilei=gmail.com@sourceware.org Sender: "Binutils" X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1759352091165982435?= X-GMAIL-MSGID: =?utf-8?q?1759352091165982435?= ... and mention its introduction in NEWS. --- a/gas/NEWS +++ b/gas/NEWS @@ -1,5 +1,7 @@ -*- text -*- +* A new .insn directive is recognized by x86 gas. + Changes in 2.40: * Add support for Intel RAO-INT instructions. --- a/gas/doc/c-i386.texi +++ b/gas/doc/c-i386.texi @@ -613,6 +613,137 @@ This directive behaves in the same way a taking a series of comma separated expressions and storing them as two-byte wide values into the current section. +@cindex @code{insn} directive +@item .insn [@var{prefix}[,...]] [@var{encoding}] @var{major-opcode}[@code{+r}|@code{/@var{extension}}] [,@var{operand}[,...]] +This directive allows composing instructions which @code{@value{AS}} +may not know about yet, or which it has no way of expressing (which +can be the case for certain alternative encodings). It assumes certain +basic structure in how operands are encoded, and it also only +recognizes - with a few extensions as per below - operands otherwise +valid for instructions. Therefore there is no guarantee that +everything can be expressed (e.g. the original Intel Xeon Phi's MVEX +encodings cannot be expressed). + +@itemize @bullet +@item +@var{prefix} expresses one or more opcode prefixes in the usual way. +Legacy encoding prefixes altering meaning (0x66, 0xF2, 0xF3) may be +specified as high byte of (perhaps already including an +encoding space prefix). Note that there can only be one such prefix. +Segment overrides are better specified in the respective memory +operand, as long as there is one. + +@item +@var{encoding} is used to specify VEX, XOP, or EVEX encodings. The +syntax tries to resemble that used in documentation: +@itemize @bullet +@item @code{VEX}[@code{.@var{len}}][@code{.@var{prefix}}][@code{.@var{space}}][@code{.@var{w}}] +@item @code{EVEX}[@code{.@var{len}}][@code{.@var{prefix}}][@code{.@var{space}}][@code{.@var{w}}] +@item @code{XOP}@var{space}[@code{.@var{len}}][@code{.@var{prefix}}][@code{.@var{w}}] +@end itemize + +Here +@itemize @bullet +@item @var{len} can be @code{LIG}, @code{128}, @code{256}, or (EVEX +only) @code{512} as well as @code{L0} / @code{L1} for VEX / XOP and +@code{L0}...@code{L3} for EVEX +@item @var{prefix} can be @code{NP}, @code{66}, @code{F3}, or @code{F2} +@item @var{space} can be +@itemize @bullet +@item @code{0f}, @code{0f38}, @code{0f3a}, or @code{M0}...@code{M31} +for VEX +@item @code{08}...@code{1f} for XOP +@item @code{0f}, @code{0f38}, @code{0f3a}, or @code{M0}...@code{M15} +for EVEX +@end itemize +@item @var{w} can be @code{WIG}, @code{W0}, or @code{W1} +@end itemize + +Defaults: +@itemize @bullet +@item Omitted @var{len} means "infer from operand size" if there is at +least one sized vector operand, or @code{LIG} otherwise. (Obviously +@var{len} has to be omitted when there's EVEX rounding control +specified later in the operands.) +@item Omitted @var{prefix} means @code{NP}. +@item Omitted @var{space} (VEX/EVEX only) implies encoding space is +taken from @var{major-opcode}. +@item Omitted @var{w} means "infer from GPR operand size" in 64-bit +code if there is at least one GPR(-like) operand, or @code{WIG} +otherwise. +@end itemize + +@item +@var{major-opcode} is an absolute expression specifying the instruction +opcode. Legacy encoding prefixes altering encoding space (0x0f, +0x0f38, 0x0f3a) have to be specified as high byte(s) here. +"Degenerate" ModR/M bytes, as present in e.g. certain FPU opcodes or +sub-spaces like that of major opcode 0x0f01, generally want encoding as +immediate operand (such opcodes wouldn't normally have non-immediate +operands); in some cases it may be possible to also encode these as low +byte of the major opcode, but there are potential ambiguities. Also +note that after stripping encoding prefixes, the residual has to fit in +two bytes (16 bits). @code{+r} can be suffixed to the major opcode +expression to specify register-only encoding forms not using a ModR/M +byte. @code{/@var{extension}} can alternatively be suffixed to the +major opcode expression to specify an extension opcode, encoded in bits +3-5 of the ModR/M byte. + +@item +@var{operand} is an instruction operand expressed the usual way. +Register operands are primarily used to express register numbers as +encoded in ModR/M byte and REX/VEX/XOP/EVEX prefixes. In certain +cases the register type (really: size) is also used to derive other +encoding attributes, if these aren't specified explicitly. Note that +there is no consistency checking among operands, so entirely bogus +mixes of operands are possible. Note further that only operands +actually encoded in the instruction should be specified. Operands like +@samp{%cl} in shift/rotate instructions have to be omitted, or else +they'll be encoded as an ordinary (register) operand. Operand order +may also not match that of the actual instruction (see below). +@end itemize + +Encoding of operands: While for a memory operand (of which there can be +only one) it is clear how to encode it in the resulting ModR/M byte, +register operands are encoded strictly in this order (operand counts do +not include immediate ones in the enumeration below, and if there was an +extension opcode specified it counts as a register operand; VEX.vvvv +is meant to cover XOP and EVEX as well): + +@itemize @bullet +@item VEX.vvvv for 1-register-operand VEX/XOP/EVEX insns, +@item ModR/M.rm, ModR/M.reg for 2-operand insns, +@item ModR/M.rm, VEX.vvvv, ModR/M.reg for 3-operand insns, and +@item Imm@{4,5@}, ModR/M.rm, VEX.vvvv, ModR/M.reg for 4-operand insns, +@end itemize + +obviously with the ModR/M.rm slot skipped when there is a memory +operand, and obviously with the ModR/M.reg slot skipped when there is +an extension opcode. For Intel syntax of course the opposite order +applies. With @code{+r} (and hence no ModR/M) there can only be a +single register operand for legacy encodings. VEX and alike can have +two register operands, where the second (first in Intel syntax) would +go into VEX.vvvv. + +Immediate operands (including immediate-like displacements, i.e. when +not part of ModR/M addressing) are emitted in the order specified, +regardless of AT&T or Intel syntax. Since it may not be possible to +infer the size of such immediates, they can be suffixed by +@code{@{:s@var{n}@}} or @code{@{:u@var{n}@}}, representing signed / +unsigned immediates of the given number of bits respectively. When +emitting such operands, the number of bits will be rounded up to the +smallest suitable of 8, 16, 32, or 64. Immediates wider than 32 bits +are permitted in 64-bit code only. + +For EVEX encoding memory operands with a displacement need to know +Disp8 scaling size in order to use an 8-bit displacement. For many +instructions this can be inferred from the types of other operands +specified. In Intel syntax @samp{DWORD PTR} and alike can be used to +specify the respective size. In AT&T syntax the memory operands can +be suffixed by @code{@{:d@var{n}@}} to specify the size (in bytes). +This can be combined with an embedded broadcast specifier: +@samp{8(%eax)@{1to8:d8@}}. + @c FIXME: Document other x86 specific directives ? Eg: .code16gcc, @end table