Merge 0b2811ef9a into 02596ba8d9

docs/design/datacontracts/contract-descriptor.md

@@ -86,13 +86,17 @@ a JSON integer constant.
     "s_pThreadStore": [ 0 ], // indirect from pointer data offset 0
     "RuntimeID": "win-x64" // string value
   },
+  "sub-descriptors":
+  {
+    "GCDescriptor": [ 1 ]
+  },
   "contracts": {"Thread": 1, "GCHandle": 1, "ThreadStore": 1}
 }
 ```
 
 ## Contract symbol
 
-To aid in discovery, the contract descriptor should be exported by the module hosting the .NET
+To aid in discovery, the main contract descriptor should be exported by the module hosting the .NET
 runtime with the name `DotNetRuntimeContractDescriptor` using the C symbol naming conventions of the
 target platform.
 

docs/design/datacontracts/data_descriptor.md

@@ -31,6 +31,7 @@ endianness.  The types `nint`, `nuint` and `pointer` have target architecture po
 The data descriptor consists of:
 * a collection of type structure descriptors
 * a collection of global value descriptors
+* an optional collection of pointers to sub-contracts
 
 ## Types
 
@@ -92,6 +93,15 @@ The value must be an integral constant within the range of its type.  Signed val
 natural encoding.  Pointer values need not be aligned and need not point to addressable target
 memory.
 
+## Sub-descriptor descriptors
+
+Each sub-descriptor descriptor is effectively a global with a type of `pointer`. They will consist of:
+* a name
+* a pointer value
+
+If these values are non-null, the pointer represents another JSON data descriptor with the specification described in this document.
+
+When parsing a data descriptor with sub-descriptors each sub-descriptor should be parsed then its type, global, and contract values should be merged in. If any conflicts arise when merging in sub-descriptor data, this is an error and behavior is undefined.
 
 ## Physical descriptors
 
@@ -129,6 +139,7 @@ The toplevel dictionary will contain:
 * optional `"baseline": "BASELINE_ID"` see below
 * `"types": TYPES_DESCRIPTOR` see below
 * `"globals": GLOBALS_DESCRIPTOR` see below
+* optional `"sub-descriptors": SUB_DESCRIPTORS_DESCRIPTOR` see below
 
 Additional toplevel keys may be present. For example, the in-memory data descriptor will contain a
 `"contracts"` key (see [contract descriptor](./contract_descriptor.md#Compatible_contracts)) for the
@@ -233,7 +244,9 @@ Note that a two element array is unambiguously "type and value", whereas a one-e
 unambiguously "indirect value".
 
 
-**Both formats**
+### Sub-descriptor Values
+
+Sub-descriptor values will be an additional array, with the same specification as [global values](#Global-values) with the exception that the only valid value type is a `pointer`.
 
 #### Specification Appendix
 
@@ -284,7 +297,7 @@ string.  For pointers, the address can be stored at a known offset in an in-proc
 array of pointers and the offset written into the constant JSON string.
 
 The indirection array is not part of the data descriptor spec.  It is part of the [contract
-descriptor](./contract_descriptor.md#Contract_descriptor).
+descriptor](./contract-descriptor.md#Contract_descriptor).
 
 
 ## Example
@@ -345,6 +358,10 @@ The following is an example of an in-memory descriptor that references the above
     "FEATURE_COMINTEROP": 0,
     "s_pThreadStore": [ 0 ], // indirect from aux data offset 0
     "RuntimeID": "windows-x64"
+  },
+  "sub-descriptors": 
+  {
+    "GCDescriptor": [ 1 ] // indirect from aux data offset 1
   }
 }
 ```

docs/design/datacontracts/datacontracts_design.md

@@ -26,7 +26,7 @@ More details are provided in the [data descriptor spec](./data_descriptor.md).
 
 #### Global Values
 
-Global values which can be either primitive integer constants or pointers.
+Global values which can be either primitive integer constants, pointers, or strings.
 All global values have a string describing their name, a type, and a value of one of the above types.
 
 #### Data Structure Layout
@@ -41,6 +41,10 @@ The determinate size of a structure may be larger than the sum of the sizes of t
 in the data descriptor (that is, the data descriptor does not include every field and may not
 include padding bytes).
 
+#### (Optional) Sub-descriptor pointers
+
+Sub-descriptors are special global values which contain a pointer to another data descriptor. These are used when data definitions are not known by the runtime at compile time but may be known by an external component. In that case the data descriptor defers to the external component to describe its data.
+
 ### Compatible Contract
 
 Each compatible contract is described by a string naming the contract, and a uint32 version. It is an ERROR if multiple versions of a contract are specified in the contract descriptor.