)]}'
{
  "commit": "5b8757b4b881ccd8fbddb5ad7e93ee45e45cebb3",
  "tree": "3d18d552d4b55287c0db35ebe9fb3c3f770433cc",
  "parents": [
    "425efcd856a6a14351071b9ce63dcb5bfa6c00f1",
    "e231b396520e94fc9609ede834733027e35c0f65"
  ],
  "author": {
    "name": "Ben Vanik",
    "email": "ben.vanik@gmail.com",
    "time": "Fri Feb 17 11:54:19 2023 -0800"
  },
  "committer": {
    "name": "GitHub",
    "email": "noreply@github.com",
    "time": "Fri Feb 17 11:54:19 2023 -0800"
  },
  "message": "Adding `--iree-hal-substitute-executable\u003d` flag. (#12240)\n\nThis allows for specifying one or more `executable_name\u003dfile.xxx` pairs\r\nthat each replace a `hal.executable` op with the `executable_name` with\r\nthe contents of `file.xxx`. .mlir/.mlirbc files are loaded and a\r\n`hal.executable` with the matching name is used as a replacement while\r\nany other file type will cause the original executable to be\r\nexternalized and linked with the specified file (.ptx/.spv/etc).\r\n\r\nThe additional `--iree-hal-substitute-executable-*-from\u003d` flags allow\r\nfor scanning a directory for executables by name to build the\r\nsubstitution mapping. Only files in the executable_name or\r\nmodule_executable_name form will be substituted but we can extend this\r\nin the future to support variant naming.\r\n\r\nBecause of phase ordering constraints around where codegen is able to\r\nmutate host-related code such as workgroup count calculations there are\r\ntwo flag sets:\r\n  `--iree-hal-substitute-executable-source\u003dname\u003dfile.xxx`\r\n  `--iree-hal-substitute-executable-sources-from\u003dpath/`\r\n and\r\n  `--iree-hal-substitute-executable-object\u003dname\u003dfile.xxx`\r\n  `--iree-hal-substitute-executable-objects-from\u003dpath/`\r\nSources are substituted immediately prior to benchmark generation and\r\nwhen substituting target objects (.ptx, .spv, etc) require that it\u0027s ok\r\nto skip codegen (workgroup count calculation is not dependent on root op\r\ndetection, etc). Objects are substituted immediately after codegen for\r\nuse in cases where codegen is to generate the host code. There are uses\r\nfor both depending on what the input IR is and what the developer wants\r\nto modify (host code, device code, or both).\r\n\r\nThe primary developer workflows this covers are:\r\n1. dump executable sources via `--iree-hal-dump-executable-sources-to\u003d`\r\nand modify them, potentially running any number of iree-opt passes,\r\nbefore linking them back in to the original program they came from\r\n2. author custom implementations ala the custom_dispatch sample in\r\ntarget toolchains (.cu -\u003e .ptx, .glsl -\u003e .spv, etc) and use those in\r\nfull programs without needing to modify the compiler\r\n3. do either of the above and use the substituted executable for\r\nmicrobenchmarking via `--iree-hal-dump-executable-benchmarks-to\u003d` (so\r\none can easily microbenchmark handwritten kernels)\r\n\r\nExample usage:\r\n```sh\r\n# dump sources for a program\r\niree-compile ... \\\r\n  --iree-hal-dump-executable-sources-to\u003d~/sources/\r\n# \u003cmodify some of the sources\u003e\r\n# recompile with the new changes and substitute 2 executables\r\niree-compile ... \\\r\n    --iree-hal-substitute-executable-source\u003d_main_dispatch_0\u003d~/sources/modified_dispatch_0.mlir \\\r\n    --iree-hal-substitute-executable-source\u003d_main_dispatch_1\u003d~/sources/modified_dispatch_1.mlir\r\n# same thing with search paths\r\niree-compile ... \\\r\n    --iree-hal-executable-object-search-path\u003d~/sources/ \\\r\n    --iree-hal-substitute-executable-source\u003d_main_dispatch_0\u003dmodified_dispatch_0.mlir\r\n# same thing but matching all files by name as from dump-sources-to:\r\niree-compile ... \\\r\n    --iree-hal-substitute-executable-sources-from\u003d~/sources/\r\n```\r\n\r\nThis works with ptx/spv as well:\r\n```sh\r\n# dump ptx binaries\r\niree-compile ... \\\r\n    --iree-hal-dump-executable-binaries-to\u003d~/binaries/\r\n# \u003cmodify dispatch ptx\u003e\r\n# replace @_main_dispatch_0 with the external ptx file\r\niree-compile ... \\\r\n    --iree-hal-substitute-executable-object\u003d_main_dispatch_0\u003d~/binaries/modified_dispatch_0.ptx\r\n```\r\n\r\nIt\u0027s also possible to iterate on microbenchmarks using the custom\r\nsources/objects:\r\n```sh\r\n# dump all benchmarks with the substitution active\r\niree-compile ... \\\r\n    --iree-hal-substitute-executable-source\u003d_main_dispatch_0\u003d~/sources/modified_dispatch_0.mlir \\\r\n    --iree-hal-dump-executable-benchmarks-to\u003d~/benchmarks/\r\n# inspect benchmark for the dispatch and see the hello.world attr\r\n# can use iree-compile to build the benchmark and then iree-benchmark-module\r\n```\r\n\r\nProgress on #12222 (the rest for linking alternative formats is\r\northogonal).",
  "tree_diff": []
}