Update PG344_important_design_considerations.rst

pciedebug/source/docs/QDMA_Subsystem_for_PCIExpress_IP_Driver/PG344_important_design_considerations.rst

@@ -59,3 +59,111 @@ Important Design Considerations from PG344
    **Link**: `Interrupt Module <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Interrupt-Module>`_
 
    - Queue-based interrupts and user interrupts are allowed on PFs and VFs, but error interrupts are allowed only on PFs.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `General Design of Queues <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/General-Design-of-Queues>`_
+
+   - PIDX update should never be equal to CIDX. For this case, if CIDX is 0, the maximum PIDX update would be 6.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `QDMA Subsystem Limitations <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/QDMA-Subsystem-Limitations>`_
+
+   - Use AXI SmartConnect to support Narrow Burst.
+   - ECC and Slave Narrow Burst support is mutually exclusive.
+   - If you want an ECC feature, the recommendation is to up-size your AXI Master externally.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Performance and Resource Utilization <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Performance-and-Resource-Utilization?tocId=6QfBEhQFba9swgGuwrX89A>`_
+
+   - Following are the QDMA register settings recommended by AMD for better performance. Performance numbers can vary based on systems and OS used.
+   - AMD recommends that you limit the total outstanding descriptor fetch to be less than 8 KB on the PCIe. For example, limit the outstanding credits across all queues to 512 for a 16B descriptor.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Descriptor Context <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Descriptor-Context>`_
+
+   - After the queue is enabled, the software context should only be updated through the direct mapped address space to update the Producer Index and Interrupt Arm® bit, unless the queue is being disabled.
+   - The hardware context and credit context contain only status. It is only necessary to interact with the hardware and credit contexts as part of queue initialization to clear them to all zeros.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Software Descriptor Context Structure 0x0-C2H and 0x1-H2C <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Software-Descriptor-Context-Structure-0x0-C2H-and-0x1-H2C>`_
+
+   - If bypass mode is not enabled, 32B is required for Memory Mapped DMA, 16B is required for H2C Stream DMA, and 8B is required for C2H Stream DMA.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Credit Descriptor Context Structure <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Credit-Descriptor-Context-Structure>`_
+
+   - The credit descriptor context is for internal DMA use only and it can be read from the indirect bus for debug.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Descriptor Fetch <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Descriptor-Fetch>`_
+
+   - If fetch crediting is enabled, the user logic is required to provide a credit for each descriptor that should be fetched.
+   - If queue size is 8, which contains the entry index 0 to 7, the last entry (index 7) is reserved for status. This index should never be used for the PIDX update, and the PIDX update should never be equal to CIDX. For this case, if CIDX is 0, the maximum PIDX update would be 6.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Internal Mode Writeback and Interrupts AXI-MM and H2C-ST <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Internal-Mode-Writeback-and-Interrupts-AXI-MM-and-H2C-ST>`_
+
+   - It is recommended the wbi_chk bit be set for all internal mode operation, including when interval mode is enabled.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Descriptor Bypass Mode <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Descriptor-Bypass-Mode?tocId=OnYtjyqAgfk9Lr7lh5_z4w>`_
+
+   - To perform DMA operations, the user logic drives descriptors (must be QDMA format) into the descriptor bypass input interface.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Descriptor Bypass Mode Writeback/Interrupts <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Descriptor-Bypass-Mode-Writeback/Interrupts>`_
+
+   - Once a descriptor with the sdi bit is sent, another irq_arm assertion must be observed before another descriptor with the sdi bit can be sent.
+   - If you set the sdi bit when the arm bit is not properly observed, an interrupt might or might not be sent, and software might hang indefinitely waiting for an interrupt.
+   - When interrupts are not enabled, setting the sdi bit has no restriction. However, excessive writeback events can severely reduce the descriptor engine performance and consume write bandwidth to the host.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Traffic Manager Output Interface <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Traffic-Manager-Output-Interface>`_
+
+   - While the tm_dsc_sts interface is a valid/ready interface, it should not be back-pressured for optimal performance. Since multiple events trigger a tm_dsc_sts cycle, if internal buffering is filled, descriptor fetching will be halted to prevent generation of new events.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Errors <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Errors?tocId=tsnP~q1s6VOFgCB4k~4Hlw>`_
+
+   - After the queue is invalidated, if there is an error you can determine the cause by reading the error registers and context for that queue. You must clear and remove that queue, and then add the queue back later when needed.
+   - If the descriptor fetch itself encounters an error, the descriptor will be marked with an error bit. If the error bit is set, the contents of the descriptor should be considered invalid.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Memory Mapped DMA <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Memory-Mapped-DMA>`_
+
+   - PCIe-to-PCIe, and AXI MM-to-AXI MM DMAs are not supported.
+
+.. note::
+   :class: highlight-box
+
+   **Link**: `Operation <https://docs.amd.com/r/en-US/pg344-pcie-dma-versal/Operation>`_
+
+   - Any descriptors that have already started the source buffer fetch will continue to be processed. Reassertion of the run bit will result in resetting internal engine state and should only be done when the engine is quiesced.
+   - Once sufficient read completion data is received, the write request will be issued to the destination interface in the same order that the read data was requested. Before the request is retired, the destination interfaces must accept all the write data and provide a completion response.
+