From patchwork Fri Mar 10 10:26:03 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jan Beulich X-Patchwork-Id: 67331 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:5915:0:0:0:0:0 with SMTP id v21csp790566wrd; Fri, 10 Mar 2023 02:27:19 -0800 (PST) X-Google-Smtp-Source: AK7set+U9bf340Gp78rY5TUnVb6ZxN5bq5YHmRoKBBJGbdgOhkkE2LMT0/J0C/Cs231BIqbmgDBY X-Received: by 2002:a05:6402:899:b0:4af:5ff1:88ef with SMTP id e25-20020a056402089900b004af5ff188efmr23352011edy.28.1678444039454; Fri, 10 Mar 2023 02:27:19 -0800 (PST) Received: from sourceware.org (server2.sourceware.org. [2620:52:3:1:0:246e:9693:128c]) by mx.google.com with ESMTPS id u11-20020a056402110b00b004c435746ddfsi2177481edv.157.2023.03.10.02.27.19 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 10 Mar 2023 02:27:19 -0800 (PST) Received-SPF: pass (google.com: domain of binutils-bounces+ouuuleilei=gmail.com@sourceware.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) client-ip=2620:52:3:1:0:246e:9693:128c; Authentication-Results: mx.google.com; dkim=pass header.i=@sourceware.org header.s=default header.b=e7cTdSaA; arc=fail (signature failed); spf=pass (google.com: domain of binutils-bounces+ouuuleilei=gmail.com@sourceware.org designates 2620:52:3:1:0:246e:9693:128c 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 85C87384F034 for ; Fri, 10 Mar 2023 10:26:17 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 85C87384F034 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1678443977; 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=e7cTdSaAZvdy5aSNIYnLHhx9CqTkU8T506khhtmub8lcWOUM9uv+oy/V15hm9x+SG tP/U6Ff4EyibIw7gHm0sou3MxkVjANzBr6X9ZSfJYkxEFH5lKFZ2PLmrRPcuzQ0TrO SOhaKSLvdtw4WVRavWPAeNDfiYrlc+EjZayD4rJ4= X-Original-To: binutils@sourceware.org Delivered-To: binutils@sourceware.org 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 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 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: In-Reply-To: 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?q?Vf5hfnoy/gkBvnBtKChHFWaD0fGO?= =?utf-8?q?k0zDG2MiwEORHUUy33z3lrYG84fM8WW1RG+30QESWY/xZu0YM7ycjmnS+cazC3yOD?= =?utf-8?q?2d2LbLTJM5dcwiU2xRjq0gCtFrnWC+/G8IB0O4wt3KbJGs9hAMjqETUg5NM2T5t+f?= =?utf-8?q?W1TNn47MMzF+bT2+/EmQyH6HcQ0ph6pFHepCbNUpGGjR9MAQU1m4Lk3ozROGh/+D3?= =?utf-8?q?TTKgKf6af5CqLkar9kNbt+d/VnKsYX9nGLAkgPN7SzKf398kItPrindeO2a+Ad0c8?= =?utf-8?q?IU5xM54wC3lNDZnxaGOxxiTUgJFec3SylFT+PeGuBq+/ENVgPqY9QSZRPao7DG2yz?= =?utf-8?q?Xr1CnSAKpLnInnoyboww1/yODy6R9WvLEeO8uXtWv/76lwtp4WI/CzCmLAJH+LrpM?= =?utf-8?q?KIUketsF7cLUbCyt+BIyMB9H+1W6dHcKfk6QD2PLPtgV2eSrdkQbfyucF6wQtmz5/?= =?utf-8?q?12V0rRxCZbOCbKuj0nj28mJQpjYM2OPm62xxXzip9UWZovsr2rySrFDMM2v7A0Mb6?= =?utf-8?q?eFUhQbMeuV5BD3JlQCs9HuOL3WS+7XjV2urJ3+SB8+iZ/jrlRzbA7ZEMXH4SK4fXg?= =?utf-8?q?VBm9jCJnILlYMBfEhIIuXtAqkwjqm6MMEj4oFDbjxV3QzRuoXm91ttC0/iYdsmKfb?= =?utf-8?q?L5qVxq0KfybLAPzyckVB73Vf344kdGr5MOuloYWhILyGIP1+o42Sr0e75F7Ewn4E+?= =?utf-8?q?/C86M+IKyJMUpARS/smzHdUqsoUC1thmPoDlA+9bqcND2RZ7Zhx63X51jiI1CPAIp?= =?utf-8?q?x7jhfLveQ2uuIRHsysah0RC0xJSOE06yUeo1XfzVDkxQQNPoaFpyH83iL+CMvjFgG?= =?utf-8?q?3YWXOgD8kN0hKC6paMWnQwiE+9FRYSKflmgXJ3GonF42RZv1NIFSuRq0a2emFG29p?= =?utf-8?q?qIj7xKnmFuCnIH8dAjFqniB2zGuHfa6MZZW6eX36aXEHSoIKkdVJGdriglR7lY+c9?= =?utf-8?q?9pDD+GmOh8b9H+qhLnO/rXo/aeK1GIc0I/E27jeRZZe7juS1pywPzYObRtJdkSDQ8?= =?utf-8?q?JxdP6rvj/ARFLJyrIo8bRIZYOwH8k21kiBVfDDcDbYncG7BdkYVQ2EMurjJCStg/H?= =?utf-8?q?Xpy6U7GpBKiZCxqaP/FnfPPM+pNSlp/llOQneMk95+OPlg3DLjkjmjS21rhQIlbET?= =?utf-8?q?La6mzcE4cDX5XZVA7xTN32DkZz1Iu97OpHk9qIG/z2h/Iym1+4XX4XAaA3Byk7zxZ?= =?utf-8?q?GUVDtIzzgYCpaz68o+ELkIhHLNzuHW2WZx3v3a2sM8BIY7M5NjpyRu7Cb+DLus+5F?= =?utf-8?q?w1DcGTKjxsOHZ9k5fdosPJMBvELzRS8qq55XKi/EZ46LhtGcDxXKt5/Yms+OnK5eD?= =?utf-8?q?prcGKXbCioSvPtWsxgaSwAtmpa/2jU94TdhzgZKnUz9NUNdels/lo6Rypma5hpHNy?= =?utf-8?q?SrybgTrz859BaPi7ncReHpNsS3xUR6bZRYjpNCch7LuAb0LZv/bL879hPThQiXrD2?= =?utf-8?q?TR5wh3zwaK1eR+YvvO2/AegTODGa48hHyr6Xt/IswI6pJLyiMpPDfvkPisLo/uaal?= =?utf-8?q?PnAFwMglR0eX?= 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 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?1759976137166310120?= X-GMAIL-MSGID: =?utf-8?q?1759976137166310120?= ... 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