External Release v2023.08.21

This release adds support for Intel® APX (Advanced Performance Extensions) and AVX10 (Advanced Vector Extensions 10) according to the August 2023 latest specification revisions. The complete documentation can be found on Intel's official SDM webpage. ### APX Support: Intel® Advanced Performance Extensions (APX) expands the Intel 64 instruction set architecture with access to more registers and adds various new features that improve general-purpose performance. The external release: - Adds a complete decoder support. Including REX2 prefix, Promoted-To-EVEX instructions and new instructions - Adds a complete chip-check support - Adds a partial encoder support - For a complete support description and status, please check: datafiles/apx-f/README.md - Decoder usage examples can be found in xed-ex1.c example tool ### AVX10 Support: Intel® Advanced Vector Extensions 10 (Intel® AVX10) represents the first major new vector ISA since the introduction of Intel® Advanced Vector Extensions 512 (Intel® AVX-512) in 2013. This ISA will establish a common, converged vector instruction set across all Intel architectures, incorporating the modern vectorization aspects of Intel AVX-512. This ISA will be supported on all future processors, including Performance cores (P-cores) and Efficient cores (E-cores). The external release adds complete CPUID support with the introduction of Group CPUID APIs which replace the CPUID records APIs (usage example in: xed-ex1.c). XED supports CPUID classification of all AVX10.1 instructions. #### CPUID groups main characters: - XED ISA-SET is mapped to several CPUID groups. - Each CPUID group is mapped to several CPUID records. - Each CPUID record represents a required CPUID value within a bits-range (instead of a single CPUID bit) - XED ISA-SET is supported by a chip if CPUID match is found for one CPUID group. - CPUID group match requires satisfaction of all group’s records. #### XED currently supports two CPUID group kinds: FBIT and AVX10: - FBIT (Feature bit): A group for the traditional CPUID model - AVX10: A group for the new AVX10 CPUID model (AVX512/EVEX only) A given AVX512 ISA-SET is usually mapped to both FBIT and AVX10 groups. Please note that the AVX10 group will always be the first group when iterating through ISA-SET's CPUID groups. The FBIT group is not allowed to include AVX10 cpuid records. ### General: #### Added: - Added new absolute Branch-Displacement (ABSBR) operand for APX/JMPABS support #### Modified: - Split KOP ISA-SETs by opmask width, adding a [B,W,D,Q] suffix - Replaced 32bits Branch-Displacement API with 64bits version (for APX/JMPABS support) - Deprecate BAD_EVEX_UBIT error type, which replaced by XED_GENERAL_ERROR #### Fixed: - Fixed AVX-VNNI-INT8 destination Operand Type - PBNDKB: Fixed CPUID name (to TSE) - Chip-Check: Fixed instructions set of the FUTURE chip Co-authored-by: marjevan <[email protected]>
intelxed · Aug 21, 2023 · 01a6da8 · 01a6da8
1 parent 539a6a3
commit 01a6da8
Show file tree

Hide file tree

Showing 426 changed files with 80,511 additions and 1,473 deletions.
diff --git a/.github/scripts/protex.py b/.github/scripts/protex.py
@@ -0,0 +1,72 @@
+#!/usr/bin/env python 
+# -*- python -*-
+#BEGIN_LEGAL
+#
+#Copyright (c) 2023 Intel Corporation
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#  
+#END_LEGAL
+
+import sys
+import argparse
+import utils
+from pathlib import Path
+
+def setup():
+    """This function sets up the script env according to cmd line knobs."""
+    parser = argparse.ArgumentParser(description='Protex scan argument parser')
+    parser.add_argument("--project-id",
+                      action="store",
+                      dest="project_id",
+                      help="Protex project ID")
+    parser.add_argument("--user",
+                      action="store",
+                      dest="user",
+                      help="Protex username")
+    parser.add_argument("--pass",
+                      action="store",
+                      dest="pass",
+                      help="Protex password")
+    parser.add_argument('--tool-path',
+                      dest='bdstool',
+                      help='bdstool path',
+                      type=Path)
+    parser.add_argument("--url",
+                      action="store",
+                      dest="url",
+                      help="Protex server url")
+    env = vars(parser.parse_args())
+    return env
+
+if __name__ == '__main__':
+
+    env = setup()
+
+    # login
+    login_cmd = login_cmd = '{bdstool} --server {url} --user {user} --password {pass} login'.format(**env)
+    utils.run_subprocess(login_cmd)
+
+    # set XED project (basically chooses which project to analyze and create a new workflow for)
+    set_project_cmd = '{bdstool} new-project {project_id}'.format(**env)
+    utils.run_subprocess(set_project_cmd)
+
+    # analyze XED
+    analyze_cmd = f'{env["bdstool"]} analyze --verbose --path .'
+    utils.run_subprocess(analyze_cmd)
+
+    # logout
+    logout_cmd = f'{env["bdstool"]} logout'
+    utils.run_subprocess(logout_cmd)
+
+    sys.exit(0)
diff --git a/.github/scripts/sanity_external.py b/.github/scripts/sanity_external.py
@@ -47,17 +47,22 @@ def main(env):
             commands.append(cmd)
 
     # do a build with asserts enabled
