| RFC-0014: Relax zx_fifo_create constraints ||
|---|---|
| Status | Accepted |
| Areas | - Kernel |
| Description | Permit \`zx_fifo_create\` calls with element counts that are not powers of two. |
| Issues | - [65697](https://fxbug.dev/65697) |
| Gerrit change | - [457334](https://fuchsia-review.googlesource.com/c/fuchsia/+/457334) |
| Authors | - [jfsulliv@google.com](https://fuchsia-review.googlesource.com/q/owner:jfsulliv@google.com) |
| Reviewers | - [kulakowski@google.com](https://fuchsia-review.googlesource.com/q/owner:kulakowski@google.com) - [jamesr@google.com](https://fuchsia-review.googlesource.com/q/owner:jamesr@google.com) - [cpu@google.com](https://fuchsia-review.googlesource.com/q/owner:cpu@google.com) - [maniscalco@google.com](https://fuchsia-review.googlesource.com/q/owner:maniscalco@google.com) - [johngro@google.com](https://fuchsia-review.googlesource.com/q/owner:johngro@google.com) - [abarth@google.com](https://fuchsia-review.googlesource.com/q/owner:abarth@google.com) |
| Date submitted (year-month-day) | 2020-12-02 |
| Date reviewed (year-month-day) | 2020-12-09 |

[Edit this RFC](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/governance/rfcs/0014_relax_fifo_create_constraints.md)
[Edit RFC metadata](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/governance/rfcs/_rfcs.yaml&searchAndJump=-+name:+'RFC-0014')

## Summary

`zx_fifo_create` currently requires the caller to pass an element count that is a power of two.
This allows the kernel to make a small optimization on the read and write paths by using a
bit-mask instead of the modulus operator to determine the offset of a wrapped record in a buffer.

This constraint means that users cannot effectively use the FIFO to its full capacity if their
element sizes do not happen to be `4096/(2**n)` bytes; in these cases the FIFO capacity
(`element_size * element_count`) will be less than possible full capacity of the FIFO (which
internally uses a `4096`-byte buffer).

The proposal is to allow FIFOs to be created with arbitrary element counts (up to the FIFO size
limit) so the full FIFO capacity can be used for FIFO records of arbitrary sizes.

## Motivation

This proposal is motivated by the desire to add a field to an existing FIFO record used in the
block stack; the field in question is a trace identifier, which will be used to support
cross-process tracing of block IO. Adding this field changes the size of the FIFO records from
`32` bytes to `40` bytes.

If FIFO records are `40` bytes long, then the maximum value that `element_count` could currently
be set to is `64`, which results in `40 * 64 = 2560` bytes used in the `4096`-byte buffer.

This RFC would permit an `element_count` value of `102`, which results in `40 * 102 = 4080` bytes
used (almost doubling the usable capacity of the FIFO).

## Design

This is a trivial change that is implemented in
<https://fuchsia-review.googlesource.com/c/fuchsia/+/409498>.

## Implementation

This is a trivial change that is implemented in
<https://fuchsia-review.googlesource.com/c/fuchsia/+/409498>.

## Performance

The kernel can currently make a small performance optimization since it knows the element count
is a power of two; particularly, the kernel can use a bitwise-AND to determine the position of an
element in the internal buffer, instead of a modulo.

That said, this performance optimization washes out given the expense of jumping back and forth
between the kernel and userspace.

Concretely: performance testing in <https://fuchsia-review.googlesource.com/c/fuchsia/+/409498>
indicates that there are no measurable performance costs for eliminating this optimization.

## Security considerations

None.

## Privacy considerations

None.

## Testing

This is a trivial change for which tests are added in
<https://fuchsia-review.googlesource.com/c/fuchsia/+/409498>.

## Documentation

The `zx_fifo_create` documentation is adjusted in
https://fuchsia-review.googlesource.com/c/fuchsia/+/409498 based on the new relaxed constraints.

## Drawbacks, alternatives, and unknowns

None.

## Prior art and references

None.
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/contribute/governance/rfcs/0014_relax_fifo_create_constraints.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/contribute/governance/rfcs/0014_relax_fifo_create_constraints.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/governance/rfcs/0014_relax_fifo_create_constraints.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/contribute/governance/rfcs/0014_relax_fifo_create_constraints.md "Edit the source code of this page")