From 6fb5f3f120d09638cf0e9602e5ddad650a31fd78 Mon Sep 17 00:00:00 2001 From: Catherine Date: Sun, 7 Apr 2024 07:56:28 +0000 Subject: [PATCH] docs/memory: use `wavedrom` directive for diagrams. --- docs/conf.py | 3 + docs/stdlib/_images/memory/example_fifo.svg | 41 -------------- docs/stdlib/_images/memory/example_hello.svg | 22 -------- docs/stdlib/memory.rst | 59 +++++++++++++++++++- pyproject.toml | 1 + 5 files changed, 61 insertions(+), 65 deletions(-) delete mode 100644 docs/stdlib/_images/memory/example_fifo.svg delete mode 100644 docs/stdlib/_images/memory/example_hello.svg diff --git a/docs/conf.py b/docs/conf.py index 177f454..3c5240a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,6 +17,7 @@ extensions = [ "sphinx.ext.napoleon", "sphinx_rtd_theme", "sphinxcontrib.platformpicker", + "sphinxcontrib.yowasp_wavedrom", ] with open(".gitignore") as f: @@ -45,6 +46,8 @@ napoleon_custom_sections = [ "Platform overrides" ] +yowasp_wavedrom_skin = "light" + html_theme = "sphinx_rtd_theme" html_static_path = ["_static"] html_css_files = ["custom.css"] diff --git a/docs/stdlib/_images/memory/example_fifo.svg b/docs/stdlib/_images/memory/example_fifo.svg deleted file mode 100644 index 2b3222c..0000000 --- a/docs/stdlib/_images/memory/example_fifo.svg +++ /dev/null @@ -1,41 +0,0 @@ - -clkpushwr_port.addr01234wr_port.data00AABBCCDDmemory[0]00AAmemory[3]00DDpoprd_port.addr01234rd_port.data00AABBCCDDxwtyru diff --git a/docs/stdlib/_images/memory/example_hello.svg b/docs/stdlib/_images/memory/example_hello.svg deleted file mode 100644 index 0a43f2f..0000000 --- a/docs/stdlib/_images/memory/example_hello.svg +++ /dev/null @@ -1,22 +0,0 @@ - -clkrd_port.addr0123456789101101rd_port.dataHelloworld\nHead diff --git a/docs/stdlib/memory.rst b/docs/stdlib/memory.rst index 2927a2c..f5f6ad9 100644 --- a/docs/stdlib/memory.rst +++ b/docs/stdlib/memory.rst @@ -74,7 +74,25 @@ In the following example, a read-only memory is used to output a fixed message i In this example, the memory read port is asynchronous, and a change of the address input (labelled `a` on the diagram below) results in an immediate change of the data output (labelled `d`). -.. image:: _images/memory/example_hello.svg +.. wavedrom:: memory/example_hello + + { + "signal": [ + {"name": "clk", + "wave": "0P............"}, + {"name": "rd_port.addr", + "wave": "==============", + "data": [0,1,2,3,4,5,6,7,8,9,10,11,0,1], + "node": ".a"}, + {"name": "rd_port.data", + "wave": "==============", + "data": ["H","e","l","l","o"," ","w","o","r","l","d","\\n","H","e"], + "node": ".d"} + ], + "edge": [ + "a-|d" + ] + } First-in, first-out queue @@ -112,7 +130,44 @@ In this example, the memory read and write ports are synchronous. A write operat However, the memory read port is also configured to be *transparent* relative to the memory write port. This means that if a write and a read operation (labelled `t`, `u` respectively) access the same row with address 3, the new contents will be read out, reducing the minimum push-to-pop latency to one cycle, down from two cycles that would be required without the use of transparency. -.. image:: _images/memory/example_fifo.svg +.. wavedrom:: memory/example_fifo + + { + "signal": [ + {"name": "clk", + "wave": "P........"}, + {"name": "push", + "wave": "01..0.10.", + "node": ".x"}, + {"name": "wr_port.addr", + "wave": "=.===..=.", + "data": ["0", "1", "2", "3", "4", "5"]}, + {"name": "wr_port.data", + "wave": "====..=..", + "data": ["00", "AA", "BB", "CC", "DD"], + "node": ".w....t"}, + {"name": "memory[0]", + "wave": "=.=......", + "data": ["00", "AA"], + "node": "..G"}, + {"name": "memory[3]", + "wave": "=......=.", + "data": ["00", "DD"], + "node": ".......H"}, + {"name": "pop", + "wave": "0..1...0.", + "node": "...y"}, + {"name": "rd_port.addr", + "wave": "=...====.", + "data": ["0", "1", "2", "3", "4", "5"]}, + {"name": "rd_port.data", + "wave": "=...====.", + "data": ["00", "AA", "BB", "CC", "DD"], + "node": "....r..u"} + ], "edge": [ + "x-~>G", "w->G", "y-~>r", "t->H", "t->u" + ] + } Memories diff --git a/pyproject.toml b/pyproject.toml index ca3fa14..c32bddc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -71,6 +71,7 @@ test = [ docs = [ "sphinx~=7.1", "sphinxcontrib-platformpicker~=1.3", + "sphinxcontrib-yowasp-wavedrom~=1.1", "sphinx-rtd-theme~=2.0", "sphinx-autobuild", ]