From fd6d51f59f380d4f479bd245ba8917af90fb1fc2 Mon Sep 17 00:00:00 2001 From: Wiktoria Kuna Date: Fri, 14 Jul 2023 15:04:03 +0200 Subject: [PATCH] Add FastVDMA docs --- .ci.yml | 40 +++++++-- .github/workflows/build.yml | 40 +++++++++ Makefile | 4 + README.md | 137 ++---------------------------- docs/Configuration.md | 125 +++++++++++++++++++++++++++ docs/CustomTests.md | 38 +++++++++ docs/LinuxDriver.md | 9 ++ docs/Overview.md | 50 +++++++++++ doc/csr.md => docs/RegisterMap.md | 97 ++++++++++++++------- docs/Simulation.md | 46 ++++++++++ docs/Synthesis.md | 15 ++++ docs/conf.py | 56 ++++++++++++ docs/index.md | 13 +++ {doc => docs}/ref-output.png | Bin docs/requirements.txt | 1 + 15 files changed, 505 insertions(+), 166 deletions(-) create mode 100644 docs/Configuration.md create mode 100644 docs/CustomTests.md create mode 100644 docs/LinuxDriver.md create mode 100644 docs/Overview.md rename doc/csr.md => docs/RegisterMap.md (71%) create mode 100644 docs/Simulation.md create mode 100644 docs/Synthesis.md create mode 100644 docs/conf.py create mode 100644 docs/index.md rename {doc => docs}/ref-output.png (100%) create mode 100644 docs/requirements.txt diff --git a/.ci.yml b/.ci.yml index 4b2331b..882d633 100644 --- a/.ci.yml +++ b/.ci.yml @@ -1,12 +1,12 @@ image: $DOCKER_IMAGE -before_script: -# sudo is necessary for setup-enviroment.sh script - - apt-get --allow-releaseinfo-change update && apt-get install -y --no-install-recommends git build-essential sudo - - ./.github/scripts/setup-environment.sh - - git submodule update --init --recursive - test: + before_script: + - export DEBIAN_FRONTEND=noninteractive + # sudo is necessary for setup-enviroment.sh script + - apt --allow-releaseinfo-change update && apt install -y --no-install-recommends git build-essential sudo + - ./.github/scripts/setup-environment.sh + - git submodule update --init --recursive script: - make testall - mkdir out/ @@ -14,3 +14,31 @@ test: artifacts: paths: - out/ + +build-docs: + stage: build + script: + - export DEBIAN_FRONTEND=noninteractive + - apt --allow-releaseinfo-change update && apt install -y --no-install-recommends git build-essential sudo + - sudo apt install -y --no-install-recommends make python3 python3-pip + - pip3 install -r docs/requirements.txt + - SPHINXOPTS="-A conf_py_path=$DOCS_DIR/$SOURCEDIR/ -A commit=$CI_BUILD_REF -A branch=$CI_BUILD_REF_NAME" make html + - make linkcheck + - cp docs/*.png build/html + - tar cf $CI_DOCS_ARCHIVE -C build/html/ . + artifacts: + paths: + - build + - $CI_DOCS_ARCHIVE + +deploy-docs: + variables: + GIT_STRATEGY: none + dependencies: + - build-docs + stage: deploy + tags: ['docs'] + script: echo 'Deploying docs' + artifacts: + paths: + - $CI_DOCS_ARCHIVE diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 5ed4d60..d0ba850 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -10,3 +10,43 @@ jobs: run: | ./.github/scripts/setup-environment.sh make testall + + + docs: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Setup environment + run: | + export DEBIAN_FRONTEND=noninteractive + sudo apt update -qq + sudo apt install -y make python3 python3-pip + pip3 install -r docs/requirements.txt + + + - name: Build the documentation + run: | + SPHINXOPTS="-A conf_py_path=$DOCS_DIR/$SOURCEDIR/ -A commit=$CI_BUILD_REF -A branch=$CI_BUILD_REF_NAME" make html + make linkcheck + cp docs/*.png build/html + + - name: 'Upload artifact: Sphinx HTML' + uses: actions/upload-artifact@v3 + with: + name: Documentation-HTML + path: build/html + + - name: Publish site to GitHub Pages + if: github.event_name != 'pull_request' + run: | + cd build/html + touch .nojekyll + git init + cp ../../.git/config ./.git/config + git add . + git config --local user.email "BuildTheDocs@GitHubActions" + git config --local user.name "GitHub Actions" + git commit -a -m "update ${{ github.sha }}" + git push -u origin +HEAD:gh-pages diff --git a/Makefile b/Makefile index d0b60b8..738a3a6 100644 --- a/Makefile +++ b/Makefile @@ -34,3 +34,7 @@ clean: $(SBT) clean .PHONY: verilog test testall + +%: + sphinx-build -M $@ docs build $(SPHINXOPTS) $(0) + diff --git a/README.md b/README.md index 428e031..eb7d967 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,8 @@ Supported features - 2D transfers with configurable stride - External frame synchronization inputs -Supported busses ----------------- +Supported buses +--------------- - Data - AXI4 @@ -26,25 +26,6 @@ Supported busses - AXI4-Lite - Wishbone -Performance ------------ - -FastVDMA performance was tested in synthetic tests that consisted of transferring an `NxM` buffer with data where `N` represents the number of 32-bit words and `M` represents the number of `N` word rows to transfer. - -FastVDMA was verified in the `xc7z030fbg676-2` chip achieving an average throughput of 750MB/s, while being clocked at 250MHz, and average of 330MB/s at 100MHz under the same workload. Both the speeds were performed in a Memory-Stream-Memory configuration using two controllers configured with AXI4 and AXI-Stream buses. The first controller reads data from memory and sends it out via an AXI-Stream interface, while the second receives the stream and writes the data received to a second buffer in memory. - -Wishbone and AXI4 busses were connected to a [LiteDRAM](https://github.com/enjoy-digital/litedram) controller providing access to DDR3 memory. -Both busses used a 32-bit data bus to connect to the DDR3 controller. - -In both cases the data transferred consisted of a 4MB block of randomly produced data which was subsequently verified for possible transmission errors after each transfer. - -Resource usage --------------- - -The AXI4=\>AXI-Stream (MM2S) configuration utilized 425 slices on a `xc7z030fbg676-2` chip which was used for tesing the design. -AXI-Stream=\>AXI4 (S2MM) requires 455 slices on the same chip. -Both configurations were instantiated in the same design and connected in a back-to-back configuration that allowed memory-to-memory transfers while still using configurations equipped with AXI-Stream interfaces. - Dependencies ------------ @@ -59,29 +40,21 @@ You can simulate the full memory to memory design by running: `make testM2M` -The full stream to memory test by: +And the full stream to memory test by: `make testS2M` -To run both full tests: - -`make test` - -To run all tests, including all mentioned above, execute: - -`make testall` - -Each testrun generates a `.vcd` file which can be opened using GTKWave or any other `.vcd` viewer. -Output files are located in a separate subdirectories inside the `test_run_dir` directory. +Each test run generates a `.vcd` file which can be opened using GTKWave or any other `.vcd` viewer. +Output files are located in a separate sub directories inside the `test_run_dir` directory. The full test should generate an `outM2M.png/outS2M.png` file demonstrating a 2D transfer with configurable stride. The resulting image should look similar to: -![Reference image](doc/ref-output.png) +![Reference image](docs/ref-output.png) Synthesis --------- -To generate a synthesizable verilog file either proceeed with the default configuration by running: +To generate a synthesizable verilog file either proceed with the default configuration by running: `make verilog` @@ -90,95 +63,7 @@ Or provide a valid configuration file with: `make CONFIG_FILE= verilog` The generated file will be named `DMATop$(configuration).v` where `configuration` is chosen configuration of buses in the DMA. Verilog module will be named in the same manner. - -Configuration file ---------- - -A configuration file should be written in json. Here's an example configuration: -``` -{ - "configuration": "AXI_AXIL_AXI", - "addrWidth": 32, - "readDataWidth": 32, - "writeDataWidth": 32, - "readMaxBurst": 0, - "writeMaxBurst": 16, - "reader4KBarrier": false, - "writer4KBarrier": true, - "controlDataWidth": 32, - "controlAddrWidth": 32, - "controlRegCount": 16, - "fifoDepth": 512 -} -``` - -The `configuration` field specifies the choice of buses for data transfer (the 1st and 3rd element) and CSR handling (the 2nd element). - -List of all supported DMA bus configurations is available in the [DMAConfig](src/main/scala/DMAController/DMAConfig.scala#51) file. - -Register map ------------- - -Current register layout is shown in the table below: - -|Address | Role | -|--------|----------------------------| -|`0x00` |Control register | -|`0x04` |Status register | -|`0x08` |Interrupt mask regiser | -|`0x0c` |Interrupt status register | -|`0x10` |Reader start address | -|`0x14` |Reader line length | -|`0x18` |Reader line count | -|`0x1c` |Reader stride between lines | -|`0x20` |Writer start address | -|`0x24` |Writer line length | -|`0x28` |Writer line count | -|`0x2c` |Writer stride between lines | -|`0x30` |Version register | -|`0x34` |Configuration register | - -For a detailed description of register fields check [Register fields](doc/csr.md). - -You can also check [WorkerCSRWrapper](src/main/scala/DMAController/Worker/WorkerCSRWrapper.scala) for more details on how the CSRs are attached to the DMA logic (`io.csr(0)` refers to `0x00`, `io.csr(1)` to `0x04` and so on). - -Tests on customized FastVDMA --------------------- - -If you would like to reuse provided tests to test your custom model you will need to write a test file similar to [DMAFullMem](src/test/scala/DMAController/DMAFullMem.scala). - -What you need to alter is: -- Cast buses in the `io` field accordingly to chosen configuration. Example for `AXIS_AXIL_AXI` bus configuration: - -``` -val io = dut.io.asInstanceOf[Bundle{ - val control: AXI4Lite - val read: AXIStream - val write: AXI4 - val irq: InterruptBundle - val sync: SyncBundle}] -``` - -- You will also need to remember to provide correct BFMs for the test: - -``` - val control = new AxiLiteMasterBfm(io.control, peek, poke, println) - val reader = new AxiStreamMasterBfm(io.read, width, peek, poke, println) - val writer = new Axi4SlaveBfm(io.write, width * height, peek, poke, println) -``` - -- Lastly, add an entry in [ControllerSpec](src/test/scala/DMAController/ControllerSpec.scala) (or write your Tester): - -``` -val myConfiguration = new DMAConfig(...) -it should "perform image transfer with my custom configuration" in { - test(new DMATop(myConfiguration)).runPeekPoke(dut => - new ImageTransfer(dut, new (dut), myConfiguration) - ) - } -``` - -After successful test, the image `out$(configuration).rgba` will be produced (where `configuration` is the DMA bus configuration). +See the documentation on how to provide custom configuration -- link here. Source code structure --------------------- @@ -191,9 +76,3 @@ Source code structure - [Bfm](src/test/scala/DMAController/Bfm) contains Bus models that are used in full configuration tests - [Frontend](src/test/scala/DMAController/Frontend) contains tests used for generating timing diagrams for various bus types - [Worker](src/test/scala/DMAController/Worker) contains tests that generate timing diagrams for the generic part of the DMA - -Linux drivers -------------- - -FastVDMA can be controlled using a Linux driver. -The source code and relevant documentation can be found in a [separate repository](https://github.com/antmicro/linux-xlnx/tree/fastvdma-driver). diff --git a/docs/Configuration.md b/docs/Configuration.md new file mode 100644 index 0000000..6b2b3b0 --- /dev/null +++ b/docs/Configuration.md @@ -0,0 +1,125 @@ +# Configuration + +## Configuration example + +The FastVDMA is configurable via the JSON configuration file. Here's an example of FastVDMA configured to read from AXI-Stream interface and write to memory with AXI4 interface: + +```json +{ + "configuration": "AXIS_AXIL_AXI", + "addrWidth": 32, + "readDataWidth": 32, + "writeDataWidth": 32, + "readMaxBurst": 0, + "writeMaxBurst": 16, + "reader4KBarrier": false, + "writer4KBarrier": true, + "controlDataWidth": 32, + "controlAddrWidth": 32, + "controlRegCount": 16, + "fifoDepth": 512 +} +``` + +:::{info} +All of the above parameters have to be specified to generate FastVDMA core. +::: + +To build a FastVDMA core with custom configuration pass the path to your config file via the `CONFIG_FILE` variable: + +```bash +make CONFIG_FILE= verilog +``` + +## Configuration parameters + +### configuration + +This field is used to specify the FastVDMA bus configuration. It's a string of format: + +``` +BUS-IN_BUS-CSR_BUS-OUT +``` + +Where the `BUS-IN` and `BUS-OUT` are the data transferring buses and `BUS-CSR` is the CSR handling bus type. + +List of all supported DMA bus configurations is available in the [DMAConfig](https://github.com/antmicro/fastvdma/blob/main/src/main/scala/DMAController/DMAConfig.scala) file. + +--- + +### addrWidth + +This field specifies address width of the data transferring buses. + +--- + +### readDataWidth + +This field specifies the data width of the `BUS-IN` bus. + +--- + +### writeDataWidth + +This field specifies the data width of the `BUS-OUT` bus. + +--- + +### readMaxBurst + +This field specifies the maximal burst for the `BUS-IN` bus. That is, the maximum number of bytes within the single transaction. + +:::{admonition} +The `0`-value is reserved for the stream interfaces. +::: + +--- + +### writeMaxBurst + +This field specifies the maximal burst for the `BUS-OUT` bus. That is, the maximum number of bytes within the single transaction. + +:::{admonition} +The `0`-value is reserved for the stream interfaces. +::: + +--- + +### reader4KBarrier + +This field takes the `true`/`false` value whether the `BUS-IN` interface may cross 4KB (4096 bytes) in a single transfer. + +--- + +### writer4KBarrier + +This field takes the `true`/`false` value whether the `BUS-OUT` interface may cross 4KB (4096 bytes) in a single transfer. + +--- + +### controlDataWidth + +This field specifies the data width of the `BUS-CSR` bus. + +--- + +### controlAddrWidth + +This field specifies the address width of the `BUS-CSR` bus. + +:::{admonition} +The FastVDMA was written with enhancements in mind. +It is not recommended to use address widths other than **32**. +::: + +--- + +### controlRegCount + +This field specifies the number of the registers the `BUS-CSR` handles. It needs to be at least **16**. + +--- + +### fifoDepth + +This parameter specifies the depth of the queue initialized and connected between `BUS-IN` and `BUS-OUT` interfaces. diff --git a/docs/CustomTests.md b/docs/CustomTests.md new file mode 100644 index 0000000..169b5b4 --- /dev/null +++ b/docs/CustomTests.md @@ -0,0 +1,38 @@ +# Writing custom tests + +If you would like to reuse provided tests to test your custom model you will need to write a test file similar to [DMAFullMem](https://github.com/antmicro/fastvdma/blob/main/src/test/scala/DMAController/DMAFullMem.scala). + +What you need to alter is: + +- Cast buses in the `io` field accordingly to chosen configuration. + Example for `AXIS_AXIL_AXI` bus configuration: + +```scala +val io = dut.io.asInstanceOf[Bundle{ + val control: AXI4Lite + val read: AXIStream + val write: AXI4 + val irq: InterruptBundle + val sync: SyncBundle}] +``` + +- You will also need to remember to provide correct BFMs for the test: + +```scala +val control = new AxiLiteMasterBfm(io.control, peek, poke, println) +val reader = new AxiStreamMasterBfm(io.read, width, peek, poke, println) +val writer = new Axi4SlaveBfm(io.write, width * height, peek, poke, println) +``` + +- Lastly, add an entry in the [ControllerSpec](https://github.com/antmicro/fastvdma/blob/main/src/test/scala/DMAController/ControllerSpec.scala) (or write your Tester): + +```scala +val myConfiguration = new DMAConfig(...) +it should "perform image transfer with my custom configuration" in { + test(new DMATop(myConfiguration)).runPeekPoke(dut => + new ImageTransfer(dut, new (dut), myConfiguration) + ) +} +``` + +After successful test, the image `out$(configuration).rgba` will be produced (where `configuration` is the DMA bus configuration). \ No newline at end of file diff --git a/docs/LinuxDriver.md b/docs/LinuxDriver.md new file mode 100644 index 0000000..db3b4bc --- /dev/null +++ b/docs/LinuxDriver.md @@ -0,0 +1,9 @@ +# Linux DMAEngine driver + + + +FastVDMA can be controlled using a Linux driver. +The driver implements DMAEngine interface with support to scatter gather and interleaved transfers. + +The source code and relevant documentation can be found in a [separate repository](https://github.com/antmicro/linux-xlnx/tree/fastvdma-driver). + diff --git a/docs/Overview.md b/docs/Overview.md new file mode 100644 index 0000000..435a02d --- /dev/null +++ b/docs/Overview.md @@ -0,0 +1,50 @@ +# Overview + +FastVDMA is a DMA controller designed with portability and customizability in mind. + +## Features + +- Interrupts +- 2D transfers with configurable stride +- External frame synchronization inputs + +--- + +## Supported buses + +FastVDMA implements several most commonly used buses for data handling and CSR handling. + +### Data + +- AXI4 +- AXI-Stream +- Wishbone + +### Control + +- AXI4-Lite +- Wishbone + +--- + +## Performance + +FastVDMA performance was tested in synthetic tests that consisted of transferring an `NxM` buffer with data where `N` represents the number of 32-bit words and `M` represents the number of `N` word rows to transfer. + +FastVDMA was verified in the `xc7z030fbg676-2` chip achieving an average throughput of 750MB/s, while being clocked at 250MHz, and average of 330MB/s at 100MHz under the same workload. Both the speeds were performed in a Memory-Stream-Memory configuration using two controllers configured with AXI4 and AXI-Stream buses. The first controller reads data from memory and sends it out via an AXI-Stream interface, while the second receives the stream and writes the data received to a second buffer in memory. + +Wishbone and AXI4 buses were connected to a [LiteDRAM](https://github.com/enjoy-digital/litedram) controller providing access to DDR3 memory. + +Both buses used a 32-bit data bus to connect to the DDR3 controller. + +In both cases the data transferred consisted of a 4MB block of randomly produced data which was subsequently verified for possible transmission errors after each transfer. + +--- + +## Resource usage + +The AXI4=\>AXI-Stream (MM2S) configuration utilized 425 slices on a `xc7z030fbg676-2` chip which was used for testing the design. + +AXI-Stream=\>AXI4 (S2MM) requires 455 slices on the same chip. + +Both configurations were instantiated in the same design and connected in a back-to-back configuration that allowed memory-to-memory transfers while still using configurations equipped with AXI-Stream interfaces. \ No newline at end of file diff --git a/doc/csr.md b/docs/RegisterMap.md similarity index 71% rename from doc/csr.md rename to docs/RegisterMap.md index 10b4b32..ad81b0a 100644 --- a/doc/csr.md +++ b/docs/RegisterMap.md @@ -1,10 +1,30 @@ -Register fields -=============== +# Register fields -Current register field layout is shown below: +## Register table -Control register (0x00) ------------------------ +Current register layout is shown in the table below: + +|Address | Role | +|--------|----------------------------| +|`0x00` |[Control register](control-register-0x00) | +|`0x04` |[Status register](status-register-0x04) | +|`0x08` |[Interrupt mask regiser](interrupt-mask-register-0x08) | +|`0x0c` |[Interrupt status register](interrupt-status-register-0x0c) | +|`0x10` |[Reader start address](reader-start-address-0x10) | +|`0x14` |[Reader line length](reader-line-length-0x14) | +|`0x18` |[Reader line count](reader-line-count-0x18) | +|`0x1c` |[Reader stride between lines](reader-stride-between-lines-0x1c) | +|`0x20` |[Writer start address](writer-start-address-0x20) | +|`0x24` |[Writer line length](writer-line-length-0x24) | +|`0x28` |[Writer line count](writer-line-count-0x28)| +|`0x2c` |[Writer stride between lines](writer-stride-between-lines-0x2c) | +|`0x30` |[Version register](version-register-0x30) | +|`0x34` |[Configuration register](configuration-register-0x34) | + + +## Detailed register description + +### Control register (0x00) |Bit |Name |Description | |----|--------------------|----------------------------------------------------------------------------------------------------| @@ -16,8 +36,9 @@ Control register (0x00) |5 |Reader loop mode |Write `1` to automatically start next read frontend transfer after finishing the current one | |6-31|- |Unused | -Status register (0x04) ----------------------- +--- + +### Status register (0x04) |Bit |Name |Description | |----|---------------|-----------------------------------------------------------| @@ -25,8 +46,9 @@ Status register (0x04) |1 |Reader busy |Reads as `1` when read frontend is busy transferring data | |2-31|- |Unused | -Interrupt mask register (0x08) ------------------------------- +--- + +### Interrupt mask register (0x08) |Bit |Name |Description | |----|------------|----------------------------------------| @@ -34,8 +56,9 @@ Interrupt mask register (0x08) |1 |Reader mask |Write `1` to enable reader interrupt | |2-31|- |Unused | -Interrupt status register (0x0c) --------------------------------- +--- + +### Interrupt status register (0x0c) |Bit |Name |Description | |----|-----------------|--------------------------------------------------------------------------------| @@ -43,72 +66,84 @@ Interrupt status register (0x0c) |1 |Reader interrupt |Reads as `1` if reader interrupt has occured, write `1` to clear that interrupt | |2-31|- |Unused | -Reader start address (0x10) ---------------------------- +--- + +### Reader start address (0x10) |Bit |Name |Description | |----|--------------|---------------------------------------------------------------------------| |0-31|Start address |Reader start address (set to `0` if reader frontend is a stream interface) | -Reader line length (0x14) -------------------------- +--- + +### Reader line length (0x14) |Bit |Name |Description | |----|------------|---------------------------------------------------------| |0-31|Line length |Reader line length (as number of reader data bus widths) | -Reader line count (0x18) ------------------------- +--- + +### Reader line count (0x18) |Bit |Name |Description | |----|-----------|------------------| |0-31|Line count |Reader line count | -Reader stride between lines (0x1c) ----------------------------------- +--- + +### Reader stride between lines (0x1c) |Bit |Name |Description | |----|-------|--------------------------------------------------------------------| |0-31|Stride |Gap between consecutive lines (as number of reader data bus widths) | -Writer start address (0x20) ---------------------------- +--- + +### Writer start address (0x20) |Bit |Name |Description | |----|--------------|---------------------------------------------------------------------------| |0-31|Start address |Writer start address (set to `0` if writer frontend is a stream interface) | -Writer line length (0x24) -------------------------- +--- + +### Writer line length (0x24) |Bit |Name |Description | |----|------------|---------------------------------------------------------| |0-31|Line length |Writer line length (as number of writer data bus widths) | -Writer line count (0x28) ------------------------- +--- + +### Writer line count (0x28) |Bit |Name |Description | |----|-----------|------------------| |0-31|Line count |Writer line count | -Writer stride between lines (0x2c) ----------------------------------- +### Writer stride between lines (0x2c) |Bit |Name |Description | |----|-------|--------------------------------------------------------------------| |0-31|Stride |Gap between consecutive lines (as number of writer data bus widths) | -Version register (0x30) ------------------------ +--- + +### Version register (0x30) |Bit |Name |Description | |----|-----------------|---------------------------| |0-31|Version register |Holds the FastVDMA version | -Configuration register (0x34) ------------------------------ +--- + +### Configuration register (0x34) |Bit |Name |Description | |----|-----------------------|-------------------------------------| |0-31|Configuration register |Reader, writer and control bus types | + +--- + +You can also check [WorkerCSRWrapper](https://github.com/antmicro/fastvdma/blob/main/src/main/scala/DMAController/Worker/WorkerCSRWrapper.scala) for the implementation details on how the CSRs are attached to the DMA logic (`io.csr(0)` refers to `0x00`, `io.csr(1)` to `0x04` and so on). \ No newline at end of file diff --git a/docs/Simulation.md b/docs/Simulation.md new file mode 100644 index 0000000..228b88f --- /dev/null +++ b/docs/Simulation.md @@ -0,0 +1,46 @@ +# Simulation + +## Chisel test simulation + +FastVDMA can be simulated as a whole but certain components can be tested separately. + +You can simulate the full memory to memory design by running: + +```bash +make testM2M +``` + +The full stream to memory test by: + +``` +make testS2M +``` + +To run both full tests: + +```bash +make test +``` + +To run all tests, including all mentioned above, execute: + +```bash +make testall +``` + +Each test run generates a `.vcd` file which can be opened using GTKWave or any other `.vcd` viewer. + +Output files are located in a separate sub directories inside the `test_run_dir` directory. + +The full test should generate an `outM2M.png/outS2M.png` file demonstrating a 2D transfer with configurable stride. +The resulting image should look similar to: + +![Reference image](ref-output.png) + +## Renode-Verilator co-simulation + +FastVDMA provided [script](https://github.com/renode/renode/blob/master/scripts/single-node/zynq_verilated_fastvdma.resc) for the open source software development framework - [Renode](https://github.com/renode/renode/tree/master). + +With the use of [renode-verilator-integration](https://github.com/antmicro/renode-verilator-integration/tree/master), Renode runs Verilator simulation of the FastVDMA design and simulates the rest of the environment itself. This includes booting the Linux kernel. You may read more about the Renode's co-simulation feature from [this blog note](https://antmicro.com/blog/2021/09/co-simulation-for-zynq-with-renode-and-verilator/). + +Then, loading the [FastVDMA driver](https://github.com/antmicro/linux-xlnx/tree/fastvdma-driver/drivers/dma/fastvdma) it performs a demo image transfer, similar to the one from chisel test. FastVDMA provides the source code to the example driver that uses FastVDMA driver through DMAEngine as well as the [demo user-space application](https://github.com/antmicro/linux-xlnx/tree/fastvdma-demo/drivers/dma/fastvdma). \ No newline at end of file diff --git a/docs/Synthesis.md b/docs/Synthesis.md new file mode 100644 index 0000000..db0faaa --- /dev/null +++ b/docs/Synthesis.md @@ -0,0 +1,15 @@ +# Synthesis + +To generate a synthesizable verilog file either proceed with the default configuration by running: + +```bash +make verilog +``` + +Or provide a valid configuration file with: + +```bash +make CONFIG_FILE= verilog +``` + +The generated file will be named `DMATop$(configuration).v` where `configuration` is chosen configuration of buses in the DMA. Verilog module will be named in the same manner. \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..5afbf71 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,56 @@ +# -*- coding: utf-8 -*- + +from datetime import datetime + +from antmicro_sphinx_utils.defaults import ( + extensions, + myst_enable_extensions, + myst_fence_as_directive, + antmicro_html, + antmicro_latex +) + +# -- General configuration ----------------------------------------------------- + +# General information about the project. +project = u'FastVDMA' +basic_filename = u'fastvdma' +authors = u'Antmicro' +copyright = f'{authors}, {datetime.now().year}' + +version = '' +release = '' + +sphinx_immaterial_override_builtin_admonitions = False +numfig = True + +myst_substitutions = { + "project": project +} + +today_fmt = '%Y-%m-%d' + +todo_include_todos=False + +# -- Options for HTML output --------------------------------------------------- + +html_theme = 'sphinx_immaterial' + +html_last_updated_fmt = today_fmt + +html_show_sphinx = False + +( + html_logo, + html_theme_options, + html_context +) = antmicro_html(pdf_url=f"{basic_filename}.pdf") + +html_title = project + +( + latex_elements, + latex_documents, + latex_logo, + latex_additional_files +) = antmicro_latex(basic_filename, authors, project) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..53f2160 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,13 @@ +# FastVDMA + +```{toctree} +:maxdepth: 1 +Overview +Configuration +Synthesis +Simulation +RegisterMap +CustomTests +LinuxDriver +``` + diff --git a/doc/ref-output.png b/docs/ref-output.png similarity index 100% rename from doc/ref-output.png rename to docs/ref-output.png diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..2bc1c6a --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +https://github.com/antmicro/antmicro-sphinx-utils/archive/main.zip