README.pydoc

Help on module __init__:

NAME
    __init__

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, libfdt=True, config=None)
     |      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, tree=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:
     |          tree (LopperTree,optional): LopperTree 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
    lopper_type(cls)
    
    stdoutIO(stdout=None)

DATA
    lopper_directory = '/home/bruce/git/system-device-tree/lopper'
    yaml_support = True

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


Help on module tree:

NAME
    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
     |  
     |  items(self)
     |      method to support items() iteration
     |      
     |      If the pure Iterators aren't used (__iter__, etc), and instead a dictionary
     |      style items() is requested for the Node. We can just return the items() from
     |      __props__ to support that style of access.
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |         LopperNode object: self
     |  
     |  load(self, dct, parent_path=None, clear_children=True, update_props=False)
     |      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
     |      
     |      If clear_children is set to True (the default), children nodes will be
     |      dropped with the expectation that they will be re-added when the children
     |      themselves are loaded. When set to False, the children are not modified,
     |      and this is used when updating a node from a dictionary.
     |      
     |      If update_props is set to True (the default is False), then existing
     |      properties will be updated with the contents of the passed dictionary.
     |      This is set to true when a dictionary should override all values in
     |      a node.
     |      
     |      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)
     |         clear_children (Optional,boolean): default is True
     |         update_props (Optional,boolean): default is False
     |      
     |      Returns:
     |         Nothing
     |  
     |  merge(self, other_node)
     |      merge a secondary node into the target
     |      
     |      This routine updates the target node with the properties of secondary.
     |      
     |      It is additive/modification only, no properties are removed as part of
     |      the processing.
     |      
     |      Args:
     |         other_node (LopperNode): The other to merge
     |      
     |      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, merge=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
     |  
     |  alias_node(self, alias)
     |      Find a node via an alias
     |      
     |      Safely (no exception raised) returns the node that can be found
     |      at a given alias.
     |      
     |      Args:
     |         alias (string): node alias to check
     |      
     |      Returns:
     |         node (LopperNode): the alias nodes if found, None otherwise
     |  
     |  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=[], module_load_paths=[])
     |      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
     |          module_load_paths (list,optional): additional load paths to use
     |                                             when loading modules
     |      
     |      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, merge=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
     |  
     |  alias_node(self, alias)
     |      Find a node via an alias
     |      
     |      Safely (no exception raised) returns the node that can be found
     |      at a given alias.
     |      
     |      Args:
     |         alias (string): node alias to check
     |      
     |      Returns:
     |         node (LopperNode): the alias nodes if found, None otherwise
     |  
     |  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=[], module_load_paths=[])
     |      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
     |          module_load_paths (list,optional): additional load paths to use
     |                                             when loading modules
     |      
     |      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)

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


Help on module fdt:

NAME
    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
    lopper.base.lopper_base(builtins.object)
        LopperFDT
    
    class LopperFDT(lopper.base.lopper_base)
     |  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.
     |  
     |  Method resolution order:
     |      LopperFDT
     |      lopper.base.lopper_base
     |      builtins.object
     |  
     |  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_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
     |  
     |  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
     |  
     |  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_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 ''
     |  
     |  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
     |  
     |  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_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_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
     |  
     |  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
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from lopper.base.lopper_base:
     |  
     |  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
     |  
     |  ----------------------------------------------------------------------
     |  Class methods inherited from lopper.base.lopper_base:
     |  
     |  phandle_possible_properties() from builtins.type
     |      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
     |  
     |  ----------------------------------------------------------------------
     |  Static methods inherited from lopper.base.lopper_base:
     |  
     |  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
     |  
     |  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
     |  
     |  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_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 a support library.
     |      
     |      This routine looks at the data of a libfdt or byte property and returns
     |      the best guess for the type. The logic behind the guesses is documented
     |      in the code itself
     |      
     |      Args:
     |         prop (libfdt or byte 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 or byte 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 or byte property)
     |      
     |      Returns:
     |         boolean: True if the property looks like a string
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from lopper.base.lopper_base:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes inherited from lopper.base.lopper_base:
     |  
     |  phandle_possible_prop_dict = {}

DATA
    MAX_RETRIES = 10
    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


Help on module dt:

NAME
    dt

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

