class StreamProcessorParticipateInBufferAllocationRequest

Returns whether no field is set.

Which port (input or output) the buffer(s) are for.

Must be set.

Which port (input or output) the buffer(s) are for.

Must be set.

For input, this field must be set to 1, at least for now.

For output, this field must set to the latest known (to the client)

buffer_constraints_version_ordinal value from the server. If the

value is less than the latest buffer_constraints_version_ordinal

created by the server which had action_reqiured true, then the

server will set generic sysmem constraints (just min_buffer_count 1)

and otherwise ignore this message. This is intended to allow

allocation to succeed (to allow simpler client error handling for

some clients); in this case a new buffer_constraints_version_ordinal

will reach the client and the client can catch up to the latest.

If this value is a future value, the server will drop the

sysmem2_token which will cause allocation failure.

Must be set.

For input, this field must be set to 1, at least for now.

For output, this field must set to the latest known (to the client)

buffer_constraints_version_ordinal value from the server. If the

value is less than the latest buffer_constraints_version_ordinal

created by the server which had action_reqiured true, then the

server will set generic sysmem constraints (just min_buffer_count 1)

and otherwise ignore this message. This is intended to allow

allocation to succeed (to allow simpler client error handling for

some clients); in this case a new buffer_constraints_version_ordinal

will reach the client and the client can catch up to the latest.

If this value is a future value, the server will drop the

sysmem2_token which will cause allocation failure.

Must be set.

This sysmem token is used by the server to inform sysmem directly of

any applicable buffer constraints. These constraints are allowed to

(and in some cases must) depend on how this StreamProcessor instance

was created. For example, secure_input_mode/secure_output_mode

during StreamProcessor creation causes the server to set

secure_required for input/output respectively (as specified by

Port.INPUT or Port.OUTPUT respectively).

Must be set.

If set, and there's been at least one AddBuffer previously sent with

this buffer_lifetime_ordinal on the same StreamProcessor instance

which hasn't yet been removed server-side, the new buffer(s) will be

allocated with identical SingleBufferSettings, or fail allocation.

If any of the conditions in this paragraph aren't met, the effect is

the same as if this field is not set.

If this field is not set, the sysmem constraints set by the server

will be suitable for a buffer of a new buffer_lifetime_ordinal, and

the new buffer's SingleBufferSettings might not match any previous

buffer's SingleBufferSettings.

If the server has a current stream and `port` indicates the output

port, the constraints set will allow the stream to be correctly

processed across the switch to new buffer_lifetime_ordinal (assuming

the client is using a new buffer_lifetime_ordinal and adds the new

buffer(s) subsequently etc). If port indicates the input port, the

constraints set will be generic for the input port regardless of any

current stream.

If this mechanism isn't used, the client must still ensure that all

AddBuffer with a given StreamProcessor instance, port, and

buffer_lifetime_ordinal have identical SingleBufferSettings. One way

to do this is to allocate all the buffers of a

buffer_lifetime_ordinal under a single sysmem buffer collection.

Another way is for the client to tell sysmem directly that a new

buffer collection must match the SingleBufferSettings of a prior

collection using

`[fuchsia.sysmem2/BufferCollectionConstraints.must_match_vmo]`

client-side.

It's not recommended for a client to attempt to force a new

collecton's SingleBufferSettings to match an old collection's

SingleBufferSettings without sysmem's help and without

StreamProcessor's help via this field, because sysmem intentionally

allows clients participating in the same collection to be using

different versions of the sysmem interfaces, so the client may not

have enough information to successfully force the

SingleBufferSettings to match without using `must_match_vmo`, for

example if the client is unaware of a new SingleBufferSettings field

(or similar). The most common StreamProcessor server implementation

(CodecImpl) will handle this field using `must_match_vmo` on behalf

of the client as long as there's still at least one buffer of the

buffer_lifetime_ordinal active in the server. The ability to

dynamically add more buffers to an existing sysmem collection may be

added to sysmem at some point; that would give the client another

way to ensure identical SingleBufferSettings within a

buffer_lifetime_ordinal, but only if/when all sysmem collection

participants indicate support for a dynamic sysmem buffer

collection.

For output, setting this field is strongly recommended if a client

is adding additional output buffers to an existing

buffer_lifetime_ordinal using a new/different sysmem buffer

collection, and setting this field is recommended for all output

buffer allocations.

For input, if a client is using the same StreamProcessor instance

