[Comgr] Explicitly describe data object mutation restrictions (llvm#746)

Since the early days of the project we have effectively left the behavior when mutating a data object ambiguous once there is a chance that it has been shared. As the user has no direct way to know when an action takes an additional reference to an object, it is implementation-defined as to when mutation will affect objects which logically belong to other data sets.

Attempt to clarify the situation by restricting mutation to newly-created data objects which have not been used as input to an action and have not been part of the output of an action.

I haven't verified that every use of the library in our codebases is correct with these restrictions, but the current implementation of AMD_COMGR_ACTION_ADD_PRECOMPILED_HEADERS effectively assumes this already, and the natural useage pattern we have intended for the library conforms.

Author: slinder1

amd/comgr/include/amd_comgr.h.in

@@ -112,7 +112,7 @@ extern "C" {
  * passed to operations must be disjoint, together with all the @p
  * amd_comgr_data_t handles that have been added to it. The exception is that
  * the default device library data object handles can be non-disjoint as they
- * are imutable.
+ * are immutable.
  *
  * The library supports generating and inspecting code objects that
  * contain machine code for a certain set of instruction set
@@ -135,6 +135,15 @@ extern "C" {
  * amd_comgr_do_action to perform an action specified by
  * @p amd_comgr_action_kind_t.
  *
+ * Data objects are reference counted and are destroyed when the
+ * reference count reaches 0. When a data object is created, its
+ * reference count is 1, it has 0 bytes of data, it has an empty name,
+ * and it has no metadata.
+ *
+ * Mutating a data object is only permitted before it is used as part of
+ * the input to an action. A data object which is the result of an action
+ * must not be mutated.
+ *
  * Some data objects can have associated metadata. There are
  * operations for querying this metadata.
  *
@@ -160,7 +169,6 @@ extern "C" {
  *   include additional Comgr-specific informational messages.
  */
 
-
 /** \defgroup symbol_versions_group Symbol Versions
  *
  * The names used for the shared library versioned symbols.
@@ -558,11 +566,6 @@ amd_comgr_get_isa_metadata(
 /**
  * @brief Create a data object that can hold data of a specified kind.
  *
- * Data objects are reference counted and are destroyed when the
- * reference count reaches 0. When a data object is created its
- * reference count is 1, it has 0 bytes of data, it has an empty name,
- * and it has no metadata.
- *
  * @param[in] kind The kind of data the object is intended to hold.
  *
  * @param[out] data A handle to the data object created. Its reference
@@ -583,12 +586,16 @@ amd_comgr_create_data(
   amd_comgr_data_kind_t kind,
   amd_comgr_data_t *data) AMD_COMGR_VERSION_1_8;
 
- /**
+/**
  * @brief Indicate that no longer using a data object handle.
  *
  * The reference count of the associated data object is
  * decremented. If it reaches 0 it is destroyed.
  *
+ * @note Although this may lead to the destruction of a data object, it is not
+ * considered a mutation for the purposes of the restrictions described in @ref
+ * codeobjectmanager.
+ *
  * @param[in] data The data object to release.
  *
  * @retval ::AMD_COMGR_STATUS_SUCCESS The function has
@@ -634,6 +641,9 @@ amd_comgr_get_data_kind(
  * associated with the data object is also replaced which invalidates
  * all metadata handles to the old metadata.
  *
+ * @warning This function mutates the data object; see @ref codeobjectmanager
+ * for restrictions.
+ *
  * @param[in] data The data object to update.
  *
  * @param[in] size The number of bytes in the data specified by @p bytes.
@@ -663,6 +673,9 @@ amd_comgr_set_data(
  * Internally this API calls amd_comgr_set_data and resets data object's
  * current state.
  *
+ * @warning This function mutates the data object; see @ref codeobjectmanager
+ * for restrictions.
+ *
  * @param[in, out] data The data object to update.
  *
  * @param[in] file_descriptor The native file descriptor for an open file.
@@ -697,6 +710,9 @@ amd_comgr_set_data_from_file_slice(
  * name. The name may also be used for other data objects in log and
  * diagnostic output.
  *
+ * @warning This function mutates the data object; see @ref codeobjectmanager
+ * for restrictions.
+ *
  * @param[in] data The data object to update.
  *
  * @param[in] name A null terminated string that specifies the name to