From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from EUR04-DB3-obe.outbound.protection.outlook.com (mail-db3eur04on2072.outbound.protection.outlook.com [40.107.6.72]) by sourceware.org (Postfix) with ESMTPS id 7BC9B385B501 for ; Fri, 10 Mar 2023 10:26:07 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 7BC9B385B501 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=kFa0OwTeSiAPIFF9ENMftoWDWxcjIL00anvYs942DQh4HsiX7J3J4K1Vb0FWCCg2jkQOGQP4aHjqrNJnmZLvu0SR3szNgBhKmteM069+lYVTuuCh9fsZiUzDr8lZMh7ZwBokNXBk0+MG3iaZCvWs+PGP7NyGk7cMhaLr7xS8XEzPE2dev+BNY60cjz+S6poHcYWMSp36PJ4DmWVDK9uB7lNksjs9wxRHmoM2yQPcIlvgH/737EKDK2N/P1jur7ZHKRgrHPP8qiHmLMN0qPneoq4FMKaNWJ/wlG0BBBrGa5yOqkwzf8hGWL73x/kLtWw4XwGwd1zTP2zxJBluu6OwZw== 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=HOSMMizDdy1x2zzaShEAqBO7UPFz3AQLUcFgdiy69CxzlvKKgJi3oXKJlHtWIH2MTejEcsEiia1IAYlneHFiXRTxo9ytXd22eiyG4a2T7hNCF//XNtLJSZpLjnztuLFDsYLbeS2UiW3bUJJ49URUfCdrJueiCEojasWVT1rTXC9duX91U/EM7TUkKmkGsfBXRwDfN3G3A1wpgwWF+5RzbNyXoIZsc+Ld+vhCTnffTJDQMYKeVrPi6khjmrwxRd1Jij3bptiqSbUcsFmHhM6p4gdkSg1AIFuMm/scRtdbcjCNHTn+mxtYIyyCUw8E3F8C3euXFTK6v/yas+Xl7mpk1w== 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=mk8yRFo71icedxlQeDTG/Gh7q7K1UExkvfN8GsbE88MfEGl9mJWe+l6sG9vBn0WZFrQzhFf0pFt/F4v4bJhbPmDB5eUnKtV5X8mH+PaGf5mAx8+rnEeUHRjp1K6s/ru245fRPuoIImbl/F97m7H+7Hp08fYF4ozSqZTUNMx72HUXNTEPLz2cfohI0yT4ZjQlu4Eowj1dBnyQew4rwaOJhjab3BGQ5qpXgGt+nuVTUAVFWd2kpE+fLr3eFQ0Xn8K4OwHEaIK8cILPEgpOX9qomykT9g1ANzKhEl8Cj1NZR+LlcHNacwDfwIkRkUOMTGcOGK49tEyKg5rO+rGx2nXnzQ== 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 AM0PR04MB7138.eurprd04.prod.outlook.com (2603:10a6:208:19e::19) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6178.19; Fri, 10 Mar 2023 10:26:05 +0000 Received: from VE1PR04MB6560.eurprd04.prod.outlook.com ([fe80::154e:166d:ec25:531b]) by VE1PR04MB6560.eurprd04.prod.outlook.com ([fe80::154e:166d:ec25:531b%5]) with mapi id 15.20.6178.019; Fri, 10 Mar 2023 10:26:05 +0000 Message-ID: Date: Fri, 10 Mar 2023 11:26:03 +0100 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Thunderbird/102.8.0 Subject: [PATCH v2 12/14] x86: document .insn Content-Language: en-US To: Binutils Cc: "H.J. Lu" , "Jiang, Haochen" References: From: Jan Beulich In-Reply-To: Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-ClientProxiedBy: FR2P281CA0122.DEUP281.PROD.OUTLOOK.COM (2603:10a6:d10:9d::11) To VE1PR04MB6560.eurprd04.prod.outlook.com (2603:10a6:803:122::25) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: VE1PR04MB6560:EE_|AM0PR04MB7138:EE_ X-MS-Office365-Filtering-Correlation-Id: 98d439e8-a5b7-427e-8f7a-08db2151dad8 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 1DTfJETnJWudGvKw5C/pXWRg9aKdlPPAZBYlSDoXvnHjUlNmI8C+XnMV9HW+gZYK4fEecnLmb/53hn7YM59BueWQ0dMrx7wbJLoxVcWvpJiO+XHu/tE15wg9gTel82p618zsgDFmHjOoZxbPGfefIshBv6wdhfB9zjbSDbZWOd3/AZyiBhk1Hsyv1j1vN1S1d60lLUv8+DtI+gpE9iKM/83TujFTM+PQhldNKvCAczccyhlZTJXH2MCHvklBdlLKat1un6tlVJ/vn3TW+0gEWAQgFzfH0olTP4WQ3hDsPh2yBE4i0ELjKw/XjM/OVS45+e8tpIBGN1LLRsaoOUJ/PVP22btCdzIatxoHOigo0YaXOQ5FxfErtM7qGCoXoJJMtltzSuNhlqVK/LjoA7Hx7IL7q8sueLGoPVzTmW17xTZW18BXWUpWixYSAKRyDnB8MVcmoWmnllLDSCt8aW6L7MQXcJbPr0qB+m+7dhj3ukvqtAa46vqGhXSMGNy70EDEIBJOwJC4hOGfF7btEhGZGNrauqRjt2s+2E+Fvg4sPHtK4EaBPCdqrdAnJ1+zgjhvtL239VVhK0dyh1+KRCJ3bBNUE3eSrR1kU/l+6I85zVL+ZmKm03B14muhFOpsR62jpOw8h1seP0xAw6lHsfRkWnWBoskGoe+K1Eah5LWnBedfoEHCyQMIync5RMK9fiVzAFUhxOI4zFx/nmPKguI0vsiuSRURCmz5ayQSgZtbysS3JB+Dxkk7lrYrkwXb+Vy34VVrsGNSzO6ETqcQXk7Oew== 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)(396003)(346002)(39860400002)(376002)(136003)(366004)(451199018)(31686004)(83380400001)(36756003)(6512007)(54906003)(478600001)(316002)(38100700002)(8936002)(6486002)(2616005)(41300700001)(6506007)(26005)(186003)(5660300002)(8676002)(66476007)(66946007)(66556008)(2906002)(6916009)(4326008)(31696002)(86362001)(142923001)(43740500002)(45980500001);DIR:OUT;SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?VmY1aGZub3kvZ2tCdm5CdEtDaEhGV2FEMGZHT2swekRHMk1pd0VPUkhVVXkz?= =?utf-8?B?M3ozbHJZRzg0Zk04V1cxUkcrMzBRRVNXWS94WnUwWU03eWNqbW5TK2NhekMz?= =?utf-8?B?eU9EMmQyTGJMVEpNNWRjd2lVMnhSanEwZ0N0RnJuV0MrL0c4SUIwTzR3dDNL?= =?utf-8?B?YkpHczloQU1qcUVUVWc1Tk0yVDV0K2ZXMVRObjQ3TU16RitiVDIrL0VtUXlI?= =?utf-8?B?NkhjUTBwaDZwRkhlcENiTlVwR0dqUjlNQVFVMW00TGszb3pST0doLytEM1RU?= =?utf-8?B?S2dLZjZhZjVDcUxrYXI5a05idCtkL1ZuS3NZWDluR0xBa2dQTjdTektmMzk4?= =?utf-8?B?a0l0UHJpbmRlTzJhK0FkMGM4SVU1eE01NHdDM2xORFpueGFHT3h4aVRVZ0pG?= =?utf-8?B?ZWMzU3lsRlQrUGVHdUJxKy9FTlZnUHFZOVFTWlJQYW83REcyeXpYcjFDblNB?= =?utf-8?B?S3BMbklubm95Ym93dzEveU9EeTZSOVd2TEVlTzh1WHRXdi83Nmx3dHA0V0kv?= =?utf-8?B?Q3pDbUxBSkgrTHJwTUtJVWtldHNGN2NMVWJDeXQrQkl5TUI5SCsxVzZkSGNL?= =?utf-8?B?Zms2UUQyUExQdGdWMmVTcmRrUWJmeXVjRjZ3UXRtejUvMTJWMHJSeENaYk9D?= =?utf-8?B?Ykt1ajBuajI4bUpRcGpZTTJPUG02Mnh4WHppcDlVV1pvdnNyMnJ5U3JGRE1N?= =?utf-8?B?MnY3QTBNYjZlRlVoUWJNZXVWNUJEM0psUUNzOUh1T0wzV1MrN1hqVjJ1ckoz?= =?utf-8?B?K1NCOCtpWi9qcmxSemJBN1pFTVhINFNLNGZYZ1ZCbTlqQ0puSUxsWU1CZkVo?= =?utf-8?B?SUl1WHRBcWt3anFtNk1NRWo0b0ZEYmp4VjNRelJ1b1htOTF0dEMwL2lZZHNt?= =?utf-8?B?S2ZiTDVxVnhxMEtmeWJMQVB6eWNrVkI3M1ZmMzQ0a2RHcjVNT3Vsb1lXaElM?= =?utf-8?B?eUdJUDErbzQyU3IwZTc1RjdFd240RSsvQzg2TStJS3lKTVVwQVJTL3Ntekhk?= =?utf-8?B?VXFzb1VDMXRobVBvRGxBKzlicWNORDJSWjdaaHg2M1g1MWppSTFDUEFJcHg3?= =?utf-8?B?amhmTHZlUTJ1dUlSSHN5c2FoMFJDMHhKU09FMDZ5VWVvMVhmelZEa3hRUU5Q?= =?utf-8?B?b2FGcHlIODNpTCtDTXZqRmdHM1lXWE9nRDhrTjBoS0M2cGFNV25Rd2lFKzlG?= =?utf-8?B?UllTS2ZsbWdYSjNHb25GNDJSWnYxTklGU3VScTBhMmVtRkcyOXBxSWo3eEtu?= =?utf-8?B?bUZ1Q25JSDhkQWpGcW5pQjJ6R3VIZmE2TVpaVzZlWDM2YVhFSFNvSUtrZFZK?= =?utf-8?B?R2RyaWdsUjdsWStjOTlwREQrR21PaDhiOUgrcWhMbk8vclhvL2FlSzFHSWMw?= =?utf-8?B?SS9FMjdqZVJaWmU3anVTMXB5d1B6WU9iUnRKZGtTRFE4SnhkUDZydmovQVJG?= =?utf-8?B?TEp5cklvOGJSSVpZT3dIOGsyMWtpQlZmRERjRGJZbmNHN0Jka1lWUTJFTXVy?= =?utf-8?B?akpDU3RnL0hYcHk2VTdHcEJLaVpDeHFhUC9GbmZQUE0rcE5TbHAvbGxPUW5l?= =?utf-8?B?TWs5NStPUGxnM0RMamtqbWpTMjFyaFFJbGJFVExhNm16Y0U0Y0RYNVhaVkE3?= =?utf-8?B?eFROMzJEa1p6MUl1OTdPcEhrOXFJRy96MmgvSXltMSs0WFg0WEFhQTNCeWs3?= =?utf-8?B?enhaR1VWRHRJenpnWUNwYXo2OG8rRUxrSWhITE56dUhXMldaeDN2M2Eyc004?= =?utf-8?B?QklZN001TmpweVJ1N0NiK0RMdXMrNUZ3MURjR1RLanhzT0haOWs1ZmRvc1BK?= =?utf-8?B?TUJ2RUx6UlM4cXE1NVhLaS9FWjQ2TGh0R2NEeFhLdDUvWW1zK09uSzVlRHBy?= =?utf-8?B?Y0dLWGJDaW9TdlB0V3N4Z2FTd0F0bXBhLzJqVTk0VGRoemdaS25VejlOVU5k?= =?utf-8?B?ZWxzL2xvNlJ5cG1hNWhwSE55U3J5YmdUcno4NTlCYVBpN25jUmVIcE5zUzN4?= =?utf-8?B?VVI2YlpSWWpwTkNjaDdMdUFiMExadi9iTDg3OWhQVGhRaVhyRDJUUjV3aDN6?= =?utf-8?B?d2FLMWVSK1l2dk8yL0FlZ1RPREdhNDhoSHlyNlh0L0lzd0k2cEpMeWlNcFBE?= =?utf-8?Q?fvkPisLo/uaalPnAFwMglR0eX?= X-OriginatorOrg: suse.com X-MS-Exchange-CrossTenant-Network-Message-Id: 98d439e8-a5b7-427e-8f7a-08db2151dad8 X-MS-Exchange-CrossTenant-AuthSource: VE1PR04MB6560.eurprd04.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 10 Mar 2023 10:26:05.2000 (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: I+5bloe8CwwmXJ1yBgE022w4VGDkMs7cpOzeoB89HTkxNCCkxkxECOxrMVJ+g9acY777EQFGkZ/HiAJj4Jxu2Q== X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM0PR04MB7138 X-Spam-Status: No, score=-3028.2 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