Skip to content

Commit e22a16e

Browse files
IstvanZsSzekelyIstvanZsSzekely
committed
docs/corundum: Added documentation for the Corundum cores, updated AD9081 documentation
Signed-off-by: Istvan-Zsolt Szekely <istvan.szekely@analog.com>
1 parent 21fcd8e commit e22a16e

File tree

5 files changed

+281
-42
lines changed

5 files changed

+281
-42
lines changed

‎docs/library/corundum/corundum_core/index.rst

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
.. _corundum_core:
2+
3+
Corundum Core
4+
================================================================================
5+
6+
.. hdl-component-diagram::
7+
8+
The :git-hdl:`Corundum Core <library/corundum/corundum_core>` is common in all
9+
projects and is used by the Corundum Network Stack. It repackages part of the
10+
`Corundum NIC <https://github.com/ucsdsysnet/corundum>`__ as an IP Core to be
11+
used with the ADI workflow.
12+
13+
Features
14+
--------------------------------------------------------------------------------
15+
16+
* Supports ARM and Microblaze processors
17+
18+
Files
19+
--------------------------------------------------------------------------------
20+
21+
.. list-table::
22+
:header-rows: 1
23+
24+
* - Name
25+
- Description
26+
* - :git-hdl:`library/corundum/corundum_core/corundum.v`
27+
- Verilog source for the Corundum Core top module.
28+
* - :git-hdl:`library/corundum/corundum_core/corundum_ip.tcl`
29+
- TCL script to generate the Vivado IP-integrator project.
30+
* - :git-hdl:`library/corundum/corundum_core/mqnic_app_block.v`
31+
- Verilog source for the Application Core that is found inside the Corundum
32+
core.
33+
* - :git-hdl:`library/corundum/corundum_core/mqnic_app_custom_params.vh`
34+
- Verilog header file used to parameterize the Application Core.
35+
* - :git-hdl:`library/corundum/corundum_core/mqnic_app_custom_ports.vh`
36+
- Verilog header file used to create the ports and interfaces for the
37+
Application Core.
38+
39+
Configuration Parameters
40+
--------------------------------------------------------------------------------
41+
42+
.. hdl-parameters::
43+
44+
Interface
45+
--------------------------------------------------------------------------------
46+
47+
.. hdl-interfaces::
48+
49+
Building
50+
--------------------------------------------------------------------------------
51+
52+
This IP uses `Corundum NIC <https://github.com/ucsdsysnet/corundum>`_
53+
repository, which needs to be cloned alongside the HDL repository.
54+
55+
.. shell::
56+
57+
~/workspace
58+
$git clone https://github.com/ucsdsysnet/corundum.git
59+
$cd hdl/library/corundum/corundum_core
60+
$make
61+
62+
.. admonition:: Publications
63+
64+
The following papers pertain to the Corundum source code:
65+
66+
- J- A. Forencich, A. C. Snoeren, G. Porter, G. Papen, Corundum: An Open-Source 100-Gbps NIC, in FCCM'20.
67+
(`FCCM Paper`_, `FCCM Presentation`_)
68+
- J- A. Forencich, System-Level Considerations for Optical Switching in Data Center Networks. (`Thesis`_)
69+
70+
.. _FCCM Paper: https://www.cse.ucsd.edu/~snoeren/papers/corundum-fccm20.pdf
71+
.. _FCCM Presentation: https://www.fccm.org/past/2020/forums/topic/corundum-an-open-source-100-gbps-nic/
72+
.. _Thesis: https://escholarship.org/uc/item/3mc9070t
73+
74+
References
75+
--------------------------------------------------------------------------------
76+
77+
* HDL IP core at :git-hdl:`library/corundum/corundum_core`

