Skip to content

Allocation of implementation-specific enum values #214

Closed
Closed
Allocation of implementation-specific enum values#214
Labels
extensibilityAdding features without breaking API changeshas resolutionIssue is resolved, just needs to be done

Description

@kainino0x
kainino0x
opened on Aug 17, 2023

This issue is no longer maintained. Please see https://webgpu-native.github.io/webgpu-headers/Extensions.html instead.

We should have a "registry" of allocated ranges to use for enums, especially WGPUSType and WGPUFeatureName
Per #212 the end of the name of the new values will be the name of the implementation.

In the webgpu.h meeting we agreed to use the top 16 bits for the implementation namespace. I think we can use this for all of the (non-bitflag) enums.

No one really cares about the actual IDs so here's an arbitrary assignment of ranges:

  • 0x0000_????: core, required to implement
    Prefix: none.

    Should be in all implementations, both native and Wasm. Used for features added to WebGPU core after this header stabilizes.

  • 0x0001_????: non-core (multi-implementation) extensions, optional to implement (though maybe they could become required in the future, or maybe we then alias them into block 0x0000_????, TBD)
    Prefix: none.

    May be native-specific or Wasm-specific, both can go in this block.

  • 0x0002_????: WebGPU Compat
    Prefix: none? TBD.

    Special: implementations that don't support compat should ignore these instead of error. This is to be used only for Compat additions that don't affect semantics of a valid program if a non-compat implementation ignores them.

  • 0x0003_????: wgpu-native
    Prefix: Wgpu? (see Naming conventions for extension structs and implementation-specific extensions #212 (comment))

  • 0x0004_????: Emscripten
    Prefix: Emscripten

  • 0x0005_????: Dawn
    Prefix: Dawn

EDIT: Per #212 (comment) (in which we switched from suffixes to prefixes), prefixes work like so:

wgpuPrefixNewFunction

WGPUPrefixNewObject
wgpuPrefixNewObjectNewMethod
wgpuOldObjectPrefixNewMethod

WGPUPrefixNewEnum
WGPUPrefixNewEnum_NewValue
WGPUOldEnum_PrefixNewValue

WGPUPrefixNewStruct

WGPUPrefixNewBitflagType
WGPUPrefixNewBitflagType_NewValue
WGPUOldBitflagType_PrefixNewValue

WGPUPrefixNewCallback

WGPU_PREFIX_NEW_CONSTANT

EDIT: For bitflags (becoming uint64_t in #273):

  • The least-significant 53 bits are reserved for core - that is, bits defined by the JS API, since it can only represent 53 bits.
  • The most-significant 11 bits are for native-only and implementation-specific bits, then overflows into the most-significant end of the least-significant 53 bits if we run out. The allocation of these bits is ad hoc for now.
    • Only bits specified in this header will be stable; implementation-specific bits can overlap or change value for now. Eventually for ABI compatibility we'll probably need a registry of these.

Activity

  1. kainino0x
    added
    has resolutionIssue is resolved, just needs to be done
    needs docsNon-trivial API contract needs to be documented. Orthogonal to open vs closed; remove when doc'd.
    extensibilityAdding features without breaking API changes
    on Aug 17, 2023
  2. rajveermalviya
    added 3 commits that reference this issue on Sep 16, 2023

    New enum values for wgpu-native specific enums.

    93386ad

    New enum values for wgpu-native specific enums.

    364d2e6

    New enum values for wgpu-native specific enums (#294)

    baaee05

  3. rajveermalviya commented on Sep 20, 2023

    @rajveermalviya
    rajveermalviya
    on Sep 20, 2023
    Collaborator

    wgpu-native now uses the 0x0003_???? namespace

  4. Kangz commented on Sep 22, 2023

    @Kangz
    Kangz
    on Sep 22, 2023
    Collaborator

    0x0001_????: (reserved)

    Shouldn't this be reserved for native-only and not upstream WebGPU (as in the JS spec) features? If we need another reserved block Dawn can move to 0x0005_???? so 0x0002_???? is free.

  5. kainino0x commented on Oct 11, 2023

    @kainino0x
    kainino0x
    on Oct 11, 2023
    CollaboratorAuthor

    Good idea. We don't really need another reserved block so I'll just change what 0x0001_???? is, above.

  6. kainino0x commented on Oct 11, 2023

    @kainino0x
    kainino0x
    on Oct 11, 2023
    CollaboratorAuthor

    We need to decide where WebGPU Compat values live (for STypes in particular). They could be in the Core block, but we might also want to give them special semantics - ignore them, rather than error, if the implementation doesn't understand them. See:
    https://dawn-review.googlesource.com/c/dawn/+/155780/comment/4e84af8f_54c41233/

  7. kainino0x commented on Oct 12, 2023

    @kainino0x
    kainino0x
    on Oct 12, 2023
    CollaboratorAuthor

    meeting: Decided tentatively to do that: make a block for Compat so the whole block can be treated specially. If either compat isn't enabled, on the implementation doesn't implement compat at all (but knows that it exists), it should ignore chained structs in this block, rather than error on them.

    This raises the question of what to do in an implementation that implements compat, if an SType is passed that's in the compat block but not recognized. This is an edge case since we don't provide ABI compatibility. But I think it should error, regardless of whether compat is enabled on the device.

    I'm going to make 0x0002 Compat, and move Dawn to 0x0005 since we haven't started using it yet.

  8. kainino0x
    pinned this issue on Jan 20, 2024

  9. kainino0x commented on Feb 15, 2024

    @kainino0x
    kainino0x
    on Feb 15, 2024
    CollaboratorAuthor

    For bitflags enums, which are becoming 64 bits, the first 10-11 extensions should be allocated (still ad hoc) in the top 11 bits that JS can't represent. (10 because might need to skip the MSB because if C enums don't like being u64.)

  10. rajveermalviya
    added
    !discussNeeds discussion (at meeting or online)
    on Mar 3, 2024

  11. kainino0x commented on Mar 16, 2024

    @kainino0x
    kainino0x
    on Mar 16, 2024
    CollaboratorAuthor

    Mar 14 meeting:

    • KN: Seems safe, don’t think we could possibly ever accidentally allocate something as native-only and then it turns out to be added to the JS API (and not a big deal if we have to dup a bit anyway)
    • (brief discussion)
    • Seems fine. Otherwise keep ad hoc allocation for now
  12. kainino0x
    removed
    !discussNeeds discussion (at meeting or online)
    on Mar 16, 2024

  13. kainino0x commented on Mar 16, 2024

    @kainino0x
    kainino0x
    on Mar 16, 2024
    CollaboratorAuthor

    Updated top post.

  14. kainino0x
    added
    !discussNeeds discussion (at meeting or online)
    on Jun 27, 2024

  15. kainino0x commented on Jun 27, 2024

    @kainino0x
    kainino0x
    on Jun 27, 2024
    CollaboratorAuthor

    Do we need a block for multi-implementation wasm-only extensions? WGPUSType_SurfaceDescriptorFromCanvasHTMLSelector could belong in that block. (Its actual behavior in Emscripten is a bit Emscripten-specific because of how it handles looking up canvases from workers, but that doesn't mean the extension has to be in the Emscripten block.)

  16. kainino0x commented on Jun 27, 2024

    @kainino0x
    kainino0x
    on Jun 27, 2024
    CollaboratorAuthor

    (Relatedly we are assuming WGPUSType_SurfaceDescriptorFromMetalLayer belongs in the "multi-implementation native-only extensions" block: https://dawn-review.googlesource.com/c/dawn/+/196174)

  17. kainino0x commented on Jul 18, 2024

    @kainino0x
    kainino0x
    on Jul 18, 2024
    CollaboratorAuthor

    Jul 18 meeting:

    • Do we need a block for multi-implementation wasm-only extensions?
    • WGPUSurfaceDescriptorFromCanvasHTMLSelector provides a string to pass to querySelector() DOM API. In Emscripten it also has some special behavior.
    • CF: wgpu-rs does not use the C API so this extension would not exist. So it is Emscripten-only for now.
    • KN: SG, we can put it in the Emscripten block.
    • Tweak the definition of block 1 - instead of "multi-implementation native", "multi-implementation C-specific".

  18. kainino0x commented on Jul 18, 2024

    @kainino0x
    kainino0x
    on Jul 18, 2024
    CollaboratorAuthor

    See also the Jul 18 notes for #212 (comment)

    I have updated the top comment on this issue for both resolutions.

  19. kainino0x
    removed
    !discussNeeds discussion (at meeting or online)
    on Jul 18, 2024

  20. kainino0x commented on Nov 9, 2024

    @kainino0x
    kainino0x
    on Nov 9, 2024
    CollaboratorAuthor

    Closing, nothing to do in this repo until we start using block 0x0001 (e.g. in #200, EDIT: and #420).

    (except for add docs, so we keep the needs docs label for that.)

  21. kainino0x
    closed this as completedon Nov 9, 2024

  22. kainino0x commented on Nov 26, 2024

    @kainino0x
    kainino0x
    on Nov 26, 2024
    CollaboratorAuthor

    Updated for #212 (comment)

  23. kainino0x commented on Dec 13, 2024

    @kainino0x
    kainino0x
    on Dec 13, 2024
    CollaboratorAuthor

    Updated description of block 0x0001 for #420 (comment)

  24. kainino0x commented on Dec 21, 2024

    @kainino0x
    kainino0x
    on Dec 21, 2024
    CollaboratorAuthor
    • 0x0001_????: non-core (multi-implementation) extensions, optional to implement (though maybe they could become required in the future, or maybe we then alias them into block 0x0000_????, TBD)

    Added this note about block 1.

  25. kainino0x
    removed
    needs docsNon-trivial API contract needs to be documented. Orthogonal to open vs closed; remove when doc'd.
    on Dec 21, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    extensibilityAdding features without breaking API changeshas resolutionIssue is resolved, just needs to be done

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions