John Kessenich | 3c4a276 | 2015-05-19 21:07:04 +0000 | [diff] [blame] | 1 | |
| 2 | VERSION |
| 3 | -------------------------------------------------------------------------------- |
| 4 | spirv-remap 0.97 |
| 5 | |
| 6 | INTRO: |
| 7 | -------------------------------------------------------------------------------- |
| 8 | spirv-remap is a utility to improve compression of SPIRV binary files via |
| 9 | entropy reduction, plus optional stripping of debug information and |
| 10 | load/store optimization. It transforms SPIRV to SPIRV, remapping IDs. The |
| 11 | resulting modules have an increased ID range (IDs are not as tightly packed |
| 12 | around zero), but will compress better when multiple modules are compressed |
| 13 | together, since compressor's dictionary can find better cross module |
| 14 | commonality. |
| 15 | |
| 16 | Remapping is accomplished via canonicalization. Thus, modules can be |
| 17 | compressed one at a time with no loss of quality relative to operating on |
| 18 | many modules at once. The command line tool operates on multiple modules |
| 19 | only in the trivial repetition sense, for ease of use. The remapper API |
| 20 | only accepts a single module at a time. |
| 21 | |
| 22 | There are two modes of use: command line, and a C++11 API. Both are |
| 23 | described below. |
| 24 | |
| 25 | spirv-remap is currently in an alpha state. Although there are no known |
| 26 | remapping defects, it has only been exercised on one real world game shader |
| 27 | workload. |
| 28 | |
| 29 | |
| 30 | FEEDBACK |
| 31 | -------------------------------------------------------------------------------- |
| 32 | Report defects, enhancements requests, code improvements, etc to: |
| 33 | spvremapper@lunarg.com |
| 34 | |
| 35 | |
| 36 | COMMAND LINE USAGE: |
| 37 | -------------------------------------------------------------------------------- |
| 38 | Examples are given with a verbosity of one (-v), but more verbosity can be |
| 39 | had via -vv, -vvv, etc, or an integer parameter to --verbose, such as |
| 40 | "--verbose 4". With no verbosity, the command is silent and returns 0 on |
| 41 | success, and a positive integer error on failure. |
| 42 | |
| 43 | Pre-built binaries for several OSs are available. Examples presented are |
| 44 | for Linux. Command line arguments can be provided in any order. |
| 45 | |
| 46 | 1. Basic ID remapping |
| 47 | |
| 48 | Perform ID remapping on all shaders in "*.spv", writing new files with |
| 49 | the same basenames to /tmp/out_dir. |
| 50 | |
John Kessenich | 01685c3 | 2015-05-20 16:04:17 +0000 | [diff] [blame^] | 51 | spirv-remap -v --map all --input *.spv --output /tmp/out_dir |
John Kessenich | 3c4a276 | 2015-05-19 21:07:04 +0000 | [diff] [blame] | 52 | |
| 53 | 2. Perform all possible size reductions |
| 54 | |
John Kessenich | 01685c3 | 2015-05-20 16:04:17 +0000 | [diff] [blame^] | 55 | spirv-remap-linux-64 -v --do-everything --input *.spv --output /tmp/out_dir |
John Kessenich | 3c4a276 | 2015-05-19 21:07:04 +0000 | [diff] [blame] | 56 | |
| 57 | Note that --do-everything is a synonym for: |
| 58 | |
| 59 | --map all --dce all --opt all --strip all |
| 60 | |
| 61 | API USAGE: |
| 62 | -------------------------------------------------------------------------------- |
| 63 | |
| 64 | The public interface to the remapper is defined in SPIRV/SPVRemapper.h as follows: |
| 65 | |
| 66 | namespace spv { |
| 67 | |
| 68 | class spirvbin_t |
| 69 | { |
| 70 | public: |
| 71 | enum Options { ... }; |
| 72 | spirvbin_t(int verbose = 0); // construct |
| 73 | |
| 74 | // remap an existing binary in memory |
| 75 | void remap(std::vector<std::uint32_t>& spv, std::uint32_t opts = Options::DO_EVERYTHING); |
| 76 | |
| 77 | // Type for error/log handler functions |
| 78 | typedef std::function<void(const std::string&)> errorfn_t; |
| 79 | typedef std::function<void(const std::string&)> logfn_t; |
| 80 | |
| 81 | // Register error/log handling functions (can be c/c++ fn, lambda fn, or functor) |
| 82 | static void registerErrorHandler(errorfn_t handler) { errorHandler = handler; } |
| 83 | static void registerLogHandler(logfn_t handler) { logHandler = handler; } |
| 84 | }; |
| 85 | |
| 86 | } // namespace spv |
| 87 | |
| 88 | The class definition is in SPVRemapper.cpp. |
| 89 | |
| 90 | remap() accepts an std::vector of SPIRV words, modifies them per the |
| 91 | request given in 'opts', and leaves the 'spv' container with the result. |
| 92 | It is safe to instantiate one spirvbin_t per thread and process a different |
| 93 | SPIRV in each. |
| 94 | |
| 95 | The "opts" parameter to remap() accepts a bit mask of desired remapping |
| 96 | options. See REMAPPING AND OPTIMIZATION OPTIONS. |
| 97 | |
| 98 | On error, the function supplied to registerErrorHandler() will be invoked. |
| 99 | This can be a standard C/C++ function, a lambda function, or a functor. |
| 100 | The default handler simply calls exit(5); The error handler is a static |
| 101 | members, so need only be set up once, not once per spirvbin_t instance. |
| 102 | |
| 103 | Log messages are supplied to registerLogHandler(). By default, log |
| 104 | messages are eaten silently. The log handler is also a static member. |
| 105 | |
| 106 | BUILD DEPENDENCIES: |
| 107 | -------------------------------------------------------------------------------- |
| 108 | 1. C++11 compatible compiler |
| 109 | 2. cmake |
| 110 | 3. glslang |
| 111 | |
| 112 | |
| 113 | BUILDING |
| 114 | -------------------------------------------------------------------------------- |
| 115 | The standalone remapper is built along side glslangValidator through its |
| 116 | normal build process. |
| 117 | |
| 118 | |
| 119 | REMAPPING AND OPTIMIZATION OPTIONS |
| 120 | -------------------------------------------------------------------------------- |
| 121 | API: |
| 122 | These are bits defined under spv::spirvbin_t::Options::, and can be |
| 123 | bitwise or-ed together as desired. |
| 124 | |
| 125 | MAP_TYPES = canonicalize type IDs |
| 126 | MAP_NAMES = canonicalize named data |
| 127 | MAP_FUNCS = canonicalize function bodies |
| 128 | DCE_FUNCS = remove dead functions |
| 129 | DCE_VARS = remove dead variables |
| 130 | DCE_TYPES = remove dead types |
| 131 | OPT_LOADSTORE = optimize unneeded load/stores |
| 132 | MAP_ALL = (MAP_TYPES | MAP_NAMES | MAP_FUNCS) |
| 133 | DCE_ALL = (DCE_FUNCS | DCE_VARS | DCE_TYPES) |
| 134 | OPT_ALL = (OPT_LOADSTORE) |
| 135 | ALL_BUT_STRIP = (MAP_ALL | DCE_ALL | OPT_ALL) |
| 136 | DO_EVERYTHING = (STRIP | ALL_BUT_STRIP) |
| 137 | |