| # Copyright lowRISC contributors. | |
| # Licensed under the Apache License, Version 2.0, see LICENSE for details. | |
| # SPDX-License-Identifier: Apache-2.0 | |
| """ | |
| Generate HTML documentation from IpBlock | |
| """ | |
| from typing import Optional, Set, TextIO, List, Union | |
| import mistletoe as mk | |
| from reggen.ip_block import IpBlock | |
| from reggen.html_helpers import expand_paras, render_td, get_reg_link | |
| from reggen.multi_register import MultiRegister | |
| from reggen.reg_block import RegBlock | |
| from reggen.register import Register | |
| from reggen.window import Window | |
| def genout(outfile: TextIO, msg: str) -> None: | |
| outfile.write(msg) | |
| # Generation of HTML table with register bit-field summary picture | |
| # Max 16-bit wide on one line | |
| def gen_tbl_row(outfile: TextIO, msb: int, width: int, close: bool) -> None: | |
| if (close): | |
| genout(outfile, "</tr>\n") | |
| genout(outfile, "<tr>") | |
| for x in range(msb, msb - width, -1): | |
| genout(outfile, "<td class=\"bitnum\">" + str(x) + "</td>") | |
| genout(outfile, "</tr><tr>") | |
| def gen_html_reg_pic(outfile: TextIO, reg: Register, width: int) -> None: | |
| if (width > 32): | |
| bsize = 3 | |
| nextbit = 63 | |
| hdrbits = 16 | |
| nextline = 48 | |
| elif (width > 16): | |
| bsize = 3 | |
| nextbit = 31 | |
| hdrbits = 16 | |
| nextline = 16 | |
| elif (width > 8): | |
| bsize = 3 | |
| nextbit = 15 | |
| nextline = 0 | |
| hdrbits = 16 | |
| else: | |
| bsize = 12 | |
| nextbit = 7 | |
| nextline = 0 | |
| hdrbits = 8 | |
| genout(outfile, "<table class=\"regpic\">") | |
| gen_tbl_row(outfile, nextbit, hdrbits, False) | |
| for field in reversed(reg.fields): | |
| fieldlsb = field.bits.lsb | |
| fieldwidth = field.bits.width() | |
| fieldmsb = field.bits.msb | |
| fname = field.name | |
| while nextbit > fieldmsb: | |
| if (nextbit >= nextline) and (fieldmsb < nextline): | |
| spans = nextbit - (nextline - 1) | |
| else: | |
| spans = nextbit - fieldmsb | |
| genout( | |
| outfile, "<td class=\"unused\" colspan=" + str(spans) + | |
| "> </td>\n") | |
| if (nextbit >= nextline) and (fieldmsb < nextline): | |
| nextbit = nextline - 1 | |
| gen_tbl_row(outfile, nextbit, hdrbits, True) | |
| nextline = nextline - 16 | |
| else: | |
| nextbit = fieldmsb | |
| while (fieldmsb >= nextline) and (fieldlsb < nextline): | |
| spans = fieldmsb - (nextline - 1) | |
| genout( | |
| outfile, "<td class=\"fname\" colspan=" + str(spans) + ">" + | |
| fname + "...</td>\n") | |
| fname = "..." + field.name | |
| fieldwidth = fieldwidth - spans | |
| fieldmsb = nextline - 1 | |
| nextline = nextline - 16 | |
| gen_tbl_row(outfile, fieldmsb, hdrbits, True) | |
| namelen = len(fname) | |
| if namelen == 0 or fname == ' ': | |
| fname = " " | |
| if (namelen > bsize * fieldwidth): | |
| usestyle = (" style=\"font-size:" + str( | |
| (bsize * 100 * fieldwidth) / namelen) + "%\"") | |
| else: | |
| usestyle = "" | |
| genout( | |
| outfile, "<td class=\"fname\" colspan=" + str(fieldwidth) + | |
| usestyle + ">" + fname + "</td>\n") | |
| if (fieldlsb == nextline) and nextline > 0: | |
| gen_tbl_row(outfile, nextline - 1, hdrbits, True) | |
| nextline = nextline - 16 | |
| nextbit = fieldlsb - 1 | |
| while (nextbit > 0): | |
| spans = nextbit - (nextline - 1) | |
| genout(outfile, | |
| "<td class=\"unused\" colspan=" + str(spans) + "> </td>\n") | |
| nextbit = nextline - 1 | |
| if (nextline > 0): | |
| gen_tbl_row(outfile, nextline - 1, hdrbits, True) | |
| nextline = nextline - 16 | |
| genout(outfile, "</tr></table>") | |
| # Generation of HTML table with header, register picture and details | |
| def gen_html_register_summary(outfile: TextIO, | |
| obj_list: List[Union[Window, Register]], | |
| comp: str, | |
| width: int, | |
| rnames: Set[str]) -> None: | |
| bytew = width // 8 | |
| genout(outfile, | |
| '<table class="regdef" id="RegSummary_{comp}">\n' | |
| ' <tr>\n' | |
| ' <th class="regdef" colspan=4> Summary </th>\n' | |
| ' </tr>\n' | |
| ' <tr>\n' | |
| ' <th class="regdef">Name</th>' | |
| ' <th class="regdef">Offset</th>' | |
| ' <th class="regdef">Length</th>' | |
| ' <th class="regdef">Description</th>' | |
| ' </tr>\n') | |
| for obj in obj_list: | |
| obj_length = bytew if isinstance(obj, Register) else bytew * obj.items | |
| desc_paras = expand_paras(obj.desc, rnames) | |
| obj_desc = desc_paras[0] | |
| genout(outfile, | |
| ' <tr>\n' | |
| ' <td class="regfn">{comp}.{link}</td>' | |
| ' <td class="regfn">{obj_offset:#x}</td>' | |
| ' <td class="regfn">{obj_length}</td>' | |
| ' <td class="regfn">{obj_desc}</td>' | |
| ' </tr>\n' | |
| .format(comp=comp, | |
| link=get_reg_link(obj.name), | |
| obj_offset=obj.offset, | |
| obj_length=obj_length, | |
| obj_desc=obj_desc)) | |
| genout(outfile, '</table>') | |
| def gen_html_register(outfile: TextIO, | |
| reg: Register, | |
| comp: str, | |
| width: int, | |
| rnames: Set[str]) -> None: | |
| rname = reg.name | |
| offset = reg.offset | |
| regwen_div = '' | |
| if reg.regwen is not None: | |
| regwen_div = (' <div>Register enable = {}</div>' | |
| .format(reg.regwen)) | |
| desc_paras = expand_paras(reg.desc, rnames) | |
| desc_head = desc_paras[0] | |
| desc_body = desc_paras[1:] | |
| # If this is the first register of a multireg, | |
| # we also insert a label without the index so | |
| # that unnumbered links from the register table | |
| # descriptions and Hugo-generated docs are possible. | |
| if rname[-2:] == "0": | |
| mr_anchor = ('id="{}"' | |
| .format(rname[:-2].lower())) | |
| else: | |
| mr_anchor = '' | |
| genout(outfile, | |
| '<table class="regdef" id="{lrname}">\n' | |
| ' <tr>\n' | |
| ' <th class="regdef" colspan=5 {mr_anchor}>\n' | |
| ' <div>{comp}.{link} @ {off:#x}</div>\n' | |
| ' <div>{desc}</div>\n' | |
| ' <div>Reset default = {resval:#x}, mask {mask:#x}</div>\n' | |
| '{wen}' | |
| ' </th>\n' | |
| ' </tr>\n' | |
| .format(mr_anchor=mr_anchor, | |
| lrname=rname.lower(), | |
| comp=comp, | |
| link=get_reg_link(rname), | |
| off=offset, | |
| desc=desc_head, | |
| resval=reg.resval, | |
| mask=reg.resmask, | |
| wen=regwen_div)) | |
| if desc_body: | |
| genout(outfile, | |
| '<tr><td colspan=5>{}</td></tr>' | |
| .format(mk.markdown(desc_body))) | |
| genout(outfile, "<tr><td colspan=5>") | |
| gen_html_reg_pic(outfile, reg, width) | |
| genout(outfile, "</td></tr>\n") | |
| genout(outfile, "<tr><th width=5%>Bits</th>") | |
| genout(outfile, "<th width=5%>Type</th>") | |
| genout(outfile, "<th width=5%>Reset</th>") | |
| genout(outfile, "<th>Name</th>") | |
| genout(outfile, "<th>Description</th></tr>") | |
| nextbit = 0 | |
| fcount = 0 | |
| for field in reg.fields: | |
| fcount += 1 | |
| fname = field.name | |
| fieldlsb = field.bits.lsb | |
| if fieldlsb > nextbit: | |
| genout(outfile, "<tr><td class=\"regbits\">") | |
| if (nextbit == (fieldlsb - 1)): | |
| genout(outfile, str(nextbit)) | |
| else: | |
| genout(outfile, str(fieldlsb - 1) + ":" + str(nextbit)) | |
| genout(outfile, | |
| "</td><td></td><td></td><td></td><td>Reserved</td></tr>") | |
| genout(outfile, "<tr><td class=\"regbits\">" + field.bits.as_str() + "</td>") | |
| genout(outfile, "<td class=\"regperm\">" + field.swaccess.key + "</td>") | |
| genout( | |
| outfile, "<td class=\"regrv\">" + | |
| ('x' if field.resval is None else hex(field.resval)) + | |
| "</td>") | |
| genout(outfile, "<td class=\"regfn\">" + fname + "</td>") | |
| # Collect up any description and enum table | |
| desc_parts = [] | |
| if field.desc is not None: | |
| desc_parts += expand_paras(mk.markdown(field.desc), rnames) | |
| if field.enum is not None: | |
| desc_parts.append('<table>') | |
| # Add two to include the "0x" part | |
| hex_width = 2 + ((field.bits.width() + 3) // 4) | |
| for enum in field.enum: | |
| enum_desc_paras = expand_paras(enum.desc, rnames) | |
| desc_parts.append('<tr>' | |
| '<td>{val:#0{hex_width}x}</td>' | |
| '<td>{name}</td>' | |
| '<td>{desc}</td>' | |
| '</tr>\n' | |
| .format(val=enum.value, | |
| hex_width=hex_width, | |
| name=enum.name, | |
| desc=''.join(enum_desc_paras))) | |
| desc_parts.append('</table>') | |
| if field.has_incomplete_enum(): | |
| desc_parts.append("<p>Other values are reserved.</p>") | |
| genout(outfile, | |
| '<td class="regde">{}</td>'.format(''.join(desc_parts))) | |
| nextbit = fieldlsb + field.bits.width() | |
| genout(outfile, "</table>\n<br>\n") | |
| def gen_window_row(outfile: TextIO, | |
| base_addr: int, | |
| validbits: int, | |
| regwidth: int, | |
| idx: Optional[int]) -> None: | |
| '''Generate a row for a window | |
| If idx is None, this is a row that shows we're skipping some addresses and | |
| has a "...". If idx is not None, this gives an address and we show the bits | |
| that are valid. | |
| ''' | |
| assert 0 < validbits | |
| assert 0 < regwidth | |
| assert regwidth % 8 == 0 | |
| assert validbits <= regwidth | |
| if idx is not None: | |
| assert idx >= 0 | |
| addr = base_addr + idx * (regwidth // 8) | |
| addr_td = f'<td class="regbits">+{addr:#x}</td>' | |
| if validbits < regwidth: | |
| pad = regwidth - validbits | |
| unused_tds = f'<td class="unused" colspan="{pad}"> </td>' | |
| else: | |
| unused_tds = '' | |
| data_tds = f'<td class="fname" colspan="{validbits}"> </td>' | |
| tds = addr_td + unused_tds + data_tds | |
| else: | |
| tds = (f'<td> </td>' | |
| f'<td align="center" colspan="{regwidth}">...</td>') | |
| genout(outfile, f'<tr>{tds}</tr>') | |
| def gen_html_window(outfile: TextIO, | |
| win: Window, | |
| comp: str, | |
| regwidth: int, | |
| rnames: Set[str]) -> None: | |
| wname = win.name or '(unnamed window)' | |
| offset = win.offset | |
| genout(outfile, | |
| '<table class="regdef" id="{lwname}">\n' | |
| ' <tr>\n' | |
| ' <th class="regdef">\n' | |
| ' <div>{comp}.{link} @ + {off:#x}</div>\n' | |
| ' <div>{items} item {swaccess} window</div>\n' | |
| ' <div>Byte writes are {byte_writes}supported</div>\n' | |
| ' </th>\n' | |
| ' </tr>\n' | |
| .format(comp=comp, | |
| link=get_reg_link(wname), | |
| lwname=wname.lower(), | |
| off=offset, | |
| items=win.items, | |
| swaccess=win.swaccess.key, | |
| byte_writes=('' if win.byte_write else '<i>not</i> '))) | |
| genout(outfile, '<tr><td><table class="regpic">') | |
| genout(outfile, '<tr><td width="10%"></td>') | |
| wid = win.validbits | |
| for x in range(regwidth - 1, -1, -1): | |
| if x == regwidth - 1 or x == wid - 1 or x == 0: | |
| genout(outfile, '<td class="bitnum">' + str(x) + '</td>') | |
| else: | |
| genout(outfile, '<td class="bitnum"></td>') | |
| genout(outfile, '</tr>') | |
| # We want to show the first and last two addresses, with a blank line in | |
| # between if we skip anything. | |
| assert win.items >= 1 | |
| if win.items <= 4: | |
| indices_0 = list(range(win.items)) | |
| indices_1 = [] | |
| else: | |
| indices_0 = [0, 1] | |
| indices_1 = [win.items - 2, win.items - 1] | |
| for idx in indices_0: | |
| gen_window_row(outfile, offset, win.validbits, regwidth, idx) | |
| if indices_1: | |
| gen_window_row(outfile, offset, win.validbits, regwidth, None) | |
| for idx in indices_1: | |
| gen_window_row(outfile, offset, win.validbits, regwidth, idx) | |
| genout(outfile, '</td></tr></table>') | |
| genout(outfile, | |
| '<tr>{}</tr>'.format(render_td(win.desc, rnames, 'regde'))) | |
| genout(outfile, "</table>\n<br>\n") | |
| def gen_html_reg_block(outfile: TextIO, | |
| rb: RegBlock, | |
| comp: str, | |
| width: int, | |
| rnames: Set[str]) -> None: | |
| if len(rb.entries) == 0: | |
| genout(outfile, 'This interface does not expose any registers.') | |
| else: | |
| # Generate overview table first. | |
| obj_list: List[Union[Register, Window]] = [] | |
| for x in rb.entries: | |
| if isinstance(x, MultiRegister): | |
| for reg in x.regs: | |
| obj_list += [reg] | |
| else: | |
| assert isinstance(x, Window) or isinstance(x, Register) | |
| obj_list += [x] | |
| gen_html_register_summary(outfile, obj_list, comp, width, rnames) | |
| # Generate detailed entries | |
| for x in rb.entries: | |
| if isinstance(x, Register): | |
| gen_html_register(outfile, x, comp, width, rnames) | |
| elif isinstance(x, MultiRegister): | |
| for reg in x.regs: | |
| gen_html_register(outfile, reg, comp, width, rnames) | |
| else: | |
| assert isinstance(x, Window) | |
| gen_html_window(outfile, x, comp, width, rnames) | |
| def gen_html(block: IpBlock, outfile: TextIO) -> int: | |
| rnames = block.get_rnames() | |
| assert block.reg_blocks | |
| # Handle the case where there's just one interface | |
| if len(block.reg_blocks) == 1: | |
| rb = list(block.reg_blocks.values())[0] | |
| gen_html_reg_block(outfile, rb, block.name, block.regwidth, rnames) | |
| return 0 | |
| # Handle the case where there is more than one device interface and, | |
| # correspondingly, more than one reg block. | |
| for iface_name, rb in block.reg_blocks.items(): | |
| iface_desc = ('device interface <code>{}</code>'.format(iface_name) | |
| if iface_name is not None | |
| else 'the unnamed device interface') | |
| genout(outfile, | |
| '<h3>Registers visible under {}</h3>'.format(iface_desc)) | |
| gen_html_reg_block(outfile, rb, block.name, block.regwidth, rnames) | |
| return 0 |