schedtools is a collection of tools used to automatically generate llvm x86 schedule model. Input to it is a json file containing scheduling information and some additional infomation for all llvm x86 instructions. This tool can also verify existing schedule mode comparing to given input json.

Usage Examples

Given input json, generate alderlake-p schedule model:

smg gen --target-cpu=alderlake-p ADLP.json -o X86SchedAlderlakeP.td

Given input json, verify alderlake-p schedule model:

smg verify --target-cpu=alderlake-p ADLP.json

Generate alderlake-p input json (refer to Tools for more detail):

llvm-tblgen -I llvm/include llvm/lib/Target/X86/X86.td -I llvm/lib/Target/X86/ --gen-x86-inst-sched-info |
  add_xed_info.py --xed <xed-dir>/obj/wkit/examples/obj/xed |
  add_uops_uopsinfo.py --inst-xml instructions.xml --arch-name=ADL-P |
  add_adl_p_uopsinfo.py --adl-p-json tpt_lat-glc-client.json |
  add_smv_uopsinfo.py --ref-cpu=skylake --target-cpu=alderlake-p -o input.json

Input JSON Format

{
  "AAA": {
    "SchedReads": [],
    "SchedWrites": [
      {
        "Name": "WriteMicrocoded",
        "Type": "SchedWrite"
      }
    ],
    "XedInfo": {
      "IsaSet": "I86"
    },
    "Port": [[1, [0, 1, 5, 6 ]]],
    "Uops": 1,
    "Tp": 0.25,
    "Latency": 100,
  },
  ...
}

Input json should be a dict which uses llvm x86 instruction's opcode as its key. It's value contains a list of information to describe this opcode.
"SchedReads" and "SchedWrites" must be presented.
"XedInfo" is optional. If it is presented, "IsaSet" must be presented. It is used to determin if this instruction is supported by specifc target.
"Port", "Uops", "Tp", "Latency" are optional. "Port" format is [[num_uop_a, ports of uop_a], ...].

Tools

Below is useful tools to assist in generating input json.

X86InstSchedInfo Emitter

This is a llvm tablegen backend that is capable to enumerate all x86 instruction's "SchedReads" and "SchedWrites" to form an initial json file. In addition, it can also enumerate an asm string for each matchable instructions(in AsmMatcher perspective). This asm string can be used by other tool to generate "XedInfo".

Usage:

git am <schedtool>/llvm-patch/0003-Add-gen-x86-inst-sched-info-to-emit-x86-instruction-.patch
rebuild llvm && cd llvm-dir
llvm-tblgen -I llvm/include llvm/lib/Target/X86/X86.td -I llvm/lib/Target/X86/ --gen-x86-inst-sched-info -o input1.json

Here's piece of output json. "Modes" indicates all valid encoding modes(16bit, 32bit, 64bit).

{
  "AAA": {
    "AsmString": "aaa",
    "Modes": [32, 16],
    "SchedReads": [],
    "SchedWrites": [
      {
        "Name": "WriteMicrocoded",
        "Type": "SchedWrite"
      }
    ]
  },
  ...
}

tools/add_xed_info.py

This tool is used to add "XedInfo" to input json. Input to add_xed_info.py is normally a json file generated by X86InstSchedInfo emitter. Output is also a json with more rich information.
This tool will first use llvm-mc (make sure it is in path) to verify and try to correct "AsmString" so the opcode of matched MCInst is the same with the input json. It then encode the corrected "AsmString" and store it into the output json. After all "AsmString" being fixed and encoded, This tool uses xed to decode the "Encoding" and extract "IForm", "IsaSet", etc to form "XedInfo" in output json.

Usage:

# Build xed
git clone https://github.com/intelxed/xed.git
git clone https://github.com/intelxed/mbuild.git
cd xed
# Print more rich info when decoding.
git am <schedtool>/xed-patch/0001-Dump-eosz-and-operand-s-xtype-width-when-verbosity-i.patch
./mfile.py
./mfile.py examples

cd llvm-dir
git am <schedtool>/llvm-patch/0002-Support-debug-only-print-opcode-to-llvm-mc.patch
rebuild llvm
add_xed_info.py --xed <xed-dir>/obj/wkit/examples/obj/xed --jf input1.json -o input2.json

tools/add_uops_uopsinfo.py

This tool is used to add corresponding "Port", "Uops", "Tp", "latency" from uops.info to input json. It won't update those info it already exited.
Input json to add_uops_uopsinfo.py must contain "XedInfo" because it uses this to find the corresponding record in uops.info. Another input to this tool is instructions.xml file. You can download it from uops.info.

Usage:

# arch-name is "architecture name" in instructions.xml
add_uops_uopsinfo.py --inst-xml instructions.xml --arch-name=ADL-P --jf input2.json -o input3.json

tools/add_adl_p_uopsinfo.py

This tool is used to add "Port", "Uops", "Tp", "Latency" from json provided by intel for GLC. It won't update those info it already exited.

Usage:

add_adl_p_uopsinfo.py --adl-p-json tpt_lat-glc-client.json --jf input3.json -o input4.json

tools/add_smv_uopsinfo.py

This tool is used to add "Port", "Uops", "Tp", "Latency" from existing schedule model. There are always some corner instructions that we don't have much scheduling information about them from uops.info or other source. This blocked us to generate a relative complete schedule model. Thus this tools is helpful since we can find nearly all instruction's scheduling info from existing schedule model though they may not be correct. Currently only part of reference targets are supported since we need to map ports between target-cpu and ref-cpu.

Usage:

cd llvm-dir
git am <schedule>/llvm-patch/0001-Add-llvm-smv-tool-to-auto-generate-instruction-sched.patch
rebuild llvm
add_smv_uopsinfo.py --ref-cpu=skylake --target-cpu=alderlake-p --jf input4.json -o input5.json