| 1 |
|
| 2 |
VERSION |
| 3 |
-------------------------------------------------------------------------------- |
| 4 |
spirv-remap 0.97 |
| 5 |
|
| 6 |
INTRO: |
| 7 |
-------------------------------------------------------------------------------- |
| 8 |
spirv-remap is a utility to improve compression of SPIR-V binary files via |
| 9 |
entropy reduction, plus optional stripping of debug information and |
| 10 |
load/store optimization. It transforms SPIR-V to SPIR-V, 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 |
[email protected] |
| 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 |
|
| 51 |
spirv-remap -v --map all --input *.spv --output /tmp/out_dir |
| 52 |
|
| 53 |
2. Perform all possible size reductions |
| 54 |
|
| 55 |
spirv-remap-linux-64 -v --do-everything --input *.spv --output /tmp/out_dir |
| 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 = 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 SPIR-V 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 |
SPIR-V 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 |
member, 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::, 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 |
|