‎docs/library/corundum/ethernet/index.rst

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
.. _corundum_ethernet_core:
2+
3+
Corundum Ethernet Core
4+
================================================================================
5+
6+
.. toctree::
7+
:hidden:
8+
9+
VCU118 <vcu118/index>
10+
11+
The :git-hdl:`Corundum Ethernet Core <library/corundum/ethernet_core>` is used
12+
by the Corundum Network Stack. The Ethernet Core is specific to each FPGA board
13+
and encompasses the Ethernet physical layer and other auxiliary structures such
14+
as SPI and I2C that are required by the Corundum system. The configurations are
15+
based on `Corundum NIC <https://github.com/ucsdsysnet/corundum>`__ reference
16+
designs that were adapted to suit the ADI workflow.
17+
18+
Depending on the board for which the IP is built, different HDL component
19+
diagrams will be available.
20+
21+
* :ref:`corundum_ethernet_core_vcu118`
22+
23+
Features
24+
--------------------------------------------------------------------------------
25+
26+
* Supports 100G Ethernet-based systems that uses the CMAC core on the VCU118
27+
board
28+
29+
Files
30+
--------------------------------------------------------------------------------
31+
32+
Depending on the board for which the IP is built, different source files will
33+
be available.
34+
35+
Configuration Parameters
36+
--------------------------------------------------------------------------------
37+
38+
Depending on the board for which the IP is built, different HDL parameters will
39+
be available.
40+
41+
Interface
42+
--------------------------------------------------------------------------------
43+
44+
Depending on the board for which the IP is built, different HDL interfaces and
45+
ports will be available.
46+
47+
Building
48+
--------------------------------------------------------------------------------
49+
50+
This IP uses `Corundum NIC <https://github.com/ucsdsysnet/corundum>`_
51+
repository, which needs to be cloned alongside the HDL repository.
52+
53+
.. shell::
54+
55+
~/workspace
56+
$git clone https://github.com/ucsdsysnet/corundum.git
57+
$cd hdl/library/corundum/ethernet_core
58+
59+
An environment variable must be exported for this IP, so Vivado builds the
60+
appropriate configuration.
61+
62+
.. shell::
63+
64+
~/workspace/hdl/library/corundum/ethernet_core
65+
$export BOARD=VCU118
66+
$make
67+
68+
.. attention::
69+
70+
If the Ethernet Core has to be used in a project that is designed for a
71+
different board than the one the IP was originally built for, then the BOARD
72+
variable must be overwritten and the IP rebuilt!
73+
74+
.. hint::
75+
76+
To check what board the IP was built for, check the content of the board.env
77+
file after the build.
78+
79+
.. shell::
80+
81+
~/workspace
82+
$cd hdl/library/corundum/ethernet_core
83+
$cat board.env
84+
85+
.. important::
86+
87+
It is recommended to include the BOARD variable inside the project's Makefile
88+
as it will check if the IP is built with the specified variable, and if not,
89+
it will build/rebuild it.
90+
91+
.. shell::
92+
93+
export BOARD := VCU118
94+
95+
.. admonition:: Publications
96+
97+
The following papers pertain to the Corundum source code:
98+
99+
- J- A. Forencich, A. C. Snoeren, G. Porter, G. Papen, Corundum: An Open-Source 100-Gbps NIC, in FCCM'20.
100+
(`FCCM Paper`_, `FCCM Presentation`_)
101+
- J- A. Forencich, System-Level Considerations for Optical Switching in Data Center Networks. (`Thesis`_)
102+
103+
.. _FCCM Paper: https://www.cse.ucsd.edu/~snoeren/papers/corundum-fccm20.pdf
104+
.. _FCCM Presentation: https://www.fccm.org/past/2020/forums/topic/corundum-an-open-source-100-gbps-nic/
105+
.. _Thesis: https://escholarship.org/uc/item/3mc9070t
106+
107+
References
108+
--------------------------------------------------------------------------------
109+
110+
* HDL IP core at :git-hdl:`library/corundum/ethernet`

‎docs/library/corundum/ethernet/vcu118/index.rst

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
.. _corundum_ethernet_core_vcu118:
2+
3+
Corundum Ethernet Core for VCU118
4+
================================================================================
5+
6+
.. hdl-component-diagram::
7+
8+
Files
9+
--------------------------------------------------------------------------------
10+
11+
.. list-table::
12+
:header-rows: 1
13+
14+
* - Name
15+
- Description
16+
* - :git-hdl:`library/corundum/ethernet_core/ethernet_core_vcu118.v`
17+
- Verilog source for the Ethernet Core top module for the VCU118 board.
18+
* - :git-hdl:`library/corundum/ethernet_core/eternet_ip.tcl`
19+
- TCL script to generate the Vivado IP-integrator project.
20+
21+
Configuration Parameters
22+
--------------------------------------------------------------------------------
23+
24+
.. hdl-parameters::
25+
26+
Interface
27+
--------------------------------------------------------------------------------
28+
29+
.. hdl-interfaces::
30+
31+
References
32+
--------------------------------------------------------------------------------
33+
34+
* HDL IP core at :git-hdl:`library/corundum/ethernet_core`

