Add experimental _Volatile module providing low-level primitives for MMIO

[kubamracek]

See the full pitch at https://forums.swift.org/t/pitch-low-level-operations-for-volatile-memory-accesses/69483. Summary:

This proposal:

• adds APIs for the most basic load + store volatile operations, on 8, 16, 32 and 64 bit integers,
  assumes the actual volatile semantics are defined by Clang and LLVM, which match the commonly understood behavior (no removal or reordering by the compiler), see the definition at https://llvm.org/docs/LangRef.html#volatile-memory-accesses,
• packages the new APIs into a separate module which must be explicitly imported by the user (import Volatile) -- this is intended to prevent accidental usage of volatile operations in e.g. userspace code for inter-thread synchronization (a common misuse of volatile in C).

This proposal:

• doesn't try to provide any safety or structured access to these operations, as that is left for libraries built on top of the low-level APIs,
• doesn't try to make it possible to mark struct members or variables as "volatile" (like C allows), instead only a pointer to storage can be volatile and a load/store using an eligible pointer can be volatile -- this sidesteps many design issues around volatile that C has,
• doesn't try to provide an abstraction over making more types volatile (e.g. how the AtomicValue and AtomicRepresentation protocols in swift-atomics provide an abstraction for making custom types atomic) -- the reasoning is that unlike atomics, volatile operations are only intended for MMIO HW register access and similar usage, which is only meaningful on machine level integer types and allowing custom types to become volatile would encourage misuse for inter-thread synchronization.

Added APIs in a new "Volatile" module (underscored name, _Volatile, for now):

struct UnsafeVolatilePointer<Pointee> {
  init(bitPattern: UInt)
}

extension UnsafeVolatilePointer<UInt8> { // also 16, 32, 64
  func load() -> UInt8 // with LLVM volatile load semantics, assume natural alignment
  func store(_ value: UInt8) // with LLVM volatile store semantics, assume natural alignment
}

extension UnsafeMutablePointer<UInt8> { // also 16, 32, 64
  func volatileLoad() -> UInt8 // with LLVM volatile load semantics, assume natural alignment
  func volatileStore(_ value: UInt8) // with LLVM volatile store semantics, assume natural alignment
}

[rauhul]

great start, we will obviously update this to match wherever the pitch ends up

[kubamracek]

@swift-ci please test

[phausler]

what happens when someone passes 0? this will assert - are there ever memory mapped registers at 0x0?

Should this not use self.init(Builtin.inttoptr_Word(bitPattern._builtinWordValue))?

[kubamracek]

I think this should now handle 0 correctly.

[phausler]

I would say drop these extensions

[kubamracek]

dropped

[phausler]

To land this we should definitely do the following

1. gate it by a flag
2. After consideration this should not conform to _Pointer
3. permit this for all build types not just embedded - I could see the use for more than just embedded.
4. the initializer should mention unsafe in it since that is the only spot that truly is unsafe; the type and the load/store are perfectly safe to hold
5. it should probably be named VolatileRegister or something like that (or VolatileMappedRegister) to avoid confusion about general volatile things that are NOT register bound
6. after validating this is the design we want we should then move it from a module down into the stdlib asap

[phausler]

it might be good to add functional tests to verify the initialization of values etc (and maybe even a test store/load on a heap region initialized unsafely)

The rest of the changes other than the tests and restriction to embedded seem on point.

[phausler]

we should allow this in non-embedded no?

[kubamracek]

yes -- it's allowed in the current implementation in this PR

[phausler]

what if I want to try out volatile thingies in regular desktop swift?

[kubamracek]

See the small block above, that's defining and building Volatile for regular platforms.

[kubamracek]

it might be good to add functional tests to verify the initialization of values etc (and maybe even a test store/load on a heap region initialized unsafely)

Added! Any more ideas what to try to cover? (The tests btw show that the Volatile module is available outside of embedded.)

[kubamracek]

@swift-ci please test

[kubamracek]

@swift-ci please test