Update various documentation

rodfrazer-intel · rodfrazer-intel · commit e24513beef79 · 2024-08-01T00:33:14.000-04:00
Update the help text in the u-boot and Linux applications to clarify the
configuration clock frequency behavior in 6S speed grade devices.

Update the documentation pages to clarify the configuration clock
frequency behavior in 6S speed grade devices.

Add a description about the msgdma configuration that allows us to avoid
the AXI 4KB boundary crossing.

Refactor the documentation link descriptions on the index page.

Signed-off-by: Rod Frazer &lt;rod.frazer@intel.com&gt;
diff --git a/common_sw/linux_apps/linux_help_text.h b/common_sw/linux_apps/linux_help_text.h
@@ -37,7 +37,7 @@
 
 //------------------------------------------------------------------------------
 #define linux_z_menu_HELP_TEXT z_menu_HELP_TEXT \
-, "\n\n\
+"\n\n\
     The demo uses UIO drivers to map the HPS peripheral addresses that\n\
     it accesses."
 
diff --git a/common_sw/u-boot_standalone_apps/help_text.h b/common_sw/u-boot_standalone_apps/help_text.h
@@ -185,13 +185,14 @@ SOFTWARE DEMO OVERVIEW\n\
     the GPIN port.  By using the system counter in the processor, the\n\
     demo can calculate the frequency of the SDM configuration clock\n\
     provided to the FPGA core logic.\n\
-\n\
-    The SDM configuration clock should be 250MHz because our Quartus\n\
-    project defines the SDM OSC_CLK frequency so that the SDM can\n\
-    provide a precise frequency based on the external oscillator\n\
+","\n\
+    The SDM configuration clock should be 250MHz on 4S and 5S speed\n\
+    grade devices and 200MHz on 6S speed grade devices because our\n\
+    Quartus project defines the SDM OSC_CLK frequency so that the SDM\n\
+    can provide a precise frequency based on the external oscillator\n\
     frequency.  When the Quartus project does not define an SDM OSC_CLK\n\
     frequency, then the SDM uses an internal oscillator that will\n\
-    produce a clock rate of 190MHz to 230MHz into the FPGA core logic."
+    produce a clock rate of 160MHz to 230MHz into the FPGA core logic."
 
 //------------------------------------------------------------------------------
 #define y_menu_HELP_TEXT \
diff --git a/documentation/01_index.md b/documentation/01_index.md
@@ -111,29 +111,29 @@ Enter menu selection:
 
 ## Hardware demo documentation
 
-* [**Top-Level PD System**](02_top_pd_sys.md) - the top-level Platform Designer system that is used for the phase 1 bitstream image that configures the device at power-on or after device wipe
+* [**Top-Level PD System**](02_top_pd_sys.md) - top-level Platform Designer system documentation, describes the top-level system that is used for the phase 1 bitstream image that configures the device at power-on or after device wipe
 
-* [**menu-g on hw_hps_gp**](03_menu_g_hw_hps_gp.md) - hps_gp demo, describes the hardware project design and software demos that run with it
+* [**menu-g on hw_hps_gp**](03_menu_g_hw_hps_gp.md) - hps_gp interface demo documentation, describes the hardware project design and software demos that interact with the hps_gp interface which provides a 32-bit GPI/GPO interface between the HPS and FPGA logic
 
-* [**menu-i, menu-l on hw_f2h_irq**](04_menu_il_hw_f2h_irq.md) - f2h_irq demos, describes the hardware project design and software demos that run with it
+* [**menu-i, menu-l on hw_f2h_irq**](04_menu_il_hw_f2h_irq.md) - f2h_irq interface demo documentation, describes the hardware project design and software demos that interact with the f2h_irq interface which provides a 64-bit interrupt interface from the FPGA into the HPS
 
-* [**menu-z on hw_config_clk**](05_menu_z_hw_config_clk.md) - configuration clock demo, describes the hardware project design and software demos that run with it
+* [**menu-z on hw_config_clk**](05_menu_z_hw_config_clk.md) - configuration clock demo documentation, describes the hardware project design and software demos that measure the configuration clock frequency
 
