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