# Copyright 2013 The Chromium Authors # Use of this source code is governed by a BSD-style license that can be # found in the LICENSE file. import copy from mojom.generate import module as mojom # This module provides a mechanism for determining the packed order and offsets # of a mojom.Struct. # # ps = pack.PackedStruct(struct) # ps.packed_fields will access a list of PackedField objects, each of which # will have an offset, a size and a bit (for mojom.BOOLs). # Size of struct header in bytes: num_bytes [4B] + version [4B]. HEADER_SIZE = 8 class PackedField: kind_to_size = { mojom.BOOL: 1, mojom.INT8: 1, mojom.UINT8: 1, mojom.INT16: 2, mojom.UINT16: 2, mojom.INT32: 4, mojom.UINT32: 4, mojom.FLOAT: 4, mojom.HANDLE: 4, mojom.MSGPIPE: 4, mojom.SHAREDBUFFER: 4, mojom.PLATFORMHANDLE: 4, mojom.DCPIPE: 4, mojom.DPPIPE: 4, mojom.NULLABLE_HANDLE: 4, mojom.NULLABLE_MSGPIPE: 4, mojom.NULLABLE_SHAREDBUFFER: 4, mojom.NULLABLE_PLATFORMHANDLE: 4, mojom.NULLABLE_DCPIPE: 4, mojom.NULLABLE_DPPIPE: 4, mojom.INT64: 8, mojom.UINT64: 8, mojom.DOUBLE: 8, mojom.STRING: 8, mojom.NULLABLE_STRING: 8 } @classmethod def GetSizeForKind(cls, kind): if isinstance(kind, (mojom.Array, mojom.Map, mojom.Struct, mojom.Interface, mojom.AssociatedInterface, mojom.PendingRemote, mojom.PendingAssociatedRemote)): return 8 if isinstance(kind, mojom.Union): return 16 if isinstance(kind, (mojom.InterfaceRequest, mojom.PendingReceiver)): kind = mojom.MSGPIPE if isinstance( kind, (mojom.AssociatedInterfaceRequest, mojom.PendingAssociatedReceiver)): return 4 if isinstance(kind, mojom.Enum): # TODO(mpcomplete): what about big enums? return cls.kind_to_size[mojom.INT32] if not kind in cls.kind_to_size: raise Exception("Undefined type: %s. Did you forget to import the file " "containing the definition?" % kind.spec) return cls.kind_to_size[kind] @classmethod def GetAlignmentForKind(cls, kind): if isinstance(kind, (mojom.Interface, mojom.AssociatedInterface, mojom.PendingRemote, mojom.PendingAssociatedRemote)): return 4 if isinstance(kind, mojom.Union): return 8 return cls.GetSizeForKind(kind) def __init__(self, field, index, ordinal, original_field=None, sub_ordinal=None, linked_value_packed_field=None): """ Args: field: the original field. index: the position of the original field in the struct. ordinal: the ordinal of the field for serialization. original_field: See below. sub_ordinal: See below. linked_value_packed_field: See below. original_field, sub_ordinal, and linked_value_packed_field are used to support nullable ValueKind fields. For legacy reasons, nullable ValueKind fields actually generate two PackedFields. This allows: - backwards compatibility prior to Mojo support for nullable ValueKinds. - correct packing of fields for the aforementioned backwards compatibility. When translating Fields to PackedFields, the original field is turned into two PackedFields: the first PackedField always has type mojom.BOOL, while the second PackedField has the non-nullable version of the field's kind. When constructing these PackedFields, original_field references the field as defined in the mojom; the name as defined in the mojom will be used for all layers above the wire/data layer. sub_ordinal is used to sort the two PackedFields correctly with respect to each other: the first mojom.BOOL field always has sub_ordinal 0, while the second field always has sub_ordinal 1. Finally, linked_value_packed_field is used by the serialization and deserialization helpers, which generally just iterate over a PackedStruct's PackedField's in ordinal order. This allows the helpers to easily reference any related PackedFields rather than having to lookup related PackedFields by index while iterating. """ self.field = field self.index = index self.ordinal = ordinal self.original_field = original_field self.sub_ordinal = sub_ordinal self.linked_value_packed_field = linked_value_packed_field self.size = self.GetSizeForKind(self.field.kind) self.alignment = self.GetAlignmentForKind(self.field.kind) self.offset = None self.bit = None self.min_version = None def GetPad(offset, alignment): """Returns the pad necessary to reserve space so that |offset + pad| equals to some multiple of |alignment|.""" return (alignment - (offset % alignment)) % alignment def GetFieldOffset(field, last_field): """Returns a 2-tuple of the field offset and bit (for BOOLs).""" if (field.field.kind == mojom.BOOL and last_field.field.kind == mojom.BOOL and last_field.bit < 7): return (last_field.offset, last_field.bit + 1) offset = last_field.offset + last_field.size pad = GetPad(offset, field.alignment) return (offset + pad, 0) def GetPayloadSizeUpToField(field): """Returns the payload size (not including struct header) if |field| is the last field. """ if not field: return 0 offset = field.offset + field.size pad = GetPad(offset, 8) return offset + pad def IsNullableValueKindPackedField(field): """Returns true if `field` is derived from a nullable ValueKind field. Nullable ValueKind fields often require special handling in the bindings due to the way the implementation is constrained for wire compatibility. """ assert isinstance(field, PackedField) return field.sub_ordinal is not None def IsPrimaryNullableValueKindPackedField(field): """Returns true if `field` is derived from a nullable ValueKind mojom field and is the "primary" field. The primary field is a bool PackedField that controls if the field should be considered as present or not; it will have a reference to the PackedField that holds the actual value representation if considered present. Bindings code that translates between the wire protocol and the higher layers can use this to simplify mapping multiple PackedFields to the single field that is logically exposed to bindings consumers. """ assert isinstance(field, PackedField) return field.linked_value_packed_field is not None class PackedStruct: def __init__(self, struct): self.struct = struct # |packed_fields| contains all the fields, in increasing offset order. self.packed_fields = [] # |packed_fields_in_ordinal_order| refers to the same fields as # |packed_fields|, but in ordinal order. self.packed_fields_in_ordinal_order = [] # No fields. if (len(struct.fields) == 0): return # Start by sorting by ordinal. src_fields = self.packed_fields_in_ordinal_order ordinal = 0 for index, field in enumerate(struct.fields): if field.ordinal is not None: ordinal = field.ordinal # Nullable value types are a bit weird: they generate two PackedFields # despite being a single ValueKind. This is for wire compatibility to # ease the transition from legacy mojom syntax where nullable value types # were not supported. if isinstance(field.kind, mojom.ValueKind) and field.kind.is_nullable: # The suffixes intentionally use Unicode codepoints which are considered # valid C++/Java/JavaScript identifiers, yet are unlikely to be used in # actual user code. has_value_field = copy.copy(field) has_value_field.name = f'{field.mojom_name}_$flag' has_value_field.kind = mojom.BOOL value_field = copy.copy(field) value_field.name = f'{field.mojom_name}_$value' value_field.kind = field.kind.MakeUnnullableKind() value_packed_field = PackedField(value_field, index, ordinal, original_field=field, sub_ordinal=1, linked_value_packed_field=None) has_value_packed_field = PackedField( has_value_field, index, ordinal, original_field=field, sub_ordinal=0, linked_value_packed_field=value_packed_field) src_fields.append(has_value_packed_field) src_fields.append(value_packed_field) else: src_fields.append(PackedField(field, index, ordinal)) ordinal += 1 src_fields.sort(key=lambda field: (field.ordinal, field.sub_ordinal)) # Set |min_version| for each field. next_min_version = 0 for packed_field in src_fields: if packed_field.field.min_version is None: assert next_min_version == 0 else: assert packed_field.field.min_version >= next_min_version next_min_version = packed_field.field.min_version packed_field.min_version = next_min_version if (packed_field.min_version != 0 and mojom.IsReferenceKind(packed_field.field.kind) and not packed_field.field.kind.is_nullable): raise Exception( "Non-nullable reference fields are only allowed in version 0 of a " "struct. %s.%s is defined with [MinVersion=%d]." % (self.struct.name, packed_field.field.name, packed_field.min_version)) src_field = src_fields[0] src_field.offset = 0 src_field.bit = 0 dst_fields = self.packed_fields dst_fields.append(src_field) # Then find first slot that each field will fit. for src_field in src_fields[1:]: last_field = dst_fields[0] for i in range(1, len(dst_fields)): next_field = dst_fields[i] offset, bit = GetFieldOffset(src_field, last_field) if offset + src_field.size <= next_field.offset: # Found hole. src_field.offset = offset src_field.bit = bit dst_fields.insert(i, src_field) break last_field = next_field if src_field.offset is None: # Add to end src_field.offset, src_field.bit = GetFieldOffset(src_field, last_field) dst_fields.append(src_field) class ByteInfo: def __init__(self): self.is_padding = False self.packed_fields = [] def GetByteLayout(packed_struct): total_payload_size = GetPayloadSizeUpToField( packed_struct.packed_fields[-1] if packed_struct.packed_fields else None) byte_info = [ByteInfo() for i in range(total_payload_size)] limit_of_previous_field = 0 for packed_field in packed_struct.packed_fields: for i in range(limit_of_previous_field, packed_field.offset): byte_info[i].is_padding = True byte_info[packed_field.offset].packed_fields.append(packed_field) limit_of_previous_field = packed_field.offset + packed_field.size for i in range(limit_of_previous_field, len(byte_info)): byte_info[i].is_padding = True for byte in byte_info: # A given byte cannot both be padding and have a fields packed into it. assert not (byte.is_padding and byte.packed_fields) return byte_info class VersionInfo: def __init__(self, version, num_fields, num_packed_fields, num_bytes): self.version = version self.num_fields = num_fields self.num_packed_fields = num_packed_fields self.num_bytes = num_bytes def GetVersionInfo(packed_struct): """Get version information for a struct. Args: packed_struct: A PackedStruct instance. Returns: A non-empty list of VersionInfo instances, sorted by version in increasing order. Note: The version numbers may not be consecutive. """ versions = [] last_version = 0 last_num_fields = 0 last_num_packed_fields = 0 last_payload_size = 0 for packed_field in packed_struct.packed_fields_in_ordinal_order: if packed_field.min_version != last_version: versions.append( VersionInfo(last_version, last_num_fields, last_num_packed_fields, last_payload_size + HEADER_SIZE)) last_version = packed_field.min_version # Nullable numeric fields (e.g. `int32?`) expand to two packed fields, so to # avoid double-counting, only increment if the field is: # - not used for representing a nullable value kind field, or # - the primary field representing the nullable value kind field. last_num_fields += 1 if ( not IsNullableValueKindPackedField(packed_field) or IsPrimaryNullableValueKindPackedField(packed_field)) else 0 last_num_packed_fields += 1 # The fields are iterated in ordinal order here. However, the size of a # version is determined by the last field of that version in pack order, # instead of ordinal order. Therefore, we need to calculate the max value. last_payload_size = max(GetPayloadSizeUpToField(packed_field), last_payload_size) assert len( versions) == 0 or last_num_packed_fields != versions[-1].num_packed_fields versions.append( VersionInfo(last_version, last_num_fields, last_num_packed_fields, last_payload_size + HEADER_SIZE)) return versions