2 # SPDX-License-Identifier: Apache-2.0
6 devicetree bindings.
26 GENERIC_OR_VENDOR_INDEPENDENT = 'Generic or vendor-independent'
31 # Base properties that have documentation in 'dt-important-props'.
42     def __init__(self, vendor_prefixes, bindings):  argument
44         self.vnd2bindings = self.init_vnd2bindings(bindings)
50     def bindings(self, vnd, default=None):  member in VndLookup
59         # Load the vendor-prefixes.txt file. Return a dict mapping 'vnd'
65         #    vnd	A stand-in for a real vendor
67         # Gets split into a key 'vnd' and a value 'A stand-in for a real
77         logger.info('found %d vendor prefixes in %s', len(vnd2vendor) - 1,
84     def init_vnd2bindings(self, bindings):  argument
85         # Take a 'vnd2vendor' map and a list of bindings and return a dict
86         # mapping 'vnd' vendor prefixes prefixes to lists of bindings. The
87         # bindings in each list are sorted by compatible. The keys in the
92         # - The 'None' key maps to bindings with no vendor prefix
93         #   in their compatibles, like 'gpio-keys'. This is the first key.
94         # - The (UNKNOWN_VENDOR,) key maps to bindings whose compatible
98         # Get an unsorted dict mapping vendor prefixes to lists of bindings.
102         for binding in bindings:
118         # Sort the bindings for each vendor by compatible.
123         # The unknown-vendor bindings being inserted as a 1-tuple key is a
145         # - The None key maps to the ref target for bindings with no
146         #   vendor prefix in their compatibles, like 'gpio-keys'
147         # - The (UNKNOWN_VENDOR,) key maps to the ref target for bindings
165     bindings = load_bindings(args.dts_roots, args.dts_folders)
168     vnd_lookup = VndLookup(args.vendor_prefixes, bindings)
169     dump_content(bindings, base_binding, vnd_lookup, driver_sources, args.out_dir,
176     parser.add_argument('-v', '--verbose', default=0, action='count',
178     parser.add_argument('--vendor-prefixes', required=True,
179                         help='vendor-prefixes.txt file path')
180     parser.add_argument('--dts-root', dest='dts_roots', action='append',
181                         help='''additional DTS root directory as it would
183     parser.add_argument('--dts-folder', dest='dts_folders', action='append', default=[],
184                         help='additional DTS folders containing binding files')
185     parser.add_argument('--turbo-mode', action='store_true',
205         sys.exit('no DTS roots; use --dts-root to specify at least one')
209         binding_files.extend(glob.glob(f'{dts_root}/dts/bindings/**/*.yml',
211         binding_files.extend(glob.glob(f'{dts_root}/dts/bindings/**/*.yaml',
217     bindings = edtlib.bindings_from_paths(binding_files, ignore_errors=True)
219     num_total = len(bindings)
221     # Remove bindings from the 'vnd' vendor, which is not a real vendor,
222     # but rather a stand-in we use for examples and tests when a real
224     bindings = [binding for binding in bindings if
227     logger.info('found %d bindings (ignored %d) in this dts_roots list: %s',
228                 len(bindings), num_total - len(bindings), dts_roots)
230     return bindings
236     # nodes from node-specific properties.
238     base_yaml = ZEPHYR_BASE / 'dts' / 'bindings' / 'base' / 'base.yaml'
239     base_includes = {"pm.yaml": os.fspath(ZEPHYR_BASE / 'dts' / 'bindings' / 'base'/ 'pm.yaml')}
256     # - There is only one and only one file with a "#define DT_DRV_COMPAT <compatible>" for a given
258     # - or, a file contains both a "#define DT_DRV_COMPAT <compatible>" and a
267                 with open(filepath, encoding="utf-8") as f:
299 def dump_content(bindings, base_binding, vnd_lookup, driver_sources, out_dir, turbo_mode):  argument
307     setup_bindings_dir(bindings, out_dir)
309         write_dummy_index(bindings, out_dir)
312         write_orphans(bindings, base_binding, vnd_lookup, driver_sources, out_dir)
314 def setup_bindings_dir(bindings, out_dir):  argument
316     # out_dir / bindings / {binding_path}.rst. Delete all the ones that
317     # shouldn't be there. Make sure the bindings output directory
321     bindings_dir = out_dir / 'bindings'
325     for binding in bindings:
336 def write_dummy_index(bindings, out_dir):  argument
337     # Write out_dir / bindings.rst, with dummy anchors
344         'Dummy bindings index',
350     compatibles = {binding.compatible for binding in bindings}
355     write_if_updated(out_dir / 'bindings.rst', content)
359     # Write out_dir / bindings.rst, the top level index of bindings.
366     Bindings index
369     This page documents the available devicetree bindings.
370     See {zref('dt-bindings')} for an introduction to the Zephyr bindings
377     Click on a vendor's name to go to the list of bindings for
380     .. rst-class:: rst-columns
383     for vnd, bindings in vnd_lookup.vnd2bindings.items():
384         if len(bindings) == 0:
386         print(f'- :ref:`{vnd_lookup.target(vnd)}`', file=string_io)
390     Bindings by vendor
393     This section contains available bindings, grouped by vendor.
394     Within each group, bindings are listed by the "compatible" property
399     .. rst-class:: rst-columns
401     - <compatible-A>
402     - <compatible-B> (on <bus-name> bus)
403     - <compatible-C>
404     - ...
406     The text "(on <bus-name> bus)" appears when bindings may behave
412     for vnd, bindings in vnd_lookup.vnd2bindings.items():
421         if len(bindings) == 0:
430         .. rst-class:: rst-columns
432         for binding in bindings:
433             print(f'- :ref:`{binding_ref_target(binding)}`', file=string_io)
436     write_if_updated(out_dir / 'bindings.rst', string_io.getvalue())
438 def write_orphans(bindings, base_binding, vnd_lookup, driver_sources, out_dir):  argument
439     # Write out_dir / bindings / foo / binding_page.rst for each binding
440     # in 'bindings', along with any "disambiguation" pages needed when a
441     # single compatible string can be handled by multiple bindings.
446     logging.info('updating :orphan: files for %d bindings', len(bindings))
449     # First, figure out which compatibles map to multiple bindings. We
451     # a compatible are "disambiguation" pages that point to per-bus
455     for binding in bindings:
457     dup_compat2bindings = {compatible: bindings for compatible, bindings
458                            in compat2bindings.items() if len(bindings) > 1}
460     # Next, write the per-binding pages. These contain the
461     # per-compatible targets for compatibles not in 'dup_compats'.
462     # We'll finish up by writing per-compatible "disambiguation" pages
467     for binding in bindings:
473         written = write_if_updated(out_dir / 'bindings' /
503     # compatibles which have multiple associated bindings; if
527         # This compatible is handled by multiple bindings;
537         <!--
540         -->
541         <style>.wy-nav-content {{ max-width: none; !important }}</style>
550     # Vendor: <link-to-vendor-section>
557     compatible = re.sub("[-,.@/+]", "_", compatible.lower())
600             print(f'- {specifier} cells: {", ".join(cells)}',
646            .. group-tab:: Node specific properties
652            .. group-tab:: Deprecated node specific properties
658            .. group-tab:: Base properties
668         print('No top-level properties.\n', file=string_io)
672     # bindings.
703     .. list-table::
705        :header-rows: 1
707        * - Name
708          - Type
709          - Details
740             details += (f'\n\nSee {zref("dt-important-props")} for more '
747    * - ``{prop_spec.name}``
748      - ``{prop_spec.type}``
749      - {textwrap.indent(details, ' ' * 7).lstrip()}
774 def print_compatible_disambiguation_page(compatible, bindings, string_io):  argument
776     # handled by any of the bindings in 'bindings', to 'string_io'.
778     assert len(bindings) > 1, (compatible, bindings)
781     output_list = '\n    '.join(f'- :ref:`{binding_ref_target(binding)}`'
782                                 for binding in bindings)
793     of the following bindings:
799     # Helper for dedenting and printing a triple-quoted RST block.
800     # (Just a block of text, not necessarily just a 'code-block'
806     # Converts 's', a string, to an indented rst .. code-block::. The
810     return ('.. code-block:: none\n\n' +
826     # Name of the per-compatible disambiguation page within the
836     # By default, the bindings docs are in the main Zephyr
844     # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
858     # directory containing documentation for all bindings. It does
859     # this by stripping off the '.../dts/bindings/' prefix common to
860     # all bindings files in a DTS_ROOT directory.
862     # For example, for .../zephyr/dts/bindings/base/base.yaml, this
869     dts_bindings = 'dts/bindings/'
872     if idx == -1:
875     # Cut past dts/bindings, strip off the extension (.yaml or .yml), and
883     return 'dtbinding_' + re.sub('[/,-]', '_', stem)