dotnet · davidwrighton · Feb 16, 2022 · Jan 12, 2022 · Jan 12, 2022 · Jan 14, 2022
diff --git a/docs/design/specs/Ecma-335-Augments.md b/docs/design/specs/Ecma-335-Augments.md
@@ -13,6 +13,7 @@ This is a list of additions and edits to be made in ECMA-335 specifications. It
 - [Static Interface Methods](#static-interface-methods)
 - [Covariant Return Types](#covariant-return-types)
 - [Unsigned data conversion with overflow detection](#unsigned-data-conversion-with-overflow-detection)
+- [Ref field support](#ref-fields)
 
 ## Signatures
 
@@ -948,3 +949,47 @@ Conversions from floating-point numbers to integral values truncate the number t
 on the top of the stack is reinterpreted as an unsigned value before the conversion.
 Note that integer values of less than 4 bytes are extended to int32 (not native int) on the
 evaluation stack.
+
+## Ref Fields
+To improve the usefulness of ref structs, support for fields which are defined as byrefs is needed. Currently their functionality can be approximated by Span<T> fields, but not all types can be converted into Span<T> types simply. In order to support these customers support for generalizing byref fields, and converting TypedReference, ArgIterator and RuntimeArgumentHandle into following the normal rules of C# ref structs is desired. With this set of changes, it becomes possible to have ByRef fields of T, but support for pointers to ByRef fields or ByRefs to ByRefs is not added to the ECMA specification.
+
+Changes to the spec. These changes are relative to the 6th edition (June 2012) of the ECMA-335 specification published by ECMA available at:
+
+https://www.ecma-international.org/publications-and-standards/standards/ecma-335/
+
+### I.8.2.1.1 Managed pointers and related types
+- First paragraph. Replace “Managed pointer types are only allowed for local variable (§I.8.6.1.3) and parameter signatures (§I.8.6.1.4); they cannot be used for field signatures (§I.8.6.1.2), as the element type of an array (§I.8.9.1), and boxing a value of managed pointer type is disallowed (§I.8.2.4).” with “Managed pointer types are only allowed for local variable (§I.8.6.1.3), parameter signatures (§I.8.6.1.4), and instance fields of byref-like types; they cannot be used for field signatures(§I.8.6.1.2) of static fields, or of instance fields of types which are not byref-like, as the element type of an array (§I.8.9.1), and boxing a value of managed pointer type is disallowed (§I.8.2.4).”
+- Add a new paragraph before the paragraph on the three special types. “Byref-like types are value types which may contain managed pointers, or pointers onto the VES stack. Byref-like types have the same restrictions as byrefs. Value types which are marked with the System.Runtime.CompilerServices.IsByRefLikeAttribute attribute are considered to be byref-like types.”
+- Replace “Typed references have the same restrictions as byrefs.” With “Typed references are byref-like types and have the same restrictions as normal byref-like types.”
+- Replace “They can be used for local variable and parameter signatures. The use of these types for fields, method return types, the element type of an array, or in boxing is not verifiable (§I.8.8). These two types are referred to as byref-like types.” With “If a function uses these types only for local variable and parameter signatures, then the use of those types is verifiable. Otherwise these types have the same restrictions as normal byref-like types.”
+### I.8.6.1
+- Remove “(A fifth kind, a local signature (see §I.8.6.1.3) is really a version of a location signature.)”
+
+### I.8.6.1.2
+- Move the contents of the byref constraint paragraph from Section I.8.6.1.3 to a bullet point.
+“- The byref constraint states that the content of the corresponding location is a managed pointer. A managed pointer can point to a local variable, parameter, field of a compound type, or element of an array. However, when a call crosses a remoting boundary (see §I.12.5) a conforming implementation can use a copy-in/copy-out mechanism instead of a managed pointer. Thus programs shall not rely on the aliasing behavior of true pointers. A managed pointer cannot point to another managed pointer, but a managed pointer can point to a byref-like type.”
+
+### I.8.6.1.3
+- Rename this section to ByRef-like and Typed Reference Signatures
+- Remove the first two paragraphs.
+- Remove “In addition, there is one special local signature.”
+- Remove “A typed reference is a full signature in itself and cannot be combined with other constraints. In particular, it is not possible to specify a byref whose type is typed reference.”
+- Replace “This type shall only be used for parameters and local variables. It shall not be boxed, nor shall it be used as the type of a field, element of an array, or return value.” With “A typed reference is considered to be a by-reflike structure”
+- Remove “A typed reference is a full signature in itself and cannot be combined with other constraints. In particular, it is not possible to specify a byref whose type is typed reference.” From the third paragraph
+
+### I.8.7
+- Remove “, local (§I.8.6.1.3)”
+- In the section about type compatibility when determining a type from a signature: The byref constraint is to be referenced from section I8.6.1.2 insetad of I.8.6.1.3
+
+### I.8.9.2
+- Insert at the end of the first paragraph “An unmanaged pointer type cannot point to a managed pointer.”
+
+Changes to signatures:
+### II.23.2.10
+- Remove special case for TYPEDBYREF
+
+### II.23.2.11
+- Remove special case for TYPEDBYREF
+
+### II.23.2.12
+- Add TYPEDBYREF as a form of Type