Add design doc for atomic<T> type.

docs/proposals/003-atomic-t.md

@@ -0,0 +1,104 @@
+SP #003 - `Atomic<T>` type
+==============
+
+
+Status
+------
+
+Author: Yong He
+
+Status: Design Discussion.
+
+Implementation: N/A
+
+Reviewed by: N/A
+
+Background
+----------
+
+HLSL defines atomic intrinsics to work on free references to ordinary values such as `int` and `float`. However, this doesn't translate well to Metal and WebGPU,
+which defines `atomic<T>` type and only allow atomic operations to be applied on values of `atomic<T>` types.
+
+Slang's Metal backend follows the same technique in SPIRV-Cross and DXIL->Metal converter that relies on a C++ undefined behavior that casts an ordinary `int*` pointer to a `atomic<int>*` pointer
+and then call atomic intrinsic on the reinterpreted pointer. This is fragile and not guaranteed to work in the future.
+
+To make the situation worse, WebGPU bans all possible ways to cast a normal pointer into an `atomic` pointer. In order to provide a truly portable way to define
+atomic operations and allow them to be translatable to all targets, we will also need an `atomic<T>` type in Slang that maps to `atomic<T>` in WGSL and Metal, and maps to
+`T` for HLSL/SPIRV.
+
+
+Proposed Approach
+-----------------
+
+We define an `Atomic<T>` type that functions as a wrapper of `T` and provides atomic operations:
+```
+interface IAtomicable {}
+extension int : IAtomicable {}
+extension uint : IAtomicable {}
+extension float : IAtomicable {}
+extension half : IAtomicable {}
+
+struct Atomic<T>
+{
+    T load();
+    [ref] void store(T newValue); // Question: do we really need this?
+    [ref] T exchange(T newValue); // returns old value
+    [ref] T compareExchange(T compareValue, T newValue); // returns old value.
+    [ref] T atomicAdd(T value); // returns original value
+    [ref] T atomicSub(T value); // returns original value
+    [ref] T atomicMax(T value); // returns original value
+    [ref] T atomicMin(T value); // returns original value
+}
+
+extension<T> Atomic<T>
+    where T : IAtomicable
+    where T : __BuiltinIntegerType
+{
+    [ref] T atomicAnd(T value); // returns original value
+    [ref] T atomicOr(T value); // returns original value
+    [ref] T atomicXor(T value); // returns original value
+}
+```
+
+We allow `Atomic<T>` to be defined anywhere: as struct fields, as array elements, as elements of `RWStructuredBuffer` types,
+or as groupshared variable types. For example, in global memory:
+
+```hlsl
+struct MyType
+{
+    int ordinaryValue;
+    Atomic<int> atomicValue;
+}
+
+RWStructuredBuffer<MyType> atomicBuffer;
+
+void main()
+{
+    atomicBuffer[0].atomicValue.atomicAdd(1);
+    printf("%d", atomicBuffer[0].atomicValue.load());
+}
+```
+
+In groupshared memory:
+
+```hlsl
+void main()
+{
+    groupshared atomic<int> c;
+    c.atomicAdd(1);
+}
+```
+
+When generating WGSL code where `atomic<T>` isn't allowed on local variables or other illegal address spaces, we will lower the type
+into its underlying type. This should be handled by a legalization pass similar to `lowerBufferElementTypeToStorageType` but operates
+in the opposite direction: the "loaded" value from a buffer is converted into an atomic-free type, and storing a value leads to an
+atomic store at the corresponding locations.
+
+For non-WGSL/Metal targets, we can simply lower the type out of existence into its underlying type.
+
+# Related Work
+
+`Atomic<T>` type exists in almost all CPU programming languages and is the proven way to express atomic operations over different
+architectures that have different memory models. WGSL and Metal follows this trend to require atomic operations being expressed
+this way. This proposal is to make Slang follow this trend and make `Atomic<T>` the recommened way to express atomic operation
+going forward.