From a9a36c79d567e3b75bb51927b3547585e17987cd Mon Sep 17 00:00:00 2001 From: Robert Schilling Date: Mon, 20 Oct 2025 12:50:13 +0200 Subject: [PATCH] [topgen] Render address map of top Signed-off-by: Robert Schilling --- hw/top_darjeeling/doc/address_map.md | 110 +++++++++++++++++++++ hw/top_earlgrey/doc/address_map.md | 74 ++++++++++++++ hw/top_englishbreakfast/doc/address_map.md | 45 +++++++++ util/topgen/gen_top_docs.py | 29 ++++++ util/topgen/templates/address_map.md.tpl | 73 ++++++++++++++ 5 files changed, 331 insertions(+) create mode 100644 hw/top_darjeeling/doc/address_map.md create mode 100644 hw/top_earlgrey/doc/address_map.md create mode 100644 hw/top_englishbreakfast/doc/address_map.md create mode 100644 util/topgen/templates/address_map.md.tpl diff --git a/hw/top_darjeeling/doc/address_map.md b/hw/top_darjeeling/doc/address_map.md new file mode 100644 index 0000000000000..6e6abb57a0318 --- /dev/null +++ b/hw/top_darjeeling/doc/address_map.md @@ -0,0 +1,110 @@ + + +# Darjeeling Address Map + +## Hart Address Space + +The main address space, shared between the CPU and DM + +### IP Memory Regions + +| Module | Interface | Base Address | Size (bytes) | Size (words) | Description | +|-------------------|-------------|----------------|----------------|----------------|----------------------------------| +| uart0 | default | `0x30010000` | `0x40` | `0x10` | uart0 | +| gpio | default | `0x30000000` | `0x100` | `0x40` | gpio | +| spi_device | default | `0x30310000` | `0x2000` | `0x800` | spi_device | +| i2c0 | default | `0x30080000` | `0x80` | `0x20` | i2c0 | +| rv_timer | default | `0x30100000` | `0x200` | `0x80` | rv_timer | +| otp_ctrl | core | `0x30130000` | `0x8000` | `0x2000` | core device on otp_ctrl | +| otp_macro | prim | `0x30140000` | `0x20` | `0x8` | prim device on otp_macro | +| lc_ctrl | regs | `0x30150000` | `0x100` | `0x40` | regs device on lc_ctrl | +| alert_handler | default | `0x30160000` | `0x800` | `0x200` | alert_handler | +| spi_host0 | default | `0x30300000` | `0x40` | `0x10` | spi_host0 | +| pwrmgr_aon | default | `0x30400000` | `0x80` | `0x20` | pwrmgr_aon | +| rstmgr_aon | default | `0x30410000` | `0x80` | `0x20` | rstmgr_aon | +| clkmgr_aon | default | `0x30420000` | `0x40` | `0x10` | clkmgr_aon | +| pinmux_aon | default | `0x30460000` | `0x800` | `0x200` | pinmux_aon | +| aon_timer_aon | default | `0x30470000` | `0x40` | `0x10` | aon_timer_aon | +| ast | default | `0x30480000` | `0x400` | `0x100` | ast | +| soc_proxy | core | `0x22030000` | `0x10` | `0x4` | core device on soc_proxy | +| sram_ctrl_ret_aon | regs | `0x30500000` | `0x40` | `0x10` | regs device on sram_ctrl_ret_aon | +| rv_dm | regs | `0x21200000` | `0x10` | `0x4` | regs device on rv_dm | +| rv_dm | mem | `0x40000` | `0x1000` | `0x400` | mem device on rv_dm | +| rv_plic | default | `0x28000000` | `0x8000000` | `0x2000000` | rv_plic | +| aes | default | `0x21100000` | `0x100` | `0x40` | aes | +| hmac | default | `0x21110000` | `0x2000` | `0x800` | hmac | +| kmac | default | `0x21120000` | `0x1000` | `0x400` | kmac | +| otbn | default | `0x21130000` | `0x10000` | `0x4000` | otbn | +| keymgr_dpe | default | `0x21140000` | `0x100` | `0x40` | keymgr_dpe | +| csrng | default | `0x21150000` | `0x80` | `0x20` | csrng | +| entropy_src | default | `0x21160000` | `0x100` | `0x40` | entropy_src | +| edn0 | default | `0x21170000` | `0x80` | `0x20` | edn0 | +| edn1 | default | `0x21180000` | `0x80` | `0x20` | edn1 | +| sram_ctrl_main | regs | `0x211C0000` | `0x40` | `0x10` | regs device on sram_ctrl_main | +| sram_ctrl_mbox | regs | `0x211D0000` | `0x40` | `0x10` | regs device on sram_ctrl_mbox | +| rom_ctrl0 | regs | `0x211E0000` | `0x80` | `0x20` | regs device on rom_ctrl0 | +| rom_ctrl1 | regs | `0x211E1000` | `0x80` | `0x20` | regs device on rom_ctrl1 | +| dma | default | `0x22010000` | `0x200` | `0x80` | dma | +| mbx0 | core | `0x22000000` | `0x80` | `0x20` | core device on mbx0 | +| mbx1 | core | `0x22000100` | `0x80` | `0x20` | core device on mbx1 | +| mbx2 | core | `0x22000200` | `0x80` | `0x20` | core device on mbx2 | +| mbx3 | core | `0x22000300` | `0x80` | `0x20` | core device on mbx3 | +| mbx4 | core | `0x22000400` | `0x80` | `0x20` | core device on mbx4 | +| mbx5 | core | `0x22000500` | `0x80` | `0x20` | core device on mbx5 | +| mbx6 | core | `0x22000600` | `0x80` | `0x20` | core device on mbx6 | +| mbx_jtag | core | `0x22000800` | `0x80` | `0x20` | core device on mbx_jtag | +| mbx_pcie0 | core | `0x22040000` | `0x80` | `0x20` | core device on mbx_pcie0 | +| mbx_pcie1 | core | `0x22040100` | `0x80` | `0x20` | core device on mbx_pcie1 | +| soc_dbg_ctrl | core | `0x30170000` | `0x20` | `0x8` | core device on soc_dbg_ctrl | +| rv_core_ibex | cfg | `0x211F0000` | `0x800` | `0x200` | cfg device on rv_core_ibex | + +### Memory Blocks + +| Memory | Interface | Base Address | Size (bytes) | Size (words) | +|-------------------|-------------|----------------|----------------|----------------| +| soc_proxy | ctn | `0x40000000` | `0x80000000` | `0x20000000` | +| sram_ctrl_ret_aon | ram | `0x30600000` | `0x1000` | `0x400` | +| sram_ctrl_main | ram | `0x10000000` | `0x10000` | `0x4000` | +| sram_ctrl_mbox | ram | `0x11000000` | `0x1000` | `0x400` | +| rom_ctrl0 | rom | `0x8000` | `0x8000` | `0x2000` | +| rom_ctrl1 | rom | `0x20000` | `0x10000` | `0x4000` | + +## Soc_mbx Address Space + +SoC address space for mailbox access + +### IP Memory Regions + +| Module | Interface | Base Address | Size (bytes) | Size (words) | Description | +|----------------|-------------|----------------|----------------|----------------|-------------------------| +| mbx0 | soc | `0x1465000` | `0x20` | `0x8` | soc device on mbx0 | +| mbx1 | soc | `0x1465100` | `0x20` | `0x8` | soc device on mbx1 | +| mbx2 | soc | `0x1465200` | `0x20` | `0x8` | soc device on mbx2 | +| mbx3 | soc | `0x1465300` | `0x20` | `0x8` | soc device on mbx3 | +| mbx4 | soc | `0x1465400` | `0x20` | `0x8` | soc device on mbx4 | +| mbx5 | soc | `0x1465500` | `0x20` | `0x8` | soc device on mbx5 | +| mbx6 | soc | `0x1496000` | `0x20` | `0x8` | soc device on mbx6 | +| mbx_pcie0 | soc | `0x1460100` | `0x20` | `0x8` | soc device on mbx_pcie0 | +| mbx_pcie1 | soc | `0x1460200` | `0x20` | `0x8` | soc device on mbx_pcie1 | +| racl_ctrl | default | `0x1461F00` | `0x100` | `0x40` | racl_ctrl | +| ac_range_check | default | `0x1464000` | `0x400` | `0x100` | ac_range_check | + + +## Soc_dbg Address Space + +SoC address space for debug module interfaces + +### IP Memory Regions + +| Module | Interface | Base Address | Size (bytes) | Size (words) | Description | +|--------------|-------------|----------------|----------------|----------------|-----------------------------| +| lc_ctrl | dmi | `0x3000` | `0x1000` | `0x400` | dmi device on lc_ctrl | +| rv_dm | dbg | `0x0` | `0x200` | `0x80` | dbg device on rv_dm | +| mbx_jtag | soc | `0x2200` | `0x20` | `0x8` | soc device on mbx_jtag | +| soc_dbg_ctrl | jtag | `0x2300` | `0x20` | `0x8` | jtag device on soc_dbg_ctrl | + + diff --git a/hw/top_earlgrey/doc/address_map.md b/hw/top_earlgrey/doc/address_map.md new file mode 100644 index 0000000000000..808611a50c5e6 --- /dev/null +++ b/hw/top_earlgrey/doc/address_map.md @@ -0,0 +1,74 @@ + + +# Earlgrey Address Map + +## Hart Address Space + +The main address space, shared between the CPU and DM + +### IP Memory Regions + +| Module | Interface | Base Address | Size (bytes) | Size (words) | Description | +|-------------------|-------------|----------------|----------------|----------------|----------------------------------| +| uart0 | default | `0x40000000` | `0x40` | `0x10` | uart0 | +| uart1 | default | `0x40010000` | `0x40` | `0x10` | uart1 | +| uart2 | default | `0x40020000` | `0x40` | `0x10` | uart2 | +| uart3 | default | `0x40030000` | `0x40` | `0x10` | uart3 | +| gpio | default | `0x40040000` | `0x80` | `0x20` | gpio | +| spi_device | default | `0x40050000` | `0x2000` | `0x800` | spi_device | +| i2c0 | default | `0x40080000` | `0x80` | `0x20` | i2c0 | +| i2c1 | default | `0x40090000` | `0x80` | `0x20` | i2c1 | +| i2c2 | default | `0x400A0000` | `0x80` | `0x20` | i2c2 | +| pattgen | default | `0x400E0000` | `0x40` | `0x10` | pattgen | +| rv_timer | default | `0x40100000` | `0x200` | `0x80` | rv_timer | +| otp_ctrl | core | `0x40130000` | `0x1000` | `0x400` | core device on otp_ctrl | +| otp_macro | prim | `0x40138000` | `0x20` | `0x8` | prim device on otp_macro | +| lc_ctrl | regs | `0x40140000` | `0x100` | `0x40` | regs device on lc_ctrl | +| lc_ctrl | dmi | `0x0` | `0x1000` | `0x400` | dmi device on lc_ctrl | +| alert_handler | default | `0x40150000` | `0x800` | `0x200` | alert_handler | +| spi_host0 | default | `0x40300000` | `0x40` | `0x10` | spi_host0 | +| spi_host1 | default | `0x40310000` | `0x40` | `0x10` | spi_host1 | +| usbdev | default | `0x40320000` | `0x1000` | `0x400` | usbdev | +| pwrmgr_aon | default | `0x40400000` | `0x80` | `0x20` | pwrmgr_aon | +| rstmgr_aon | default | `0x40410000` | `0x80` | `0x20` | rstmgr_aon | +| clkmgr_aon | default | `0x40420000` | `0x80` | `0x20` | clkmgr_aon | +| sysrst_ctrl_aon | default | `0x40430000` | `0x100` | `0x40` | sysrst_ctrl_aon | +| adc_ctrl_aon | default | `0x40440000` | `0x80` | `0x20` | adc_ctrl_aon | +| pwm_aon | default | `0x40450000` | `0x80` | `0x20` | pwm_aon | +| pinmux_aon | default | `0x40460000` | `0x1000` | `0x400` | pinmux_aon | +| aon_timer_aon | default | `0x40470000` | `0x40` | `0x10` | aon_timer_aon | +| ast | default | `0x40480000` | `0x400` | `0x100` | ast | +| sensor_ctrl_aon | default | `0x40490000` | `0x80` | `0x20` | sensor_ctrl_aon | +| sram_ctrl_ret_aon | regs | `0x40500000` | `0x40` | `0x10` | regs device on sram_ctrl_ret_aon | +| flash_ctrl | core | `0x41000000` | `0x200` | `0x80` | core device on flash_ctrl | +| flash_ctrl | prim | `0x41008000` | `0x80` | `0x20` | prim device on flash_ctrl | +| rv_dm | regs | `0x41200000` | `0x10` | `0x4` | regs device on rv_dm | +| rv_dm | mem | `0x10000` | `0x1000` | `0x400` | mem device on rv_dm | +| rv_dm | dbg | `0x1000` | `0x200` | `0x80` | dbg device on rv_dm | +| rv_plic | default | `0x48000000` | `0x8000000` | `0x2000000` | rv_plic | +| aes | default | `0x41100000` | `0x100` | `0x40` | aes | +| hmac | default | `0x41110000` | `0x2000` | `0x800` | hmac | +| kmac | default | `0x41120000` | `0x1000` | `0x400` | kmac | +| otbn | default | `0x41130000` | `0x10000` | `0x4000` | otbn | +| keymgr | default | `0x41140000` | `0x100` | `0x40` | keymgr | +| csrng | default | `0x41150000` | `0x80` | `0x20` | csrng | +| entropy_src | default | `0x41160000` | `0x100` | `0x40` | entropy_src | +| edn0 | default | `0x41170000` | `0x80` | `0x20` | edn0 | +| edn1 | default | `0x41180000` | `0x80` | `0x20` | edn1 | +| sram_ctrl_main | regs | `0x411C0000` | `0x40` | `0x10` | regs device on sram_ctrl_main | +| rom_ctrl | regs | `0x411E0000` | `0x80` | `0x20` | regs device on rom_ctrl | +| rv_core_ibex | cfg | `0x411F0000` | `0x100` | `0x40` | cfg device on rv_core_ibex | + +### Memory Blocks + +| Memory | Interface | Base Address | Size (bytes) | Size (words) | +|-------------------|-------------|----------------|----------------|----------------| +| sram_ctrl_ret_aon | ram | `0x40600000` | `0x1000` | `0x400` | +| flash_ctrl | mem | `0x20000000` | `0x100000` | `0x40000` | +| sram_ctrl_main | ram | `0x10000000` | `0x20000` | `0x8000` | +| rom_ctrl | rom | `0x8000` | `0x8000` | `0x2000` | + diff --git a/hw/top_englishbreakfast/doc/address_map.md b/hw/top_englishbreakfast/doc/address_map.md new file mode 100644 index 0000000000000..1f8d09f4055c1 --- /dev/null +++ b/hw/top_englishbreakfast/doc/address_map.md @@ -0,0 +1,45 @@ + + +# Englishbreakfast Address Map + +## Hart Address Space + +The main address space, shared between the CPU and DM + +### IP Memory Regions + +| Module | Interface | Base Address | Size (bytes) | Size (words) | Description | +|----------------|-------------|----------------|----------------|----------------|-------------------------------| +| uart0 | default | `0x40000000` | `0x40` | `0x10` | uart0 | +| uart1 | default | `0x40010000` | `0x40` | `0x10` | uart1 | +| gpio | default | `0x40040000` | `0x80` | `0x20` | gpio | +| spi_device | default | `0x40050000` | `0x2000` | `0x800` | spi_device | +| spi_host0 | default | `0x40060000` | `0x40` | `0x10` | spi_host0 | +| rv_timer | default | `0x40100000` | `0x200` | `0x80` | rv_timer | +| usbdev | default | `0x40320000` | `0x1000` | `0x400` | usbdev | +| pwrmgr_aon | default | `0x40400000` | `0x80` | `0x20` | pwrmgr_aon | +| rstmgr_aon | default | `0x40410000` | `0x80` | `0x20` | rstmgr_aon | +| clkmgr_aon | default | `0x40420000` | `0x80` | `0x20` | clkmgr_aon | +| pinmux_aon | default | `0x40460000` | `0x1000` | `0x400` | pinmux_aon | +| aon_timer_aon | default | `0x40470000` | `0x40` | `0x10` | aon_timer_aon | +| ast | default | `0x40480000` | `0x400` | `0x100` | ast | +| flash_ctrl | core | `0x41000000` | `0x200` | `0x80` | core device on flash_ctrl | +| flash_ctrl | prim | `0x41008000` | `0x80` | `0x20` | prim device on flash_ctrl | +| rv_plic | default | `0x48000000` | `0x8000000` | `0x2000000` | rv_plic | +| aes | default | `0x41100000` | `0x100` | `0x40` | aes | +| sram_ctrl_main | regs | `0x411C0000` | `0x40` | `0x10` | regs device on sram_ctrl_main | +| rom_ctrl | regs | `0x411E0000` | `0x80` | `0x20` | regs device on rom_ctrl | +| rv_core_ibex | cfg | `0x411F0000` | `0x100` | `0x40` | cfg device on rv_core_ibex | + +### Memory Blocks + +| Memory | Interface | Base Address | Size (bytes) | Size (words) | +|----------------|-------------|----------------|----------------|----------------| +| flash_ctrl | mem | `0x20000000` | `0x10000` | `0x4000` | +| sram_ctrl_main | ram | `0x10000000` | `0x20000` | `0x8000` | +| rom_ctrl | rom | `0x8000` | `0x8000` | `0x2000` | + diff --git a/util/topgen/gen_top_docs.py b/util/topgen/gen_top_docs.py index 25e4de7f5b2e7..08e7a2e709c60 100644 --- a/util/topgen/gen_top_docs.py +++ b/util/topgen/gen_top_docs.py @@ -5,6 +5,8 @@ r"""Top Module Documentation Generator """ from tabulate import tabulate +from mako.template import Template +from pathlib import Path from .lib import find_module @@ -209,7 +211,34 @@ def gen_pinmux_docs(top, c_helper, out_path): summary_table_path.write_text(summary_table) +def gen_address_map_docs(top, c_helper, out_path): + """Generate address map documentation for all address spaces. + + Creates a markdown file showing the memory layout for all address spaces + defined in the top configuration. + """ + doc_path = out_path / 'doc' + doc_path.mkdir(parents=True, exist_ok=True) + + gencmd = ("util/topgen.py -t hw/top_{topname}/data/top_{topname}.hjson " + "-o hw/top_{topname}/".format(topname=top['name'])) + + template_path = Path(__file__).parent / 'templates' / 'address_map.md.tpl' + template = Template(filename=str(template_path)) + + address_map_content = template.render( + top=top, + helper=c_helper, + gencmd=gencmd + ) + + address_map_path = doc_path / 'address_map.md' + address_map_path.write_text(address_map_content) + + def gen_top_docs(top, c_helper, out_path): + gen_address_map_docs(top, c_helper, out_path) + if find_module(top['module'], 'pinmux'): # create pinout / pinmux specific tables for all targets gen_pinmux_docs(top, c_helper, out_path) diff --git a/util/topgen/templates/address_map.md.tpl b/util/topgen/templates/address_map.md.tpl new file mode 100644 index 0000000000000..f001e41573de0 --- /dev/null +++ b/util/topgen/templates/address_map.md.tpl @@ -0,0 +1,73 @@ + + +# ${top["name"].capitalize()} Address Map + +% for addr_space in top['addr_spaces']: +${"##"} ${addr_space['name'].capitalize()} Address Space + +% if 'desc' in addr_space: +${addr_space['desc']} + +% endif +${"###"} IP Memory Regions +<% + from tabulate import tabulate + headers = [ + "Module", + "Interface", + "Base Address", + "Size (bytes)", + "Size (words)", + "Description", + ] + rows = [] + for (inst_name, if_name), region in helper.devices(addr_space['name']): + if_desc = inst_name if if_name is None else "{} device on {}".format(if_name, inst_name) + hex_base_addr = "`0x{:X}`".format(region.base_addr) + hex_size_bytes = "`0x{:X}`".format(region.size_bytes) + hex_size_words = "`0x{:X}`".format(region.size_words) + rows.append([ + inst_name, + (if_name if if_name else 'default'), + hex_base_addr, + hex_size_bytes, + hex_size_words, + if_desc, + ]) + table_str = tabulate(rows, headers=headers, tablefmt='github') +%> +${table_str} + +% if len(helper.memories(addr_space['name'])): +${"###"} Memory Blocks +<% + mem_rows = [] + for mem_name, region in helper.memories(addr_space['name']): + hex_base_addr = "`0x{:X}`".format(region.base_addr) + hex_size_bytes = "`0x{:X}`".format(region.size_bytes) + hex_size_words = "`0x{:X}`".format(region.size_words) + mem_rows.append([ + mem_name[0], + mem_name[1], + hex_base_addr, + hex_size_bytes, + hex_size_words, + ]) + + mem_headers = [ + "Memory", + "Interface", + "Base Address", + "Size (bytes)", + "Size (words)", + ] + mem_table_str = tabulate(mem_rows, headers=mem_headers, tablefmt='github') +%> +${mem_table_str} +% endif + +% endfor