-* [**menu-y on hw_h2f_user_clk**](06_menu_y_hw_h2f_user_clk.md) - H2F user clocks demo, describes the hardware project design and software demos that run with it
+* [**menu-y on hw_h2f_user_clk**](06_menu_y_hw_h2f_user_clk.md) - H2F user clocks demo documentation, describes the hardware project design and software demos that measure the H2F user clock frequencies
 
-* [**menu-x, menu-w on hw_lwh2f_bridge**](07_menu_xw_hw_lwh2f_bridge.md) - LWH2F bridge demos, describes the hardware project design and software demos that run with it
+* [**menu-x, menu-w on hw_lwh2f_bridge**](07_menu_xw_hw_lwh2f_bridge.md) - LWH2F bridge demo documentation, describes the hardware project design and software demos that interact through the memory mapped LWH2F bridge into the FPGA logic design
 
-* [**menu-t, menu-r on hw_h2f_bridge**](08_menu_tr_hw_h2f_bridge.md) - H2F bridge demos, describes the hardware project design and software demos that run with it
+* [**menu-t, menu-r on hw_h2f_bridge**](08_menu_tr_hw_h2f_bridge.md) - H2F bridge demo documentation, describes the hardware project design and software demos that interact through the memory mapped H2F bridge into the FPGA logic design
 
-* [**menu-p on hw_f2sdram_bridge**](09_menu_p_hw_f2sdram_bridge.md) - F2SDRAM bridge demo, describes the hardware project design and software demos that run with it
+* [**menu-p on hw_f2sdram_bridge**](09_menu_p_hw_f2sdram_bridge.md) - F2SDRAM bridge demo documentation, describes the hardware project design and software demos that interact through the memory mapped F2SDRAM bridge allowing FPGA logic to interact with HPS EMIF memory
 
-* [**menu-b on hw_f2h_bridge**](10_menu_b_hw_f2h_bridge.md) - F2H bridge demo, describes the hardware project design and software demos that run with it
+* [**menu-b on hw_f2h_bridge**](10_menu_b_hw_f2h_bridge.md) - F2H bridge demo documentation, describes the hardware project design and software demos that interacts through the memory mapped F2H bridge allowing FPGA logic to interact coherently with HPS EMIF memory
 
-* [**menu-k on hw_uart**](11_menu_k_hw_uart.md) - HPS UART demo, describes the hardware project design and software demos that run with it
+* [**menu-k on hw_uart**](11_menu_k_hw_uart.md) - HPS UART demo documentation, describes the hardware project design and software demos that interact through the HPS UART peripheral into FPGA logic
 
-* [**menu-f on hw_spi_bridge**](12_menu_f_hw_spi_bridge.md) - HPS SPI demo, describes the hardware project design and software demos that run with it
+* [**menu-f on hw_spi_bridge**](12_menu_f_hw_spi_bridge.md) - HPS SPI demo documentation, describes the hardware project design and software demos that interact through the HPS SPI perihperal into FPGA logic
 
-* [**menu-e on hw_i2c_bridge**](13_menu_e_hw_i2c_bridge.md) - HPS I2C demo, describes the hardware project design and software demos that run with it
+* [**menu-e on hw_i2c_bridge**](13_menu_e_hw_i2c_bridge.md) - HPS I2C demo documentation, describes the hardware project design and software demos that interact through the HPS I2C peripheral into FPGA logic
 
 ## Software-only demo documentation
 
@@ -143,4 +143,4 @@ Enter menu selection:
 
 * [Maintenance Menus](16_maintenance_menus.md) - general overview of maintenance menu operations
 
-* [**menu-j on hw_hps_jamb**](14_menu_j_hw_hps_jamb.md) - JTAG Avalon Master Bridge maintenance image, describes the hardware project design and the development and debugging techniques that can be used with it
+* [**menu-j on hw_hps_jamb**](14_menu_j_hw_hps_jamb.md) - JTAG Avalon Master Bridge maintenance image documentation, describes the hardware project design and the development and debugging techniques that can be used with it
diff --git a/documentation/05_menu_z_hw_config_clk.md b/documentation/05_menu_z_hw_config_clk.md
@@ -15,7 +15,7 @@ Linux software applications referenced from this document:
 
 ## Overview
 
