docs/uctypes: Tweak descriptor reference to hopefully be easier to follow.
Put offset first in OR expressions, and use "offset" var instead of
hardcoded numbers. Hopefully, this will make it more self-describing
and show patterns better.
@@ -29,16 +29,16 @@ Following are encoding examples for various field types:
* Scalar types::
- "field_name": uctypes.UINT32 | 0
+ "field_name": offset | uctypes.UINT32
in other words, value is scalar type identifier ORed with field offset
(in bytes) from the start of the structure.
* Recursive structures::
- "sub": (2, {
- "b0": uctypes.UINT8 | 0,
- "b1": uctypes.UINT8 | 1,
+ "sub": (offset, {
+ "b0": 0 | uctypes.UINT8,
+ "b1": 1 | uctypes.UINT8,
})
i.e. value is a 2-tuple, first element of which is offset, and second is
@@ -47,7 +47,7 @@ Following are encoding examples for various field types:
* Arrays of primitive types::
- "arr": (uctypes.ARRAY | 0, uctypes.UINT8 | 2),
+ "arr": (offset | uctypes.ARRAY, size | uctypes.UINT8),
i.e. value is a 2-tuple, first element of which is ARRAY flag ORed
with offset, and second is scalar element type ORed number of elements
@@ -55,7 +55,7 @@ Following are encoding examples for various field types:
* Arrays of aggregate types::
- "arr2": (uctypes.ARRAY | 0, 2, {"b": uctypes.UINT8 | 0}),
+ "arr2": (offset | uctypes.ARRAY, size, {"b": 0 | uctypes.UINT8}),
i.e. value is a 3-tuple, first element of which is ARRAY flag ORed
with offset, second is a number of elements in array, and third is
@@ -63,21 +63,21 @@ Following are encoding examples for various field types:
* Pointer to a primitive type::
- "ptr": (uctypes.PTR | 0, uctypes.UINT8),
+ "ptr": (offset | uctypes.PTR, uctypes.UINT8),
i.e. value is a 2-tuple, first element of which is PTR flag ORed
with offset, and second is scalar element type.
* Pointer to an aggregate type::
- "ptr2": (uctypes.PTR | 0, {"b": uctypes.UINT8 | 0}),
+ "ptr2": (offset | uctypes.PTR, {"b": 0 | uctypes.UINT8}),
i.e. value is a 2-tuple, first element of which is PTR flag ORed
with offset, second is descriptor of type pointed to.
* Bitfields::
- "bitf0": uctypes.BFUINT16 | 0 | 0 << uctypes.BF_POS | 8 << uctypes.BF_LEN,
+ "bitf0": offset | uctypes.BFUINT16 | lsbit << uctypes.BF_POS | bitsize << uctypes.BF_LEN,
i.e. value is type of scalar value containing given bitfield (typenames are
similar to scalar types, but prefixes with "BF"), ORed with offset for
@@ -91,9 +91,10 @@ Following are encoding examples for various field types:
In the example above, first a UINT16 value will be extracted at offset 0
(this detail may be important when accessing hardware registers, where
particular access size and alignment are required), and then bitfield
- whose rightmost bit is least-significant bit of this UINT16, and length
- is 8 bits, will be extracted - effectively, this will access
- least-significant byte of UINT16.
+ whose rightmost bit is *lsbit* bit of this UINT16, and length
+ is *bitsize* bits, will be extracted. For example, if *lsbit* is 0 and
+ *bitsize* is 8, then effectively it will access least-significant byte
+ of UINT16.
Note that bitfield operations are independent of target byte endianness,
in particular, example above will access least-significant byte of UINT16