-    host = 'x86-64'
-    dir = f'obj-assert-{env["pyver"]}-{host}'
+    host64 = 'x86-64'
+    dir = f'obj-assert-{env["pyver"]}-{host64}'
     build_dir = Path(kits_dir, utils.KIT_PREFIX_PATT + dir)
-    cmd = utils.gen_build_cmd(env, xed_builder, '', build_dir, host, flags + ' --assert')
+    cmd = utils.gen_build_cmd(env, xed_builder, '', build_dir, host64, flags + ' --assert')
+    commands.append(cmd)
+
+    # No-future build (For no-APX validation)
+    dir = f'obj-no-future-{env["pyver"]}-{host64}'
+    build_dir = Path(kits_dir, utils.KIT_PREFIX_PATT + dir)
+    cmd = utils.gen_build_cmd(env, xed_builder, '', build_dir, host64, flags + ' --no-future --assert')
     commands.append(cmd)
 
     # Test opt=3 build
-    host = 'x86-64'
-    dir = f'obj-opt3-{env["pyver"]}-{host}'
+    dir = f'obj-opt3-{env["pyver"]}-{host64}'
     build_dir = Path(kits_dir, utils.KIT_PREFIX_PATT + dir)
-    cmd = utils.gen_build_cmd(env, xed_builder, '', build_dir, host, flags + ' --opt=3')
+    cmd = utils.gen_build_cmd(env, xed_builder, '', build_dir, host64, flags + ' --opt=3')
     commands.append(cmd)
 
     # enc2test - test encode-decode path of all instructions

diff --git a/.github/workflows/sanity_external.yml b/.github/workflows/sanity_external.yml
@@ -110,16 +110,15 @@ jobs:
     env:
       AV_SCAN_PATH: ${{ secrets.AV_SCAN_PATH }}
     steps:
-    - name: Checkout
+    - name: Checkout xed
       uses: actions/checkout@v3
       with:
         path: xed
-        fetch-depth: 0
     - name: Checkout mbuild
       uses: actions/checkout@v3
       with:
-        repository: intel-innersource/libraries.isa.xed.mbuild
-        ref: ${{ needs.init.outputs.mbuild_branch }}
+        repository: intelxed/mbuild
+        ref: main
         path: mbuild
         token: ${{ secrets.PAT }}
     - name: anti-virus check
@@ -145,3 +144,46 @@ jobs:
             repo: context.repo.repo,
             body: "Anti-virus scan summary: " + antivirusSummary
           })
