lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 1 | # Copyright lowRISC contributors. |
| 2 | # Licensed under the Apache License, Version 2.0, see LICENSE for details. |
| 3 | # SPDX-License-Identifier: Apache-2.0 |
| 4 | """ |
Rupert Swarbrick | 200d8b4 | 2021-03-08 12:32:11 +0000 | [diff] [blame] | 5 | Generate HTML documentation from Block |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 6 | """ |
| 7 | |
Rupert Swarbrick | 200d8b4 | 2021-03-08 12:32:11 +0000 | [diff] [blame] | 8 | from typing import TextIO |
| 9 | |
Eunchan Kim | 2861a7c | 2022-07-29 11:52:36 -0700 | [diff] [blame] | 10 | from reggen.ip_block import IpBlock |
| 11 | from reggen.html_helpers import render_td |
| 12 | from reggen.signal import Signal |
Rupert Swarbrick | 302f038 | 2021-02-05 13:32:02 +0000 | [diff] [blame] | 13 | |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 14 | |
Rupert Swarbrick | 200d8b4 | 2021-03-08 12:32:11 +0000 | [diff] [blame] | 15 | def genout(outfile: TextIO, msg: str) -> None: |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 16 | outfile.write(msg) |
| 17 | |
| 18 | |
Rupert Swarbrick | 200d8b4 | 2021-03-08 12:32:11 +0000 | [diff] [blame] | 19 | def name_width(x: Signal) -> str: |
Rupert Swarbrick | 269bb3d | 2021-02-23 15:41:56 +0000 | [diff] [blame] | 20 | if x.bits.width() == 1: |
| 21 | return x.name |
| 22 | |
| 23 | return '{}[{}:0]'.format(x.name, x.bits.msb) |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 24 | |
| 25 | |
Rupert Swarbrick | 200d8b4 | 2021-03-08 12:32:11 +0000 | [diff] [blame] | 26 | def gen_kv(outfile: TextIO, key: str, value: str) -> None: |
Rupert Swarbrick | 6c83129 | 2021-02-25 17:08:53 +0000 | [diff] [blame] | 27 | genout(outfile, |
| 28 | '<p><i>{}:</i> {}</p>\n'.format(key, value)) |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 29 | |
| 30 | |
Rupert Swarbrick | 4f282bb | 2021-03-31 10:32:06 +0100 | [diff] [blame] | 31 | def gen_cfg_html(cfgs: IpBlock, outfile: TextIO) -> None: |
Rupert Swarbrick | 200d8b4 | 2021-03-08 12:32:11 +0000 | [diff] [blame] | 32 | rnames = cfgs.get_rnames() |
Rupert Swarbrick | 302f038 | 2021-02-05 13:32:02 +0000 | [diff] [blame] | 33 | |
Rupert Swarbrick | 6c83129 | 2021-02-25 17:08:53 +0000 | [diff] [blame] | 34 | ot_server = 'https://docs.opentitan.org' |
| 35 | comport_url = ot_server + '/doc/rm/comportability_specification' |
Eunchan Kim | 0bd7566 | 2020-04-24 10:21:18 -0700 | [diff] [blame] | 36 | genout(outfile, |
Rupert Swarbrick | 6c83129 | 2021-02-25 17:08:53 +0000 | [diff] [blame] | 37 | '<p>Referring to the <a href="{url}">Comportable guideline for ' |
| 38 | 'peripheral device functionality</a>, the module ' |
| 39 | '<b><code>{mod_name}</code></b> has the following hardware ' |
| 40 | 'interfaces defined.</p>\n' |
| 41 | .format(url=comport_url, mod_name=cfgs.name)) |
| 42 | |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 43 | # clocks |
Rupert Swarbrick | 6c83129 | 2021-02-25 17:08:53 +0000 | [diff] [blame] | 44 | gen_kv(outfile, |
| 45 | 'Primary Clock', |
Rupert Swarbrick | d0cbfad | 2021-06-29 17:04:51 +0100 | [diff] [blame] | 46 | '<b><code>{}</code></b>'.format(cfgs.clocking.primary.clock)) |
| 47 | other_clocks = cfgs.clocking.other_clocks() |
| 48 | if other_clocks: |
| 49 | other_clocks_str = ['<b><code>{}</code></b>'.format(clk) |
| 50 | for clk in other_clocks] |
| 51 | gen_kv(outfile, 'Other Clocks', ', '.join(other_clocks_str)) |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 52 | else: |
Rupert Swarbrick | 6c83129 | 2021-02-25 17:08:53 +0000 | [diff] [blame] | 53 | gen_kv(outfile, 'Other Clocks', '<i>none</i>') |
| 54 | |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 55 | # bus interfaces |
Rupert Swarbrick | 6c83129 | 2021-02-25 17:08:53 +0000 | [diff] [blame] | 56 | dev_ports = ['<b><code>{}</code></b>'.format(port) |
| 57 | for port in cfgs.bus_interfaces.get_port_names(False, True)] |
| 58 | assert dev_ports |
| 59 | gen_kv(outfile, 'Bus Device Interfaces (TL-UL)', ', '.join(dev_ports)) |
| 60 | |
| 61 | host_ports = ['<b><code>{}</code></b>'.format(port) |
| 62 | for port in cfgs.bus_interfaces.get_port_names(True, False)] |
| 63 | if host_ports: |
| 64 | gen_kv(outfile, 'Bus Host Interfaces (TL-UL)', ', '.join(host_ports)) |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 65 | else: |
Rupert Swarbrick | 6c83129 | 2021-02-25 17:08:53 +0000 | [diff] [blame] | 66 | gen_kv(outfile, 'Bus Host Interfaces (TL-UL)', '<i>none</i>') |
Rupert Swarbrick | 302f038 | 2021-02-05 13:32:02 +0000 | [diff] [blame] | 67 | |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 68 | # IO |
Rupert Swarbrick | 269bb3d | 2021-02-23 15:41:56 +0000 | [diff] [blame] | 69 | ios = ([('input', x) for x in cfgs.xputs[1]] + |
| 70 | [('output', x) for x in cfgs.xputs[2]] + |
| 71 | [('inout', x) for x in cfgs.xputs[0]]) |
Rupert Swarbrick | 302f038 | 2021-02-05 13:32:02 +0000 | [diff] [blame] | 72 | if ios: |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 73 | genout(outfile, "<p><i>Peripheral Pins for Chip IO:</i></p>\n") |
| 74 | genout( |
| 75 | outfile, "<table class=\"cfgtable\"><tr>" + |
| 76 | "<th>Pin name</th><th>direction</th>" + |
| 77 | "<th>Description</th></tr>\n") |
Rupert Swarbrick | 302f038 | 2021-02-05 13:32:02 +0000 | [diff] [blame] | 78 | for direction, x in ios: |
| 79 | genout(outfile, |
| 80 | '<tr><td>{}</td><td>{}</td>{}</tr>' |
| 81 | .format(name_width(x), |
| 82 | direction, |
Rupert Swarbrick | 269bb3d | 2021-02-23 15:41:56 +0000 | [diff] [blame] | 83 | render_td(x.desc, rnames, None))) |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 84 | genout(outfile, "</table>\n") |
| 85 | else: |
| 86 | genout(outfile, "<p><i>Peripheral Pins for Chip IO: none</i></p>\n") |
Rupert Swarbrick | e166d87 | 2021-02-05 13:34:35 +0000 | [diff] [blame] | 87 | |
Eunchan Kim | fdcfb3b | 2022-08-01 15:39:32 -0700 | [diff] [blame] | 88 | # Inter-Module Signals |
| 89 | if not cfgs.inter_signals: |
| 90 | genout(outfile, "<p><em>Inter-Module Signals: none</em></p>\n") |
| 91 | else: |
Eli Kim | 233dca2 | 2022-10-19 09:43:14 -0700 | [diff] [blame] | 92 | genout(outfile, |
| 93 | "<p><em>Inter-Module Signals:</em>\n" + |
| 94 | "<a href=\"/doc/rm/comportability_specification/#inter-signal-handling\">\n" + |
| 95 | "Reference</a></p>\n") |
Eunchan Kim | fdcfb3b | 2022-08-01 15:39:32 -0700 | [diff] [blame] | 96 | |
| 97 | genout(outfile, |
| 98 | "<table class=\"cfgtable\">\n" + |
| 99 | " <caption>Inter-Module Signals</caption>\n" + |
| 100 | " <thead>\n" + |
| 101 | " <tr>\n" + |
| 102 | " <th>Port Name</th>\n" + |
| 103 | " <th>Package::Struct</th>\n" + |
| 104 | " <th>Type</th>\n" + |
| 105 | " <th>Act</th>\n" + |
| 106 | " <th>Width</th>\n" + |
Michael Schaffner | ea40386 | 2022-09-01 14:45:49 -0700 | [diff] [blame] | 107 | " <th>Description</th>\n" + |
Eunchan Kim | fdcfb3b | 2022-08-01 15:39:32 -0700 | [diff] [blame] | 108 | " </tr>\n" + |
| 109 | " </thead>\n" + |
| 110 | " <tbody>\n") |
| 111 | |
| 112 | for ims in cfgs.inter_signals: |
| 113 | name = ims.name |
| 114 | pkg_struct = ims.package + "::" + ims.struct if ims.package is not None else ims.struct |
| 115 | sig_type = ims.signal_type |
| 116 | act = ims.act |
| 117 | width = str(ims.width) if ims.width is not None else "1" |
Michael Schaffner | ea40386 | 2022-09-01 14:45:49 -0700 | [diff] [blame] | 118 | desc = ims.desc if ims.desc is not None else "" |
Eunchan Kim | fdcfb3b | 2022-08-01 15:39:32 -0700 | [diff] [blame] | 119 | genout(outfile, |
| 120 | " <tr>\n" + |
| 121 | " <td>" + name + "</td>\n" + |
| 122 | " <td>" + pkg_struct + "</td>\n" + |
Eli Kim | 233dca2 | 2022-10-19 09:43:14 -0700 | [diff] [blame] | 123 | " <td>" + sig_type + "</td>\n" + |
Eunchan Kim | fdcfb3b | 2022-08-01 15:39:32 -0700 | [diff] [blame] | 124 | " <td>" + act + "</td>\n" + |
| 125 | " <td>" + width + "</td>\n" + |
Michael Schaffner | ea40386 | 2022-09-01 14:45:49 -0700 | [diff] [blame] | 126 | " <td>" + desc + "</td>\n" + |
Eunchan Kim | fdcfb3b | 2022-08-01 15:39:32 -0700 | [diff] [blame] | 127 | " </tr>\n") |
| 128 | continue |
| 129 | |
| 130 | genout(outfile, |
| 131 | " </tbody>\n" + |
| 132 | "</table>\n") |
| 133 | |
Rupert Swarbrick | 269bb3d | 2021-02-23 15:41:56 +0000 | [diff] [blame] | 134 | if not cfgs.interrupts: |
Rupert Swarbrick | e166d87 | 2021-02-05 13:34:35 +0000 | [diff] [blame] | 135 | genout(outfile, "<p><i>Interrupts: none</i></p>\n") |
| 136 | else: |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 137 | genout(outfile, "<p><i>Interrupts:</i></p>\n") |
| 138 | genout( |
| 139 | outfile, "<table class=\"cfgtable\"><tr><th>Interrupt Name</th>" + |
Eli Kim | 233dca2 | 2022-10-19 09:43:14 -0700 | [diff] [blame] | 140 | "<th>Type</th><th>Description</th></tr>\n") |
Rupert Swarbrick | 269bb3d | 2021-02-23 15:41:56 +0000 | [diff] [blame] | 141 | for x in cfgs.interrupts: |
Rupert Swarbrick | 302f038 | 2021-02-05 13:32:02 +0000 | [diff] [blame] | 142 | genout(outfile, |
Eli Kim | 233dca2 | 2022-10-19 09:43:14 -0700 | [diff] [blame] | 143 | '<tr><td>{}</td><td>{}</td>{}</tr>' |
Rupert Swarbrick | 302f038 | 2021-02-05 13:32:02 +0000 | [diff] [blame] | 144 | .format(name_width(x), |
Eli Kim | 233dca2 | 2022-10-19 09:43:14 -0700 | [diff] [blame] | 145 | x.intr_type.name, |
Rupert Swarbrick | 269bb3d | 2021-02-23 15:41:56 +0000 | [diff] [blame] | 146 | render_td(x.desc, rnames, None))) |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 147 | genout(outfile, "</table>\n") |
Rupert Swarbrick | e166d87 | 2021-02-05 13:34:35 +0000 | [diff] [blame] | 148 | |
Rupert Swarbrick | 269bb3d | 2021-02-23 15:41:56 +0000 | [diff] [blame] | 149 | if not cfgs.alerts: |
Rupert Swarbrick | e166d87 | 2021-02-05 13:34:35 +0000 | [diff] [blame] | 150 | genout(outfile, "<p><i>Security Alerts: none</i></p>\n") |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 151 | else: |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 152 | genout(outfile, "<p><i>Security Alerts:</i></p>\n") |
| 153 | genout( |
| 154 | outfile, "<table class=\"cfgtable\"><tr><th>Alert Name</th>" + |
| 155 | "<th>Description</th></tr>\n") |
Rupert Swarbrick | 269bb3d | 2021-02-23 15:41:56 +0000 | [diff] [blame] | 156 | for x in cfgs.alerts: |
Rupert Swarbrick | 302f038 | 2021-02-05 13:32:02 +0000 | [diff] [blame] | 157 | genout(outfile, |
| 158 | '<tr><td>{}</td>{}</tr>' |
Rupert Swarbrick | 269bb3d | 2021-02-23 15:41:56 +0000 | [diff] [blame] | 159 | .format(x.name, |
| 160 | render_td(x.desc, rnames, None))) |
lowRISC Contributors | 802543a | 2019-08-31 12:12:56 +0100 | [diff] [blame] | 161 | genout(outfile, "</table>\n") |
Michael Schaffner | d6f6f3e | 2021-12-10 15:26:08 -0800 | [diff] [blame] | 162 | |
| 163 | if not cfgs.countermeasures: |
| 164 | genout(outfile, "<p><i>Security Countermeasures: none</i></p>\n") |
| 165 | else: |
| 166 | genout(outfile, "<p><i>Security Countermeasures:</i></p>\n") |
| 167 | genout( |
| 168 | outfile, "<table class=\"cfgtable\"><tr><th>Countermeasure ID</th>" + |
| 169 | "<th>Description</th></tr>\n") |
| 170 | for cm in cfgs.countermeasures: |
| 171 | genout(outfile, |
| 172 | '<tr><td>{}</td>{}</tr>' |
| 173 | .format(cfgs.name.upper() + '.' + str(cm), |
| 174 | render_td(cm.desc, rnames, None))) |
| 175 | genout(outfile, "</table>\n") |