CLASSES
    lopper.base.lopper_base(builtins.object)
        LopperDT
    
    class LopperDT(lopper.base.lopper_base)
     |  The Lopper Class contains static methods for manipulating DT
     |  
     |  Method resolution order:
     |      LopperDT
     |      lopper.base.lopper_base
     |      builtins.object
     |  
     |  Static methods defined here:
     |  
     |  dt_compile(dts_file, i_files='', includes='', force_overwrite=False, outdir='./', save_temps=False, verbose=0, enhanced=True)
     |  
     |  export(dt, start_node_path='/', 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
     |  
     |  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_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_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_properties_as_dict(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_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 ''
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from lopper.base.lopper_base:
     |  
     |  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
     |  
     |  ----------------------------------------------------------------------
     |  Class methods inherited from lopper.base.lopper_base:
     |  
     |  phandle_possible_properties() from builtins.type
     |      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
     |  
     |  ----------------------------------------------------------------------
     |  Static methods inherited from lopper.base.lopper_base:
     |  
     |  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
     |  
     |  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
     |  
     |  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_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 a support library.
     |      
     |      This routine looks at the data of a libfdt or byte property and returns
     |      the best guess for the type. The logic behind the guesses is documented
     |      in the code itself
     |      
     |      Args:
     |         prop (libfdt or byte 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 or byte 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 or byte property)
     |      
     |      Returns:
     |         boolean: True if the property looks like a string
     |  
     |  sync(dt, dct, verbose=False)
     |      sync (write) a tree dictionary to a backend file
     |      
     |      This routine takes an input dictionary, and writes the details to
     |      the passed dt.
     |      
     |      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:
     |          dt (dt): device tree object
     |          node_in: (dictionary): Node description dictionary
     |          parent (dictionary,optional): parent node description dictionary
     |          verbose (bool,optional): verbosity level
     |      
     |      Returns:
     |          Nothing
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from lopper.base.lopper_base:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes inherited from lopper.base.lopper_base:
     |  
     |  phandle_possible_prop_dict = {}

DATA
    printable = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTU...

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


Help on module yaml:

NAME
    yaml

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

CLASSES
    anytree.exporter.dictexporter.DictExporter(builtins.object)
        LopperDictExporter
    builtins.object
        LopperDictImporter
        LopperTreeImporter
        LopperYAML
    ruamel.yaml.dumper.Dumper(ruamel.yaml.emitter.Emitter, ruamel.yaml.serializer.Serializer, ruamel.yaml.representer.Representer, ruamel.yaml.resolver.Resolver)
        LopperDumper
    
    class LopperDictExporter(anytree.exporter.dictexporter.DictExporter)
     |  # Extension of the default anytree DictExporter, since we don't want added
     |  # nodes like "root" and children to be in the export.
     |  
     |  Method resolution order:
     |      LopperDictExporter
     |      anytree.exporter.dictexporter.DictExporter
     |      builtins.object
     |  
     |  Methods defined here:
     |  
     |  export(self, node)
     |      Export tree starting at `node`.
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from anytree.exporter.dictexporter.DictExporter:
     |  
     |  __init__(self, dictcls=<class 'dict'>, attriter=None, childiter=<class 'list'>, maxlevel=None)
     |      Tree to dictionary exporter.
     |      
     |      Every node is converted to a dictionary with all instance
     |      attributes as key-value pairs.
     |      Child nodes are exported to the children attribute.
     |      A list of dictionaries.
     |      
     |      Keyword Args:
     |          dictcls: class used as dictionary. :any:`dict` by default.
     |          attriter: attribute iterator for sorting and/or filtering.
     |          childiter: child iterator for sorting and/or filtering.
     |          maxlevel (int): Limit export to this number of levels.
     |      
     |      >>> from pprint import pprint  # just for nice printing
     |      >>> from anytree import AnyNode
     |      >>> from anytree.exporter import DictExporter
     |      >>> root = AnyNode(a="root")
     |      >>> s0 = AnyNode(a="sub0", parent=root)
     |      >>> s0a = AnyNode(a="sub0A", b="foo", parent=s0)
     |      >>> s0b = AnyNode(a="sub0B", parent=s0)
     |      >>> s1 = AnyNode(a="sub1", parent=root)
     |      
     |      >>> exporter = DictExporter()
     |      >>> pprint(exporter.export(root))  # order within dictionary might vary!
     |      {'a': 'root',
     |       'children': [{'a': 'sub0',
     |                     'children': [{'a': 'sub0A', 'b': 'foo'}, {'a': 'sub0B'}]},
     |                    {'a': 'sub1'}]}
     |      
     |      Pythons dictionary `dict` does not preserve order.
     |      :any:`collections.OrderedDict` does.
     |      In this case attributes can be ordered via `attriter`.
     |      
     |      >>> from collections import OrderedDict
     |      >>> exporter = DictExporter(dictcls=OrderedDict, attriter=sorted)
     |      >>> pprint(exporter.export(root))
     |      OrderedDict([('a', 'root'),
     |                   ('children',
     |                    [OrderedDict([('a', 'sub0'),
     |                                  ('children',
     |                                   [OrderedDict([('a', 'sub0A'), ('b', 'foo')]),
     |                                    OrderedDict([('a', 'sub0B')])])]),
     |                     OrderedDict([('a', 'sub1')])])])
     |      
     |      The attribute iterator `attriter` may be used for filtering too.
     |      For example, just dump attributes named `a`:
     |      
     |      >>> exporter = DictExporter(attriter=lambda attrs: [(k, v) for k, v in attrs if k == "a"])
     |      >>> pprint(exporter.export(root))
     |      {'a': 'root',
     |       'children': [{'a': 'sub0', 'children': [{'a': 'sub0A'}, {'a': 'sub0B'}]},
     |                    {'a': 'sub1'}]}
     |      
     |      The child iterator `childiter` can be used for sorting and filtering likewise:
     |      
     |      >>> exporter = DictExporter(childiter=lambda children: [child for child in children if "0" in child.a])
     |      >>> pprint(exporter.export(root))
     |      {'a': 'root',
     |       'children': [{'a': 'sub0',
     |                     'children': [{'a': 'sub0A', 'b': 'foo'}, {'a': 'sub0B'}]}]}
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from anytree.exporter.dictexporter.DictExporter:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
    
    class LopperDictImporter(builtins.object)
     |  Methods defined here:
     |  
     |  __init__(self, nodecls=<class 'anytree.node.anynode.AnyNode'>)
     |      Import Tree from dictionary.
     |      
     |      This is taken from the Anytree codebase, and modified to not
     |      require a "children" element in the yaml.
     |      
     |      Every dictionary is converted to an instance of `nodecls`.
     |      The dictionaries listed in the children attribute are converted
     |      likewise and added as children.
     |      
     |      Keyword Args:
     |          nodecls: class used for nodes.
     |      
     |      >>> from anytree.importer import DictImporter
     |      >>> from anytree import RenderTree
     |      >>> importer = DictImporter()
     |      >>> data = {
     |      ...     'a': 'root',
     |      ...     'children': [{'a': 'sub0',
     |      ...                   'children': [{'a': 'sub0A', 'b': 'foo'}, {'a': 'sub0B'}]},
     |      ...                  {'a': 'sub1'}]}
     |      >>> root = importer.import_(data)
     |      >>> print(RenderTree(root))
     |      AnyNode(a='root')
     |      ├── AnyNode(a='sub0')
     |      │   ├── AnyNode(a='sub0A', b='foo')
     |      │   └── AnyNode(a='sub0B')
     |      └── AnyNode(a='sub1')
     |  
     |  import_(self, data)
     |      Import tree from `data`.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
    
    class LopperDumper(ruamel.yaml.dumper.Dumper)
     |  Lopper specific dumper
     |  
     |  Any simple formating changes to the yaml output are contained in
     |  this class.
     |  
     |  Currently it only increases the indent on yaml sequences, but may
     |  container more adjustments in the future.
     |  
     |  Method resolution order:
     |      LopperDumper
     |      ruamel.yaml.dumper.Dumper
     |      ruamel.yaml.emitter.Emitter
     |      ruamel.yaml.serializer.Serializer
     |      ruamel.yaml.representer.Representer
     |      ruamel.yaml.representer.SafeRepresenter
     |      ruamel.yaml.representer.BaseRepresenter
     |      ruamel.yaml.resolver.Resolver
     |      ruamel.yaml.resolver.BaseResolver
     |      builtins.object
     |  
     |  Methods defined here:
     |  
     |  increase_indent(self, flow=False, indentless=False)
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from ruamel.yaml.dumper.Dumper:
     |  
     |  __init__(self, stream, default_style=None, default_flow_style=None, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None, block_seq_indent=None, top_level_colon_align=None, prefix_colon=None)
     |      Initialize self.  See help(type(self)) for accurate signature.
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from ruamel.yaml.emitter.Emitter:
     |  
     |  analyze_scalar(self, scalar)
     |  
     |  check_empty_document(self)
     |  
     |  check_empty_mapping(self)
     |  
     |  check_empty_sequence(self)
     |  
     |  check_simple_key(self)
     |  
     |  choose_scalar_style(self)
     |  
     |  determine_block_hints(self, text)
     |  
     |  dispose(self)
     |  
     |  emit(self, event)
     |  
     |  expect_alias(self)
     |  
     |  expect_block_mapping(self)
     |  
     |  expect_block_mapping_key(self, first=False)
     |  
     |  expect_block_mapping_simple_value(self)
     |  
     |  expect_block_mapping_value(self)
     |  
     |  expect_block_sequence(self)
     |  
     |  expect_block_sequence_item(self, first=False)
     |  
     |  expect_document_end(self)
     |  
     |  expect_document_root(self)
     |  
     |  expect_document_start(self, first=False)
     |  
     |  expect_first_block_mapping_key(self)
     |  
     |  expect_first_block_sequence_item(self)
     |  
     |  expect_first_document_start(self)
     |  
     |  expect_first_flow_mapping_key(self)
     |  
     |  expect_first_flow_sequence_item(self)
     |  
     |  expect_flow_mapping(self, single=False)
     |  
     |  expect_flow_mapping_key(self)
     |  
     |  expect_flow_mapping_simple_value(self)
     |  
     |  expect_flow_mapping_value(self)
     |  
     |  expect_flow_sequence(self)
     |  
     |  expect_flow_sequence_item(self)
     |  
     |  expect_node(self, root=False, sequence=False, mapping=False, simple_key=False)
     |  
     |  expect_nothing(self)
     |  
     |  expect_scalar(self)
     |  
     |  expect_stream_start(self)
     |  
     |  flush_stream(self)
     |  
     |  need_events(self, count)
     |  
     |  need_more_events(self)
     |  
     |  prepare_anchor(self, anchor)
     |  
     |  prepare_tag(self, tag)
     |  
     |  prepare_tag_handle(self, handle)
     |  
     |  prepare_tag_prefix(self, prefix)
     |  
     |  prepare_version(self, version)
     |  
     |  process_anchor(self, indicator)
     |  
     |  process_scalar(self)
     |  
     |  process_tag(self)
     |  
     |  write_comment(self, comment, pre=False)
     |  
     |  write_double_quoted(self, text, split=True)
     |  
     |  write_folded(self, text)
     |  
     |  write_indent(self)
     |  
     |  write_indicator(self, indicator, need_whitespace, whitespace=False, indention=False)
     |  
     |  write_line_break(self, data=None)
     |  
     |  write_literal(self, text, comment=None)
     |  
     |  write_plain(self, text, split=True)
     |  
     |  write_post_comment(self, event)
     |  
     |  write_pre_comment(self, event)
     |  
     |  write_single_quoted(self, text, split=True)
     |  
     |  write_stream_end(self)
     |  
     |  write_stream_start(self)
     |  
     |  write_tag_directive(self, handle_text, prefix_text)
     |  
     |  write_version_directive(self, version_text)
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from ruamel.yaml.emitter.Emitter:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
     |  
     |  flow_level
     |  
     |  serializer
     |  
     |  stream
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes inherited from ruamel.yaml.emitter.Emitter:
     |  
     |  DEFAULT_TAG_PREFIXES = {'!': '!', 'tag:yaml.org,2002:': '!!'}
     |  
     |  ESCAPE_REPLACEMENTS = {'\x00': '0', '\x07': 'a', '\x08': 'b', '\t': 't...
     |  
     |  MAX_SIMPLE_KEY_LENGTH = 128
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from ruamel.yaml.serializer.Serializer:
     |  
     |  anchor_node(self, node)
     |  
     |  close(self)
     |  
     |  generate_anchor(self, node)
     |  
     |  open(self)
     |  
     |  serialize(self, node)
     |  
     |  serialize_node(self, node, parent, index)
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from ruamel.yaml.serializer.Serializer:
     |  
     |  emitter
     |  
     |  resolver
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes inherited from ruamel.yaml.serializer.Serializer:
     |  
     |  ANCHOR_RE = <ruamel.yaml.util.LazyEval object>
     |  
     |  ANCHOR_TEMPLATE = 'id%03d'
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from ruamel.yaml.representer.Representer:
     |  
     |  represent_complex(self, data)
     |  
     |  represent_module(self, data)
     |  
     |  represent_name(self, data)
     |  
     |  represent_object(self, data)
     |  
     |  represent_tuple(self, data)
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes inherited from ruamel.yaml.representer.Representer:
     |  
     |  yaml_multi_representers = {<class 'object'>: <function Representer.rep...
     |  
     |  yaml_representers = {<class 'NoneType'>: <function SafeRepresenter.rep...
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from ruamel.yaml.representer.SafeRepresenter:
     |  
     |  ignore_aliases(self, data)
     |  
     |  represent_binary(self, data)
     |  
     |  represent_bool(self, data, anchor=None)
     |  
     |  represent_date(self, data)
     |  
     |  represent_datetime(self, data)
     |  
     |  represent_dict(self, data)
     |  
     |  represent_float(self, data)
     |  
     |  represent_int(self, data)
     |  
     |  represent_list(self, data)
     |  
     |  represent_none(self, data)
     |  
     |  represent_ordereddict(self, data)
     |  
     |  represent_set(self, data)
     |  
     |  represent_str(self, data)
     |  
     |  represent_undefined(self, data)
     |  
     |  represent_yaml_object(self, tag, data, cls, flow_style=None)
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes inherited from ruamel.yaml.representer.SafeRepresenter:
     |  
     |  inf_value = inf
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from ruamel.yaml.representer.BaseRepresenter:
     |  
     |  represent(self, data)
     |  
     |  represent_data(self, data)
     |  
     |  represent_key(self, data)
     |      David Fraser: Extract a method to represent keys in mappings, so that
     |      a subclass can choose not to quote them (for example)
     |      used in represent_mapping
     |      https://bitbucket.org/davidfraser/pyyaml/commits/d81df6eb95f20cac4a79eed95ae553b5c6f77b8c
     |  
     |  represent_mapping(self, tag, mapping, flow_style=None)
     |  
     |  represent_omap(self, tag, omap, flow_style=None)
     |  
     |  represent_scalar(self, tag, value, style=None, anchor=None)
     |  
     |  represent_sequence(self, tag, sequence, flow_style=None)
     |  
     |  ----------------------------------------------------------------------
     |  Class methods inherited from ruamel.yaml.representer.BaseRepresenter:
     |  
     |  add_multi_representer(data_type, representer) from builtins.type
     |  
     |  add_representer(data_type, representer) from builtins.type
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes inherited from ruamel.yaml.resolver.Resolver:
     |  
     |  yaml_implicit_resolvers = {'': [('tag:yaml.org,2002:null', <ruamel.yam...
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from ruamel.yaml.resolver.BaseResolver:
     |  
     |  ascend_resolver(self)
     |  
     |  check_resolver_prefix(self, depth, path, kind, current_node, current_index)
     |  
     |  descend_resolver(self, current_node, current_index)
     |  
     |  resolve(self, kind, value, implicit)
     |  
     |  ----------------------------------------------------------------------
     |  Class methods inherited from ruamel.yaml.resolver.BaseResolver:
     |  
     |  add_implicit_resolver(tag, regexp, first) from builtins.type
     |  
     |  add_implicit_resolver_base(tag, regexp, first) from builtins.type
     |  
     |  add_path_resolver(tag, path, kind=None) from builtins.type
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors inherited from ruamel.yaml.resolver.BaseResolver:
     |  
     |  parser
     |  
     |  processing_version
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes inherited from ruamel.yaml.resolver.BaseResolver:
     |  
     |  DEFAULT_MAPPING_TAG = 'tag:yaml.org,2002:map'
     |  
     |  DEFAULT_SCALAR_TAG = 'tag:yaml.org,2002:str'
     |  
     |  DEFAULT_SEQUENCE_TAG = 'tag:yaml.org,2002:seq'
     |  
     |  yaml_path_resolvers = {}
    
    class LopperTreeImporter(builtins.object)
     |  Methods defined here:
     |  
     |  __init__(self, nodecls=<class 'anytree.node.anynode.AnyNode'>)
     |      Import Tree from LopperTree
     |      
     |      Every node is converted to an instance of `nodecls`.
     |      The node's children are converted likewise and added as children.
     |      
     |      Keyword Args:
     |          nodecls: class used for nodes.
     |  
     |  import_(self, data)
     |      Import tree from `data`.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
    
    class LopperYAML(builtins.object)
     |  YAML read/writer for Lopper
     |  
     |  A Lopper "container" around a yaml input/output.
     |  
     |  This class is capable of reading a yaml inputfile, and
     |  creating a LopperTree. It is also capabable of taking a
     |  LopperTree and creating a yaml description of that tree.
     |  
     |  This is done by internally storing either a yaml or lopper tree input as a
     |  generic tree structure. The generic tree structure can be converted to a
     |  LopperTree or Yaml file on demand. Hence we have the capability of
     |  converting between the two formats as required.
     |  
     |  Methods defined here:
     |  
     |  __init__(self, yaml_file=None, tree=None, config=None)
     |      Initialize a a LopperYAML representation from either a yaml file
     |      or from a LopperTree.
     |      
     |      Args:
     |         yaml_file (string,optional): path to a yaml input file
     |         tree (LopperTree,optional): reference to a LopperTree
     |      
     |      Returns:
     |         LopperYAML object: self
     |  
     |  dump(self)
     |      Dump/print the internal representation of the YAML tree
     |      
     |      Debug routine to print the details of the Tree created for the
     |      input YAML or LopperTree
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |          None
     |  
     |  load_tree(self, tree=None)
     |      Load/Read a LopperTree into a YAML representation
     |      
     |      Create an internal tree object from an input LopperTree. The tree can be
     |      passed directly to this routine, or already be part of the object
     |      through initialization.
     |      
     |      Args:
     |          tree (LopperTree,optional): LopperTree representation of a device tree
     |      
     |      Returns:
     |          Nothing
     |  
     |  load_yaml(self, filename=None)
     |      Load/Read a YAML file into tree structure
     |      
     |      Create an internal tree object from an input YAML file. The file can be
     |      passed directly to this routine, or already be part of the object
     |      through initialization.
     |      
     |      Args:
     |          filename (string,optional): path to yaml file to read
     |      
     |      Returns:
     |          Nothing
     |  
     |  path(self, node)
     |      Determine the string representation of a Node's path
     |      
     |      Generate and return a string that represents the path of a node in
     |      the Yaml internal tree.
     |      
     |      Args:
     |          node (AnyTreeNode): node to query for path
     |      
     |      Returns:
     |          string: absolute path of the node
     |  
     |  print(self)
     |      Print/Render tree representation of the YAML input
     |      
     |      Args:
     |          None
     |      
     |      Returns:
     |          Nothing
     |  
     |  prop_expand(self, prop)
     |      Expand a property into a format a device tree can represent
     |      
     |      This routine is for use when json is not available as a serialization
     |      mechanism for imported yaml. It expands lists and dictionaries into
     |      a ":::" separate string, that can be carried in a device tree.
     |      
     |      This is mostly obsolete, but is kept for compatibility
     |      
     |      Args:
     |         Anytree Property
     |      
     |      Returns:
     |         string: serialized representation of the property
     |  
     |  props(self, node)
     |      Create a dictionary representation of Node attributes
     |      
     |      Gather a dictionary representation of the properties of a LopperYAML
     |      Node.
     |      
     |      This routine skips internal members of a node, and returns only
     |      attributes that are meaningful to the caller.
     |      
     |      It knows how to expand node references and returns them as properties
     |      of the node.
     |      
     |      Args:
     |          node (AnyTreeNode): node to export as dictionary
     |      
     |      Returns:
     |          dict of node names -> properties
     |  
     |  to_tree(self)
     |      Export LopperYAML to a LopperTree
     |      
     |      Args:
     |         None
     |      
     |      Returns:
     |        LopperTree object representation of YAML object
     |  
     |  to_yaml(self, outfile=None, verbose=0)
     |      Export LopperYAML tree to a yaml output file
     |      
     |      Args:
     |         outfile (string): path to a yaml output file
     |      
     |      Returns:
     |         Nothing
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)

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