diff --git a/docs/fud/axi-gen.md b/docs/fud/axi-gen.md index 855dadda1b..c6500bd1a5 100644 --- a/docs/fud/axi-gen.md +++ b/docs/fud/axi-gen.md @@ -1,22 +1,27 @@ # AXI Interface Generation -Calyx currently generates a fairly complex AXI interface that can be daunting + +In order to run programs on FPGAs, fud is capable of utilizing +Calyx to generate a fairly complex AXI interface that can be daunting to deal with if confronting for the first time. The following is an overview of how the generation occurs -and how the output AXI interface behaves as of 2022-9-11. +and how the fud-generated AXI interface behaves as of 2022-9-11. In general, when `fud` is asked to create an [`.xclbin` file][xclbin] a `kernel.xml`, -`main.sv`, and `toplevel.v` are created as intermediate steps for [xilinx tools][xilinx_tools] -to properly work. +`main.sv`, and `toplevel.v` are created as intermediate files required for our +[Xilinx tools][xilinx_tools] to properly work. -`main.sv` contains the SystemVerilog needed for our computations to perform -correctly. It is implemented as an FSM that derives from the original Calyx program. -[`kernel.xml`][kernel_xml] defines register maps and ports of our -toplevel xilinx tools needs. `toplevel.v` wraps our computation kernel and contains -the AXI interface for each memory defined in a Calyx program and corresponds to the standard Calux lowering process. +`main.sv` contains the SystemVerilog implementation of the Calyx program +we are interested in executing on an FPGA. +`toplevel.v` wraps our SystemVerilog implementation and contains +the AXI interface for each memory marked [`@external`][external] in a Calyx program. +Our `toplevel.v` and [`kernel.xml`][kernel_xml] is what our Xilinx tools interface with. +Our toplevel adheres to the Xilinx [kernel interface requirements][kernel_requirements]. +`kernel.xml` defines register maps and ports of our +toplevel module used by our Xilinx tools. -For more info on file generation see [how the Xilinx Toolchain works][xilinx_how] +For more information on the generation of the files mentioned above see [how the Xilinx Toolchain works][xilinx_how] ## Toplevel @@ -31,16 +36,16 @@ To note, separate AXI interfaces are created for each memory the memory. Eventually the BRAMs are read and fed into the computation kernel of `main.sv`, which outputs results directly into the relevant memories as defined in the original Calyx program. -Address and data widths and sizes are determined from cell declerations. +Addresses, data widths, and sizes are determined from cell declarations. > There is always the possiblity that something is hardcoded as a remnant -> from previous versions of our AXI generation. If something is hardcoded where it shouldn't +> of previous versions of our AXI generation. If something is hardcoded where it shouldn't > be please open an [issue][issues]. AXI memory controllers are constructed as (full) [AXI4 managers][signals] that lack a small amount of functionality. For example, [xPROT signals][access_protection] are not currently supported. Additionally, things like [bursting][bursting] are not currently supported, but should be -easy to implement due to the existing infrastructure and generation. +easy to implement due to the existing infrastructure and generation tools. A list of current signals that are hardcoded follows: @@ -56,10 +61,11 @@ A list of current signals that are hardcoded follows: * No [low power signals](https://developer.arm.com/documentation/ihi0022/e/AMBA-AXI3-and-AXI4-Protocol-Specification/Signal-Descriptions/Low-power-interface-signals?lang=en) are generated. ### Subordinate AXI control controller -In addition to our manager memory controllers, a subordinate controller for -our control module is also generated. This module is responsible for signaling +In addition to our manager memory-controllers, a subordinate interface, +connected to our control module is also generated. +This module is responsible for signaling our computational kernel to start working, as well as calculating the correct -base addresses to use for our memory controllers. Things like address and +base addresses to use for our memory controllers. Things like addresses and data widths are hard coded at the moment. It is suspected that this hardcoding is okay for the types of programs we generate. But more work needs to be done to see if our control structure works for arbitrary programs or needs to be changed to @@ -77,3 +83,4 @@ allow this. [access_protection]: https://developer.arm.com/documentation/ihi0022/e/AMBA-AXI3-and-AXI4-Protocol-Specification/Transaction-Attributes/Access-permissions?lang=en [toplevel]: https://docs.calyxir.org/lang/attributes.html?highlight=toplevel#toplevel [xilinx_how]: https://docs.calyxir.org/fud/xilinx.html?highlight=synthesis#how-it-works +[kernel_requirements]: https://docs.xilinx.com/r/en-US/ug1393-vitis-application-acceleration/Kernel-Interface-Requirements