From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 Authentication-Results: sourceware.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=suse.com 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 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=ecRg+UpfJLPz4vQ2LE2hEAzMiKLz2PPb5oT+mkmLkY8=; b=W72qUJTZgkbqx7UbYMSPHhbTFKCUE/oeP0GEx2j2Qb2ZnSG183Zrt3uQm2HUo/bBUiT5dtg1w8m/NieERrmXEug8be+CqNDUAuZ97hXVfdxYnQyZVxePn7JBSfH9lhS3EjiwC1h5lId0L745mie0Cq0pbX4UmE2UXuIJDjOP91+z+WklB2m+F+y/5BZKhUIbqzAcKY+7SdwiF3b6v8Jhsb7oNGx6y+p8SQPraZNOX1OIzyllzqmYq3M9+8w/HN4hcwkfJ0DjF4rbDfqEeArLPhZtAzjZncNew/9lZVUNgXCZtLacGLRB/0VuZ4v17PxUiFL+6mBX6ycyKYjgExKuMw== Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=suse.com; 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> From: Jan Beulich In-Reply-To: <764b9e03-18bd-6945-692f-a250522196ca@suse.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit 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?B?N1g5bkFCZjZ2ZkttVnEyYk9Lek1FS2ZDU1dBYXFKQnkrOHBuQ3hQejlkMm5C?= =?utf-8?B?ckpHd0ZQVlErVnNaSk1uaHh5Q1VXQ3ljRHBJUklXallqL1BTbnM5NjBwdkNa?= =?utf-8?B?dFBESmJPRGRteDlOSE8xUXdmUE5HNXdQNEIxcXRTekNZa2loZG5sdHMxYVB2?= =?utf-8?B?OFcrc1U4bk1aWndwL05Ycnk2enRITmMvUFk1QUo2blpjZTZHNmN6UU5VYlBp?= =?utf-8?B?RVhyeDBCR1YwZi9nTWc2WGVsZzd4TTVGTFZwektheDBYTE5xa29oMG4rOFh2?= =?utf-8?B?UWRTbnNIeGZxQ2lkZFR4U1JIYmdBMlJHTk8reWhDQlFXem1xNXAyb1pNQmdt?= =?utf-8?B?dWM1KzN3WTBMOEk2cElOY05GYTFjVVFvVUEyc3dHZ25ldGJ0djBmMmc2RldW?= =?utf-8?B?dnJjMkl3WUU4RGJMSys0bVZaa2Z1N3lqWVJXbEJYZ3g0K1NtWmVXKzFocWxH?= =?utf-8?B?bjZCclRIa1gwbmpsQm9KWTZhcG5ESkgyNkthV1pYaEdMbWJjTkgvY1ZJY05X?= =?utf-8?B?WGhVSVBHVlZSSjhGWk9aVUdybWRjMTFvWG5OU211VlYreUVmcUJQdFdhL1lw?= =?utf-8?B?QXJMNlhMYktJN29la0ROeDlPamx4c3VPQmlydzFQQzNMKzdQdXdwaE5ITzNv?= =?utf-8?B?WVBDYnVsZWc4TVNLbFhnc3REMTkvYitrNXFkOElXS0F5S3R0SjVoSG5uN1JE?= =?utf-8?B?b0djMG9xTG45WFJ5ei96RnpRd1RHdXJwRFdMb0cwRUJybklEL3dNL3BEYkxD?= =?utf-8?B?N09WUXJjR0gveTRSeDhqc0NrcGhGRWxLcDNCSklqdHNKWGozSG9jendYc3dx?= =?utf-8?B?STI2YXJGbG5pM1p0aU5PZlJPbi9hODF1aGNqSUU0T2l0YWd2aWNrdVNFYnFv?= =?utf-8?B?R2o3ZVZuWC9qci85Q0creEpJeWpoZFdnZEdJWWRzdUVSWGNCNjF1WjNCcWZv?= =?utf-8?B?alhaRzBPcEJLWHY2WGZ3Vkw2bVl0YitXMmQyMUdnMy8ra3dmazNJMWlNTmg2?= =?utf-8?B?dTNtV0pFZkkxUHFhYk1jbGt1Q2t5aVlIQ0JIbEtTb2w3UmxQeGM0Wm56RWlS?= =?utf-8?B?amlrNlpIRXg2NU9kNGRnbUF2ZEpYRDlsNUFZRXErNjZ1dTFQQ2lJV3d6Ync3?= =?utf-8?B?YnlTbHI2MytLeFRYR2ZZR2F6WjY1dVRlYzV6c3Y3dHFEVDJ5akxjRXphS1g0?= =?utf-8?B?ZGp0M040OG5vYnFCY1hpbXU2VXBEdFZvbXd2TmxZOXpCcGFIRFBqa3hOTkJU?= =?utf-8?B?eGlBUTZXTmRRNmJhVHJDVmVwU2ZWSUF2Qm5NOXNxRi8wOGs5YTBKMVhtWjhv?= =?utf-8?B?dWV0TUhnQ29Qd2tWbzN6elpCL09JQXZuS0M3YVFvTzZncnJzZDNYRG9OMjVL?= =?utf-8?B?a1NTdllSMjhydDZVZWlvdER0a0JYZEdEZTZieWJlSmhkMGs1WmZTcmxCdEFq?= =?utf-8?B?ek5MMUl2bVRtclE2V3RjVCs1U2ZnNEZFZDFPaGhtQnNXVk1XdGRrd1cwNHJL?= =?utf-8?B?WURVcUpZN0t5b0twWWlVR0s3NlZ1UXpFekMrc1REWHdUdlZkUjdZNldBbnJW?= =?utf-8?B?clJXU3Q5WkhlTTIrOUJkd21KY0tvZm1NLzgybXQxSWtpZzBqK1kyQ0dGR0V2?= =?utf-8?B?OFBWbnozNUFJRWhGWGhiVW43eWVGVEJXdDFzbmtlSHVSNHpaVzVqdVJ0NGVB?= =?utf-8?B?SGEwY1BWV09wVFBiMnJqWm0yUzBBRGR0NHo0U0hMaHZIT3E2ZDQ0L0NPSDRP?= =?utf-8?B?VzR4R1pZQTZpb1kzcHpGZGlES0VFenBEN3hGOGRzbW41RDRnUiszcVJQVEt4?= =?utf-8?B?eXJBUWcrRi8zMk1HaUVRZkJ3NEwyR0VuZkU2RnFIeCt4YkNLUkRrWEVIRnFV?= =?utf-8?B?MzZXNHVRdTdkanhVcnJNQ0xla3RnNjFRU2d1TzdlYWtNQ3ZDOUlBYUdjNGhD?= =?utf-8?B?empMQ1JHZGhQd21FM1I2dmg1S1FvUDdSTTdyMU8zbW5KdW1CWGIvSm54L3Fs?= =?utf-8?B?L1VmcnZjR0tHdFF6QzFuY0NDa1hLeG9US3NXb2V1bnZZT0k4bVhVclB6VWkx?= =?utf-8?B?cTNndEJCOVV0d1I1SkpRNmpaT21LRkhjMVRWYk9aL3Rjc3hYUTZnajI0TDYr?= =?utf-8?Q?efGqyRY3GwKX/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 List-Id: ... 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