Xilinx qdma

一、开源代码及文档

        xilinx qdma代码链接 qdma.h

        文档链接 xilinx文档说明

二、关于文档和代码的理解

1.队列总体设计（general design of queues)

1.文档原文

        1.H2C and C2H are always written by the driver/software; hardware always reads from these queues. H2C carries the descriptors for the DMA read operations from Host. C2H carries the descriptors for the DMA write operations to the Host.

        2.In internal mode, H2C descriptors carry address and length information and are called gather descriptors. They support 32 bits of metadata that can be passed from software to hardware along with every descriptor. The descriptor can be memory mapped (where it carries host address, card address, and length of DMA transfer) or streaming (only host address, and length of DMA transfer) based on context settings. Through descriptor bypass, an arbitrary descriptor format can be defined, where software can pass immediate data and/or additional metadata along with packet.

        3.The software advertises valid descriptors for H2C and C2H queues by writing its producer index (PIDX) to the hardware. The status descriptor is the last entry of the descriptor ring, except for a C2H stream ring. The status descriptor carries the consumer index (CIDX) of the hardware so that the driver knows when to reclaim the descriptor and deallocate the buffers in the host.

        4.For the C2H stream mode, C2H descriptors will be reclaimed based on the CMPT queue entry.Typically, this carries one entry per C2H packet, indicating one or more C2H descriptors is consumed. The CMPT queue entry carries enough information for software to claim all the descriptors consumed. Through external logic, this can be extended to carry other kinds of completions or information to the host.CMPT entries written by the hardware to the ring can be detected by the driver using either the color bit in the descriptor or the status descriptor at the end of the CMPT ring. Each CMPT entry can carry metadata for a C2H stream packet and can also serve as a custom completion or immediate notification for the user application.      

        5.  The base address of all ring buffers (H2C, C2H, and CMPT) should be aligned to a 4 KB address.

        6.The software can program 16 different ring sizes. The ring size for each queue can be selected from context programing. The last queue entry is the descriptor status, and the number of allowable entries is (queue size -1)。

        For example, 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 PIDX update, and PIDX update should never be equal to CIDX. For this case, if CIDX is 0, the maximum PIDX update would be 6.

        In the example above, if traffic has already started and the CIDX is 4, the maximum PIDX update is 3.

2.翻译和个人理解

        1.H2C 和 C2H 一定是 driver/software这边写的，hardward 总是去queue里面读这些内容。H2C carries 的 descriptors 是 DMA 从 host 这边 read 的descriptors； C2H carries 的 descriptors 是 DMA 往 host 这边 write 的 descriptors。

        2.在 internal mode下，H2C descriptor 携带的是 address and length information，支持32 bit 的数据 ; 通过bypass,可以定义任意的描述符格式，软件可以将即时数据和/或附加元数据与数据包一起传递。 可以这么认为： descriptor 携带的信息 =  address information + length information + 元数据（metadata)。

        3. data 和 descriptor 都是通过 queue 来发送的，当 host 从internet 中接收一个数据包（data）后，会把 data 放入内存当中，然后会在descriptor ring 中添加一个新的描述符来描述这个data 的地址等信息, 然后 software 会向 hardware 中 wirte 新的 PIDX 以告诉 hardware 描述符环中有效的描述符又增加了，其实 PIDX 就相当于一个计数器，来计算 descriptor ring 中有效 descriptor 的数量，PIDX(copy)是在hardware这边。CIDX 是在descriptor ring 的最后一个 descriptor 即 status_descriptor里面，它蕴含的是上一个已经被 hardware 读取的描述符信息，也就是说，hradware 每从host这边读取一个描述符，CIDX都要相应的增加，CIDX(copy)是在host这边。

        4. C2H stream 传输模式是 CMPT，在这个CMPT mode下，当DMA消耗一个或多个描述符后，就会往CMPT queue 中写入相应的完成条目。注意：描述符一定是主机产生的。

        5.每一个ring buffer都对齐一个 4 KB 的的地址。猜测应该就是 page_size。

        6. queue 也是一个 ring ，queue 有自己的 queue size , 即 queue 的 entry 数量，最后一个entry 索引对应 status descriptor，所以 PIDX 和 CIDX 只能更新到 index - 1。如果queue_size = 6, 可以这么理解 PIDX和CIDX最大能更新到6 ，同时，PIDX 不能 等于 CIDX。通过 PIDX 和 CIDX 的组合可以知道目前还有多少 descriptor 还没传递，比如CIDX = 3 ,PIDX 的index可以为 4 5 6 0 1 2 ，如果 PIDX =4 ，说明还有一个有效描述符没有读取。如果 PIDX = 2 ,说明还有6个描述符没有被读取。注意，这是一个环，是可以从6回到0的。

2.  H2C and C2H queues

1.文档原文

        1.H2C/C2H queues are rings located in host memory. For both type of queues, the producer is software and consumer is the descriptor engine. The software maintains producer index (PIDX) and a copy of hardware consumer index (HW CIDX) to avoid overwriting unread descriptors. The descriptor engine also maintains consumer index (CIDX) and a copy of SW PIDX, which is to make sure the engine does not read unwritten descriptors. The las