README-spirv-remap.txt

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