for this message and AddBuffer (which is itself recommended when

feasible), use of this field is recommended for those input buffers.

If set, this value must match the buffer_lifetime_ordinal later sent

in AddBuffer.

Clients should set this when feasible; see above.

If set, and there's been at least one AddBuffer previously sent with

this buffer_lifetime_ordinal on the same StreamProcessor instance

which hasn't yet been removed server-side, the new buffer(s) will be

allocated with identical SingleBufferSettings, or fail allocation.

If any of the conditions in this paragraph aren't met, the effect is

the same as if this field is not set.

If this field is not set, the sysmem constraints set by the server

will be suitable for a buffer of a new buffer_lifetime_ordinal, and

the new buffer's SingleBufferSettings might not match any previous

buffer's SingleBufferSettings.

If the server has a current stream and `port` indicates the output

port, the constraints set will allow the stream to be correctly

processed across the switch to new buffer_lifetime_ordinal (assuming

the client is using a new buffer_lifetime_ordinal and adds the new

buffer(s) subsequently etc). If port indicates the input port, the

constraints set will be generic for the input port regardless of any

current stream.

If this mechanism isn't used, the client must still ensure that all

AddBuffer with a given StreamProcessor instance, port, and

buffer_lifetime_ordinal have identical SingleBufferSettings. One way

to do this is to allocate all the buffers of a

buffer_lifetime_ordinal under a single sysmem buffer collection.

Another way is for the client to tell sysmem directly that a new

buffer collection must match the SingleBufferSettings of a prior

collection using

`[fuchsia.sysmem2/BufferCollectionConstraints.must_match_vmo]`

client-side.

It's not recommended for a client to attempt to force a new

collecton's SingleBufferSettings to match an old collection's

SingleBufferSettings without sysmem's help and without

StreamProcessor's help via this field, because sysmem intentionally

allows clients participating in the same collection to be using

different versions of the sysmem interfaces, so the client may not

have enough information to successfully force the

SingleBufferSettings to match without using `must_match_vmo`, for

example if the client is unaware of a new SingleBufferSettings field

(or similar). The most common StreamProcessor server implementation

(CodecImpl) will handle this field using `must_match_vmo` on behalf

of the client as long as there's still at least one buffer of the

buffer_lifetime_ordinal active in the server. The ability to

dynamically add more buffers to an existing sysmem collection may be

added to sysmem at some point; that would give the client another

way to ensure identical SingleBufferSettings within a

buffer_lifetime_ordinal, but only if/when all sysmem collection

participants indicate support for a dynamic sysmem buffer

collection.

For output, setting this field is strongly recommended if a client

is adding additional output buffers to an existing

buffer_lifetime_ordinal using a new/different sysmem buffer

collection, and setting this field is recommended for all output

buffer allocations.

For input, if a client is using the same StreamProcessor instance

for this message and AddBuffer (which is itself recommended when

feasible), use of this field is recommended for those input buffers.

If set, this value must match the buffer_lifetime_ordinal later sent

in AddBuffer.

Clients should set this when feasible; see above.

If set to true, the server will leave all `buffer_count_*` fields

un-set when sending SetConstraints to sysmem, and will set

`min_buffer_count` to 1.

If un-set or set to false, the server will fill out buffer count

fields when sending SetConstraints to sysmem based on the current

value of `buffer_count_for_server_current`, without any extra slack.

The client can add slack as desired via its own retained token.

Regardless of whether this field is set to true, it's up to the

client to `AddBuffer` at least `buffer_count_for_server_current`

buffers so that processing can make progress.

If set to true, the server will leave all `buffer_count_*` fields

un-set when sending SetConstraints to sysmem, and will set

`min_buffer_count` to 1.

If un-set or set to false, the server will fill out buffer count

fields when sending SetConstraints to sysmem based on the current

value of `buffer_count_for_server_current`, without any extra slack.

The client can add slack as desired via its own retained token.

Regardless of whether this field is set to true, it's up to the

client to `AddBuffer` at least `buffer_count_for_server_current`

buffers so that processing can make progress.

This sysmem token is used by the server to inform sysmem directly of

any applicable buffer constraints. These constraints are allowed to

(and in some cases must) depend on how this StreamProcessor instance

was created. For example, secure_input_mode/secure_output_mode

during StreamProcessor creation causes the server to set

secure_required for input/output respectively (as specified by

Port.INPUT or Port.OUTPUT respectively).

Must be set.