Skip to content

Commit

Permalink
Clarify mapping of target env to SPIR-V version (KhronosGroup#3150)
Browse files Browse the repository at this point in the history 
* Clarify mapping of target env to SPIR-V version

It depends on the API method.

* Update SPIR-V version comments on validator
  • Loading branch information
@dneto0
dneto0 authored Jan 24, 2020
1 parent e7afeb0 commit 5d786f6
Show file tree
Hide file tree
Showing 3 changed files with 79 additions and 9 deletions.
36 changes: 33 additions & 3 deletions include/spirv-tools/libspirv.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -419,8 +419,17 @@ SPIRV_TOOLS_EXPORT const char* spvSoftwareVersionString(void);
SPIRV_TOOLS_EXPORT const char* spvSoftwareVersionDetailsString(void);

// Certain target environments impose additional restrictions on SPIR-V, so it's
// often necessary to specify which one applies. SPV_ENV_UNIVERSAL means
// often necessary to specify which one applies. SPV_ENV_UNIVERSAL_* implies an
// environment-agnostic SPIR-V.
//
// When an API method needs to derive a SPIR-V version from a target environment
// (from the spv_context object), the method will choose the highest version of
// SPIR-V supported by the target environment. Examples:
// SPV_ENV_VULKAN_1_0 -> SPIR-V 1.0
// SPV_ENV_VULKAN_1_1 -> SPIR-V 1.3
// SPV_ENV_VULKAN_1_1_SPIRV_1_4 -> SPIR-V 1.4
// SPV_ENV_VULKAN_1_2 -> SPIR-V 1.5
// Consult the description of API entry points for specific rules.
typedef enum {
SPV_ENV_UNIVERSAL_1_0, // SPIR-V 1.0 latest revision, no other restrictions.
SPV_ENV_VULKAN_1_0, // Vulkan 1.0 latest revision.
Expand Down Expand Up @@ -448,7 +457,10 @@ typedef enum {
SPV_ENV_VULKAN_1_1, // Vulkan 1.1 latest revision.
SPV_ENV_WEBGPU_0, // Work in progress WebGPU 1.0.
SPV_ENV_UNIVERSAL_1_4, // SPIR-V 1.4 latest revision, no other restrictions.
SPV_ENV_VULKAN_1_1_SPIRV_1_4, // Vulkan 1.1 with SPIR-V 1.4 binary.

// Vulkan 1.1 with VK_KHR_spirv_1_4, i.e. SPIR-V 1.4 binary.
SPV_ENV_VULKAN_1_1_SPIRV_1_4,

SPV_ENV_UNIVERSAL_1_5, // SPIR-V 1.5 latest revision, no other restrictions.
SPV_ENV_VULKAN_1_2, // Vulkan 1.2 latest revision.
} spv_target_env;
Expand Down Expand Up @@ -486,7 +498,11 @@ SPIRV_TOOLS_EXPORT bool spvParseVulkanEnv(uint32_t vulkan_ver,
uint32_t spirv_ver,
spv_target_env* env);

// Creates a context object. Returns null if env is invalid.
// Creates a context object for most of the SPIRV-Tools API.
// Returns null if env is invalid.
//
// See specific API calls for how the target environment is interpeted
// (particularly assembly and validation).
SPIRV_TOOLS_EXPORT spv_context spvContextCreate(spv_target_env env);

// Destroys the given context object.
Expand Down Expand Up @@ -667,6 +683,8 @@ SPIRV_TOOLS_EXPORT void spvFuzzerOptionsEnableFuzzerPassValidation(
// be stored into *binary. Any error will be written into *diagnostic if
// diagnostic is non-null, otherwise the context's message consumer will be
// used. The generated binary is independent of the context and may outlive it.
// The SPIR-V binary version is set to the highest version of SPIR-V supported
// by the context's target environment.
SPIRV_TOOLS_EXPORT spv_result_t spvTextToBinary(const spv_const_context context,
const char* text,
const size_t length,
Expand Down Expand Up @@ -704,13 +722,25 @@ SPIRV_TOOLS_EXPORT void spvBinaryDestroy(spv_binary binary);
// Validates a SPIR-V binary for correctness. Any errors will be written into
// *diagnostic if diagnostic is non-null, otherwise the context's message
// consumer will be used.
//
// Validate for SPIR-V spec rules for the SPIR-V version named in the
// binary's header (at word offset 1). Additionally, if the context target
// environment is a client API (such as Vulkan 1.1), then validate for that
// client API version, to the extent that it is verifiable from data in the
// binary itself.
SPIRV_TOOLS_EXPORT spv_result_t spvValidate(const spv_const_context context,
const spv_const_binary binary,
spv_diagnostic* diagnostic);

// Validates a SPIR-V binary for correctness. Uses the provided Validator
// options. Any errors will be written into *diagnostic if diagnostic is
// non-null, otherwise the context's message consumer will be used.
//
// Validate for SPIR-V spec rules for the SPIR-V version named in the
// binary's header (at word offset 1). Additionally, if the context target
// environment is a client API (such as Vulkan 1.1), then validate for that
// client API version, to the extent that it is verifiable from data in the
// binary itself, or in the validator options.
SPIRV_TOOLS_EXPORT spv_result_t spvValidateWithOptions(
const spv_const_context context, const spv_const_validator_options options,
const spv_const_binary binary, spv_diagnostic* diagnostic);
Expand Down
25 changes: 24 additions & 1 deletion include/spirv-tools/libspirv.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ class Context {
public:
// Constructs a context targeting the given environment |env|.
//
// See specific API calls for how the target environment is interpeted
// (particularly assembly and validation).
//
// The constructed instance will have an empty message consumer, which just
// ignores all messages from the library. Use SetMessageConsumer() to supply
// one if messages are of concern.
Expand Down Expand Up @@ -279,16 +282,20 @@ class SpirvTools {
// Assembles the given assembly |text| and writes the result to |binary|.
// Returns true on successful assembling. |binary| will be kept untouched if
// assembling is unsuccessful.
// The SPIR-V binary version is set to the highest version of SPIR-V supported
// by the target environment with which this SpirvTools object was created.
bool Assemble(const std::string& text, std::vector<uint32_t>* binary,
uint32_t options = kDefaultAssembleOption) const;
// |text_size| specifies the number of bytes in |text|. A terminating null
// character is not required to present in |text| as long as |text| is valid.
// The SPIR-V binary version is set to the highest version of SPIR-V supported
// by the target environment with which this SpirvTools object was created.
bool Assemble(const char* text, size_t text_size,
std::vector<uint32_t>* binary,
uint32_t options = kDefaultAssembleOption) const;

// Disassembles the given SPIR-V |binary| with the given |options| and writes
// the assembly to |text|. Returns ture on successful disassembling. |text|
// the assembly to |text|. Returns true on successful disassembling. |text|
// will be kept untouched if diassembling is unsuccessful.
bool Disassemble(const std::vector<uint32_t>& binary, std::string* text,
uint32_t options = kDefaultDisassembleOption) const;
Expand All @@ -300,10 +307,26 @@ class SpirvTools {
// Validates the given SPIR-V |binary|. Returns true if no issues are found.
// Otherwise, returns false and communicates issues via the message consumer
// registered.
// Validates for SPIR-V spec rules for the SPIR-V version named in the
// binary's header (at word offset 1). Additionally, if the target
// environment is a client API (such as Vulkan 1.1), then validate for that
// client API version, to the extent that it is verifiable from data in the
// binary itself.
bool Validate(const std::vector<uint32_t>& binary) const;
// Like the previous overload, but provides the binary as a pointer and size:
// |binary_size| specifies the number of words in |binary|.
// Validates for SPIR-V spec rules for the SPIR-V version named in the
// binary's header (at word offset 1). Additionally, if the target
// environment is a client API (such as Vulkan 1.1), then validate for that
// client API version, to the extent that it is verifiable from data in the
// binary itself.
bool Validate(const uint32_t* binary, size_t binary_size) const;
// Like the previous overload, but takes an options object.
// Validates for SPIR-V spec rules for the SPIR-V version named in the
// binary's header (at word offset 1). Additionally, if the target
// environment is a client API (such as Vulkan 1.1), then validate for that
// client API version, to the extent that it is verifiable from data in the
// binary itself, or in the validator options.
bool Validate(const uint32_t* binary, size_t binary_size,
spv_validator_options options) const;

Expand Down
27 changes: 22 additions & 5 deletions include/spirv-tools/optimizer.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,9 +65,9 @@ class Optimizer {
// Constructs an instance with the given target |env|, which is used to decode
// the binaries to be optimized later.
//
// The constructed instance will have an empty message consumer, which just
// ignores all messages from the library. Use SetMessageConsumer() to supply
// one if messages are of concern.
// The instance will have an empty message consumer, which ignores all
// messages from the library. Use SetMessageConsumer() to supply a consumer
// if messages are of concern.
//
// For collections of passes that are meant to transform the input into
// another execution environment, then the source environment should be
Expand Down Expand Up @@ -164,17 +164,26 @@ class Optimizer {
bool FlagHasValidForm(const std::string& flag) const;

// Allows changing, after creation time, the target environment to be
// optimized for. Should be called before calling Run().
// optimized for and validated. Should be called before calling Run().
void SetTargetEnv(const spv_target_env env);

// Optimizes the given SPIR-V module |original_binary| and writes the
// optimized binary into |optimized_binary|.
// optimized binary into |optimized_binary|. The optimized binary uses
// the same SPIR-V version as the original binary.
//
// Returns true on successful optimization, whether or not the module is
// modified. Returns false if |original_binary| fails to validate or if errors
// occur when processing |original_binary| using any of the registered passes.
// In that case, no further passes are executed and the contents in
// |optimized_binary| may be invalid.
//
// By default, the binary is validated before any transforms are performed,
// and optionally after each transform. Validation uses SPIR-V spec rules
// for the SPIR-V version named in the binary's header (at word offset 1).
// Additionally, if the target environment is a client API (such as
// Vulkan 1.1), then validate for that client API version, to the extent
// that it is verifiable from data in the binary itself.
//
// It's allowed to alias |original_binary| to the start of |optimized_binary|.
bool Run(const uint32_t* original_binary, size_t original_binary_size,
std::vector<uint32_t>* optimized_binary) const;
Expand All @@ -190,6 +199,14 @@ class Optimizer {

// Same as above, except it takes an options object. See the documentation
// for |OptimizerOptions| to see which options can be set.
//
// By default, the binary is validated before any transforms are performed,
// and optionally after each transform. Validation uses SPIR-V spec rules
// for the SPIR-V version named in the binary's header (at word offset 1).
// Additionally, if the target environment is a client API (such as
// Vulkan 1.1), then validate for that client API version, to the extent
// that it is verifiable from data in the binary itself, or from the
// validator options set on the optimizer options.
bool Run(const uint32_t* original_binary, const size_t original_binary_size,
std::vector<uint32_t>* optimized_binary,
const spv_optimizer_options opt_options) const;
Expand Down

0 comments on commit 5d786f6

Please sign in to comment.