utils: ipc: Update mojo

Update mojo from the Chromium repository. The commit from which this was
taken is:

9c138d992bfc1fb8f4f7bcf58d00bf19c219e4e2 "Updating trunk VERSION from
4523.0 to 4524.0"

The update-mojo.sh script was used for this update.

Bug: https://bugs.libcamera.org/show_bug.cgi?id=34
Signed-off-by: Paul Elder <paul.elder@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

1 files changed, 126 insertions, 61 deletions

diff --git a/utils/ipc/mojo/public/tools/bindings/README.md b/utils/ipc/mojo/public/tools/bindings/README.md
index 1a3d5c58..43882450 100644
--- a/utils/ipc/mojo/public/tools/bindings/README.md
+++ b/utils/ipc/mojo/public/tools/bindings/README.md
@@ -113,8 +113,8 @@ for message parameters.
 
 Every Mojom file may optionally specify a single **module** to which it belongs.
 
-This is used strictly for aggregaging all defined symbols therein within a
-common Mojom namespace. The specific impact this has on generated binidngs code
+This is used strictly for aggregating all defined symbols therein within a
+common Mojom namespace. The specific impact this has on generated bindings code
 varies for each target language. For example, if the following Mojom is used to
 generate bindings:
 
@@ -132,7 +132,7 @@ Generated C++ bindings will define a class interface `MoneyGenerator` in the
 bindings at this time are unaffected by module declarations.
 
 **NOTE:** By convention in the Chromium codebase, **all** Mojom files should
-declare a module name with at least (and preferrably exactly) one top-level name
+declare a module name with at least (and preferably exactly) one top-level name
 as well as an inner `mojom` module suffix. *e.g.*, `chrome.mojom`,
 `business.mojom`, *etc.*
 
@@ -271,7 +271,7 @@ code, see
 ### Unions
 
 Mojom supports tagged unions using the **union** keyword. A union is a
-collection of fields which may taken the value of any single one of those fields
+collection of fields which may take the value of any single one of those fields
 at a time. Thus they provide a way to represent a variant value type while
 minimizing storage requirements.
 
@@ -320,7 +320,7 @@ enum definition. By default, values are based at zero and increment by
 1 sequentially.
 
 The effect of nested definitions on generated bindings varies depending on the
-target language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages)
+target language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages).
 
 ### Constants
 
