Package: r-map
r_mapA library for working with register map data.The data source is abstracted such that if a user wants to work with aparticular data source, he/she may:Provide an appropriately formatted serialized data source (probably theeasiest)Create a parser of the source data and dynamically generate the datastructure using the provided data classesPurposeEasily utilize register map dataBe able to iterate through register map from arbitrary positionProvide conveniences for walking through dataProvide ability to serialize/deserialize dataProvide mechanism to easily subclass base element implementationsProvide means to register which elements are accessed in data base and createa subtree from this dataFeaturesKey and attribute accessKey and attribute access to an elements sub elements. The key access isparticularly useful for cases where a sub element happens to have the name of areserved keyword in Python.r_map1.reg.value=10r_map1['reg'].value=10That elements are not intended to be added to a node via key based assignmentlike a dictionary. A method:_addis provided for that.Key based assignment is not intended to be supported because it can result in asub element having an alias which would be confusing and is an unlikely usecase.Simple IterationIteration is supported by the base Node class and hence provided by allsubclasses.For example:forreginreg_map:forbf_refinreg:print(f"bitfield reference:{bf_ref.name}has value:{bf_ref.value}")Register to bitfield value mappingA register's value is based on its component bitfield's values. In fact, thereis an additional layer of indirection to support a register only having apartial view to a bitfield. It's therefore possible for multiple registers tohave access to the same bitfield. Support for this level is complexity is bakedinto the data structre and modelled with a class: BitFieldRef.A full register map tree is serialized using a common dictionary with nodesreferencing others via their uuids.For example:"1b99635555e647638f8a1ff38a1e3cf1": {

    "name": "root",

    "type": "Node",

    "children": [

        "3e2f9ba277e44050b52b5111fd814008"

    ]

},

"3e2f9ba277e44050b52b5111fd814008": {

    "name": "r_map1",

    "descr": "An example register map containing r

    "local_address": 268435456,

    "type": "RegisterMap",

    "children": [

        "c897cf71021449bdbdc819e7255fcab7",

        "569715f765f14ba09313796ee98b6db6"

    ]

},

"c897cf71021449bdbdc819e7255fcab7": {

    "local_address": 0,

    "name": "reg1",

    "width": 32,

    "type": "Register",

    "children": [

        "8cded8916e014bb3ab621e327f9c0ae8"

    ]

},

"8cded8916e014bb3ab621e327f9c0ae8": {

    "reg_offset": 8,

    "field_offset": 7,

    "name": "bf1_ref",

    "slice_width": 6,

    "type": "BitFieldRef",

    "children": [

        "b138d3d5335442479f25ec4d57859cda"

    ]

},

"b138d3d5335442479f25ec4d57859cda": {

    "access": "RW",

    "name": "bf1",

    "reset_val": 74565,

    "width": 20,

    "doc": "Some documentation to describe the bit

    "type": "BitField",

    "children": [

        "ba75ebd0924a46f29f0dd1726fd5fb5f",

        "36b5d3a221e6400bba2d76a303dac2c2"

    ]

},

"ba75ebd0924a46f29f0dd1726fd5fb5f": {

    "name": "use_auto_inc",

    "value": 20,

    "type": "Enumeration"

},

"36b5d3a221e6400bba2d76a303dac2c2": {

    "name": "use_auto_dec",

    "value": 10,

    "type": "Enumeration"

},

"569715f765f14ba09313796ee98b6db6": {

    "local_address": 4,

    "name": "reg2",

    "width": 32,

    "type": "Register",

    "children": [

        "14b8d11fea244200a6d0efee16d740f7",

        "37a9c221ab77446aafe9f74ec14c78c6",

        "6f695b3dbdd74cb3abaddf82c9594e4b"

    ]

},

"14b8d11fea244200a6d0efee16d740f7": {

    "_alias": true,

    "reg_offset": 0,

    "field_offset": 0,

    "name": "bf4_ref",

    "slice_width": 2,

    "_ref": "6f695b3dbdd74cb3abaddf82c9594e4b",

    "type": "BitFieldRef"

},

"6f695b3dbdd74cb3abaddf82c9594e4b": {

    "reg_offset": 5,

    "field_offset": 2,

    "name": "bf3_ref",

    "slice_width": 5,

    "type": "BitFieldRef",

    "children": [

        "28c6a9c6929a4ad2baabc18751ec21d3"

    ]

},

"28c6a9c6929a4ad2baabc18751ec21d3": {

    "access": "R",

    "name": "bf2",

    "reset_val": 26505,

    "width": 20,

    "type": "BitField"

},

"37a9c221ab77446aafe9f74ec14c78c6": {

    "_alias": true,

    "reg_offset": 4,

    "field_offset": 3,

    "name": "bf2_ref",

    "slice_width": 4,

    "_ref": "8cded8916e014bb3ab621e327f9c0ae8",

    "type": "BitFieldRef"

},

"root": "1b99635555e647638f8a1ff38a1e3cf1"}The_refattribute facilitates modeling that one node can be an instance ofanother. Which saves duplication of common information within the serializedtree. The_aliasattribute indicates that an instance can be an alias ofanother. This simply means that the new instance's bitfields will be shared withthe source node.r_map classesCommon AttributesAll tree objects have the following common attributes:nameThe name of the itemdescrA short description of the itemdocA longer description of the itemNote that the descr and doc attributes could potentially be None or an emptystring.There are other common attributes but as a user of an r_map tree, they are notof interest.RegisterMapUsed to hold register objects.RegisterMap AttributesObjects of this class have:addressThe starting address of the register map. This may not be awfully useful asthe most interesting addresses are probably those of the child Registers.local_addressThe aforementioned address is found dynamically by summing the local_addresswith the local_addresses of the parent nodes in the tree hierarchy. Unlessyou're using a subclassed FixedRegisterMap where the local_address ==address.RegisterMap MethodsreadThis method can be used to read the current register map's data and updatethe child register's values. It relies upon a_block_read_funcfunctionhaving been added to it or some parent in the tree hierarchy.writeWrite the register map's child register values value to some destination.Note that if there are gaps between adjacent child registers, zeroes arewritten to those addresses.This method relies upon a_block_write_funchaving been added.RegisterRegister AttributesObjects of this class have the same attributes as RegisterMap objects and inaddition have a width attribute, indicating the width of the register.These are children of RegisterMap instances.Registers have the following additional attributes:valueThis is the current value of the register. It is dynamically computed basedon the current values from all of the child BitFieldRefs. It can be assigneddirectly as well and the value will update the child bitfields accordingly.reset_valThis is the reset value of the registeraccessThis indicates the access level for the register, dynamically computed basedon the child BitFieldRef's access levels. If different children havedifferent access levels, they will be'|'.joined together.Register MethodsreadThis method can be used to read the current register's data and update theregister's value. It relies upon a_reg_read_funcfunction having been addedto it or some parent in the tree hierarchy.writeWrite the register's value to some destination. Works similarly to the readfunction above and similarly relies upon a_reg_write_funchaving beenadded.BitFieldRefThese ojects represent a contribution of a bitfield within a register. Theyallow a register to provide access to only a portion of a bitfield.Alternatively they also allow multiple registers to provide access to commonbitfields or for bitfields to span multiple registers.BitFieldRef AttributesObjects of this class are children of Register instances. They have thefollowing additional attributes:reg_offsetThis is the offset within the host register that the contribution from thisobject's child bitfield starts at.slice_widthThis is the width of the slice from the child bitfield that this contributionrepresents.field_offsetThis is like the reg_offset but instead its the offset within the childbitfield that this contribution is taken from.valueThis is the value of the contribution of the child's bitfield, shifted up byreg_offsetRepresents whatvalueabove would be at reset time.bfThis attribute returns the child bitfield of the bitfield reference.BitFieldBitField AttributesObjects of this class represent a bitfield.They have the following additional attributes:widthThe width of the bit field in bitsreset_valThe value of this bit field at reset.accessThe access level of the reset_val. This is currently just for documentationsake but could conceivably be used by the user. It would contain a stringsuch as 'RW' or 'R' for example.valueThis is the current value of the bitfield.BitFieldBitField MethodsresetReset the value of this bitfield to the value specified byreset_val.annotationFind the name of a child annotation, should its value match the currentvalue, otherwise, return the value in hex.EnumerationObjects of this class are used to represent an enumeration. They are children ofBitField objects. They can be assigned directly to a BitField's value.Enumeration AttributesEnumeration objects have a value Attribute to provide the value of it.Notesthe_nb_attrsclass attribute is used to control what is serialized in eachclass instance.