Answer an Array of type descriptors in member order
Note: To force a specific structure alignment, the
OSStructure subclass may override the method
OSStructure class>>structureAlignmentOverride to answer a specific
Integer byte value.
aMemberArray - Array of <
Symbol>s describing the names of the struct members. These must be in member order.
aTypeDescriptorArray - Array of <
Symbol>s describing the data types of the members. These must also be in member order. Below is a classification of the various type descriptors.
Base Types - These are the default primitive base types that are found the the
TypeMappings class variable of
OSStructure. These can also be extended by the user by injecting new types into
TypeMappings.
Examples: bool8, bool16, bool32, char8, char16, double, float, float32, float64, int8, int16, int32, int64, pad, pointer, spointer, ssize, uint8, uint16, uint32, uint64, upointer, usize
Nested Structures/Unions - If a member is a nested structure/union which has been modeled by an
OSStructure/OSUnion subclass, then the name of the
OSStructure/OSUnion can be used as the type descriptor.
Example: Given struct
Foo { int a; int b; } and struct
Bar { Foo x; int y; }, then the definitions for
OSStructure Foo and
Bar would be:
Foo members: #(a b) types: #(int32 int32)
Bar members: #(x y) types: #(
Foo int32)
Anonymous Structures/Unions - Anonymous Unions are represented by grouping the member names and type descriptors with a single set of parentheses. Anonymous Structures also require a single set of parentheses for the member array, but a double set of parentheses for the type descriptor array. This is easier to understand by example:
Example 1: Given struct
Foo { union { char x; double y; }; char z; }, then the definition for
OSStructure Foo would be:
Foo members: #( (x y) z ) types: #( (char8 double) char8).
Example 2: Given struct
Foo { struct { char x; double y; }; char z; }, then the definition of
OSStructure Foo would be:
Foo members: #( (x y) z ) types: #( ((char8 double)) char8).
theAlignmentType - One of the enumerated values from the OSAlignments pool dictionary. These include:
AlignNone - No alignment computation is performed. Members are aligned on nearest 1-byte boundary. This can be used in conjunction with custom padding types to achieve specialized alignments
AlignDefault - Alignment will be automatically computed based on the rules of the current platform.
Align2 - Alignment on 2-byte boundaries
Align4 - Alignment on 4-byte boundaries
Align8 - Alignment on 8-byte boundaries
Align16 - Alignment on 16-byte boundaries
OSStructures have an auto-layout generation capability that radically simplifies writing code to access native structures. This simplification is due to the fact that developers no longer need to compute member offsets by hand. Instead, all
OSStructure subclasses do this automatically.
In order to have VA Smalltalk generate the layout of an OSStructure subclass automatically, a definition of the native structure must be provided. Typically, this is done at load time meaning that once an
OSStructure is loaded into the running image, then its definition should be defined.
OSStructure subclasses may also override a class side method called
regenerateDefinition. This method is called at image startUp and allows for dynamically adjusting the definition based on some criteria. While the criteria is user-defined, the motivation is for 32-bit images being loaded on a 64-bit virtual machine. In this scenario, some structures may have a different definition when compiled with a 64-bit compiler and therefore certain
OSStructures may need to redefine themselves before the image finishes starting up.
Separately, the layout of an OSStructure may need to be recomputed even though its definition is the same. This occurs for all
OSStructures when loading a 32-bit image on a 64-bit virtual machine. The reason has to do with the change in native pointer sizes which impacts member offsets. For example, given the struct
Foo { char *x; char y; }, y has a (0-based) offset of 4 in a 32-bit environment, but an offset of 8 in a 64-bit environment. In both environments the definition of the structure is exactly the same, however the layout is different.
Copyright 2005, 2020 Instantiations, Inc. All rights reserved.