‎docs/library/corundum/index.rst

Lines changed: 19 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,33 @@
11
.. _corundum:
22

3-
Corundum
3+
Corundum Network Stack
44
================================================================================
55

6-
.. hdl-component-diagram::
6+
.. toctree::
7+
:hidden:
78

8-
The :git-hdl:`Corundum <library/corundum>` IP core
9-
repackages `Corundum NIC <https://github.com/corundum/corundum>`__ as an IP Core.
9+
Corundum Core <corundum_core/index>
10+
Corundum Ethernet Core <ethernet/index>
1011

11-
Features
12-
--------------------------------------------------------------------------------
13-
14-
* AXI-based configuration
15-
* Vivado compatible
16-
17-
Files
18-
--------------------------------------------------------------------------------
19-
20-
.. list-table::
21-
:header-rows: 1
22-
23-
* - Name
24-
- Description
25-
* - :git-hdl:`library/corundum/corundum.v`
26-
- Verilog source for the Corundum top module.
27-
* - :git-hdl:`library/corundum/corundum_ip.tcl`
28-
- TCL script to generate the Vivado IP-integrator project.
12+
The :git-hdl:`Corundum <library/corundum>` framework repackages
13+
`Corundum NIC <https://github.com/ucsdsysnet/corundum>`__ into 2 separate IP
14+
cores. These cores are the :ref:`corundum_core`, which is common in all projects
15+
that use the Corundum Network Stack and the :ref:`corundum_ethernet_core`, which
16+
is specific to each FPGA board and encompasses the Ethernet physical layer and
17+
other auxiliary structures such as SPI and I2C that are required by the Corundum
18+
system.
2919

30-
Configuration Parameters
20+
Sub-modules
3121
--------------------------------------------------------------------------------
3222

33-
.. hdl-parameters::
23+
* :ref:`corundum_core`
24+
* :ref:`corundum_ethernet_core`
3425

35-
Interface
26+
Software support
3627
--------------------------------------------------------------------------------
3728

38-
.. hdl-interfaces::
39-
40-
Building
41-
--------------------------------------------------------------------------------
42-
43-
This project uses `Corundum NIC <https://github.com/corundum/corundum>`_
44-
and it needs to be cloned alongside this repository.
45-
46-
.. code::
47-
48-
hdl/../> git clone https://github.com/corundum/corundum.git
49-
hdl/../corundum/> git checkout ed4a26e2cbc0a429c45d5cd5ddf1177f86838914
50-
hdl/library/corundum> make &
29+
* :git-linux:`Linux Driver <staging/corundum:drivers/net/mqnic/mqnic_main.c>`:
30+
Linux driver for the Corundum Network Stack.
5131

5232
.. admonition:: Publications
5333

@@ -64,7 +44,4 @@ and it needs to be cloned alongside this repository.
6444
References
6545
--------------------------------------------------------------------------------
6646

67-
* HDL IP core at :git-hdl:`library/corundum`
68-
* HDL project at :git-hdl:`projects/ad_gmsl2eth_sl`
69-
* :ref:`ad_gmsl2eth_sl`
70-
* :adi:`AD-GMSL2ETH-SL`
47+
* HDL IP cores at :git-hdl:`library/corundum`

‎docs/projects/ad9081_fmca_ebz/index.rst

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,10 @@ Example block design for Single link; M=2; L=8; JESD204C
267267
$ TX_JESD_S=4 \
268268
$ TX_JESD_NP=8
269269

270+
In the case of :adi:`VCU118` board, a CORUNDUM parameter is also available,
271+
which enables or disables the Corundum Network Stack. By default it is
272+
disabled, set to 0. To enable it, set the value to 1.
273+
270274
The Rx link is operating with the following parameters:
271275

