blob: fefb049c8aea22da1f387fa09efadab7dd9adb02 [file] [log] [blame]
#!/usr/bin/env python3
#
# Copyright (c) 2017 Intel Corporation
# Copyright (c) 2020 Nordic Semiconductor NA
#
# SPDX-License-Identifier: Apache-2.0
"""Translate generic handles into ones optimized for the application.
Immutable device data includes information about dependencies,
e.g. that a particular sensor is controlled through a specific I2C bus
and that it signals event on a pin on a specific GPIO controller.
This information is encoded in the first-pass binary using identifiers
derived from the devicetree. This script extracts those identifiers
and replaces them with ones optimized for use with the devices
actually present.
For example the sensor might have a first-pass handle defined by its
devicetree ordinal 52, with the I2C driver having ordinal 24 and the
GPIO controller ordinal 14. The runtime ordinal is the index of the
corresponding device in the static devicetree array, which might be 6,
5, and 3, respectively.
The output is a C source file that provides alternative definitions
for the array contents referenced from the immutable device objects.
In the final link these definitions supersede the ones in the
driver-specific object file.
"""
import sys
import argparse
import os
import struct
import pickle
from packaging import version
import elftools
from elftools.elf.elffile import ELFFile
from elftools.elf.sections import SymbolTableSection
import elftools.elf.enums
# This is needed to load edt.pickle files.
sys.path.insert(0, os.path.join(os.path.dirname(__file__),
'dts', 'python-devicetree', 'src'))
from devicetree import edtlib # pylint: disable=unused-import
if version.parse(elftools.__version__) < version.parse('0.24'):
sys.exit("pyelftools is out of date, need version 0.24 or later")
scr = os.path.basename(sys.argv[0])
def debug(text):
if not args.verbose:
return
sys.stdout.write(scr + ": " + text + "\n")
def parse_args():
global args
parser = argparse.ArgumentParser(
description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument("-k", "--kernel", required=True,
help="Input zephyr ELF binary")
parser.add_argument("-d", "--num-dynamic-devices", required=False, default=0,
type=int, help="Input number of dynamic devices allowed")
parser.add_argument("-o", "--output-source", required=True,
help="Output source file")
parser.add_argument("-v", "--verbose", action="store_true",
help="Print extra debugging information")
parser.add_argument("-z", "--zephyr-base",
help="Path to current Zephyr base. If this argument \
is not provided the environment will be checked for \
the ZEPHYR_BASE environment variable.")
parser.add_argument("-s", "--start-symbol", required=True,
help="Symbol name of the section which contains the \
devices. The symbol name must point to the first \
device in that section.")
args = parser.parse_args()
if "VERBOSE" in os.environ:
args.verbose = 1
ZEPHYR_BASE = args.zephyr_base or os.getenv("ZEPHYR_BASE")
if ZEPHYR_BASE is None:
sys.exit("-z / --zephyr-base not provided. Please provide "
"--zephyr-base or set ZEPHYR_BASE in environment")
sys.path.insert(0, os.path.join(ZEPHYR_BASE, "scripts/dts"))
def symbol_data(elf, sym):
addr = sym.entry.st_value
len = sym.entry.st_size
for section in elf.iter_sections():
start = section['sh_addr']
end = start + section['sh_size']
if (start <= addr) and (addr + len) <= end:
offset = addr - section['sh_addr']
return bytes(section.data()[offset:offset + len])
def symbol_handle_data(elf, sym):
data = symbol_data(elf, sym)
if data:
format = "<" if elf.little_endian else ">"
format += "%uh" % (len(data) / 2)
return struct.unpack(format, data)
# These match the corresponding constants in <device.h>
DEVICE_HANDLE_SEP = -32768
DEVICE_HANDLE_ENDS = 32767
DEVICE_HANDLE_NULL = 0
def handle_name(hdl):
if hdl == DEVICE_HANDLE_SEP:
return "DEVICE_HANDLE_SEP"
if hdl == DEVICE_HANDLE_ENDS:
return "DEVICE_HANDLE_ENDS"
if hdl == 0:
return "DEVICE_HANDLE_NULL"
return str(int(hdl))
class Device:
"""
Represents information about a device object and its references to other objects.
"""
def __init__(self, elf, ld_constants, sym, addr):
self.elf = elf
self.ld_constants = ld_constants
self.sym = sym
self.addr = addr
# Point to the handles instance associated with the device;
# assigned by correlating the device struct handles pointer
# value with the addr of a Handles instance.
self.__handles = None
self.__pm = None
@property
def obj_handles(self):
"""
Returns the value from the device struct handles field, pointing to the
array of handles for devices this device depends on.
"""
if self.__handles is None:
data = symbol_data(self.elf, self.sym)
format = "<" if self.elf.little_endian else ">"
if self.elf.elfclass == 32:
format += "I"
size = 4
else:
format += "Q"
size = 8
offset = self.ld_constants["_DEVICE_STRUCT_HANDLES_OFFSET"]
self.__handles = struct.unpack(format, data[offset:offset + size])[0]
return self.__handles
@property
def obj_pm(self):
"""
Returns the value from the device struct pm field, pointing to the
pm struct for this device.
"""
if self.__pm is None:
data = symbol_data(self.elf, self.sym)
format = "<" if self.elf.little_endian else ">"
if self.elf.elfclass == 32:
format += "I"
size = 4
else:
format += "Q"
size = 8
offset = self.ld_constants["_DEVICE_STRUCT_PM_OFFSET"]
self.__pm = struct.unpack(format, data[offset:offset + size])[0]
return self.__pm
class PMDevice:
"""
Represents information about a pm_device object and its references to other objects.
"""
def __init__(self, elf, ld_constants, sym, addr):
self.elf = elf
self.ld_constants = ld_constants
self.sym = sym
self.addr = addr
# Point to the device instance associated with the pm_device;
self.__flags = None
def is_domain(self):
"""
Checks if the device that this pm struct belongs is a power domain.
"""
if self.__flags is None:
data = symbol_data(self.elf, self.sym)
format = "<" if self.elf.little_endian else ">"
if self.elf.elfclass == 32:
format += "I"
size = 4
else:
format += "Q"
size = 8
offset = self.ld_constants["_PM_DEVICE_STRUCT_FLAGS_OFFSET"]
self.__flags = struct.unpack(format, data[offset:offset + size])[0]
return self.__flags & (1 << self.ld_constants["_PM_DEVICE_FLAG_PD"])
class Handles:
def __init__(self, sym, addr, handles, node):
self.sym = sym
self.addr = addr
self.handles = handles
self.node = node
self.dep_ord = None
self.dev_deps = None
self.ext_deps = None
def main():
parse_args()
assert args.kernel, "--kernel ELF required to extract data"
elf = ELFFile(open(args.kernel, "rb"))
edtser = os.path.join(os.path.split(args.kernel)[0], "edt.pickle")
with open(edtser, 'rb') as f:
edt = pickle.load(f)
pm_devices = {}
devices = []
handles = []
# Leading _ are stripped from the stored constant key
want_constants = set([args.start_symbol,
"_DEVICE_STRUCT_SIZEOF",
"_DEVICE_STRUCT_HANDLES_OFFSET"])
if args.num_dynamic_devices != 0:
want_constants.update(["_PM_DEVICE_FLAG_PD",
"_DEVICE_STRUCT_PM_OFFSET",
"_PM_DEVICE_STRUCT_FLAGS_OFFSET"])
ld_constants = dict()
for section in elf.iter_sections():
if isinstance(section, SymbolTableSection):
for sym in section.iter_symbols():
if sym.name in want_constants:
ld_constants[sym.name] = sym.entry.st_value
continue
if sym.entry.st_info.type != 'STT_OBJECT':
continue
if sym.name.startswith("__device"):
addr = sym.entry.st_value
if sym.name.startswith("__device_"):
devices.append(Device(elf, ld_constants, sym, addr))
debug("device %s" % (sym.name,))
elif sym.name.startswith("__devicehdl_"):
hdls = symbol_handle_data(elf, sym)
# The first element of the hdls array is the dependency
# ordinal of the device, which identifies the devicetree
# node.
node = edt.dep_ord2node[hdls[0]] if (hdls and hdls[0] != 0) else None
handles.append(Handles(sym, addr, hdls, node))
debug("handles %s %d %s" % (sym.name, hdls[0] if hdls else -1, node))
if sym.name.startswith("__pm_device__") and not sym.name.endswith("_slot"):
addr = sym.entry.st_value
pm_devices[addr] = PMDevice(elf, ld_constants, sym, addr)
debug("pm device %s" % (sym.name,))
assert len(want_constants) == len(ld_constants), "linker map data incomplete"
devices = sorted(devices, key = lambda k: k.sym.entry.st_value)
device_start_addr = ld_constants[args.start_symbol]
device_size = 0
assert len(devices) == len(handles), 'mismatch devices and handles'
used_nodes = set()
for handle in handles:
handle.device = None
for device in devices:
if handle.addr == device.obj_handles:
handle.device = device
break
device = handle.device
assert device, 'no device for %s' % (handle.sym.name,)
device.handle = handle
if device_size == 0:
device_size = device.sym.entry.st_size
# The device handle is one plus the ordinal of this device in
# the device table.
device.dev_handle = 1 + int((device.sym.entry.st_value - device_start_addr) / device_size)
debug("%s dev ordinal %d" % (device.sym.name, device.dev_handle))
n = handle.node
if n is not None:
debug("%s dev ordinal %d\n\t%s" % (n.path, device.dev_handle, ' ; '.join(str(_) for _ in handle.handles)))
used_nodes.add(n)
n.__device = device
else:
debug("orphan %d" % (device.dev_handle,))
hv = handle.handles
hvi = 1
handle.dev_deps = []
handle.ext_deps = []
handle.dev_sups = []
hdls = handle.dev_deps
while hvi < len(hv):
h = hv[hvi]
if h == DEVICE_HANDLE_ENDS:
break
if h == DEVICE_HANDLE_SEP:
if hdls == handle.dev_deps:
hdls = handle.ext_deps
else:
hdls = handle.dev_sups
else:
hdls.append(h)
n = edt
hvi += 1
# Compute the dependency graph induced from the full graph restricted to the
# the nodes that exist in the application. Note that the edges in the
# induced graph correspond to paths in the full graph.
root = edt.dep_ord2node[0]
assert root not in used_nodes
for n in used_nodes:
# Where we're storing the final set of nodes: these are all used
n.__depends = set()
n.__supports = set()
deps = set(n.depends_on)
debug("\nNode: %s\nOrig deps:\n\t%s" % (n.path, "\n\t".join([dn.path for dn in deps])))
while len(deps) > 0:
dn = deps.pop()
if dn in used_nodes:
# this is used
n.__depends.add(dn)
elif dn != root:
# forward the dependency up one level
for ddn in dn.depends_on:
deps.add(ddn)
debug("Final deps:\n\t%s\n" % ("\n\t".join([ _dn.path for _dn in n.__depends])))
sups = set(n.required_by)
debug("\nOrig sups:\n\t%s" % ("\n\t".join([dn.path for dn in sups])))
while len(sups) > 0:
sn = sups.pop()
if sn in used_nodes:
# this is used
n.__supports.add(sn)
else:
# forward the support down one level
for ssn in sn.required_by:
sups.add(ssn)
debug("\nFinal sups:\n\t%s" % ("\n\t".join([_sn.path for _sn in n.__supports])))
with open(args.output_source, "w") as fp:
fp.write('#include <zephyr/device.h>\n')
fp.write('#include <zephyr/toolchain.h>\n')
for dev in devices:
hs = dev.handle
assert hs, "no hs for %s" % (dev.sym.name,)
dep_paths = []
ext_paths = []
sup_paths = []
hdls = []
sn = hs.node
if sn:
hdls.extend(dn.__device.dev_handle for dn in sn.__depends)
for dn in sn.depends_on:
if dn in sn.__depends:
dep_paths.append(dn.path)
else:
dep_paths.append('(%s)' % dn.path)
# Force separator to signal start of injected dependencies
hdls.append(DEVICE_HANDLE_SEP)
if len(hs.ext_deps) > 0:
# TODO: map these to something smaller?
ext_paths.extend(map(str, hs.ext_deps))
hdls.append(DEVICE_HANDLE_SEP)
hdls.extend(hs.ext_deps)
# Force separator to signal start of supported devices
hdls.append(DEVICE_HANDLE_SEP)
if len(hs.dev_sups) > 0:
for dn in sn.required_by:
if dn in sn.__supports:
sup_paths.append(dn.path)
else:
sup_paths.append('(%s)' % dn.path)
hdls.extend(dn.__device.dev_handle for dn in sn.__supports)
if args.num_dynamic_devices != 0:
pm = pm_devices.get(dev.obj_pm)
if pm and pm.is_domain():
hdls.extend(DEVICE_HANDLE_NULL for dn in range(args.num_dynamic_devices))
# Terminate the array with the end symbol
hdls.append(DEVICE_HANDLE_ENDS)
lines = [
'',
'/* %d : %s:' % (dev.dev_handle, (sn and sn.path) or "sysinit"),
]
if len(dep_paths) > 0:
lines.append(' * Direct Dependencies:')
lines.append(' * - %s' % ('\n * - '.join(dep_paths)))
if len(ext_paths) > 0:
lines.append(' * Injected Dependencies:')
lines.append(' * - %s' % ('\n * - '.join(ext_paths)))
if len(sup_paths) > 0:
lines.append(' * Supported:')
lines.append(' * - %s' % ('\n * - '.join(sup_paths)))
lines.extend([
' */',
'const device_handle_t __aligned(2) __attribute__((__section__(".__device_handles_pass2")))',
'%s[] = { %s };' % (hs.sym.name, ', '.join([handle_name(_h) for _h in hdls])),
'',
])
fp.write('\n'.join(lines))
if __name__ == "__main__":
main()