-The menu-z demo demonstrates the functionality of the configuration clock that is supplied into the FPGA core logic from the SDM. The configuration clock is derived from the internal oscillator within the SDM unless the user specifies the expected frequency for an external clock provided into the SDM OSC_CLK input pin. When the user specifies an SDM OSC_CLK frequency, the configuration clock provided into the FPGA fabric on 4S and 5S speed grade devices will be 250MHz, otherwise the frequency will be ~190MHz-230MHz based on the imprecise frequency of the internal oscillator. The configuration clock frequency for the 4S and 5S speed grade devices is expected to be 250MHz when an SDM OSC_CLK frequency is specified. The configuration clock frequency for the 6S speed grade device is expected to be 200MHz when an SDM OSC_CLK frequency is specified.
+The menu-z demo demonstrates the functionality of the configuration clock that is supplied into the FPGA core logic from the SDM. The configuration clock is derived from the internal oscillator within the SDM unless the user specifies the expected frequency for an external clock provided into the SDM OSC_CLK input pin. When the user specifies an SDM OSC_CLK frequency, the configuration clock provided into the FPGA fabric on 4S and 5S speed grade devices will be 250MHz, otherwise the frequency will be ~160MHz-230MHz based on the imprecise frequency of the internal oscillator. The configuration clock frequency for the 4S and 5S speed grade devices is expected to be 250MHz when an SDM OSC_CLK frequency is specified. The configuration clock frequency for the 6S speed grade device is expected to be 200MHz when an SDM OSC_CLK frequency is specified.
 
 ## Hardware system
 
diff --git a/documentation/09_menu_p_hw_f2sdram_bridge.md b/documentation/09_menu_p_hw_f2sdram_bridge.md
@@ -35,6 +35,7 @@ Two additional components are visible in the f2sdram_bridge subsystem, a limiter
 | :---: |
 | ![hw_f2sdram_bridge_subsys.png](./images/captures/hw_f2sdram_bridge_subsys.png) |
 
+**NOTE:** the msgdma core has been configured in this demo to support a maximum transfer length of 4KB. This was specifically chosen to optimize around the AXI requirement that bursts must not cross a 4KB boundary. This allows our software demo to choose base addresses aligned to 4KB boundaries and burst as much data as desired knowing that the msgdma core will break up any bursts larger than 4KB into multiple maximum 4KB burst transactions. Also, since the f2sdram bridge and the msgdma are configured for 256-bit data width, we do not have to worry about exceeding the AXI4 burst limit of 256 words per transaction. A full 4KB burst at 256-bit width will only require 128-word bursts per transaction. If software wanted to begin a DMA transfer using this msgdma core configuration that begins at an unaligned base address, then it would need to compensate for this in the descriptor configuration to ensure that no burst transactions cross a 4KB boundary.
 
 ## Software demo - u-boot standalone - menu-p
 
diff --git a/documentation/10_menu_b_hw_f2h_bridge.md b/documentation/10_menu_b_hw_f2h_bridge.md
@@ -37,6 +37,7 @@ Two additional components are visible in the f2h_bridge subsystem, a limiter_rem
 | :---: |
 | ![hw_f2h_bridge_subsys.png](./images/captures/hw_f2h_bridge_subsys.png) |
 
+**NOTE:** the msgdma core has been configured in this demo to support a maximum transfer length of 4KB. This was specifically chosen to optimize around the AXI requirement that bursts must not cross a 4KB boundary. This allows our software demo to choose base addresses aligned to 4KB boundaries and burst as much data as desired knowing that the msgdma core will break up any bursts larger than 4KB into multiple maximum 4KB burst transactions. Also, since the f2h bridge and the msgdma are configured for 256-bit data width, we do not have to worry about exceeding the AXI4 burst limit of 256 words per transaction. A full 4KB burst at 256-bit width will only require 128-word bursts per transaction. If software wanted to begin a DMA transfer using this msgdma core configuration that begins at an unaligned base address, then it would need to compensate for this in the descriptor configuration to ensure that no burst transactions cross a 4KB boundary.
 
 ## Software demo - u-boot standalone - menu-b
 