272276
- Rx Deframer parameters: L=8, M=2, F=1, S=2, NP=16, N=16 (Quick Config 0x13)
@@ -347,6 +351,7 @@ The following are the parameters of this project that can be configured:
347351
kilosamples per converter (M)
348352
- [ADC/DAC]_DO_MEM_TYPE
349353
- Check out this guide on more details regarding these parameters: :ref:`axi_tdd`
354+
- CORUNDUM: enables the Corundum Network Stack
350355

351356
Clock scheme
352357
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -408,6 +413,16 @@ mxfe_tx_data_offload $INTF_CFG!="RX" 0x7C44_0000 0x9C44_00
408413
axi_tdd_0 $TDD_SUPPORT==1 0x7C46_0000 0x9C46_0000 0xBC46_00000
409414
==================== ================================= =============== =========== ============
410415

416+
In case of :adi:`VCU118`, additional CPU interconnects may be present in the
417+
system.
418+
419+
=================== ==================== ===========
420+
Instance Depends on parameter Microblaze
421+
=================== ==================== ===========
422+
corundum_core $CORUNDUM==1 0x5000_0000
423+
corundum_gpio_reset $CORUNDUM==1 0x5200_0000
424+
=================== ==================== ===========
425+
411426
For the Intel carriers, only a part of the CPU interrupts are specified,
412427
as the rest depend on the values of $TX_NUM_OF_LANES and $TRANSCEIVER_TYPE
413428
(see :git-hdl:`projects/ad9081_fmca_ebz/common/ad9081_fmca_ebz_qsys.tcl`
@@ -534,6 +549,14 @@ axi_mxfe_rx_jesd 11 55 87 107 139
534549
axi_mxfe_tx_jesd 10 54 86 106 138
535550
================ === ========== =========== ============ =============
536551

552+
In case of :adi:`VCU118`, additional interrupts may be present in the system.
553+
554+
================ ======
555+
Instance name HDL MB
556+
================ ======
557+
corundum_core 5
558+
================ ======
559+
537560
Building the HDL project
538561
-------------------------------------------------------------------------------
539562

@@ -640,6 +663,8 @@ for that project (ad9081_fmca_ebz/$carrier or ad9082_fmca_ebz/$carrier).
640663
+-------------------+----------+----------+--------+--------+--------+--------+-------+--------+
641664
| DAC_DO_MEM_TYPE | --- | --- | --- | --- | --- | 2 | --- | --- |
642665
+-------------------+----------+----------+--------+--------+--------+--------+-------+--------+
666+
| CORUNDUM | --- | --- | --- | --- | 0 | --- | --- | --- |
667+
+-------------------+----------+----------+--------+--------+--------+--------+-------+--------+
643668

644669
.. collapsible:: Default values of the ``make`` parameters for AD9082-FMCA-EBZ
645670

@@ -705,6 +730,16 @@ because of truncation of some keywords so the name will not exceed the limits
705730
of the Operating System (``JESD``, ``LANE``, etc. are removed) of 260
706731
characters.
707732

733+
In case of the :adi:`VCU118`, if the Corundum Network Stack needs to be added,
734+
run the make command such as:
735+
736+
``make CORUNDUM=1``
737+
738+
.. note::
739+
740+
Other build parameters may be added to the make command as shown in the
741+
previous example with multiple prameters when using the Corundum system.
742+
708743
A more comprehensive build guide can be found in the :ref:`build_hdl` user guide.
709744

710745
Software considerations
@@ -848,6 +883,12 @@ HDL related
848883
* - JESD204_TPL_DAC
849884
- :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_dac`
850885
- :ref:`ad_ip_jesd204_tpl_dac`
886+
* - CORUNDUM_CORE
887+
- :git-hdl:`library/corundum/corundum_core`
888+
- :ref:`corundum_core`
889+
* - ETHERNET_CORE
890+
- :git-hdl:`library/corundum/ethernet`
891+
- :ref:`corundum_ethernet_core`
851892

852893
- :dokuwiki:`[Wiki] Generic JESD204B block designs <resources/fpga/docs/hdl/generic_jesd_bds>`
853894
- :ref:`jesd204`

0 commit comments

Comments
 (0)