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, 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
  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 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::, 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