+  
+  protex_scan:
+    needs: init
+    runs-on:
+      - self-hosted
+      - xed-runners
+      - Linux
+    env:
+      PROTEX_BDSTOOL:  ${{ secrets.PROTEX_BDSTOOL }}
+      PROTEX_USERNAME: ${{ secrets.PROTEX_USERNAME }}
+      PROTEX_PASSWORD: ${{ secrets.PROTEX_PASSWORD }}
+      PROTEX_SERVER:   ${{ secrets.PROTEX_SERVER }}
+      PROTEX_PROJ_ID:  ${{ secrets.PROTEX_PROJECT_ID }}
+    steps:
+    - name: Checkout xed
+      uses: actions/checkout@v3
+      with:
+        path: xed
+    - name: Checkout mbuild
+      uses: actions/checkout@v3
+      with:
+        repository: intelxed/mbuild
+        ref: main
+        path: mbuild
+        token: ${{ secrets.PAT }}
+    - name: protex scan
+      run: |
+          cd xed
+          python3 .github/scripts/protex.py --project-id "${PROTEX_PROJ_ID}" --url "${PROTEX_SERVER}" \
+            --user "${PROTEX_USERNAME}" --pass "${PROTEX_PASSWORD}" --tool-path "${PROTEX_BDSTOOL}"
+    - name: add comment   # uploads protex guidance as pull-request comment
+      uses: actions/github-script@v6
+      if: github.event_name == 'pull_request'   # add scan summary as comment only if there is a PR
+      with:
+        script: |
+          github.rest.issues.createComment({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: "Protex scan finished; view results at ${{env.PROTEX_SERVER}}"
+          })
+
+
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-v2023.07.09
+v2023.08.21
diff --git a/datafiles/apx-f/README.md b/datafiles/apx-f/README.md
@@ -0,0 +1,117 @@
+# General
+Intel® Advanced Performance Extensions (Intel® APX) expands the Intel® 64 instruction set architecture with
+access to more registers and adds various new features that improve general-purpose performance. The
+extensions are designed to provide efficient performance gains across a variety of workloads without
+significantly increasing silicon area or power consumption of the core.
+The main features of Intel® APX include:
+• 16 additional general-purpose registers (GPRs) R16–R31, also referred to as Extended GPRs (EGPRs)
+in this document;
+• Three-operand instruction formats with a new data destination (NDD) register for many integer
+instructions;
+• Conditional ISA improvements: New conditional load, store and compare instructions, combined
+with an option for the compiler to suppress the status flags writes of common instructions;
+• Optimized register state save/restore operations;
+• A new 64-bit absolute direct jump instruction
+
+This file describes XED's support status and comments for APX
+
+## APX instructions definition by XED
+#### Legacy
+- Instructions with REX2 prefix are not defined with new iforms or new ISA-SETs
+#### EVEX
+- Existing (non-APX) EVEX instructions with EGPRs are not defined with new iforms or new ISA-SETs
+- Promoted and new instructions are defined with new iforms, using the `_apx` suffix
+- Introduce new `APX_NDD` XED attribute For NDD (new data destination) instructions with 3 operands
+- Introduce new `APX_NF` XED attribute For No-Flags instructions
+
+# XED support status
+## Decoder support
+XED decoder currently supports:
+#### Legacy
+- REX2 prefix and APX extended GPRs (EGPRs)
+#### EVEX 
+- EGPRs decoding for existing instructions
+- All APX-Promoted instructions
+- All APX new instructions
+
+## Encoder support
+XED encoder supports status:
+#### Legacy
+- :x: No REX2 support
+#### EVEX 
+- :x: No EGPRs support
+- All APX-Promoted instructions
+- All APX new instructions. Note:
+  - {CF,}CMOVcc - Partial support, need to set the NF XED operand for forms with EVEX.NF=1
+#### ENC2 XED module
+- :x: No ENC2 support for APX. Users should not use this module for APX encoding
+
+
+## APX CPUID support
+XED defines only the Foundational APX CPUID bit for promoted/new EVEX instructions.
+APX-Promoted instructions require the equivalent Legacy CPUID as well - Those Legacy 
+CPUIDs are not listed by XED yet (TBD)
+
+
+## Chip-Check support
+XED's chip-check supports the detection of all APX instructions and flavors.
+APX instruction can be:
+- New APX instruction
+- Legacy instruction with REX2 prefix
+- EVEX instruction with EGPR as one of its operands (register or memory)
+- EVEX instruction with ignored EGPR encoding (EVEX.B4 or EVEX.X4 bit is set but ignored). Such encoding causes illegal instruction on non-APX chips. 
+
+
+# Useful APIs
+Numerous examples and vivid explanations regarding APX features can be found in the xed-ex1 example tool.
+
+## Decoder
+1. Users can dynamically disable APX support using the `NO_APX` API:
+    ```c
+    void xed3_operand_set_no_apx(xed_decoded_inst_t* d, 1)
+    ```
+    The API disables support for all APX architecture, including:
+    - EGPRs for Legacy instructions (actually disables REX2 support)
+    - EGPRs for EVEX instructions (for both APX and no-APX instructions). It means no support for the reinterpreted EVEX bits (EGPRs, NDD/NF and more...)
+    - APX new/promoted EVEX instructions
+
+
+ ## Encoder
+ 1. The `MUST_USE_EVEX` API forces encoding request to the EVEX space. Use it for APX promoted instructions:
+
+    <sub>C Library API</sub>
+    ```c
+    void xed3_operand_set_must_use_evex(xed_decoded_inst_t* d, 1)
+    ```
+
+    <sub>XED command-line tool</sub>
+    ```bash
+    $ xed.exe -set MUST_USE_EVEX 1 ....
+    ```
+
+2. Encode request for promoted No-Flags instruction should be built with the `NF` operand:
+
+    <sub>C Library API</sub>
+    ```c
+    void xed3_operand_set_nf(xed_decoded_inst_t* d, 1)
+    ```
+
+    <sub>XED command-line tool</sub>
+    ```bash
+    $ xed.exe -set NF 1 ....
+    ```
+
+## CCMPcc/CTESTcc (Encode/Decode)
+- Introduce new `DFV` 4-bit pseudo-register for "Default Flags Values" (EVEX.[OF, SF, ZF, CF])
+- The register index represents the default flags bits. For example: `DFV10.index == 10 == 0b1010  ->  OF=1, SF=0, ZF=1, CF=0`
+- The DFV pseudo-register should be explicitly defined in an encoder request. For example:
+    ```bash
+    $ xed -64 -e CCMPB r8b r9b dfv14
+    Request: CCMPB MODE:2, REG0:R8B, REG1:R9B, REG2:DFV14, SMODE:2
+    OPERAND ORDER: REG0 REG1 REG2 
+    Encodable! 6254740238C8
+    .byte 0x62,0x54,0x74,0x02,0x38,0xc8
+    ```
+- the official APX assembly syntax is not support yet. 
+Current XED syntax is: `<MNEMONIC> <reg/mem>, <reg/mem/imm>, <dfv>`
+
diff --git a/datafiles/apx-f/apx-amx-evex-reg-tables.txt b/datafiles/apx-f/apx-amx-evex-reg-tables.txt
@@ -0,0 +1,28 @@
+#BEGIN_LEGAL
+#
+#Copyright (c) 2023 Intel Corporation
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#  
+#END_LEGAL
+
+xed_reg_enum_t TMM_R3()::
+REXR4=0 REXR=0 REG=0 | OUTREG=XED_REG_TMM0
+REXR4=0 REXR=0 REG=1 | OUTREG=XED_REG_TMM1
+REXR4=0 REXR=0 REG=2 | OUTREG=XED_REG_TMM2
+REXR4=0 REXR=0 REG=3 | OUTREG=XED_REG_TMM3
+REXR4=0 REXR=0 REG=4 | OUTREG=XED_REG_TMM4
+REXR4=0 REXR=0 REG=5 | OUTREG=XED_REG_TMM5
+REXR4=0 REXR=0 REG=6 | OUTREG=XED_REG_TMM6
+REXR4=0 REXR=0 REG=7 | OUTREG=XED_REG_TMM7
+
diff --git a/datafiles/apx-f/apx-error-enum.txt b/datafiles/apx-f/apx-error-enum.txt
@@ -0,0 +1,19 @@
+#BEGIN_LEGAL
+#
+#Copyright (c) 2023 Intel Corporation
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#  
+#END_LEGAL
+
+BAD_REX2_PREFIX   ///< A REX2 prefix was found where none is allowed.
diff --git a/datafiles/apx-f/apx-evex-dec.txt b/datafiles/apx-f/apx-evex-dec.txt
@@ -0,0 +1,48 @@
+#BEGIN_LEGAL
+#
+#Copyright (c) 2023 Intel Corporation
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#  
+#END_LEGAL
+
+###################################################
+# Extends avx512-evex-dec.txt XED NT
+# This NT enables EGPRs encoding using the EVEX.R4 bit when APX enabled. 
+# We're using NT in order to imply #UD on non-apx mode with EGPRs EVEX.R4 instructions
+
+EVEXR4_ONE()::
+    ### Extend an existing NT ###
+    ############# New rules: #############
+    NO_APX=0 REXR4=1   | 
+    NO_APX=1 REXR4=1   | error       # Not mandatory, but easy to understand
+    ##### Origin NT will expends to: #####
+    # NO_APX=0 REXR4=0   | 
+    # NO_APX=1 REXR4=0   | 
+    # Default: otherwise | error 
+
+###################################################
+
+EVAPX()::
+    # 1. Clean legacy-EVEX operands which reinterpreted with APX-promoted instructions.
+    # 2. Set the EVVSPACE to APX so the encoder will choose the right EVEX path
+    # 3. Check that the lower MASK bits are zeroed.
+    #
+    # (MASK[0-1] == 0) & (MASK[2] == NF) & (APX Enabled)
+    NO_APX=0 NF=0 MASK=0 | EVEX_APX         SCC=0 BCRC=0
+    NO_APX=0 NF=1 MASK=4 | EVEX_APX  MASK=0 SCC=0 BCRC=0
+    # Default: otherwise | error 
+
+EVAPX_SCC()::
+    # Clear Legacy reinterpreted bits by the SCC field and set EVEX sub-encoding space
+    true  | EVEX_APX_SCC MASK=0 VEXDEST4=0 NF=0 BCRC=0