@@ -346,7 +346,7 @@ struct Employee {
 ```
 
 The effect of nested definitions on generated bindings varies depending on the
-target language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages)
+target language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages).
 
 ### Interfaces
 
@@ -379,58 +379,82 @@ Mojom definitions may have their meaning altered by **attributes**, specified
 with a syntax similar to Java or C# attributes. There are a handle of
 interesting attributes supported today.
 
-**`[Sync]`**
-:   The `Sync` attribute may be specified for any interface method which expects
-    a response. This makes it so that callers of the method can wait
-    synchronously for a response. See
-    [Synchronous Calls](/mojo/public/cpp/bindings/README.md#Synchronous-Calls)
-    in the C++ bindings documentation. Note that sync methods are only actually
-    synchronous when called from C++.
-
-**`[Extensible]`**
-:   The `Extensible` attribute may be specified for any enum definition. This
-    essentially disables builtin range validation when receiving values of the
-    enum type in a message, allowing older bindings to tolerate unrecognized
-    values from newer versions of the enum.
-
-**`[Native]`**
-:   The `Native` attribute may be specified for an empty struct declaration to
-    provide a nominal bridge between Mojo IPC and legacy `IPC::ParamTraits` or
-    `IPC_STRUCT_TRAITS*` macros.
-    See
-    [Repurposing Legacy IPC Traits](/docs/mojo_ipc_conversion.md#repurposing-and-invocations)
-    for more details. Note support for this attribute is strictly limited to C++
-    bindings generation.
-
-**`[MinVersion=N]`**
-:   The `MinVersion` attribute is used to specify the version at which a given
-    field, enum value, interface method, or method parameter was introduced.
-    See [Versioning](#Versioning) for more details.
-
-**`[Stable]`**
-:   The `Stable` attribute specifies that a given mojom type or interface
-    definition can be considered stable over time, meaning it is safe to use for
-    things like persistent storage or communication between independent
-    version-skewed binaries. Stable definitions may only depend on builtin mojom
-    types or other stable definitions, and changes to such definitions MUST
-    preserve backward-compatibility through appropriate use of versioning.
-    Backward-compatibility of changes is enforced in the Chromium tree using a
-    strict presubmit check. See [Versioning](#Versioning) for more details on
-    backward-compatibility constraints.
-
-**`[EnableIf=value]`**
-:   The `EnableIf` attribute is used to conditionally enable definitions when
-    the mojom is parsed. If the `mojom` target in the GN file does not include
-    the matching `value` in the list of `enabled_features`, the definition
-    will be disabled. This is useful for mojom definitions that only make
-    sense on one platform. Note that the `EnableIf` attribute can only be set
-    once per definition.
+* **`[Sync]`**:
+  The `Sync` attribute may be specified for any interface method which expects a
+  response. This makes it so that callers of the method can wait synchronously
+  for a response. See [Synchronous
+  Calls](/mojo/public/cpp/bindings/README.md#Synchronous-Calls) in the C++
+  bindings documentation. Note that sync methods are only actually synchronous
+  when called from C++.
+
+* **`[NoInterrupt]`**:
+  When a thread is waiting for a reply to a `Sync` message, it's possible to be
+  woken up to dispatch other unrelated incoming `Sync` messages. This measure
+  helps to avoid deadlocks. If a `Sync` message is also marked as `NoInterrupt`
+  however, this behavior is disabled: instead the calling thread will only wake
+  up for the precise message being waited upon. This attribute must be used with
+  extreme caution, because it can lead to deadlocks otherwise.
+
+* **`[Default]`**:
+  The `Default` attribute may be used to specify an enumerator value that
+  will be used if an `Extensible` enumeration does not deserialize to a known
+  value on the receiver side, i.e. the sender is using a newer version of the
+  enum. This allows unknown values to be mapped to a well-defined value that can
+  be appropriately handled.
+
+* **`[Extensible]`**:
+  The `Extensible` attribute may be specified for any enum definition. This
+  essentially disables builtin range validation when receiving values of the
+  enum type in a message, allowing older bindings to tolerate unrecognized
+  values from newer versions of the enum.
+
+  Note: in the future, an `Extensible` enumeration will require that a `Default`
+  enumerator value also be specified.
+
+* **`[Native]`**:
+  The `Native` attribute may be specified for an empty struct declaration to
+  provide a nominal bridge between Mojo IPC and legacy `IPC::ParamTraits` or
+  `IPC_STRUCT_TRAITS*` macros. See [Repurposing Legacy IPC
+  Traits](/docs/mojo_ipc_conversion.md#repurposing-and-invocations) for more
+  details. Note support for this attribute is strictly limited to C++ bindings
+  generation.
+
+* **`[MinVersion=N]`**:
+  The `MinVersion` attribute is used to specify the version at which a given
+  field, enum value, interface method, or method parameter was introduced.
+  See [Versioning](#Versioning) for more details.
+
+* **`[Stable]`**:
+  The `Stable` attribute specifies that a given mojom type or interface
+  definition can be considered stable over time, meaning it is safe to use for
+  things like persistent storage or communication between independent
+  version-skewed binaries. Stable definitions may only depend on builtin mojom
+  types or other stable definitions, and changes to such definitions MUST
+  preserve backward-compatibility through appropriate use of versioning.
+  Backward-compatibility of changes is enforced in the Chromium tree using a
+  strict presubmit check. See [Versioning](#Versioning) for more details on
+  backward-compatibility constraints.
+
+* **`[Uuid=<UUID>]`**:
+  Specifies a UUID to be associated with a given interface. The UUID is intended
+  to remain stable across all changes to the interface definition, including
+  name changes. The value given for this attribute should be a standard UUID
+  string representation as specified by RFC 4122. New UUIDs can be generated
+  with common tools such as `uuidgen`.
+
+* **`[EnableIf=value]`**:
+  The `EnableIf` attribute is used to conditionally enable definitions when the
+  mojom is parsed. If the `mojom` target in the GN file does not include the
+  matching `value` in the list of `enabled_features`, the definition will be
+  disabled. This is useful for mojom definitions that only make sense on one
+  platform. Note that the `EnableIf` attribute can only be set once per
+  definition.
 
 ## Generated Code For Target Languages
 
 When the bindings generator successfully processes an input Mojom file, it emits
 corresponding code for each supported target language. For more details on how
-Mojom concepts translate to a given target langauge, please refer to the
+Mojom concepts translate to a given target language, please refer to the
 bindings API documentation for that language:
 
 * [C++ Bindings](/mojo/public/cpp/bindings/README.md)
@@ -441,7 +465,7 @@ bindings API documentation for that language:
 
 Regardless of target language, all interface messages are validated during
 deserialization before they are dispatched to a receiving implementation of the
-interface. This helps to ensure consitent validation across interfaces without
+interface. This helps to ensure consistent validation across interfaces without
 leaving the burden to developers and security reviewers every time a new message
 is added.
 
@@ -555,25 +579,37 @@ struct Employee {
 };
 ```
 
-and you would like to add a birthday field. You can do:
+and you would like to add birthday and nickname fields. You can add them as
+optional types with a `MinVersion` like so:
 
 ``` cpp
 struct Employee {
   uint64 employee_id;
   string name;
   [MinVersion=1] Date? birthday;
+  [MinVersion=1] string? nickname;
 };
 ```
 
+*** note
+**NOTE:** Mojo object or handle types added with a `MinVersion` **MUST** be
+optional (nullable). See [Primitive Types](#Primitive-Types) for details on
+nullable values.
+***
+
 By default, fields belong to version 0. New fields must be appended to the
 struct definition (*i.e*., existing fields must not change **ordinal value**)
 with the `MinVersion` attribute set to a number greater than any previous
 existing versions.
 
+The value of `MinVersion` is unrelated to ordinals. The choice of a particular
+version number is arbitrary. All its usage means is that a field isn't present
+before the numbered version.
+
 *** note
 **NOTE:** do not change existing fields in versioned structs, as this is
 not backwards-compatible. Instead, rename the old field to make its
-deprecation clear and add a new field with the new version number.
+deprecation clear and add a new field with a new `MinVersion` number.
 ***
 
 **Ordinal value** refers to the relative positional layout of a struct's fields
@@ -602,14 +638,10 @@ struct Employee {
   uint64 employee_id@0;
   [MinVersion=1] Date? birthday@2;
   string name@1;
+  [MinVersion=1] string? nickname@3;
 };
 ```
 
-*** note
-**NOTE:** Newly added fields of Mojo object or handle types MUST be nullable.
-See [Primitive Types](#Primitive-Types).
-***
-
 ### Versioned Interfaces
 
 There are two dimensions on which an interface can be extended
@@ -706,6 +738,39 @@ values and will need to deal with them gracefully. See
 [C++ Versioning Considerations](/mojo/public/cpp/bindings/README.md#Versioning-Considerations)
 for details.
 
+### Renaming versioned structs
+It's possible to rename versioned structs by using the `[RenamedFrom]` attribute.
+RenamedFrom
+
+``` cpp
+module asdf.mojom;
+
+// Old version:
+[Stable]
+struct OldStruct {
+};
+
+// New version:
+[Stable, RenamedFrom="asdf.mojom.OldStruct"]
+struct NewStruct {
+};
+```
+
+## Component targets
+
+If there are multiple components depending on the same mojom target within one binary,
+the target will need to be defined as `mojom_component` instead of `mojom`.
+Since `mojom` targets are generated `source_set` targets and `mojom_component` targets
+are generated `component` targets, you would use `mojom_component` in the same cases
+where you would use `component` for non-mojom files.
+*** note
+**NOTE**: by default, components for both blink and non-blink bindings are generated.
+Use the `disable_variants` target parameter to generate only non-blink bindings.
+You can also generate a `source_set` for one of the variants by defining
+[export_*](https://source.chromium.org/chromium/chromium/src/+/main:mojo/public/tools/bindings/mojom.gni;drc=739b9fbce50310c1dd2b59c279cd90a9319cb6e8;l=318)
+parameters for the `mojom_component` target.
+***
+
 ## Grammar Reference
 
 Below is the (BNF-ish) context-free grammar of the Mojom language: