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, enhancements requests, code improvements, etc to:
33   spvremapper@lunarg.com
34
35
36COMMAND LINE USAGE:
37--------------------------------------------------------------------------------
38Examples are given with a verbosity of one (-v), but more verbosity can be
39had 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
41success, and a positive integer error on failure.
42
43Pre-built binaries for several OSs are available.  Examples presented are
44for Linux.  Command line arguments can be provided in any order.
45
461. Basic ID remapping
47
48Perform ID remapping on all shaders in "*.spv", writing new files with
49the same basenames to /tmp/out_dir.
50
51  spirv-remap -v --map all --input *.spv --output /tmp/out_dir
52
532. Perform all possible size reductions
54
55  spirv-remap-linux-64 -v --do-everything --input *.spv --output /tmp/out_dir
56
57Note that --do-everything is a synonym for:
58
59  --map all --dce all --opt all --strip all
60
61API USAGE:
62--------------------------------------------------------------------------------
63
64The public interface to the remapper is defined in SPIRV/SPVRemapper.h as follows:
65
66namespace spv {
67
68class spirvbin_t
69{
70public:
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
88The class definition is in SPVRemapper.cpp.
89
90remap() accepts an std::vector of SPIR-V words, modifies them per the
91request given in 'opts', and leaves the 'spv' container with the result.
92It is safe to instantiate one spirvbin_t per thread and process a different
93SPIR-V in each.
94
95The "opts" parameter to remap() accepts a bit mask of desired remapping
96options.  See REMAPPING AND OPTIMIZATION OPTIONS.
97
98On error, the function supplied to registerErrorHandler() will be invoked.
99This can be a standard C/C++ function, a lambda function, or a functor.
100The default handler simply calls exit(5); The error handler is a static
101member, so need only be set up once, not once per spirvbin_t instance.
102
103Log messages are supplied to registerLogHandler().  By default, log
104messages are eaten silently.  The log handler is also a static member.
105
106BUILD DEPENDENCIES:
107--------------------------------------------------------------------------------
108 1. C++11 compatible compiler
109 2. cmake
110 3. glslang
111
112
113BUILDING
114--------------------------------------------------------------------------------
115The standalone remapper is built along side glslangValidator through its
116normal build process.
117
118
119REMAPPING AND OPTIMIZATION OPTIONS
120--------------------------------------------------------------------------------
121API:
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
138