| // Copyright 2020 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| library fuchsia.sysmem2; |
| |
| const MAX_COUNT_BUFFER_COLLECTION_CONSTRAINTS_IMAGE_FORMAT_CONSTRAINTS uint32 = 64; |
| const MAX_COUNT_BUFFER_MEMORY_CONSTRAINTS_HEAP_PERMITTED uint32 = 64; |
| const MAX_COUNT_IMAGE_FORMAT_CONSTRAINTS_COLOR_SPACES uint32 = 32; |
| |
| // The contents of this file are not final. Incompatible changes are still |
| // being made to this file. Do not rely on the contents of this file to provide |
| // backward compatibility (yet). |
| // |
| // TODO(fxbug.dev/34192): Sysmem should use llcpp and FIDL tables. The |
| // fuchsia.sysmem2.BufferCollectionConstraints defined here are part of that |
| // transition, but the definitions here are not final. For now, the definition |
| // here is only used internally to sysmem (not between processes), and therefore |
| // this definition can change for now. Later after we're happy with this |
| // representation, we'll create |
| // fuchsia.sysmem2.BufferCollection.SetConstraints() which will accept |
| // constraints as defined here. |
| |
| /// Constraints on BufferCollection parameters. These constraints can be |
| /// specified per-participant. The sysmem service implements aggregation of |
| /// constraints from multiple participants. |
| type BufferCollectionConstraints = table { |
| /// The usage is only meant as a hint to help sysmem choose a more optimal |
| /// PixelFormat or similar when multiple compatible options exist. |
| /// |
| /// When aggregating BufferCollectionConstraints, these values bitwise-OR. |
| /// |
| /// At least one usage bit must be specified unless the whole |
| /// BufferCollectionConstraints is logically null (no fields set). |
| 1: usage BufferUsage; |
| |
| /// Per-participant number of buffers that the participant may concurrently |
| /// hold for its exclusive use for a non-transient period of time (camp on). |
| /// |
| /// For example, a video decoder would specify (at least) the maximum number |
| /// of reference frames + 1 frame currently being decoded into. |
| /// |
| /// A participant must not camp on more buffers than specified here (except |
| /// very transiently) else processing may get stuck. |
| /// |
| /// When aggregating BufferCollectionConstraints, these values add. |
| /// |
| /// In testing scenarios, camping on more buffers than this for any |
| /// significant duration may (ideally will) be flagged as a failure. In |
| /// testing scenarios, the participant may not be provided with more buffers |
| /// than this concurrently. |
| 2: min_buffer_count_for_camping uint32; |
| |
| /// Per-participant minimum number of buffers that are needed for slack |
| /// reasons, for better overlap of processing / better performance. |
| /// |
| /// When aggregating BufferCollectionConstraints, these values add. |
| /// |
| /// A participant should typically specify 0 or 1 here - typically 0 is |
| /// appropriate if min_buffer_count_for_camping is already enough to keep |
| /// the participant busy 100% of the time when the participant is slightly |
| /// behind, while 1 can be appropriate if 1 more buffer than strictly needed |
| /// for min-camping reasons gives enough slack to stay busy 100% of the time |
| /// (when slightly behind, vs. lower % without the extra buffer). |
| /// |
| /// In testing scenarios, this field may be forced to 0, and all |
| /// participants are expected to continue to work without getting stuck. If |
| /// a buffer is needed for forward progress reasons, that buffer should be |
| /// accounted for in min_buffer_count_for_camping. |
| 3: min_buffer_count_for_dedicated_slack uint32; |
| |
| /// Similar to min_buffer_count_for_dedicated_slack, except when aggregating |
| /// these values max (instead of add). The value here is not shared with |
| /// any participant's min_buffer_count_for_dedicated_slack. |
| /// |
| /// A participant can specify > 0 here if a participant would like to ensure |
| /// there's some slack overall, but doesn't need that slack to be dedicated. |
| /// |
| /// The choice whether to use min_buffer_count_for_dedicated_slack or |
| /// min_buffer_count_for_shared_slack (or both) will typically be about the |
| /// degree to which the extra slack improves performance. |
| /// |
| /// In testing scenarios, this field may be forced to 0, and all |
| /// participants are expected to continue to work without getting stuck. If |
| /// a buffer is needed for forward progress reasons, that buffer should be |
| /// accounted for in min_buffer_count_for_camping. |
| 4: min_buffer_count_for_shared_slack uint32; |
| |
| /// A particularly-picky participant may unfortunately need to demand a tight |
| /// range of buffer_count, or even a specific buffer_count. This field |
| /// should remain 0 unless a participant really must set this field to |
| /// constrain the overall BufferCollectionInfo_2.buffer_count. Any such |
| /// participant should still fill out the min_buffer_count_for_* fields. |
| /// |
| /// If this field is un-set, the logical min_buffer_count is 1. |
| 5: min_buffer_count uint32; |
| /// A particularly-picky participant may unfortunately need to demand a tight |
| /// range of buffer_count, or even a specific buffer_count. This field |
| /// should remain 0 unless a participant really must set this field to |
| /// constrain the overall BufferCollectionInfo_2.buffer_count. Any such |
| /// participant should still fill out the min_buffer_count_for_* fields. |
| /// |
| /// If this field is un-set, the logical max_buffer_count is 0xFFFFFFFF. |
| 6: max_buffer_count uint32; |
| |
| /// Optional constraints on BufferCollectionSettings.buffer_settings. |
| /// |
| /// A participant that intends to specify image_format_constraints_count > 1 |
| /// will typically specify the minimum buffer size implicitly via |
| /// image_format_constraints, and possibly specify only the max buffer size |
| /// via buffer_memory_constraints. |
| /// |
| /// If un-set, the client is specifying "don't care" re. any buffer memory |
| /// constraints. |
| 7: buffer_memory_constraints BufferMemoryConstraints; |
| |
| /// Optional constraints on the image format parameters of an image stored |
| /// in a buffer of the BufferCollection. This includes pixel format and |
| /// image layout. These constraints are per-pixel-format, so more than one |
| /// is permitted. Entries in the list must have unique pixel_formats. |
| /// |
| /// When aggregating, only pixel formats that are specified by all |
| /// particpants with non-zero image_format_constraints_count (and non-Null) |
| /// BufferCollectionConstraints) are retained. |
| /// |
| /// un-set means no image format constraints. set but zero length is an |
| /// error. |
| 8: image_format_constraints |
| vector<ImageFormatConstraints>:MAX_COUNT_BUFFER_COLLECTION_CONSTRAINTS_IMAGE_FORMAT_CONSTRAINTS; |
| |
| /// If true, a secure heap may only be selected if all participants with |
| /// BufferMemoryConstraints specify allow_clear_aux_buffers_for_secure. If |
| /// "need" is true, "allow" must also be true. |
| /// |
| /// If false (or unset), the participant can still work, potentially even |
| /// with secure memory (depending on supported heaps), without clear aux |
| /// buffers. |
| 9: need_clear_aux_buffers_for_secure bool; |
| |
| /// If true, the participant will use clear aux buffers, if they are |
| /// allocated, as appropriate to the participant's role. If the participant |
| /// is a writer, then the participant writer will populate the clear aux |
| /// buffers with the clear (not-encrypted, not-DRM-protected) bytes, and |
| /// fill protected bytes with data that does not emulate start codes, such |
| /// as 0xFF. |
| /// |
| /// If un-set, then allow_clear_aux_buffers_for_secure is true iff the |
| /// participant specifies usage which is read-only. |
| /// |
| /// If un-set from a participant with write usage, or false, the buffer |
| /// collection won't be able to allocate if any participant specifies |
| /// need_clear_aux_buffers_for_secure true. |
| 10: allow_clear_aux_buffers_for_secure bool; |
| }; |
| |
| /// Known heap types. |
| /// Device specific types should have bit 60 set. Top order bit is reserved |
| /// and should not be set. |
| type HeapType = strict enum : uint64 { |
| SYSTEM_RAM = 0x0000000000000000; |
| |
| /// Heap used for amlogic protected memory. |
| AMLOGIC_SECURE = 0x1000000000010000; |
| |
| /// Heap used for amlogic protected memory between decrypt and video decode. |
| AMLOGIC_SECURE_VDEC = 0x1000000000010001; |
| |
| /// Heap used by goldfish vulkan for device-local memory. |
| GOLDFISH_DEVICE_LOCAL = 0x1000000000020000; |
| |
| /// Heap used by goldfish vulkan for host-visible memory. |
| GOLDFISH_HOST_VISIBLE = 0x1000000000020001; |
| |
| /// Heap used for display framebuffer. This is used by display drivers |
| /// limited to a single framebuffer located at a specific physical address. |
| /// The framebuffer heap makes it possible to create buffer collections |
| /// for the framebuffer and enables sysmem support in these drivers. |
| FRAMEBUFFER = 0x1000000000030001; |
| }; |
| |
| type BufferMemoryConstraints = table { |
| 1: min_size_bytes uint32; |
| /// un-set is treated as 0xFFFFFFFF. |
| 2: max_size_bytes uint32; |
| |
| 3: physically_contiguous_required bool; |
| |
| /// If true, at least one participant requires secure memory. |
| /// |
| /// When aggregating BufferCollectionConstraints, these values boolean-OR. |
| 4: secure_required bool; |
| |
| /// By default, participants must ensure the CPU can read or write data to |
| /// the buffer without cache operations. If they support using the RAM |
| /// domain, data must be available in RAM (with CPU cache state such that |
| /// the RAM data won't get corrupted by a dirty CPU cache line writing |
| /// incorrect data to RAM), and a consumer reading using the CPU must |
| /// invalidate CPU cache before reading (the producer doesn't guarantee |
| /// zero stale "clean" cache lines) |
| 5: cpu_domain_supported bool; |
| 6: ram_domain_supported bool; |
| 7: inaccessible_domain_supported bool; |
| |
| /// Optional heap constraints. Participants that don't care which heap |
| /// memory is allocated on should leave this field un-set. |
| 8: heap_permitted vector<HeapType>:MAX_COUNT_BUFFER_MEMORY_CONSTRAINTS_HEAP_PERMITTED; |
| }; |
| |
| /// Inaccessible is only for cases where there is no CPU-based access to the |
| /// buffers. A secure_required buffer can still have CoherencyDomain Cpu or |
| /// Ram even if the secure_required buffer can only be accessed by the CPU when |
| /// the CPU is running in secure mode (or similar). In contrast, device-local |
| /// memory that isn't reachable from the CPU is CoherencyDomain Inaccessible, |
| /// even if it's possible to cause a device (physical or virtual) to copy the |
| /// data from the Inaccessible buffers to buffers that are visible to the CPU. |
| type CoherencyDomain = strict enum { |
| CPU = 0; |
| RAM = 1; |
| INACCESSIBLE = 2; |
| }; |
| |
| /// Describes constraints on layout of image data in buffers. |
| // TODO(fxbug.dev/32119): change struct to table |
| type ImageFormatConstraints = table { |
| /// The PixelFormat for which the following constraints apply. A |
| /// participant may have more than one PixelFormat that's supported, in |
| /// which case that participant can use a list of ImageFormatConstraints |
| /// with an entry per PixelFormat. It's not uncommon for the other fields |
| /// of ImageFormatConstraints to vary by PixelFormat - for example for a |
| /// linear format to support smaller max size than a tiled format. |
| 1: pixel_format PixelFormat; |
| |
| /// Empty is an error. Redundant entries are an error. Arbitrary ordering |
| /// is not an error. |
| 2: color_spaces vector<ColorSpace>:MAX_COUNT_IMAGE_FORMAT_CONSTRAINTS_COLOR_SPACES; |
| |
| /// Minimum permitted width in pixels. |
| /// |
| /// For example a video decoder participant may set this field to the |
| /// minimum coded_width that might potentially be specified by a stream. In |
| /// contrast, required_min_coded_width would be set to the current |
| /// coded_width specified by the stream. While min_coded_width aggregates |
| /// by taking the max, required_min_coded_width aggregates by taking the |
| /// min. |
| /// |
| /// See also required_min_coded_width. |
| 3: min_coded_width uint32; |
| /// Maximum width in pixels. For example Scenic may set this field |
| /// (directly or via sub-participants) to the maximum width that can be |
| /// composited. |
| /// un-set is treated as 0xFFFFFFFF. |
| 4: max_coded_width uint32; |
| |
| /// Minimum height in pixels. For example a video decoder participant may |
| /// set this field to the coded_height specified by a stream. |
| 5: min_coded_height uint32; |
| /// Maximum height in pixels. For example Scenic may set this field |
| /// (directly or via sub-participants) to the maximum height that can be |
| /// composited. |
| /// un-set is treated as 0xFFFFFFFF. |
| 6: max_coded_height uint32; |
| |
| /// Must be >= the value implied by min_coded_width for plane 0. |
| 7: min_bytes_per_row uint32; |
| /// Must be >= the value implied by max_coded_width for plane 0. |
| /// un-set is treated as 0xFFFFFFFF. |
| 8: max_bytes_per_row uint32; |
| |
| /// The max image area in pixels is limited indirectly via |
| /// BufferSettings.size_bytes, and can also be enforced directly via this |
| /// field. |
| /// un-set is treated as 0xFFFFFFFF. |
| 9: max_coded_width_times_coded_height uint32; |
| |
| /// coded_width % width_divisor must be 0. |
| /// un-set is treated as 1. |
| 10: coded_width_divisor uint32; |
| |
| /// coded_height % height_divisor must be 0. |
| /// un-set is treated as 1. |
| 11: coded_height_divisor uint32; |
| |
| /// bytes_per_row % bytes_per_row_divisor must be 0. |
| /// un-set is treated as 1. |
| 12: bytes_per_row_divisor uint32; |
| |
| /// vmo_usable_start % start_offset_divisor must be 0. |
| /// un-set is treated as 1. |
| 13: start_offset_divisor uint32; |
| |
| /// display_width % display_width_divisor must be 0. |
| /// un-set is treated as 1. |
| 14: display_width_divisor uint32; |
| |
| /// display_height % display_height_divisor must be 0. |
| /// un-set is treated as 1. |
| 15: display_height_divisor uint32; |
| |
| /// required_ dimension bounds. |
| /// |
| /// In contrast to the corresponding fields without "required_" at the |
| /// start, these fields (when set to non-zero values) express a requirement |
| /// that the resulting aggregated non-required_ fields specify a space that |
| /// fully contain the space expressed by each participant's required_ |
| /// fields. |
| /// |
| /// For example, a producer video decoder is perfectly happy for the |
| /// consumer to be willing to accept anything, and the video decoder doesn't |
| /// really want to constrain the potential space of dimensions that might be |
| /// seen in a stream and may be acceptable to the consumer, but the video |
| /// decoder needs to ensure that the resulting dimension ranges contain |
| /// at least the current dimensions decoded from the stream. |
| /// |
| /// Similarly, an initiator with a particular dynamic-dimension scenario in |
| /// mind may wish to require up front that participants agree to handle at |
| /// least the range of dimensions expected by the initiator in that |
| /// scenario (else fail earlier rather than later, maybe trying again with |
| /// smaller required_ space). |
| /// |
| /// It's much more common for a producer or initiator to set these fields |
| /// than for a consumer to set these fields. |
| /// |
| /// While the non-required_ fields aggregate by taking the intersection, the |
| /// required_ fields aggregate by taking the union. |
| /// |
| /// If set, the required_max_coded_width and required_max_coded_height will |
| /// cause the allocated buffers to be large enough to hold an image that is |
| /// required_max_coded_width * required_max_coded_height. |
| /// |
| /// TODO(fxbug.dev/34192): Make it easier to allocate buffers of minimal size |
| /// that can (optionally) also handle 90 degree rotated version of the max |
| /// dimensions / alternate required bounds for another main aspect ratio. |
| /// un-set is treated as 0xFFFFFFFF. |
| 16: required_min_coded_width uint32; |
| 17: required_max_coded_width uint32; |
| /// un-set is treated as 0xFFFFFFFF. |
| 18: required_min_coded_height uint32; |
| 19: required_max_coded_height uint32; |
| /// un-set is treated as 0xFFFFFFFF. |
| 20: required_min_bytes_per_row uint32; |
| 21: required_max_bytes_per_row uint32; |
| }; |
| |
| /// Describes how an image is represented. |
| // TODO(fxbug.dev/32119): Currently this table is not considered ready for use between |
| // processes, but should be fairly soon. |
| type ImageFormat = table { |
| /// Pixel format. |
| 1: pixel_format PixelFormat; |
| |
| /// Row width in pixels that exist in the buffer. Must be >= display_width. |
| /// Can be < the width implied by stride_bytes. |
| 2: coded_width uint32; |
| |
| /// Number of rows. Must be >= display_height. |
| 3: coded_height uint32; |
| |
| // Stride in bytes of plane 0. Planes beyond plane 0 (if any, depending on |
| // pixel_format) have a known fixed relationship with plane 0's stride. |
| 4: bytes_per_row uint32; |
| |
| /// Row width in pixels that are to be displayed. This can be <= |
| /// coded_width. Any cropping occurs on the right of the image (not left). |
| 5: display_width uint32; |
| |
| /// Number of rows to be displayed. This can be <= coded_height, with any |
| /// cropping on the bottom (not top). |
| 6: display_height uint32; |
| |
| /// Color space. |
| 7: color_space ColorSpace; |
| |
| /// The pixel_aspect_ratio_width : pixel_aspect_ratio_height is the pixel |
| /// aspect ratio (AKA sample aspect ratio aka SAR) for the luma (AKA Y) |
| /// samples. A pixel_aspect_ratio of 1:1 mean square pixels. A |
| /// pixel_aspect_ratio of 2:1 would mean pixels that are displayed twice as |
| /// wide as they are tall. Codec implementation should ensure these two |
| /// values are relatively prime by reducing the fraction (dividing both by |
| /// GCF) if necessary. |
| /// |
| /// A producer should set both these fields, or neither of them. |
| /// |
| /// A consumer should interpret either of these fields being un-set as an |
| /// unknown pixel_aspect_ratio. A default of 1:1 can be appropriate in some |
| /// cases, but a consumer may determine the actual pixel_aspect_ratio by OOB |
| /// means. |
| 8: pixel_aspect_ratio_width uint32; |
| 9: pixel_aspect_ratio_height uint32; |
| }; |