summaryrefslogtreecommitdiff
path: root/utils/ipc/mojo/public/tools/bindings/README.md
diff options
context:
space:
mode:
authorPaul Elder <paul.elder@ideasonboard.com>2020-09-08 20:47:19 +0900
committerPaul Elder <paul.elder@ideasonboard.com>2021-05-26 13:03:27 +0900
commit139d8855747799da9218f36720004fb1927bd2ef (patch)
tree7f3f47e68e08cfcf19ee9f37cc91f31690b9fc53 /utils/ipc/mojo/public/tools/bindings/README.md
parenta7ded8e8f5dd0ae0841960280fe9a7107f945a34 (diff)
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>
Diffstat (limited to 'utils/ipc/mojo/public/tools/bindings/README.md')
-rw-r--r--utils/ipc/mojo/public/tools/bindings/README.md187
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: