README.pydoc

Help on module lopper:

NAME
    lopper

DESCRIPTION
    #/*
    # * Copyright (c) 2019,2020 Xilinx Inc. All rights reserved.
    # *
    # * Author:
    # *       Bruce Ashfield <bruce.ashfield@xilinx.com>
    # *
    # * SPDX-License-Identifier: BSD-3-Clause
    # */

CLASSES
    builtins.object
        LopperAssist
        LopperFile
        LopperSDT
    
    class LopperAssist(builtins.object)
     |  Internal class to contain the details of a lopper assist
     |  
     |  Methods defined here:
     |  
     |  __init__(self, lop_file, module='', properties_dict={})
     |      Initialize self.  See help(type(self)) for accurate signature.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
    
    class LopperFile(builtins.object)
     |  Internal class to contain the details of a lopper file
     |  
     |  Attributes:
     |     - dts: the dts source file path for a lop
     |     - dtb: the compiled dtb file path for a lop
     |     - fdt: the loaded FDT representation of the dtb
     |  
     |  Methods defined here:
     |  
     |  __init__(self, lop_file)
     |      Initialize self.  See help(type(self)) for accurate signature.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
    
    class LopperSDT(builtins.object)
     |  The LopperSDT Class represents and manages the full system DTS file
     |  
     |  In particular this class:
     |    - wraps a dts/dtb/fdt containing a system description
     |    - Has a LopperTree representation of the system device tree
     |    - manages and applies operations to the tree
     |    - calls modules and assist functions for processing of that tree
     |  
     |  Attributes:
     |    - dts (string): the source device tree file
     |    - dtb (blob): the compiled dts
     |    - FDT (fdt): the primary flattened device tree represention of the dts
     |    - lops (list): list of loaded lopper operations
     |    - verbose (int): the verbosity level of operations
     |    - tree (LopperTree): node/property representation of the system device tree
     |    - dry_run (bool): whether or not changes should be written to disk
     |    - output_file (string): default output file for writing
     |  
     |  Methods defined here:
     |  
     |  __init__(self, sdt_file)
     |      Initialize self.  See help(type(self)) for accurate signature.
     |  
     |  assist_autorun_setup(self, module_name, module_args=[])
     |  
     |  assist_find(self, assist_name, local_load_paths=[])
     |      Locates a python module that matches assist_name
     |      
     |      This routine searches both system (lopper_directory, lopper_directory +
     |      "assists", and passed paths (local_load_paths) to locate a matching
     |      python implementation.
     |      
     |      Args:
     |         assist_name (string): name of the assist to locate
     |         local_load_paths (list of strings, optional): list of directories to search
     |                                                       in addition to system dirs
     |      
     |      Returns:
     |         Path: Path object to the located python module, None on failure
     |  
     |  assists_setup(self, assists=[])
     |      assists (list,optional): list of python assist modules to load. Default is []
     |  
     |  assists_wrap(self)
     |      wrap assists that have been added to the device tree
     |      
     |      Wraps any command line assists that have been added to the system
     |      device tree. A standard lop format dtb is generated for any found
     |      assists, such that they will be loaded in the same manner as
     |      assists passed directly in lop files.
     |      
     |      Note: this is for internal use only
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         Nothing
     |  
     |  cleanup(self)
     |      cleanup any temporary or copied files
     |      
     |      Either called directly, or registered as an atexit handler. Any
     |      temporary or copied files are removed, as well as other relevant
     |      cleanup.
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         Nothing
     |  
     |  domain_spec(self, tgt_domain, tgt_domain_id='openamp,domain-v1')
     |      generate a lop for a command line passed domain
     |      
     |      When a target domain is passed on the command line, we must generate
     |      a lop dtb for it, so that it can be processed along with other
     |      operations
     |      
     |      Args:
     |         tgt_domain (string): path to the node to use as the domain
     |         tgt_domain_id (string): assist identifier to use for locating a
     |                                 registered assist.
     |      
     |      Returns:
     |         Nothing
     |  
     |  exec_lop(self, lop_node, lops_tree, options=None)
     |      Executes a a lopper operation (lop)
     |      
     |      Runs a lopper operation against the system device tree.
     |      
     |      Details of the lop are in the lops_fdt, with extra parameters and lop
     |      specific information from the caller being passed in the options
     |      variable.
     |      
     |      Args:
     |          lops_fdt (FDT): lopper operation flattened device tree
     |          lop_node_number (int): node number for the operation in lops_fdt
     |          options (dictionary,optional): lop specific options passed from the caller
     |      
     |      Returns:
     |          boolean
     |  
     |  find_compatible_assist(self, cb_node=None, cb_id='', mask='')
     |      Finds a registered assist that is compatible with a given ID
     |      
     |      Searches the registered assists for one that is compatible with an ID.
     |      
     |      The is_compat() routine is called for each registered module. If an
     |      assist is capabable of handling a given ID, it returns True and
     |      associated actions can then be taken.
     |      
     |      I addition to an ID string, a mask can optionally be provided to this
     |      routine. Any assists that have registered a mask, will have that
     |      checked, before calling the is_compat() routine. This allows assists to
     |      be generically registered, but filtered by the caller rather than only
     |      their is_compat() routines.
     |      
     |      Args:
     |          cb_node (int,optional): node offset to be tested. Default is 0 (root)
     |          cb_id (string,optional): ID to be tested for compatibility. Default is ""
     |          mask (string,optional): caller mask for filtering nodes. Default is ""
     |      
     |      Returns:
     |          function reference: the callback routine, or "", if no compatible routine found
     |  
     |  perform_lops(self)
     |      Execute all loaded lops
     |      
     |      Iterates and executes all the loaded lopper operations (lops) for the
     |      System Device tree.
     |      
     |      The lops are processed in priority order (priority specified at the file
     |      level), and the rules processed in order as they appear in the lop file.
     |      
     |      lopper operations can immediately process the output of the previous
     |      operation and hence can be stacked to perform complex operations.
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |          Nothing
     |  
     |  setup(self, sdt_file, input_files, include_paths, force=False)
     |      executes setup and initialization tasks for a system device tree
     |      
     |      setup validates the inputs, and calls the appropriate routines to
     |      preprocess and compile passed input files (.dts).
     |      
     |      Args:
     |         sdt_file (String): system device tree path/file
     |         input_files (list): list of input files (.dts, or .dtb) in addition to the sdt_file
     |         include_paths (list): list of paths to search for files
     |         force (bool,optional): flag indicating if files should be overwritten and compilation
     |                                forced. Default is False.
     |      
     |      Returns:
     |         Nothing
     |  
     |  write(self, fdt=None, output_filename=None, overwrite=True, enhanced=False)
     |      Write a system device tree to a file
     |      
     |      Write a fdt (or system device tree) to an output file. This routine uses
     |      the output filename to determine if a module should be used to write the
     |      output.
     |      
     |      If the output format is .dts or .dtb, Lopper takes care of writing the
     |      output. If it is an unrecognized output type, the available assist
     |      modules are queried for compatibility. If there is a compatible assist,
     |      it is called to write the file, otherwise, a warning or error is raised.
     |      
     |      Args:
     |          fdt (fdt,optional): source flattened device tree to write
     |          output_filename (string,optional): name of the output file to create
     |          overwrite (bool,optional): Should existing files be overwritten. Default is True.
     |          enhanced(bool,optional): whether enhanced printing should be performed. Default is False
     |      
     |      Returns:
     |          Nothing
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)

FUNCTIONS
    at_exit_cleanup()
    
    main()
    
    stdoutIO(stdout=None)
    
    usage()

DATA
    LOPPER_VERSION = '2020.4-beta'
    lopper_directory = '/home/bruce/git/system-device-tree'
    yaml_support = True

FILE
    /home/bruce/git/system-device-tree/lopper.py


Help on module lopper_tree:

NAME
    lopper_tree

DESCRIPTION
    #/*
    # * Copyright (c) 2019,2020 Xilinx Inc. All rights reserved.
    # *
    # * Author:
    # *       Bruce Ashfield <bruce.ashfield@xilinx.com>
    # *
    # * SPDX-License-Identifier: BSD-3-Clause
    # */

CLASSES
    builtins.object
        LopperNode
        LopperProp
        LopperTree
            LopperTreePrinter
    enum.Enum(builtins.object)
        LopperAction
    
    class LopperAction(enum.Enum)
     |  Enum class to define the actions available in Lopper's node_filter function
     |  
     |  Method resolution order:
     |      LopperAction
     |      enum.Enum
     |      builtins.object
     |  
     |  Data and other attributes defined here:
     |  
     |  BLACKLIST = <LopperAction.BLACKLIST: 4>
     |  
     |  DELETE = <LopperAction.DELETE: 1>
     |  
     |  NONE = <LopperAction.NONE: 5>
     |  
     |  REPORT = <LopperAction.REPORT: 2>
     |  
     |  WHITELIST = <LopperAction.WHITELIST: 3>
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from enum.Enum:
     |  
     |  name
     |      The name of the Enum member.
     |  
     |  value
     |      The value of the Enum member.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from enum.EnumMeta:
     |  
     |  __members__
     |      Returns a mapping of member name->value.
     |      
     |      This mapping lists all enum members, including aliases. Note that this
     |      is a read-only view of the internal mapping.
    
    class LopperNode(builtins.object)
     |  Class representing a device tree node
     |  
     |  This class implements:
     |     - a property iterator
     |     - dictionary access to properties
     |     - str(): string cast
     |     - equality check (==): for comparison
     |     - ref counting: set, get, clear
     |     - property add, modify, delete (via methods and '-', '+')
     |     - resolve(): to update/calculate properties against the tree
     |     - sync(): sync modified node elements (and properties)
     |     - deep node copy via LopperNode()
     |  
     |   Attributes:
     |     - number: the node number in the backing structure
     |     - name: the node name in the backing structure (this is not the node path)
     |     - parent: a link to the parent LopperNode object
     |     - tree: the tree which contains this node
     |     - depth: the nodes depth in the backing structure (0 is root, 1 for first level children)
     |     - child_nodes: the list of child LopperNodes
     |     - phandle: the phandle in the backing FDT (optional)
     |     - type: the type of the node (based on 'compatible' property)
     |     - abs_path: the full/absolute path to this node in the backing FDT
     |     - _ref: the refcount for this node
     |     - __props__: ordered dictionary of LopperProp
     |     - __current_property__: place holder for property iterator
     |     - __dbg__: debug level for the node
     |     - __nstate__: the state of the node ("init", "resolved" )
     |     - __modified__: flag indicating if the node has been modified
     |  
     |  Methods defined here:
     |  
     |  __add__(self, other)
     |      magic method for adding a property to a node
     |      
     |      Supports adding a property to a node through "+"
     |      
     |          node + <LopperProp object>
     |      
     |      Args:
     |         other (LopperProp): property to add
     |      
     |      Returns:
     |         LopperNode: returns self, Exception on invalid input
     |  
     |  __call__(self, othernode=None)
     |      Callable implementation for the node class
     |      
     |      When used, this creates a deep copy of the current node, versus
     |      a reference. This allows a node to be cloned and used in a secondary
     |      tree, free from changes to the original node.
     |      
     |      Two modes are supported:
     |         A) <LopperNode Object>()
     |         B) <LopperNode Object>( <other node> )
     |      
     |      When no other node is passed (mode A) a copy of the existing node is
     |      made, including properties with the state is set to "init", this node
     |      should then be resolved to fill in missing information.
     |      
     |      When mode B is used, the current node is updated using copies of the
     |      values from the other node. This is used on a newly created node, to
     |      initalize it with values from an existing node.
     |      
     |      Args:
     |         othernode (LopperNode,optional): node to use for initalization values
     |      
     |      Returns:
     |         The copied node, or self (if updating).
     |  
     |  __deepcopy__(self, memodict={})
     |      Create a deep copy of a node
     |      
     |      Only certain parts of a node need to be copied, we also have to
     |      trigger deep copies of properties, since they have references
     |      to nodes.
     |      
     |      We leave most values as the defaults on the new node instance,
     |      since the copied node needs to be added to a tree, where they'll
     |      be filled in.
     |  
     |  __delitem__(self, key)
     |      magic method for removing a property from a node dictionary style
     |      
     |      ** Not currently implemented **, overridden to prevent use
     |      
     |      Supports removing a property from a node through "del"
     |      
     |          del <node>[prop]
     |      
     |      Args:
     |         key (LopperProp): property/index to remove
     |      
     |      Returns:
     |         Nothing
     |  
     |  __eq__(self, other)
     |      magic method for node comparision
     |      
     |      Support LopperNode comparisons: nodea == nodeb
     |      
     |      If the node numbers of two nodes match, we consider them equal.
     |      
     |      Args:
     |          other: LopperNode
     |      
     |      Returns:
     |         LopperNode object: self
     |  
     |  __getattribute__(self, name)
     |      magic method around object attribute access
     |      
     |      This method first attempts to access the objects inherent attributes and
     |      returns the value if one exists matching the passed name.
     |      
     |      If one is not found, then the properties dictionary is checked, and that
     |      value returned.
     |      
     |      This allows access like:
     |      
     |          <LopperNode Object>.compatible
     |      
     |      To get the compatible LopperProperty value.
     |      
     |      In practice, this is only of limited use, since many property names are
     |      not valid python attribute names.
     |      
     |      Args:
     |         name: attribute name
     |      
     |      Returns:
     |         The attribute value, or AttributeError if it doesn't exist.
     |  
     |  __getitem__(self, key)
     |      magic method for accessing LopperNode properties like a dictionary
     |      
     |      Allow accessing of properties as a dictionary:
     |      
     |          <Lopper Node Object>[<property name>]
     |      
     |      This abstracts the storage of the properties and allows direct access
     |      by name. Either the string name of the property may be used, or a
     |      LopperProp object itself.
     |      
     |      The standard KeyError exception is raised if the property is not valid for
     |      a node.
     |      
     |      For an exception free way of checking for a property, see the propval()
     |      method.
     |      
     |      Args:
     |          key: string or LopperProp
     |      
     |      Returns:
     |         LopperProp object or KeyError exception
     |  
     |  __hash__(self)
     |      magic method for hasing a node
     |      
     |      Used when searching for a node in a list (among other things). We return
     |      the hash of a nodes absolute path as the identity value.
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |         Integer hash for the node
     |  
     |  __init__(self, number=-1, abspath='', tree=None, phandle=-1, name='', debug=0)
     |      Initialize self.  See help(type(self)) for accurate signature.
     |  
     |  __int__(self)
     |      magic method for int type conversion of LopperNode
     |      
     |      If a LopperNode is converted to an int, we use the node number
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |         int: the node number
     |  
     |  __iter__(self)
     |      magic method to support iteration
     |      
     |      For iterating the properties of a LopperNode, we are the iterator.
     |      This is required by the iterator protocol.
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |         LopperNode object: self
     |  
     |  __next__(self)
     |      magic method for iteration on a node
     |      
     |      This routine uses the __current_property__ attribute to move
     |      through the properties of a node.
     |      
     |      If there are no properties, or we have iterated all properties,
     |      StopIteration is raised (as is required by the iterator protocol).
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |         LopperProp object or StopIteration exception
     |  
     |  __setattr__(self, name, value)
     |      magic method to check the setting of a LopperNode attribute
     |      
     |      If the attribute being set is the debug level (__dbg__), this wrapper
     |      chains the setting to any LopperProps of the node.
     |      
     |      If the attribute is any other, we set the value and tag the node as
     |      modified, so it can be sync'd later.
     |      
     |      Args:
     |         name: attribute name
     |         value: attribute value
     |      
     |      Returns:
     |         Nothing
     |  
     |  __setitem__(self, key, val)
     |      magic method for setting LopperNode properties like a dictionary
     |      
     |      Allow setting of properties as a dictionary:
     |      
     |          <Lopper Node Object>[<property name>] = <LopperProperty Object>
     |      
     |             or
     |      
     |          <Lopper Node Object>[<property name>] = [list of property values]
     |      
     |      
     |      This abstracts the storage of the properties and allows direct access
     |      by name.
     |      
     |      If a LopperProp is passed as 'val', it is directly assigned. If a list
     |      of values is passed, a LopperProp object is created, the values assigned
     |      and then placed in the property dictionary.
     |      
     |      Args:
     |          key: string
     |          val: LopperProp or string
     |      
     |      Returns:
     |         Nothing
     |  
     |  __str__(self)
     |      magic method for string type conversion of LopperNode
     |      
     |      If a LopperNode is converted to a string, we use the absolute (full) path
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |         string: the abs path
     |  
     |  __sub__(self, other)
     |      magic method for removing a property from a node
     |      
     |      Supports removing a property from a node through "-"
     |      
     |          node - <LopperProp object>
     |      
     |      Args:
     |         other (LopperProp): property to remove
     |      
     |      Returns:
     |         LopperNode: returns self
     |  
     |  add(self, prop)
     |      Add a property or subnode to a node
     |      
     |      Supports adding a property or node to a node through
     |      
     |          node.add( prop )
     |      
     |      After adding the new elelent, the node is tagged as modified to it
     |      can be sync'd in the future.
     |      
     |      Args:
     |         prop (LopperProp or LopperNode): element to add
     |      
     |      Returns:
     |         LopperNode: returns self, raises Exception on invalid parameter
     |  
     |  delete(self, prop)
     |      delete a property from a node
     |      
     |      Queues a property for deletion on the next sync of a node.
     |      
     |      Takes a property name or LopperProp object as the parameter, and if
     |      it is a valid property, queues it for deletion.
     |      
     |      The node is marked as modified, so on the next sync, it will be remove.
     |      
     |      Args:
     |         prop (string or LopperProp): the property to delete
     |      
     |      Returns:
     |         Nothing. KeyError if property is not found
     |  
     |  export(self)
     |      Export node details as a dictionary
     |      
     |      Export the details of a node in a dictionary. The format of the dictionary
     |      is suitable for loading() into a LopperTree, or syncing() to a flattened
     |      device tree by lopper_fdt.
     |      
     |      Internal / FDT properties are prefixed/suffixed with __.
     |      
     |      As part of exporting a node, if paths are detected as changed (a moved
     |      node, a renamed node, etc), then the are adjusted in the tree and
     |      exported in the dictionary.
     |      
     |      Note: This is not recursive, so child nodes are not exported
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         Ordered Dict Describing a node
     |  
     |  load(self, dct, parent_path=None)
     |      load (calculate) node details against a property dictionary
     |      
     |      Some attributes of a node are not known at initialization time, or may
     |      change due to tree operations.
     |      
     |      This method calculates those values using information in the node and in
     |      the passed property dictionary
     |      
     |      The only value that must be set in the node before resolve() is called
     |      is the node number.
     |      
     |      Fields resolved (see class for descriptions)
     |         - name
     |         - abs_path
     |         - phandle
     |         - depth
     |         - children
     |         - type
     |         - __props__
     |         - __nstate__
     |         - __modified__
     |      
     |      Args:
     |         Property dictionary: Dictionary with the node details/properties
     |         parent_path (Optional,string)
     |      
     |      Returns:
     |         Nothing
     |  
     |  phandle_or_create(self)
     |      Access (and generate) a phandle for this node
     |      
     |      Invoked the containing tree (if available), ad creates a unique phandle
     |      for a node. This is basic tracking and is used since
     |      fdt_find_max_phandle is not fully exposed, and removes a binding to
     |      libfdt.
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         phandle number
     |  
     |  print(self, output=None, strict=None)
     |      print a node
     |      
     |      Print a node to the passed output stream. If it isn't passed, then
     |      the containg tree's output is used. If the tree has no output, stdout
     |      is the final fallback.
     |      
     |      The node  will be indented to match the depth of a node
     |      in a tree.
     |      
     |      Args:
     |         output (optional, output stream).
     |      
     |      Returns:
     |         Nothing
     |  
     |  props(self, name)
     |      Access a property or list of properties described by a name/regex
     |      
     |      Looks through the properties of a node and returns any that match
     |      the name or regex passed to the routine.
     |      
     |      Args:
     |         name (string): property name or property regex
     |      
     |      Returns:
     |         list: list of LopperProp objects that match the name/regex, or [] if none match
     |  
     |  propval(self, pname, ptype=None)
     |      Access the value of a property
     |      
     |      This is a safe (no Exception) way to access the value of a named property,
     |      versus access it through the dictionary accessors.
     |      
     |      Args:
     |         name (string): property name
     |         ptype(Optional): the format of the returned value
     |      
     |      Returns:
     |         list: list of values for the property, or [""] if the property name is invalid
     |  
     |  reset(self)
     |      reset the iterator of the node
     |      
     |      Sets the node iteration index to the starting value.
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         None
     |  
     |  resolve(self, fdt=None)
     |      resolve (calculate) node details against a FDT
     |      
     |      Some attributes of a node are not known at initialization time, or may
     |      change due to tree operations.
     |      
     |      This method calculates those values using information in the node and in
     |      the passed FDT. If no FDT is passed only partial resolution is done.
     |      
     |      The only value that must be set in the node before resolve() is called
     |      is the node number. Which simply means it should have been added to the
     |      FDT first (see LopperTree.add()) and then resolved.
     |      
     |      Fields resolved (see class for descriptions)
     |         - name
     |         - abs_path
     |         - phandle
     |         - depth
     |         - children
     |         - type
     |         - __props__
     |         - __nstate__
     |         - __modified__
     |      
     |      Args:
     |         fdt (FDT): flattened device tree to sync to or None if no
     |                    tree is available
     |      
     |      Returns:
     |         Nothing
     |  
     |  resolve_all_refs(self, property_mask=[])
     |      Resolve and Return all references in a node
     |      
     |      Finds all the references starting from a given node. This includes:
     |      
     |         - The node itself
     |         - The parent nodes
     |         - Any phandle referenced nodes, and any nodes they reference, etc
     |      
     |      Args:
     |         property_mask (list of regex): Any properties to exclude from reference
     |                                        tracking, "*" to exclude all properties
     |      
     |      Returns:
     |         A list of referenced nodes, or [] if no references are found
     |  
     |  subnodes(self, depth=0, max_depth=None, children_only=False)
     |      Return all the subnodes of this node
     |      
     |      Gathers and returns all the reachable subnodes of the current node
     |      (this includes nodes of children, etc).
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         A list of child LopperNodes
     |  
     |  sync(self, fdt=None)
     |      sync a LopperNode to a backing FDT
     |      
     |      This routine looks for changes to the LopperNode and writes them back
     |      to the passed FDT.
     |      
     |      For the node itself, this is primarily a write back of a changed name.
     |      
     |      As part of the sync process, the node's number in the backing FDT is
     |      checked and the stored number changed to match as appropriate.
     |      
     |      We also check fo modified properties and sync them to the FDT.
     |      
     |      Removed properties are deleted from the FDT.
     |      
     |      And finally, the __modified__ flag is set to False.
     |      
     |      Args:
     |         fdt (FDT): device tree to sync against
     |      
     |      Returns:
     |         boolean: True if the node was sync'd, False otherwise
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
     |  
     |  ref
     |      Node reference count getter
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         int: The node refcount
    
    class LopperProp(builtins.object)
     |  Class representing a device tree property
     |  
     |  This class implements:
     |     - resolve(): to update information / state against a device tree
     |     - sync(): to write changes back to the device tree
     |     - utility routines for easy access and iteration of the values
     |  
     |  Attributes:
     |     - __modified__: Flag to indicate if the property has been changed
     |     - __pstate__: The state of the property. For internal use only.
     |                   Values can be: "init", "resolved", "syncd" or "deleted"
     |     - __dbg__: The debug/verbosity level of property operations. 0 is no
     |                debug, and levels increase from there.
     |  
     |     - name: The property name
     |     - value: The property value (always as a list of values)
     |     - node: The node that contains this property
     |     - number: The property offset within the containing node (rarely used)
     |     - string_val: The enhanced printed string representation of a property
     |     - type: The type of a property, "comment", "preamble" or "list"
     |     - abs_path: The absolute device tree path to this property
     |  
     |  Methods defined here:
     |  
     |  __deepcopy__(self, memodict={})
     |      Create a deep copy of a property
     |      
     |      Properties have links to nodes, so we need to ensure that they are
     |      cleared as part of a deep copy.
     |  
     |  __getitem__(self, key)
     |      Access a property's value by key
     |      
     |      Allows the property's value to be access by 'index', since
     |      properties are normally lists of value.
     |      
     |      If the property is a special type, i.e. a json pclass, then
     |      the value is expanded and indexed. Otherwise, the value list
     |      is simply indexed
     |      
     |      Non-integer keys return None. Unless "value" is used as a key
     |      and you get the raw/entire value list.
     |      
     |      Normal list exceptions are raised if you index outside of the
     |      range of the value
     |      
     |      Args:
     |        Key (int or "value")
     |      
     |      Returns:
     |        The item at the specified index
     |  
     |  __init__(self, name, number=-1, node=None, value=None, debug_lvl=0)
     |      Initialize self.  See help(type(self)) for accurate signature.
     |  
     |  __iter__(self)
     |      magic method to support iteration
     |      
     |      This allows the values of a property to be iterated, which
     |      isn't very useful. But it is useful that functions like dict()
     |      take this iterator and create a usable dictionary for the
     |      caller.
     |      
     |      If the property is special, like json, then you get an
     |      keyed return of 'value' and the loaded value
     |      
     |      if the property is standard, you get a keyed return of
     |      'value' and the value list
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |         iterator for use in dict()
     |  
     |  __len__(self)
     |      Get the length of a property
     |      
     |      When using the __getitem__ access to property values, knowing
     |      the length is important.
     |      
     |      if the property is a special class (i.e. json), the lenght of
     |      the loaded list is returned.
     |      
     |      if the values are a list, the lenght of that list is returned
     |      
     |      if the value is a single item, 0 is returned
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         Int: The lenght of the list
     |  
     |  __setattr__(self, name, value)
     |      magic method to check the setting of a LopperProp attribute
     |      
     |      If the attribute being set is "value" (i.e. LopperProp.value), this
     |      method makes sure that it is stored as a list, that the property is
     |      marked as modified (for future write backs) and triggers a resolve()
     |      of the property value.
     |      
     |      Args:
     |         name: attribute name
     |         value: attribute value
     |      
     |      Returns:
     |         Nothing
     |  
     |  __str__(self)
     |      The string representation of the property
     |      
     |      Returns the enhanced printed property when str() is used to access
     |      an object.
     |      
     |      The string_val is composed in the resolv() function, and takes the
     |      format of:  <property name> = <property value>;
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         string
     |  
     |  compare(self, other_prop)
     |      Compare one property to another
     |      
     |      Due to the complexity of property representations, this compare is
     |      not a strict 1:1 value equality. It looks through various elements
     |      of the source and comparision properties to decide if they have
     |      common components.
     |      
     |      The following metrics are used, where "single" means a property with
     |      a single value (string or number) and "list" is a property with
     |      multiple strings or integer properties.
     |      
     |        comparison types:
     |             single -> list:   single must be somewhere in the list
     |                                  - for strings, single may be a regex
     |             single -> single: single must be in or equal the other
     |                                  - for strings, single may be a regex
     |             list -> single:   any value in list must match single
     |                                  - for strings, list elements can be regexs
     |             list -> list:     all individual elements must match
     |                                  - NO regexs allowed
     |      
     |      Args:
     |         other_prop (LopperProp): comparison target
     |         value: attribute value
     |      
     |      Returns:
     |         boolean: True there is a match, false otherwise
     |  
     |  hex(self)
     |      Get the property value as a list of hex formatted numbers
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         list: hex formatted property value
     |  
     |  int(self)
     |      Get the property value as a list of integers
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         list: integer formatted property value
     |  
     |  phandle_params(self)
     |      Determines the phandle elements/params of a property
     |      
     |      Takes a property name and returns where to find a phandle in
     |      that property.
     |      
     |      Both the index of the phandle, and the number of fields in
     |      the property are returned.
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |          The the phandle index and number of fields, if the node can't
     |          be found 0, 0 are returned.
     |  
     |  print(self, output)
     |      print a property
     |      
     |      Print the resolved value of a property to the passed output
     |      stream.
     |      
     |      The property will be indented to match the depth of a node
     |      in a tree.
     |      
     |      Args:
     |         output (output stream).
     |      
     |      Returns:
     |         Nothing
     |  
     |  property_type_guess(self, force=False)
     |      'guess' the type of a property
     |      
     |      For properties that aren't created from a fdt, we can either
     |      explicitly set the type (if we know it), or we can run this routine
     |      to look at the values and give us the best guess.
     |      
     |      This routine does NOT update the property type, that is the
     |      responsibility of the caller.
     |      
     |      Args:
     |         force: if the property already has a type, ignore it and guess anyway
     |      
     |      Returns:
     |         type of the propery (LopperFmt)
     |  
     |  resolve(self, strict=True)
     |      resolve (calculate) property details
     |      
     |      Some attributes of a property are not known at initialization
     |      time, or may change due to tree operations.
     |      
     |      This method calculates those values using information in the
     |      property and in the tree
     |      
     |      Fields resolved:
     |         - abs_path
     |         - type
     |         - string_val (with phandles resolved)
     |         - __pstate__
     |      
     |      Args:
     |           None
     |      
     |      Returns:
     |         Nothing
     |  
     |  resolve_phandles(self, tag_invalid=False)
     |      Resolve the targets of any phandles in a property
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |          A list of all resolved phandle node numbers, [] if no phandles are present
     |  
     |  sync(self, fdt)
     |      sync the property to a backing FDT
     |      
     |      Writes the property value to the backing flattended device tree. After
     |      write, the state is set to  "syncd" and the modified flat is cleared.
     |      
     |      Args:
     |         fdt (FDT): flattened device tree to sync to
     |      
     |      Returns:
     |         boolean: True if the property was sync'd, otherwise False
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
    
    class LopperTree(builtins.object)
     |  Class for walking a device tree, and providing callbacks at defined points
     |  
     |  This class implements:
     |     - a node iterator
     |     - dictionary access to nodes by path or node number
     |     - a tree walker / exec() that has callbacks for: tree start, node start,
     |       property start, node end, tree end
     |     - debug level
     |     - tree wide reference tracking control: clear, get
     |     - sync(): to sync changes to a backing FDT
     |     - export(): to export the tree description as a dictionary
     |     - node manipulatins: add, delete, filter, subnodes
     |     - phandle access to nodes
     |     - label access to nodes
     |     - node search by regex
     |  
     |  A LopperTree object is instantiated for an easier/structure interface to a backing
     |  device tree store (currently only a flattened device tree from libfdt). It provides
     |  the ability to add/delete/manipulate nodes on a tree wide basis and can sync those
     |  changes to the backing store.
     |  
     |  When initialized, the tree is created from an exported description of the
     |  FDT. If the changes made by the tree  are to be indepdendent, then the FDT
     |  should not be re-exported and loaded by the tree. But if other components are
     |  changing the FDT, it can be reloaded to synchronize the tree and the backing
     |  store.
     |  
     |  During the walking of a tree via exec(), callbacks are made (if set) at defined
     |  points in the process. This makes it easy to implement structured output of a
     |  tree, without the need to have deep encoding/understanding of the underlying
     |  structure.
     |  
     |  Callbacks are functions of the form: <fn>( <node or property>, FDT )
     |  
     |  Attributes:
     |     - __nodes__: The nodes of the tree, ordered by absolute path indexing
     |     - __nnodes__: The nodes of the tree, ordered by node number
     |     - __pnodes__: The nodes of the tree, ordered by phandle
     |     - __dbg__: treewide debug level
     |     - __must_sync__: flag, true when the tree must be syncd to the FDT
     |     - __current_node__: The current node in an iteration
     |     - __start_node__: The starting node for an iteration
     |     - __new_iteration__: Flag set to start a new iteration
     |     - __node_iter__: The current iterator
     |     - start_tree_cb, start_node_cb, end_node_cb, property_cb, end_tree_cb: callbacks
     |     - depth_first: not currently implemented
     |     - strict: Flag indicating if strict property resolution should be enforced
     |  
     |  Methods defined here:
     |  
     |  __add__(self, other)
     |      magic method for adding a node to a tree
     |      
     |      Supports adding a node to a tree through "+"
     |      
     |          tree + <LopperNode object>
     |      
     |      Args:
     |         other (LopperNode): node to add
     |      
     |      Returns:
     |         LopperTree: returns self, Exception on invalid input
     |  
     |  __delitem__(self, key)
     |      magic method for removing a property from a tree dictionary style
     |      
     |      ** Not currently implemented **, overridden to prevent use
     |      
     |      Supports removing a node from a tree through "del"
     |      
     |          del <tree>[node]
     |      
     |      Args:
     |         key (LopperNode): node/index to remove
     |      
     |      Returns:
     |         Nothing
     |  
     |  __getattribute__(self, name)
     |      magic method around object attribute access
     |      
     |      This method first attempts to access the objects inherent attributes and
     |      returns the value if one exists matching the passed name.
     |      
     |      If one is not found, then the node dictionary is checked, and that
     |      value returned.
     |      
     |      This allows access like:
     |      
     |          <LopperTree Object>.path_to_node
     |      
     |      To get the LopperNode at that path
     |      
     |      In practice, this is only of limited use, since many node paths are
     |      not valid python attribute names.
     |      
     |      Args:
     |         name: attribute name
     |      
     |      Returns:
     |         The attribute value, or AttributeError if it doesn't exist.
     |  
     |  __getitem__(self, key)
     |      magic method for accessing LopperTree nodes like a dictionary
     |      
     |      Allow accessing of nodes as a dictionary:
     |      
     |          <Lopper Tree Object>[<node path>]
     |      
     |      This abstracts the storage of nodesand allows direct access by name,
     |      by number or by node regex.
     |      
     |      Either the string name of the node path, the node number, a LopperNode
     |      object, or a node path with a regex can be used to access a node.
     |      
     |      Note that on a regex search, the first match is returned. For multiple
     |      node returns, use the nodes() method.
     |      
     |      The standard KeyError exception is raised if the node is not valid for
     |      a tree
     |      
     |      Args:
     |          key: string, int or LopperNode
     |      
     |      Returns:
     |         LopperNode object or KeyError exception
     |  
     |  __init__(self, snapshot=False, depth_first=True)
     |      Initialize self.  See help(type(self)) for accurate signature.
     |  
     |  __iter__(self)
     |      magic method to support iteration
     |      
     |      For iterating the nodes of a LopperTree, we are the iterator.
     |      This is required by the iterator protocol.
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |         LopperTree object: self
     |  
     |  __next__(self)
     |      magic method for iteration on a tree
     |      
     |      This routine uses the next() method to move through the nodes of a
     |      tree.
     |      
     |      If there are no nodes, or we have iterated all nodes, StopIteration is
     |      raised (as is required by the iterator protocol).
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |         LopperNode object or StopIteration exception
     |  
     |  __setattr__(self, name, value)
     |      magic method to check the setting of a LopperTree attribute
     |      
     |      If the attribute being set is __current_node__ or __start_node__
     |      then the new iteration flag is set to trigger the start of a new
     |      iteration. When setting these attributes, value can either be a
     |      node number or a node name. When it is a name, it is internally
     |      converted to a number on behalf of the caller.
     |      
     |      If the attribute is __dbg__, then the debug setting is chained
     |      to contained nodes.
     |      
     |      Args:
     |         name: attribute name
     |         value: attribute value
     |      
     |      Returns:
     |         Nothing
     |  
     |  __setitem__(self, key, val)
     |      magic method for setting LopperTree nodes like a dictionary
     |      
     |              Allow setting of properties as a dictionary:
     |      
     |                  <Lopper Tree Object>[<node name>] = <LopperNode Object>
     |      
     |                     or
     |      
     |                  <Lopper Tree Object>[<node number>] =  <LopperNode Object>
     |      
     |              During assignment of the node, access is created by name, number and
     |              phandle as appropriate
     |      
     |              Args:
     |                  key: string or int
     |                  val: LopperNode
     |      
     |              Returns:
     |      ;           Nothing, raises TypeError on invalid parameters
     |  
     |  __sub__(self, other)
     |      magic method for removing a node from a tree
     |      
     |      Supports removing a node from a tree through "-"
     |      
     |          tree - <LopperNode object>
     |      
     |      Args:
     |         other (LopperNode): Node to remove
     |      
     |      Returns:
     |         LopperTree: returns self
     |  
     |  add(self, node, dont_sync=False)
     |      Add a node to a tree
     |      
     |      Supports adding a node to a tree through:
     |      
     |          tree.add( <node> )
     |      
     |      The node is added to the FDT, resolved and syncd. It is then available
     |      for use in any tree operations.
     |      
     |      Args:
     |         node (LopperNode): node to add
     |         dont_sync (boolean, optional): don't invoke a tree wide sync when
     |                                        complete
     |      
     |      Returns:
     |         LopperTree: returns self, raises Exception on invalid parameter
     |  
     |  delete(self, node, delete_from_parent=True)
     |      delete a node from a tree
     |      
     |      If a node is resolved and syncd to the FDT, this routine deletes it
     |      from the FDT and the LopperTree structure.
     |      
     |      Args:
     |         node (int or LopperNode): the node to delete
     |         delete_fom_parent (bool): flag indicating if the node should be
     |                                   removed from the parent node.
     |      
     |      Returns:
     |         Boolean: True if deleted, False otherwise. KeyError if node is not found
     |  
     |  exec(self)
     |      Start a tree walk execution, with callbacks executed as required
     |      
     |      Starts walking the tree, beginning at the preamble, and then through a depth
     |      first walking of the nodes.
     |      
     |      If the tree has registered callbacks, they are executed before the walk
     |      starts, at the start/end of each node, at each property and at the end of
     |      the tree.
     |      
     |      See the class description for details on the callbacks
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         Nothing
     |  
     |  exec_cmd(self, node, cmd, env=None, module_list=[])
     |      Execute a (limited) code block against a node
     |      
     |      Execute a python clode block with the 'node' context set to the
     |      value passed to this routine.
     |      
     |      The "cmd" python code, runs in a constructed/safe environment to ensure
     |      that the code won't cause harmful sideffects to the execution
     |      environment.
     |      
     |      The following functions and variables are currently available in the
     |      safe_dict:
     |      
     |          len
     |          print
     |          verbose
     |      
     |      When executing in the code context, the following variables are
     |      available to the python code block.
     |      
     |          tree : the LopperTree object containing the node
     |          node : the LopperNode being processed
     |          __selected__ : the list of LopperNodes being processed
     |          node_name : the name of the node (as defined by the dts/dtb)
     |          node_number : the number of the node being processed
     |      
     |      The return value of the block is sent to the caller, so it can act
     |      accordingly.
     |      
     |      Args:
     |          node (LopperNode or string): starting node
     |          cmd (string): block of python code to execute
     |          env (dictionary,optional): values to make available as
     |                                     variables to the code block
     |          module_list (list,optional): list of assists to load before
     |                                       running the code block
     |      
     |      Returns:
     |          Return value from the execution of the code block
     |  
     |  export(self, start_path='/')
     |  
     |  filter(self, node_prefix, action, test_cmd, fdt=None, verbose=0)
     |      Filter tree nodes and perform an action
     |      
     |      Starting from the supplied path (node_prefix), this function walks
     |      the device tree and executes a block of python code to test each
     |      node.
     |      
     |      If the block of code (test_cmd) returns True, then the action is
     |      taken. If false, nothing is done.
     |      
     |      Currently defined actions:
     |      
     |         - delete: delete the node
     |         - report: (not currently implemented)
     |         - whitelist: (not currently implemented)
     |         - blacklist: (not currently implemented)
     |      
     |      The "test_cmd" python code, runs in a constructed/safe environment to
     |      ensure that the code won't cause harmful sideffects to the execution
     |      environment. See the exec_cmd method for details of the command
     |      execution.
     |      
     |      A standard python "return True" and "return False" should be used to
     |      indicate the result of the test.
     |      
     |      Args:
     |          node_prefix (string): starting node path
     |          action (LopperAction): action to take in the True condition
     |          test_cmd (string): block of python code to test against each node
     |          fdt (FDT,optional): flattended device tree for reference
     |          verbose (int,optional): verbosity level to use.
     |      
     |      Returns:
     |          Nothing
     |  
     |  lnodes(self, label)
     |      Find nodes in a tree by label
     |      
     |      Safely (no exception raised) returns the node that can be found
     |      at a given label value.
     |      
     |      Args:
     |         label (string): node string  to check
     |      
     |      Returns:
     |         list (LopperNode): the matching nodes if found, [] otherwise
     |  
     |  load(self, dct=None)
     |      load a tree
     |      
     |      Loads the details around the nodes of a tree, and completes values that
     |      are not possible at initialization time.
     |      
     |      In particular, it updates the path, node and phandle ordered
     |      dictionaries to reflect the dictionary. This is often done after a node
     |      is added to ensure that iterations will see the new node in tree order,
     |      versus added order.
     |      
     |      Args:
     |         dct (Dictionary): dictionary from a lopper_fdt export, or a tree export
     |      
     |      Returns:
     |         Nothing
     |  
     |  next(self)
     |      Returns the next node in a tree iteration
     |      
     |      This method maintains the iteration state of a tree and returns
     |      the next LopperNode in the iteration.
     |      
     |      Three types of iterations are common:
     |      
     |        - full iteration: a depth first walk of every node in the tree
     |        - subnode iteration: a depth first walk of all nodes under a given
     |                             starting point
     |        - startnode iteration: A depth first walk starting at a given node
     |                               and continuing to the end of the tree
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         LopperNode
     |  
     |  nodes(self, nodename)
     |      Get nodes that match a given name or regex
     |      
     |      Looks for a node at a name/path, or nodes that match a regex.
     |      
     |      Args:
     |         nodename (string): node name or regex
     |      
     |      Returns:
     |         list: a list all nodes that match the name or regex
     |  
     |  phandle_gen(self)
     |      Generate a phandle for use in a node
     |      
     |      Creates a unique phandle for a node. This is basic tracking and is
     |      used since fdt_find_max_phandle is not fully exposed, and removes
     |      a binding to libfdt.
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         phandle number
     |  
     |  phandles(self)
     |      Utility function to get the active phandles in the tree
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         list (numbers): list of in use phandles in the tree
     |  
     |  pnode(self, phandle)
     |      Find a node in a tree by phandle
     |      
     |      Safely (no exception raised) returns the node that can be found
     |      at a given phandle value.
     |      
     |      Args:
     |         phandle (int): node phandle to check
     |      
     |      Returns:
     |         LopperNode: the matching node if found, None otherwise
     |  
     |  print(self, output=None)
     |      print the contents of a tree
     |      
     |      Outputs the tree to the passed output stream, if not passed the tree's
     |      output stream is used. If the tree has no output stream, stdout is the
     |      final fallback.
     |      
     |      Args:
     |         output (optional,output stream).
     |      
     |      Returns:
     |         Nothing
     |  
     |  ref(self, value, node_regex=None)
     |      Tree wide setting of a refcount
     |      
     |      Sets a refcount for all nodes in the tree, or a regex contained set
     |      of nodes.
     |      
     |      Calling this routine with zero, is a treewide reset of all refcounts.
     |      
     |      If a regex is passed, only matching nodes will be set/cleared.
     |      
     |      Args:
     |         value (int): refcount value by which to increment
     |         node_regex (string,optional): node path regex to restrict scope of
     |                                       refcount operations
     |      
     |      Returns:
     |         Nothing
     |  
     |  ref_all(self, starting_node, parent_nodes=False)
     |      Increment the refcount for a node and its subnodes (and optionally parents)
     |      
     |      Creates a reference to a node and its subnodes.
     |      
     |      If parent_nodes is set to True, parent nodes will be also referenced.
     |      
     |      Args:
     |         starting_node (LopperNode): node to reference
     |         parent_nodes (boolean,optional): flag to indicate if parent nodes
     |                                          should be referenced
     |      
     |      Returns:
     |         Nothing
     |  
     |  refd(self, node_regex='')
     |      Get a list of referenced nodes
     |      
     |      When refcounting is enabled, this routine returns the list of nodes
     |      that have been referenced.
     |      
     |      We use the name, rather than the offset, since the offset can change if
     |      something is deleted from the tree. But we need to use the full path so
     |      we can find it later.
     |      
     |      Args:
     |         node_regex: limit returned nodes to those that match the regex, which
     |                     is applied to the path of the nodes.
     |      
     |      Returns:
     |         list (strings): list of referenced nodes, or [] if there are no referenced nodes
     |  
     |  reset(self)
     |      reset a tree
     |      
     |      Resets certain parts of the tree to their initial values. Specifically
     |      it resets the tree for a new iteration.
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         Nothing
     |  
     |  resolve(self)
     |  
     |  subnodes(self, start_node, node_regex=None)
     |      return the subnodes of a node
     |      
     |      Returns a list of all subnodes from a given starting node.
     |      
     |      If a node regex is passed, those nodes that do not match the
     |      regex are removed from the returned value.
     |      
     |      Args:
     |         start_node (LopperNode): the starting node
     |         node_regex (string,optional): node mask
     |      
     |      Returns:
     |         list: returns a list of all subnodes (or matching subnodes)
     |  
     |  sync(self, fdt=None, only_if_required=False)
     |      Sync a tree to a backing FDT
     |      
     |      This routine walks the FDT, and sync's changes from any LopperTree nodes
     |      into the backing store.
     |      
     |      Once complete, all nodes are resolved() to ensure their attributes reflect
     |      the FDT status.
     |      
     |      Args:
     |         fdt (FDT,optional): the flattended device tree to sync to. If it isn't
     |                             passed, the stored FDT is use for sync.
     |         only_if_required(boolean,optional): flag to indicate that we should only
     |                                             sync if something is dirty
     |      
     |      Returns:
     |         Nothing
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
    
    class LopperTreePrinter(LopperTree)
     |  SubClass for enhanced printing a lopper tree
     |  
     |  This class implements:
     |     - routines to print the start of a tree, nodes, properties and end of a tree
     |       to DTS format.
     |  
     |  Enhanced printing is done by implementing callbacks that the base LopperTree
     |  class will call during a tree walk.
     |  
     |  Attributes:
     |     - output: output file name, if not passed stdout is used
     |  
     |  Method resolution order:
     |      LopperTreePrinter
     |      LopperTree
     |      builtins.object
     |  
     |  Methods defined here:
     |  
     |  __init__(self, snapshot=False, output=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, debug=0)
     |      Initialize self.  See help(type(self)) for accurate signature.
     |  
     |  end(self, n)
     |      LopperTreePrinter tree end
     |      
     |      Ends the walking of a tree
     |      
     |      Args:
     |          n (LopperNode): -1
     |      
     |      Returns:
     |          Nothing
     |  
     |  end_node(self, n)
     |      LopperTreePrinter node end
     |      
     |      Prints the end / closing of a node
     |      
     |      Args:
     |          n (LopperNode): the node being closed
     |      
     |      Returns:
     |          Nothing
     |  
     |  reset(self, output_file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)
     |      reset the output of a printer
     |      
     |      closes the existing output_file (if not stdout) and opens a new
     |      output_file (if not stdout)
     |      
     |      Args:
     |          output_file (string,optional): name of file to open for output, default is stdout
     |      
     |      Returns:
     |          Nothing
     |  
     |  start(self, n)
     |      LopperTreePrinter start
     |      
     |      Prints the start / opening of a tree and handles the preamble.
     |      
     |      Args:
     |          n (LopperNode): the opening node of the tree
     |      
     |      Returns:
     |          Nothing
     |  
     |  start_node(self, n)
     |      LopperTreePrinter node start
     |      
     |      Prints the start / opening of a node
     |      
     |      Args:
     |          n (LopperNode): the node being opened
     |      
     |      Returns:
     |          Nothing
     |  
     |  start_property(self, p)
     |      LopperTreePrinter property print
     |      
     |      Prints a property
     |      
     |      Args:
     |          p (LopperProperty): the property to print
     |      
     |      Returns:
     |          Nothing
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from LopperTree:
     |  
     |  __add__(self, other)
     |      magic method for adding a node to a tree
     |      
     |      Supports adding a node to a tree through "+"
     |      
     |          tree + <LopperNode object>
     |      
     |      Args:
     |         other (LopperNode): node to add
     |      
     |      Returns:
     |         LopperTree: returns self, Exception on invalid input
     |  
     |  __delitem__(self, key)
     |      magic method for removing a property from a tree dictionary style
     |      
     |      ** Not currently implemented **, overridden to prevent use
     |      
     |      Supports removing a node from a tree through "del"
     |      
     |          del <tree>[node]
     |      
     |      Args:
     |         key (LopperNode): node/index to remove
     |      
     |      Returns:
     |         Nothing
     |  
     |  __getattribute__(self, name)
     |      magic method around object attribute access
     |      
     |      This method first attempts to access the objects inherent attributes and
     |      returns the value if one exists matching the passed name.
     |      
     |      If one is not found, then the node dictionary is checked, and that
     |      value returned.
     |      
     |      This allows access like:
     |      
     |          <LopperTree Object>.path_to_node
     |      
     |      To get the LopperNode at that path
     |      
     |      In practice, this is only of limited use, since many node paths are
     |      not valid python attribute names.
     |      
     |      Args:
     |         name: attribute name
     |      
     |      Returns:
     |         The attribute value, or AttributeError if it doesn't exist.
     |  
     |  __getitem__(self, key)
     |      magic method for accessing LopperTree nodes like a dictionary
     |      
     |      Allow accessing of nodes as a dictionary:
     |      
     |          <Lopper Tree Object>[<node path>]
     |      
     |      This abstracts the storage of nodesand allows direct access by name,
     |      by number or by node regex.
     |      
     |      Either the string name of the node path, the node number, a LopperNode
     |      object, or a node path with a regex can be used to access a node.
     |      
     |      Note that on a regex search, the first match is returned. For multiple
     |      node returns, use the nodes() method.
     |      
     |      The standard KeyError exception is raised if the node is not valid for
     |      a tree
     |      
     |      Args:
     |          key: string, int or LopperNode
     |      
     |      Returns:
     |         LopperNode object or KeyError exception
     |  
     |  __iter__(self)
     |      magic method to support iteration
     |      
     |      For iterating the nodes of a LopperTree, we are the iterator.
     |      This is required by the iterator protocol.
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |         LopperTree object: self
     |  
     |  __next__(self)
     |      magic method for iteration on a tree
     |      
     |      This routine uses the next() method to move through the nodes of a
     |      tree.
     |      
     |      If there are no nodes, or we have iterated all nodes, StopIteration is
     |      raised (as is required by the iterator protocol).
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |         LopperNode object or StopIteration exception
     |  
     |  __setattr__(self, name, value)
     |      magic method to check the setting of a LopperTree attribute
     |      
     |      If the attribute being set is __current_node__ or __start_node__
     |      then the new iteration flag is set to trigger the start of a new
     |      iteration. When setting these attributes, value can either be a
     |      node number or a node name. When it is a name, it is internally
     |      converted to a number on behalf of the caller.
     |      
     |      If the attribute is __dbg__, then the debug setting is chained
     |      to contained nodes.
     |      
     |      Args:
     |         name: attribute name
     |         value: attribute value
     |      
     |      Returns:
     |         Nothing
     |  
     |  __setitem__(self, key, val)
     |      magic method for setting LopperTree nodes like a dictionary
     |      
     |              Allow setting of properties as a dictionary:
     |      
     |                  <Lopper Tree Object>[<node name>] = <LopperNode Object>
     |      
     |                     or
     |      
     |                  <Lopper Tree Object>[<node number>] =  <LopperNode Object>
     |      
     |              During assignment of the node, access is created by name, number and
     |              phandle as appropriate
     |      
     |              Args:
     |                  key: string or int
     |                  val: LopperNode
     |      
     |              Returns:
     |      ;           Nothing, raises TypeError on invalid parameters
     |  
     |  __sub__(self, other)
     |      magic method for removing a node from a tree
     |      
     |      Supports removing a node from a tree through "-"
     |      
     |          tree - <LopperNode object>
     |      
     |      Args:
     |         other (LopperNode): Node to remove
     |      
     |      Returns:
     |         LopperTree: returns self
     |  
     |  add(self, node, dont_sync=False)
     |      Add a node to a tree
     |      
     |      Supports adding a node to a tree through:
     |      
     |          tree.add( <node> )
     |      
     |      The node is added to the FDT, resolved and syncd. It is then available
     |      for use in any tree operations.
     |      
     |      Args:
     |         node (LopperNode): node to add
     |         dont_sync (boolean, optional): don't invoke a tree wide sync when
     |                                        complete
     |      
     |      Returns:
     |         LopperTree: returns self, raises Exception on invalid parameter
     |  
     |  delete(self, node, delete_from_parent=True)
     |      delete a node from a tree
     |      
     |      If a node is resolved and syncd to the FDT, this routine deletes it
     |      from the FDT and the LopperTree structure.
     |      
     |      Args:
     |         node (int or LopperNode): the node to delete
     |         delete_fom_parent (bool): flag indicating if the node should be
     |                                   removed from the parent node.
     |      
     |      Returns:
     |         Boolean: True if deleted, False otherwise. KeyError if node is not found
     |  
     |  exec(self)
     |      Start a tree walk execution, with callbacks executed as required
     |      
     |      Starts walking the tree, beginning at the preamble, and then through a depth
     |      first walking of the nodes.
     |      
     |      If the tree has registered callbacks, they are executed before the walk
     |      starts, at the start/end of each node, at each property and at the end of
     |      the tree.
     |      
     |      See the class description for details on the callbacks
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         Nothing
     |  
     |  exec_cmd(self, node, cmd, env=None, module_list=[])
     |      Execute a (limited) code block against a node
     |      
     |      Execute a python clode block with the 'node' context set to the
     |      value passed to this routine.
     |      
     |      The "cmd" python code, runs in a constructed/safe environment to ensure
     |      that the code won't cause harmful sideffects to the execution
     |      environment.
     |      
     |      The following functions and variables are currently available in the
     |      safe_dict:
     |      
     |          len
     |          print
     |          verbose
     |      
     |      When executing in the code context, the following variables are
     |      available to the python code block.
     |      
     |          tree : the LopperTree object containing the node
     |          node : the LopperNode being processed
     |          __selected__ : the list of LopperNodes being processed
     |          node_name : the name of the node (as defined by the dts/dtb)
     |          node_number : the number of the node being processed
     |      
     |      The return value of the block is sent to the caller, so it can act
     |      accordingly.
     |      
     |      Args:
     |          node (LopperNode or string): starting node
     |          cmd (string): block of python code to execute
     |          env (dictionary,optional): values to make available as
     |                                     variables to the code block
     |          module_list (list,optional): list of assists to load before
     |                                       running the code block
     |      
     |      Returns:
     |          Return value from the execution of the code block
     |  
     |  export(self, start_path='/')
     |  
     |  filter(self, node_prefix, action, test_cmd, fdt=None, verbose=0)
     |      Filter tree nodes and perform an action
     |      
     |      Starting from the supplied path (node_prefix), this function walks
     |      the device tree and executes a block of python code to test each
     |      node.
     |      
     |      If the block of code (test_cmd) returns True, then the action is
     |      taken. If false, nothing is done.
     |      
     |      Currently defined actions:
     |      
     |         - delete: delete the node
     |         - report: (not currently implemented)
     |         - whitelist: (not currently implemented)
     |         - blacklist: (not currently implemented)
     |      
     |      The "test_cmd" python code, runs in a constructed/safe environment to
     |      ensure that the code won't cause harmful sideffects to the execution
     |      environment. See the exec_cmd method for details of the command
     |      execution.
     |      
     |      A standard python "return True" and "return False" should be used to
     |      indicate the result of the test.
     |      
     |      Args:
     |          node_prefix (string): starting node path
     |          action (LopperAction): action to take in the True condition
     |          test_cmd (string): block of python code to test against each node
     |          fdt (FDT,optional): flattended device tree for reference
     |          verbose (int,optional): verbosity level to use.
     |      
     |      Returns:
     |          Nothing
     |  
     |  lnodes(self, label)
     |      Find nodes in a tree by label
     |      
     |      Safely (no exception raised) returns the node that can be found
     |      at a given label value.
     |      
     |      Args:
     |         label (string): node string  to check
     |      
     |      Returns:
     |         list (LopperNode): the matching nodes if found, [] otherwise
     |  
     |  load(self, dct=None)
     |      load a tree
     |      
     |      Loads the details around the nodes of a tree, and completes values that
     |      are not possible at initialization time.
     |      
     |      In particular, it updates the path, node and phandle ordered
     |      dictionaries to reflect the dictionary. This is often done after a node
     |      is added to ensure that iterations will see the new node in tree order,
     |      versus added order.
     |      
     |      Args:
     |         dct (Dictionary): dictionary from a lopper_fdt export, or a tree export
     |      
     |      Returns:
     |         Nothing
     |  
     |  next(self)
     |      Returns the next node in a tree iteration
     |      
     |      This method maintains the iteration state of a tree and returns
     |      the next LopperNode in the iteration.
     |      
     |      Three types of iterations are common:
     |      
     |        - full iteration: a depth first walk of every node in the tree
     |        - subnode iteration: a depth first walk of all nodes under a given
     |                             starting point
     |        - startnode iteration: A depth first walk starting at a given node
     |                               and continuing to the end of the tree
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         LopperNode
     |  
     |  nodes(self, nodename)
     |      Get nodes that match a given name or regex
     |      
     |      Looks for a node at a name/path, or nodes that match a regex.
     |      
     |      Args:
     |         nodename (string): node name or regex
     |      
     |      Returns:
     |         list: a list all nodes that match the name or regex
     |  
     |  phandle_gen(self)
     |      Generate a phandle for use in a node
     |      
     |      Creates a unique phandle for a node. This is basic tracking and is
     |      used since fdt_find_max_phandle is not fully exposed, and removes
     |      a binding to libfdt.
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         phandle number
     |  
     |  phandles(self)
     |      Utility function to get the active phandles in the tree
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |         list (numbers): list of in use phandles in the tree
     |  
     |  pnode(self, phandle)
     |      Find a node in a tree by phandle
     |      
     |      Safely (no exception raised) returns the node that can be found
     |      at a given phandle value.
     |      
     |      Args:
     |         phandle (int): node phandle to check
     |      
     |      Returns:
     |         LopperNode: the matching node if found, None otherwise
     |  
     |  print(self, output=None)
     |      print the contents of a tree
     |      
     |      Outputs the tree to the passed output stream, if not passed the tree's
     |      output stream is used. If the tree has no output stream, stdout is the
     |      final fallback.
     |      
     |      Args:
     |         output (optional,output stream).
     |      
     |      Returns:
     |         Nothing
     |  
     |  ref(self, value, node_regex=None)
     |      Tree wide setting of a refcount
     |      
     |      Sets a refcount for all nodes in the tree, or a regex contained set
     |      of nodes.
     |      
     |      Calling this routine with zero, is a treewide reset of all refcounts.
     |      
     |      If a regex is passed, only matching nodes will be set/cleared.
     |      
     |      Args:
     |         value (int): refcount value by which to increment
     |         node_regex (string,optional): node path regex to restrict scope of
     |                                       refcount operations
     |      
     |      Returns:
     |         Nothing
     |  
     |  ref_all(self, starting_node, parent_nodes=False)
     |      Increment the refcount for a node and its subnodes (and optionally parents)
     |      
     |      Creates a reference to a node and its subnodes.
     |      
     |      If parent_nodes is set to True, parent nodes will be also referenced.
     |      
     |      Args:
     |         starting_node (LopperNode): node to reference
     |         parent_nodes (boolean,optional): flag to indicate if parent nodes
     |                                          should be referenced
     |      
     |      Returns:
     |         Nothing
     |  
     |  refd(self, node_regex='')
     |      Get a list of referenced nodes
     |      
     |      When refcounting is enabled, this routine returns the list of nodes
     |      that have been referenced.
     |      
     |      We use the name, rather than the offset, since the offset can change if
     |      something is deleted from the tree. But we need to use the full path so
     |      we can find it later.
     |      
     |      Args:
     |         node_regex: limit returned nodes to those that match the regex, which
     |                     is applied to the path of the nodes.
     |      
     |      Returns:
     |         list (strings): list of referenced nodes, or [] if there are no referenced nodes
     |  
     |  resolve(self)
     |  
     |  subnodes(self, start_node, node_regex=None)
     |      return the subnodes of a node
     |      
     |      Returns a list of all subnodes from a given starting node.
     |      
     |      If a node regex is passed, those nodes that do not match the
     |      regex are removed from the returned value.
     |      
     |      Args:
     |         start_node (LopperNode): the starting node
     |         node_regex (string,optional): node mask
     |      
     |      Returns:
     |         list: returns a list of all subnodes (or matching subnodes)
     |  
     |  sync(self, fdt=None, only_if_required=False)
     |      Sync a tree to a backing FDT
     |      
     |      This routine walks the FDT, and sync's changes from any LopperTree nodes
     |      into the backing store.
     |      
     |      Once complete, all nodes are resolved() to ensure their attributes reflect
     |      the FDT status.
     |      
     |      Args:
     |         fdt (FDT,optional): the flattended device tree to sync to. If it isn't
     |                             passed, the stored FDT is use for sync.
     |         only_if_required(boolean,optional): flag to indicate that we should only
     |                                             sync if something is dirty
     |      
     |      Returns:
     |         Nothing
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from LopperTree:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)

DATA
    MAX_RETRIES = 3
    QUIET_ALL = range(1, 18)
    QUIET_NOTFOUND = (1,)
    printable = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTU...
    python_version_dir = 'python3.6'

FILE
    /home/bruce/git/system-device-tree/lopper_tree.py


Help on module lopper_fdt:

NAME
    lopper_fdt

DESCRIPTION
    #/*
    # * Copyright (c) 2019,2020 Xilinx Inc. All rights reserved.
    # *
    # * Author:
    # *       Bruce Ashfield <bruce.ashfield@xilinx.com>
    # *
    # * SPDX-License-Identifier: BSD-3-Clause
    # */

CLASSES
    builtins.object
        Lopper
    enum.Enum(builtins.object)
        LopperFmt
    
    class Lopper(builtins.object)
     |  The Lopper Class contains static methods for manipulating device trees
     |  
     |  Use the lopper methods when manipulating device trees (in particular
     |  libfdt FDT objects) or SystemDeviceTree classes.
     |  
     |  Static methods defined here:
     |  
     |  dt_compile(dts_file, i_files, includes, force_overwrite=False, outdir='./', save_temps=False, verbose=0, enhanced=True)
     |      Compile a dts file to a dtb
     |      
     |      This routine takes a dts input file, other dts include files,
     |      include search path and then uses standard tools (cpp, dtc, etc).
     |      
     |      Environment variables can be used tweak the execution of the various
     |      tools and stages:
     |      
     |         LOPPER_CPP: set if a different cpp than the standard one should
     |                     be used, or if cpp is not on the path
     |         LOPPER_PPFLAGS: flags to be used when calling cpp
     |         LOPPER_DTC: set if a non standard dtc should be used, or if dtc
     |                     is not on the path
     |         LOPPER_DTC_FLAGS: flags to use when calling dtc
     |         LOPPER_DTC_OFLAGS: extra dtc flags if an overlay is being compiled
     |         LOPPER_DTC_BFLAGS: extra dtc args/flags
     |      
     |      Args:
     |         dts_file (string): path to the dts file to be compiled
     |         i_files (list): files to be included
     |         includes (list): list of include directories (translated into -i <foo>
     |                          for dtc calls)
     |         force_overwrite (bool,optional): should files be overwritten.
     |                                          Default is False
     |         save_temps (bool, optional): should temporary files be saved on failure
     |         verbose (bool,optional): verbosity level
     |      
     |      Returns:
     |         string: Name of the compiled dtb
     |  
     |  dt_preprocess(dts_file, includes, outdir='./', verbose=0)
     |      Compile a dts file to a dtb
     |      
     |      This routine takes a dts input file, include search path and then
     |      uses standard tools (cpp, etc) to expand references.
     |      
     |      Environment variables can be used tweak the execution of the various
     |      tools and stages:
     |      
     |         LOPPER_CPP: set if a different cpp than the standard one should
     |                     be used, or if cpp is not on the path
     |         LOPPER_PPFLAGS: flags to be used when calling cpp
     |      
     |      Args:
     |         dts_file (string): path to the dts file to be preprocessed
     |         includes (list): list of include directories (translated into -i <foo>
     |                          for cpp calls)
     |         outdir (string): directory to place all output and temporary files
     |         verbose (bool,optional): verbosity level
     |      
     |      Returns:
     |         string: Name of the preprocessed dts
     |  
     |  dt_to_fdt(dtb, rmode='rb')
     |      takes a dtb and returns a flattened device tree object
     |      
     |      Args:
     |         dtb: a compiled device tree
     |         rmode (string,optional): the read mode of the file, see libfdt for possible values
     |                                  default is 'rb'
     |      
     |      Returns:
     |         A flattended device tree object (as defined by libfdt)
     |  
     |  dtb_dts_export(dtb, outfilename='', verbose=0)
     |      writes a dtb to a file or to stdout as a dts
     |      
     |      Args:
     |         dtb: a compiled device tree
     |         outfilename (string): the output filename (stdout is used if empty)
     |         verbose (int,optional): extra debug info. default 0.
     |      
     |      Returns:
     |         The return value of executing dtc to dump the dtb to dts
     |  
     |  encode_byte_array(values)
     |      utility to encode a list of values into a bytearray
     |      
     |      Args:
     |         values (list): integer (numeric) values to encode
     |      
     |      Returns:
     |         byte array: the encoded byte array
     |  
     |  encode_byte_array_from_strings(values)
     |      utility to encode a list of strings into a bytearray
     |      
     |      Args:
     |         values (list): string values to encode
     |      
     |      Returns:
     |         byte array: the encoded byte array
     |  
     |  export(fdt, start_node='/', verbose=False, strict=False)
     |      export a FDT to a description / nested dictionary
     |      
     |      This routine takes a FDT, a start node, and produces a nested dictionary
     |      that describes the nodes and properties in the tree.
     |      
     |      The dictionary contains a set of internal properties, as well as
     |      a list of standand properties to the node. Internal properties have
     |      a __ suffix and __ prefix.
     |      
     |      Child nodes are indexed by their absolute path. So any property that
     |      starts with "/" and is a dictionary, represents another node in the
     |      tree.
     |      
     |      In particular:
     |          - __path__ : is the absolute path fo the node, and is used to lookup
     |                       the target node
     |          - __fdt_name__ : is the name of the node and will be written to the
     |                           fdt name property
     |          - __fdt_phandle__ : is the phandle for the node
     |      
     |      All other "standard" properties are returned as entries in the dictionary.
     |      
     |      if strict is enabled, structural issues in the input tree will be
     |      flagged and an error triggered. Currently, this is duplicate nodes, but
     |      may be extended in the future
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          start_node (string,optional): the starting node
     |          verbose (bool,optional): verbosity level
     |          strict (bool,optional): toggle validity checking
     |      
     |      Returns:
     |          OrderedDict describing the tree
     |  
     |  fdt(size=None, other_fdt=None)
     |      Create a new FDT
     |      
     |      Creats a new FDT of a passed size. If other_fdt is passed, it
     |      is used as the start size of the fdt.
     |      
     |      If no size or other fdt is passed, 128 bytes is the default
     |      size
     |      
     |      Args:
     |          size (int,optional): size in bytes of the FDT
     |          other_fdt (FDT,optional): reference FDT for size
     |      
     |      Returns:
     |          fdt: The newly created FDT
     |  
     |  fdt_copy(fdt)
     |      Copy a fdt
     |      
     |      Creats a new FDT that is a copy of the passed one.
     |      
     |      Args:
     |          fdt (FDT): reference FDT
     |      
     |      Returns:
     |          fdt: The newly created FDT
     |  
     |  input_file_type(infile)
     |      utility to return the "type" of a file, aka the extension
     |      
     |      Args:
     |         infile (string): path of the file
     |      
     |      Returns:
     |         string: the extension of the file
     |  
     |  node_abspath(fdt, nodeid)
     |      Get the absolute (fully specified) path of a nodes
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          nodeid: device tree node offset
     |      
     |      Returns:
     |          string: node path, if successful, otherwise ""
     |  
     |  node_add(fdt_dest, node_full_path, create_parents=True, verbose=0)
     |      Add an empty node to a flattened device tree
     |      
     |      Creates a new node in a flattened devide tree at a given path. If
     |      desired a node structure (aka parents) will be created as part of
     |      adding the node at the specified path.
     |      
     |      Args:
     |          fdt_dest (fdt): flattened device tree object
     |          node_full_path (string): fully specified path (and name) of the node to create
     |          create_parents (bool,optional): Should parent nodes be created. Default is True.
     |              True: create parents as required, False: error if parents are missing
     |          verbose (int,optional): verbosity level. default is 0.
     |      
     |      Returns:
     |          int: The node offset of the created node, if successfull, otherwise -1
     |  
     |  node_by_phandle(fdt, phandle, verbose=0)
     |      Get a node offset by a phandle
     |      
     |      Thin wrapper around the libfdt routine. The wrapper provides
     |      consistent exception handling and verbosity level handling.
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          phandle(int): phandle to use as lookup key
     |          verbose(bool,optional): verbosity level. Deafult is 0.
     |      
     |      Returns:
     |          int: if > 0, the node that was found. -1 if node was not found.
     |  
     |  node_copy(fdt_source, node_source_offset, fdt_dest, node_dest_parent_offset, verbose=0)
     |      Copies a node from one FDT to another
     |      
     |      Copies a node between flattened device trees. The node (and
     |      properties) will be copied to the specified target device tree and
     |      path (ensure that a node does not already exist at the destination
     |      path).
     |      
     |      Note: the destination node parent must exist before calling this routine
     |      
     |      Properties are iterated, decoded and then copied (encoded) to the
     |      destination node. As such, the copies are limited by the
     |      decode/encode capabilities. If properties do not look correct in the
     |      copy, the decode/encode routines need to be checked.
     |      
     |      Args:
     |          fdt_source (fdt): source flattened device tree object
     |          node_source_offset: source device tree node offset
     |          fdt_dest (fdt): destination flattened device tree object
     |          node_dest_parent_offset: destination device parent node
     |          verbose (int,optional): verbosity level. default is 0.
     |      
     |      Returns:
     |          bool: True if the node was copied, otherise, False
     |  
     |  node_copy_from_path(fdt_source, node_source_path, fdt_dest, node_full_dest, verbose=0)
     |      Copies a node from one FDT to another
     |      
     |      Copies a node between flattened device trees. The node (and
     |      properties) will be copied to the specified target device tree and
     |      path (ensure that a node does not already exist at the destination
     |      path).
     |      
     |      This routine is a wrapper around node_copy(), and will create a
     |      parent node structure in the destination fdt as required.
     |      
     |      Args:
     |          fdt_source (fdt): source flattened device tree object
     |          node_source_path: source device tree node path (fully specified)
     |          fdt_dest (fdt): destination flattened device tree object
     |          node_full_dest: destination device tree path for copied node (fully specified)
     |          verbose (int,optional): verbosity level. default is 0.
     |      
     |      Returns:
     |          bool: True if the node was copied, otherise, False
     |  
     |  node_find(fdt, node_prefix)
     |      Finds a node by its prefix
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_prefix (string): device tree path
     |      
     |      Returns:
     |          int: node number if successful, otherwise -1
     |  
     |  node_find_by_name(fdt, node_name, starting_node=0, multi_match=False)
     |      Finds a node by its name (not path)
     |      
     |      Searches for a node by its name, and returns the offset of that same node
     |      Note: use this when you don't know the full path of a node
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_name (string): name of the node
     |          starting_node (int): node number to use as the search starting point
     |          multi_match (bool,optional): flag to indicate if more than one matching
     |                                       node should be found, default is False
     |      
     |      Returns:
     |          tuple: first matching node, list of matching nodes. -1 and [] if no match is found
     |  
     |  node_find_by_regex(fdt, node_regex, starting_node=0, multi_match=False, paths_not_numbers=False)
     |      Finds a node by a regex /path/<regex>/<name>
     |      
     |      Searches for nodes that match a regex (path + name).
     |      
     |      Note: if you pass the name of a node as the regex, you'll get a list of
     |            that node + children
     |      Note: if you pass no regex, you'll get all nodes from the starting point
     |            to the end of the tree.
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_regex (string): regex to use for comparision
     |          starting_node (int): node number to use as the search starting point
     |          multi_match (bool,optional): flag to indicate if more than one matching
     |                                       node should be found, default is False
     |          paths_not_numbers (bool,optional): flag to request paths, not node numbers
     |                                             be returned
     |      
     |      Returns:
     |          tuple: first matching node, list of matching nodes. -1 and [] if no match is found
     |  
     |  node_getname(fdt, node_number_or_path)
     |      Gets the FDT name of a node
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_number_or_path: node number or path
     |      
     |      Returns:
     |          string: name of the node, or "" if node wasn't found
     |  
     |  node_getphandle(fdt, node_number)
     |      utility command to get a phandle (as a number) from a node
     |      
     |      Args:
     |         fdt (FDT): flattened device tree
     |         node_number (int): node number in the fdt
     |      
     |      Returns:
     |         int: the phandle of the node number, if successful, -1 if not
     |  
     |  node_number(fdt, node)
     |      Get the number for the passed node
     |      
     |      Return the node number of a node by its path, or just return
     |      its number if it is already a number. This is a normalization
     |      routine for node references
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node (string or ing): the name or node number to check
     |      
     |      Returns:
     |          string: node number, or -1 if the node doesn't exist
     |  
     |  node_parent(fdt, node_number_or_path)
     |      Get the parent offset / number of a node
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_number_or_path: (string or int): node number or full path to
     |                               the target node.
     |      
     |      Returns:
     |          int: the node number of the parent
     |  
     |  node_prop_check(fdt, node_name, property_name)
     |      Check if a node contains a property
     |      
     |      Boolean check to see if a node contains a property.
     |      
     |      The node name does not need to be a full path or path prefix, since
     |      the node will be searched starting at the root node, which means that
     |      a non-unique node name could match multiple nodes.
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_name (string): name of the node
     |          property_name (string): name of the property to check
     |      
     |      Returns:
     |          bool: True if the node has the property, otherwise False
     |  
     |  node_properties(fdt, node_number_or_path)
     |      Get the list of properties for a node
     |      
     |      Gather the list of FDT properties for a given node.
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_number_or_path: (string or int): node number or full path to
     |                               the target node.
     |      
     |      Returns:
     |          list (FDT prop): The properties of the node [] if no props
     |  
     |  node_properties_as_dict(fdt, node, type_hints=True, verbose=0)
     |      Create a dictionary populated with the nodes properties.
     |      
     |      Builds a dictionary that is propulated with a node's properties as
     |      the keys, and their values. Used as a utility routine to avoid
     |      multiple calls to check if a property exists, and then to fetch its
     |      value.
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node (int or string): either a node number or node path
     |          type_hints  (bool,optional): flag indicating if type hints should be returned
     |          verbose (int,optional): verbosity level. default is 0.
     |      
     |      Returns:
     |          dict: dictionary of the properties, if successfull, otherwise and empty dict
     |  
     |  node_remove(fdt, target_node_offset, verbose=0)
     |      remove a node from the device tree
     |      
     |      Thin wrapper and consistent logging around libfdt's node delete.
     |      
     |      Args:
     |         fdt (fdt): flattended device tree
     |         target_node_offset (int): offset of the node to be deleted
     |      
     |      Returns:
     |         Boolean: True if node is removed, false otherwise
     |  
     |  node_remove_if_not_compatible(fdt, node_prefix, compat_string)
     |      Remove a node if incompatible with passed string
     |      
     |      Utility/cleanup function to remove all nodues under a node_prefix
     |      that are not compatible with a given string.
     |      
     |      Args:
     |          fdt (FDT): flattened device tree
     |          node_prefix (string): starting node path
     |          compat_strin (string): string for compat property comparison
     |      
     |      Returns:
     |          Nothing
     |  
     |  node_setname(fdt, node_number_or_path, newname)
     |      Sets the FDT name of a node
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_number_or_path: node number or path
     |          newname (string): name of the node
     |      
     |      Returns:
     |          boolean: True if the name was set, False otherwise
     |  
     |  node_subnodes(fdt, node_number_or_path, abs_paths=True)
     |      Get the list of properties for a node
     |      
     |      Gather the list of FDT properties for a given node.
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_number_or_path: (string or int): node number or full path to
     |                               the target node.
     |          abs_paths (boolean, optional): indicate if absolute paths should be returned
     |      
     |      Returns:
     |          list (strings): The subnodes, [] if no subnodes
     |  
     |  node_sync(fdt, node_in, parent=None, verbose=False)
     |      Write a node description to a FDT
     |      
     |      This routine takes an input dictionary, and writes the details to
     |      the passed fdt.
     |      
     |      The dictionary contains a set of internal properties, as well as
     |      a list of standand properties to the node. Internal properties have
     |      a __ suffix and __ prefix.
     |      
     |      In particular:
     |          - __path__ : is the absolute path fo the node, and is used to lookup
     |                       the target node
     |          - __fdt_name__ : is the name of the node and will be written to the
     |                           fdt name property
     |          - __fdt_phandle__ : is the phandle for the node
     |      
     |      All other '/' leading, or '__' leading properties will be written to
     |      the FDT as node properties.
     |      
     |      If the node doesn't exist, it will be created. If the node exists, then
     |      the existing properties are read, and any that are no present in the
     |      passed dictionary are deleted.
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_in: (dictionary): Node description dictionary
     |          parent (string,optional): path to the parent node
     |          verbose (bool,optional): verbosity level
     |      
     |      Returns:
     |          Nothing
     |  
     |  node_type(fdt, node_offset, verbose=0)
     |      Utility function to get the "type" of a node
     |      
     |      A small wrapper around the compatible property, but we can use this
     |      instead of directly getting compatible, since if we switch formats or if
     |      we want to infer anything based on the name of a node, we can hide it in
     |      this routine
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_offset (int): node number
     |          verbose (int): verbose output level
     |      
     |      Returns:
     |          string: compatible string of the node if successful, otherwise ''
     |  
     |  node_walk(fdt, verbose=0)
     |      Walk nodes and gather a list
     |      
     |      Utility / reference routine for gathering a list of nodes.
     |      Always starts at node 0.
     |      
     |      Args:
     |          fdt (FDT): flattened device tree
     |          verbose (int,optional): verbosity level, default 0.
     |      
     |      Returns:
     |          List of nodes. Each containg the [node number, name, phandle, depth]
     |  
     |  nodes(fdt, node_number_or_path, abs_paths=True)
     |      Get the nodes of a tree from a starting point
     |      
     |      Gather the list nodes in the tree from a particular starting point
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_number_or_path: (string or int): node number or full path to
     |                               the target node.
     |          abs_paths (boolean, optional): indicate if absolute paths should be returned
     |      
     |      Returns:
     |          list (strings): The nodes, [] if no nodes
     |  
     |  nodes_with_property(fdt, match_propname, match_regex='', start_path='/', include_children=True, match_depth=0)
     |      Get a list of nodes with a particular property
     |      
     |      Searches a device tree and returns a list of nodes that contain
     |      a given property.
     |      
     |      Matching is done by the existence of a property name in a node.
     |      
     |      If a match_regex is passed, then the value of the property is
     |      tested against the regex. If there's a match, then the node is
     |      added to the list.
     |      
     |      Args:
     |          fdt (fdt): source flattened device tree to search
     |          match_propname (string): target property name
     |          match_regex (string,optional): property value match regex. Default is ""
     |          start_path (string,optional): starting path in the device tree. Default is "/"
     |          include_children (bool,optional): should child nodes be searched. Default is True.
     |          match_depth (int): depth of the node, relative to the start path. Default is 0 (all nodes)
     |      
     |      Returns:
     |          list: list of matching nodes if successful, otherwise an empty list
     |  
     |  phandle_possible_properties()
     |      Get the diectionary of properties that can contain phandles
     |      
     |      dictionary of possible properties that can have phandles.
     |      To do the replacement, we map out the properties so we can locate any
     |      handles and do replacement on them with symbolic values. This format is
     |      internal only, and yes, could be the schema for the fields, but for now,
     |      this is easier.
     |      
     |      Each key (property name) maps to a list of: 'format', 'flag'
     |      flag is currently unused, and format is the following:
     |      
     |         - field starting with #: is a size value, we'll look it up and add 'x'
     |           number of fields based on it. If we can't find it, we'll just use '1'
     |         - phandle: this is the location of a phandle, size is '1'
     |         - anything else: is just a field we can ignore, size is '1'
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |          The phandle property dictionary
     |  
     |  phandle_safe_name(phandle_name)
     |      Make the passed name safe to use as a phandle label/reference
     |      
     |      Args:
     |          phandle_name (string): the name to use for a phandle
     |      
     |      Returns:
     |          The modified phandle safe string
     |  
     |  property_convert(property_string)
     |      utility command to convert a string to a list of property values
     |      
     |      Takes a string formatted in device tree notation, and returns a list
     |      of property values.
     |      
     |      Formats of the following types will work, and be converted to their
     |      base types in the returned list.
     |      
     |            <0x1 0x2 0x3>
     |            <0x1>
     |            "string value"
     |            "string value1","string value2"
     |            10
     |      
     |      Args:
     |         property_string (string): device tree "style" string
     |      
     |      Returns:
     |         list: converted property values, empty string if cannot convert
     |  
     |  property_get(fdt, node_number, prop_name, ftype=<LopperFmt.SIMPLE: 1>, encode=<LopperFmt.DEC: 4>)
     |      utility command to get a property (as a string) from a node
     |      
     |      A more robust way to get the value of a property in a node, when
     |      you aren't sure of the format of that property. This routine takes
     |      hints when getting the property in the form of a "format type" and
     |      an encoding.
     |      
     |      The format and encoding options are in the following enum type:
     |      
     |         class LopperFmt(Enum):
     |            SIMPLE = 1 (format)
     |            COMPOUND = 2 (format)
     |            HEX = 3 (encoding)
     |            DEC = 4 (encoding)
     |            STRING = 5 (encoding)
     |            MULTI_STRING = 5 (encoding)
     |      
     |      Args:
     |         fdt (FDT): flattened device tree
     |         node_number (int): node number in the fdt
     |         property (string): property name whose value to get
     |         ftype (LopperFmt,optional): format of the property. Default SIMPLE.
     |         encode (LopperFmt,optional); encoding of the property. Default DEC
     |      
     |      Returns:
     |         string: if format is SIMPLE: string value of the property, or "" if not found
     |         list: if format is COMPOUND: list of property values as strings, [] if not found
     |  
     |  property_list(fdt, node_path)
     |      Read a list of properties from a node
     |      
     |      Args:
     |         node_path: Full path to node, e.g. '/subnode@1/subsubnode'
     |      
     |      Returns:
     |         List of property names for that node, e.g. ['compatible', 'reg']
     |  
     |  property_phandle_params(fdt, nodeoffset, property_name)
     |      Determines the phandle elements/params of a property
     |      
     |      Takes a property name and returns where to find a phandle in
     |      that property.
     |      
     |      Both the index of the phandle, and the number of fields in
     |      the property are returned.
     |      
     |      Args:
     |          fdt (FDT): flattened device tree
     |          nodeoffset (int): node number of the property
     |          property_name (string): the name of the property to fetch
     |      
     |      Returns:
     |          The the phandle index and number of fields, if the node can't
     |          be found 0, 0 are returned.
     |  
     |  property_remove(fdt, node_name, prop_name, verbose=0)
     |      removes a property from a fdt
     |      
     |      Removes a property (if it exists) from a node (and optionally its children).
     |      
     |      Args:
     |          fdt (FDT): flattened device tree to modify
     |          node_name (int or string): the node number or name to process
     |          prop_name (string): name of property to remove
     |      
     |      Returns:
     |          Boolean: True if the property was deleted, False if it wasn't
     |  
     |  property_resolve_phandles(fdt, nodeoffset, property_name)
     |      Resolve the targets of any phandles in a property
     |      
     |      Args:
     |          fdt (FDT): flattened device tree
     |          nodeoffset (int): node number of the property
     |          property_name (string): the name of the property to resolve
     |      
     |      Returns:
     |          A list of all resolved phandle nodes, [] if no phandles are present
     |  
     |  property_set(fdt, node_number, prop_name, prop_val, ftype=<LopperFmt.SIMPLE: 1>, verbose=False)
     |      utility command to set a property in a node
     |      
     |      A more robust way to set the value of a property in a node, This routine
     |      takes hints when getting the property in the form of a "format type"
     |      
     |      The format options are in the following enum type:
     |      
     |         class LopperFmt(Enum):
     |            SIMPLE = 1 (format)
     |            COMPOUND = 2 (format)
     |      
     |      Based on the format hint, and the passed value, the property is encoded
     |      into a byte array and stored into the flattened device tree node.
     |      
     |      Args:
     |         fdt_dst (FDT): flattened device tree
     |         node_number (int): node number in the fdt
     |         prop_name (string): property name whose value to set
     |         ftype (LopperFmt,optional): format of the property. Default SIMPLE.
     |      
     |      Returns:
     |         Nothing
     |  
     |  property_type_guess(prop)
     |      utility routine to guess the type of a property
     |      
     |      Often the type of a property is not know, in particular if there isn't
     |      access to markers via libfdt.
     |      
     |      This routine looks at the data of a libFDT property and returns the best
     |      guess for the type. The logic behind the guesses is documented in the code
     |      itself
     |      
     |      Args:
     |         prop (libfdt property): the property to process
     |      
     |      Returns:
     |         LopperFmt description of the property. Default is UINT8 (binary)
     |                     LopperFmt.STRING: string
     |                     LopperFmt.UINT32 1: uint32
     |                     LopperFmt.UINT64 2: uint64
     |                     LopperFmt.UINT8 3: uint8 (binary)
     |                     LopperFmt.EMPTY 4: empty (just a name)
     |  
     |  property_value_decode(prop, poffset, ftype=<LopperFmt.SIMPLE: 1>, encode=<LopperFmt.UNKNOWN: 11>, verbose=0)
     |      Decodes a property
     |      
     |      Decode a property into a common data type (string, integer, list of
     |      strings, etc).
     |      
     |      This is a robust wrapper around the decode facilities provided via
     |      libfdt. This routine tries multiple encode formats and uses
     |      heuristics to determine the best format for the decoded property.
     |      
     |      The format type (ftype) and encod arguments can be used to help
     |      decode properly when the type of a property is known.
     |      
     |      The format and encoding options are in the following enum type:
     |      
     |         class LopperFmt(Enum):
     |            SIMPLE = 1 (format)
     |            COMPOUND = 2 (format)
     |            HEX = 3 (encoding)
     |            DEC = 4 (encoding)
     |            STRING = 5 (encoding)
     |            MULTI_STRING = 5 (encoding)
     |      
     |      Args:
     |         prop (libfdt property): property to decode
     |         poffset (int): offset of the property in the node (unused)
     |         ftype (LopperFmt,optional): format hint for the property. default is SIMPLE
     |         encode (LopperFmt,optional): encoding hint. default is DEC
     |         verbose (int,optional): verbosity level, default is 0
     |      
     |      Returns:
     |         (string): if SIMPLE. The property as a string
     |         (list): if COMPOUND. The property as a list of strings / values
     |  
     |  string_test(prop, allow_multiline=True)
     |      Check if a property (byte array) is a string
     |      
     |      Args:
     |         prop: (libfdt property)
     |      
     |      Returns:
     |         boolean: True if the property looks like a string
     |  
     |  sync(fdt, dct, verbose=False)
     |      sync (write) a tree dictionary to a fdt
     |      
     |      This routine takes an input dictionary, and writes the details to
     |      the passed fdt.
     |      
     |      The dictionary contains a set of internal properties, as well as
     |      a list of standand properties to the node. Internal properties have
     |      a __ suffix and __ prefix.
     |      
     |      Child nodes are indexed by their absolute path. So any property that
     |      starts with "/" and is a dictionary, represents another node in the
     |      tree.
     |      
     |      In particular:
     |          - __path__ : is the absolute path fo the node, and is used to lookup
     |                       the target node
     |          - __fdt_name__ : is the name of the node and will be written to the
     |                           fdt name property
     |          - __fdt_phandle__ : is the phandle for the node
     |      
     |      All other non  '/' leading, or '__' leading properties will be written to
     |      the FDT as node properties.
     |      
     |      Passed nodes will be synced via the node_sync() function, and will
     |      be created if they don't exist. Existing nodes will have their properties
     |      deleted if they are not in the corresponding dictionary.
     |      
     |      All of the existing nodes in the FDT are read, if they aren not found
     |      in the passed dictionary, they will be deleted.
     |      
     |      Args:
     |          fdt (fdt): flattened device tree object
     |          node_in: (dictionary): Node description dictionary
     |          parent (dictionary,optional): parent node description dictionary
     |          verbose (bool,optional): verbosity level
     |      
     |      Returns:
     |          Nothing
     |  
     |  write_fdt(fdt_to_write, output_filename, overwrite=True, verbose=0, enhanced=False)
     |      Write a system device tree to a file
     |      
     |      Write a fdt (or system device tree) to an output file. This routine uses
     |      the output filename to determine if a module should be used to write the
     |      output.
     |      
     |      If the output format is .dts or .dtb, Lopper takes care of writing the
     |      output. If it is an unrecognized output type, the available assist
     |      modules are queried for compatibility. If there is a compatible assist,
     |      it is called to write the file, otherwise, a warning or error is raised.
     |      
     |      Args:
     |          fdt_to_write (fdt): source flattened device tree to write
     |          output_filename (string): name of the output file to create
     |          overwrite (bool,optional): Should existing files be overwritten. Default is True.
     |          verbose (int,optional): verbosity level to use.
     |          enhanced(bool,optional): whether enhanced printing should be performed. Default is False
     |      
     |      Returns:
     |          Nothing
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |  
     |  phandle_possible_prop_dict = {}
    
    class LopperFmt(enum.Enum)
     |  Enum class to define the types and encodings of Lopper format routines
     |  
     |  Method resolution order:
     |      LopperFmt
     |      enum.Enum
     |      builtins.object
     |  
     |  Data and other attributes defined here:
     |  
     |  COMPOUND = <LopperFmt.COMPOUND: 2>
     |  
     |  DEC = <LopperFmt.DEC: 4>
     |  
     |  EMPTY = <LopperFmt.EMPTY: 10>
     |  
     |  HEX = <LopperFmt.HEX: 3>
     |  
     |  MULTI_STRING = <LopperFmt.MULTI_STRING: 6>
     |  
     |  SIMPLE = <LopperFmt.SIMPLE: 1>
     |  
     |  STRING = <LopperFmt.STRING: 5>
     |  
     |  UINT32 = <LopperFmt.UINT32: 8>
     |  
     |  UINT64 = <LopperFmt.UINT64: 9>
     |  
     |  UINT8 = <LopperFmt.UINT8: 7>
     |  
     |  UNKNOWN = <LopperFmt.UNKNOWN: 11>
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from enum.Enum:
     |  
     |  name
     |      The name of the Enum member.
     |  
     |  value
     |      The value of the Enum member.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from enum.EnumMeta:
     |  
     |  __members__
     |      Returns a mapping of member name->value.
     |      
     |      This mapping lists all enum members, including aliases. Note that this
     |      is a read-only view of the internal mapping.

DATA
    MAX_RETRIES = 3
    QUIET_ALL = range(1, 18)
    QUIET_NOTFOUND = (1,)
    printable = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTU...
    python_version_dir = 'python3.6'

FILE
    /home/bruce/git/system-device-tree/lopper_fdt.py