Struct BufferMemorySettings 

pub struct BufferMemorySettings {
    pub size_bytes: Option<u64>,
    pub is_physically_contiguous: Option<bool>,
    pub is_secure: Option<bool>,
    pub coherency_domain: Option<CoherencyDomain>,
    pub heap: Option<Heap>,
    pub raw_vmo_size: Option<u64>,
    /* private fields */
}

These are memory-related settings for all buffers of a buffer collection.

Fields

size_bytes: Option<u64>

This field will always be set by sysmem.

Rule for producers: For BufferCollectionInfo with ImageFormatConstraints, storing an image of a given ImageFormat in a buffer of that BufferCollection is only allowed if the result of calling ImageFormatImageSize or a strictly equivalent computation is less than or equal to size_bytes.

Producer participants must stay within size_bytes when determining whether an image will fit in a buffer, even if the VMO’s size is larger than this.

Failure of a producer to use size_bytes as the constraint (not VMO size) when determining whether a given ImageFormat will fit in a buffer will, in general, cause problems for any participant that has set ImageFormatConstraints.pad_for_block_size to larger than {1, 1}, or pad_beyond_image_size_bytes to greater than 0. Those participants rely on the ability to access bytes in the VMO beyond the image size. Putting an image in the VMO that exceeds size_bytes can potentially lead to those participants trying to access an offset beyond the last page of the VMO.

Similarly, any future padding-only constraint which is irrelevant to a non-padding participant when locating each valid pixel’s valid data will also be accounted for by checking ImageFormatImageSize() against size_bytes instead of the VMO size.

Following this rule allows producers to not need to worry about arbitrary padding requirements of participants, including future-added padding-only constraints.

The bytes_per_row and rounding up to a tile size boundary are included in ImageFormatImageSize and accounted for in size_bytes, even though these two aspects are partially about padding. These two aspects are included in the ImageFormatImageSize calculation because these two aspects are also relevant to all participants that need to locate pixel data. The fuchsia.images2.ImageFormat intentionally doesn’t contain any padding-only fields.

Participants with a padding constraint (in addition to bytes_per_row or tile size boundary), such as pad_for_block_size or pad_beyond_image_size_bytes, are allowed to access, but not treat as meaningful, bytes which are at offset size_bytes up to the max offset implied by their own padding constraint, which will never exceed the VMO size minus 1, as long as the ImageFormatImageSize is less than or equal to BufferMemorySettings.size_bytes and other constraints under BufferCollectionInfo aren’t violated by the producer.

The same size_bytes value is sent to all participants.

This field is not page aligned. This value rounded up to zx_system_page_size() boundary is guaranteed to be less than or equal the buffer VMO size. In other words, the VMO can have more pages than implied by this value, due to padding-only constraints from participant(s).

is_physically_contiguous: Option<bool>

This field will always be set by sysmem.

is_secure: Option<bool>

This field will always be set by sysmem.

coherency_domain: Option<CoherencyDomain>

This field will always be set by sysmem.

heap: Option<Heap>

The specific heap from which buffers are allocated.

This field will always be set by sysmem.

raw_vmo_size: Option<u64>

This is guaranteed to be equal to the VMO size obtained via zx_vmo_get_size. This field is here because pad_* constraints can result in the VMO size being larger than implied by size_bytes, and for participants using pad_* constraints, it can be convenient to have this field available rather than having to query for the VMO size.

When checking with ImageFormatImageSize to see if an image will fit in a buffer, use size_bytes as the threshold, not raw_vmo_size.

Producers using pad_* constraints must still only put images in the buffer which have ImageFormatImageSize() <= size_bytes. Participants using pad_* constraints are allowed to access bytes beyond size_bytes consistent with what the participant set for the pad_* constriant(s), which will always fit within raw_vmo_size assuming correct operation of the participant and sysmem. This field can be useful for double-checking that accesses will be within the VMO.

When setting up VMO mappings and VMO pins, a participant using pad_* constraint(s) should use raw_vmo_size for the size of the mapping. In contrast, a participant not using any pad_* constraint can use size_bytes rounded up to a page size boundary or said participant can use raw_vmo_size, but for that participant, using size_bytes rounded up to the page size can avoid mapping a few pages.

Trait Implementations

impl Clone for BufferMemorySettings

fn clone(&self) -> BufferMemorySettings

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BufferMemorySettings

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<D> Decode<BufferMemorySettings, D> for BufferMemorySettings

where D: ResourceDialect,

fn new_empty() -> BufferMemorySettings

Creates a valid instance of Self. The specific value does not matter, since it will be overwritten by decode.

unsafe fn decode( &mut self, decoder: &mut Decoder<'_, D>, offset: usize, depth: Depth, ) -> Result<(), Error>

Decodes an object of type T from the decoder’s buffers into self.

impl Default for BufferMemorySettings

fn default() -> BufferMemorySettings

Returns the “default value” for a type.

impl<D> Encode<BufferMemorySettings, D> for &BufferMemorySettings

where D: ResourceDialect,

unsafe fn encode( self, encoder: &mut Encoder<'_, D>, offset: usize, depth: Depth, ) -> Result<(), Error>

Encodes the object into the encoder’s buffers. Any handles stored in the object are swapped for Handle::INVALID.

impl PartialEq for BufferMemorySettings

fn eq(&self, other: &BufferMemorySettings) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TypeMarker for BufferMemorySettings

type Owned = BufferMemorySettings

The owned Rust type which this FIDL type decodes into.

fn inline_align(_context: Context) -> usize

Returns the minimum required alignment of the inline portion of the encoded object. It must be a (nonzero) power of two.

fn inline_size(_context: Context) -> usize

Returns the size of the inline portion of the encoded object, including padding for alignment. Must be a multiple of inline_align.

fn encode_is_copy() -> bool

Returns true if the memory layout of Self::Owned matches the FIDL wire format and encoding requires no validation. When true, we can optimize encoding arrays and vectors of Self::Owned to a single memcpy.

fn decode_is_copy() -> bool

Returns true if the memory layout of Self::Owned matches the FIDL wire format and decoding requires no validation. When true, we can optimize decoding arrays and vectors of Self::Owned to a single memcpy.

impl ValueTypeMarker for BufferMemorySettings

type Borrowed<'a> = &'a BufferMemorySettings

The Rust type to use for encoding. This is a particular Encode<Self> type cheaply obtainable from &Self::Owned. There are three cases:

fn borrow( value: &<BufferMemorySettings as TypeMarker>::Owned, ) -> <BufferMemorySettings as ValueTypeMarker>::Borrowed<'_>

Cheaply converts from &Self::Owned to Self::Borrowed.

impl Persistable for BufferMemorySettings

impl StructuralPartialEq for BufferMemorySettings