Merge branch 'develop'

Author: lleon95

README.md

@@ -45,6 +45,7 @@ outbuf = allocate(shape=(output_elements,), dtype=np.uint16)
 # Run
 dma.sendchannel.transfer(inbuf)
 accel.write(accel.register_map.CTRL.address, 0x81)
+accel.write(accel.register_map.n_elements.address, input_elements)
 dma.recvchannel.transfer(outbuf)
 dma.recvchannel.wait()
 
@@ -53,7 +54,7 @@ del input_hw
 del output_hw
 ```
 
-With CYNQ:
+With CYNQ for Xilinx Ultrascale+:
 
 ```c++
 #include <cynq/cynq.hpp>
@@ -62,7 +63,7 @@ using namespace cynq;
 
 // Configure the FPGA
 auto kArch = HardwareArchitecture::UltraScale;
-auto platform = IHardware::Create(kArch, "design.bit", "default.xclbin");
+auto platform = IHardware::Create(kArch, "design.bit");
 
 // Extract the accelerator (IP Core) and DMA
 // Addresses are given by the design
@@ -72,17 +73,57 @@ auto accel = platform->GetAccelerator(accel_addr);
 auto dma = platform->GetDataMover(dma_addr);
 
 // Allocate buffers and get the pointers
-auto inbuf = mover->GetBuffer(input_size);
-auto outbuf = mover->GetBuffer(output_size);
+auto inbuf = mover->GetBuffer(input_size, accel->GetMemoryBank(0));
+auto outbuf = mover->GetBuffer(output_size, accel->GetMemoryBank(1));
 uint16_t* input_ptr = inbuf->HostAddress<uint16_t>().get();
 uint16_t* output_ptr = outbuf->HostAddress<uint16_t>().get();
 
+// Configure data - Bus: AXI4 Stream is handled by DMA
+uint32_t num_elements = 4096;
+const uint64_t addr_num_elements = 0x20;
+accel->Attach(addr_num_elements, &num_elements, RegisterAccess::RO);
+
 // Run
+mover->Upload(in_mem, infbuf->Size(), 0, ExecutionType::Async);
 accel->Start(StartMode::Continuous);
-inbuf->Sync(SyncType::HostToDevice);
-mover->Upload(in_mem, infbuf->Size(), 0, ExecutionType::Sync);
 mover->Download(out_mem, outbuf->Size(), 0, ExecutionType::Sync);
-outbuf->Sync(SyncType::DeviceToHost);
+accel->Stop();
+
+// Dispose? We use RAII
+```
+
+With CYNQ for Alveo
+
+```c++
+#include <cynq/cynq.hpp>
+
+using namespace cynq;
+
+// Configure the FPGA
+auto kArch = HardwareArchitecture::Alveo;
+auto platform = IHardware::Create(kArch, "design.xclbin");
+
+// Extract the accelerator (IP Core) and DMA
+// Addresses are given by the design
+auto accel = platform->GetAccelerator("vadd");
+auto dma = platform->GetDataMover(0);
+
+// Allocate buffers and get the pointers
+auto inbuf = mover->GetBuffer(input_size, accel->GetMemoryBank(0));
+auto outbuf = mover->GetBuffer(output_size, accel->GetMemoryBank(1));
+uint16_t* input_ptr = inbuf->HostAddress<uint16_t>().get();
+uint16_t* output_ptr = outbuf->HostAddress<uint16_t>().get();
+
+// Configure the accel - memory mapped
+const uint32_t num_elements = 4096;
+accel->Attach(0, bo_0);
+accel->Attach(1, bo_1);
+accel->Attach(2, &num_elements, RegisterAccess::RO);
+
+// Run
+mover->Upload(in_mem, infbuf->Size(), 0, ExecutionType::Async);
+accel->Start(StartMode::Once);
+mover->Download(out_mem, outbuf->Size(), 0, ExecutionType::Sync);
 
 // Dispose? We use RAII
 ```
@@ -92,6 +133,7 @@ outbuf->Sync(SyncType::DeviceToHost);
 So far, we have tested CYNQ on:
 
 1. Xilinx KV26-based with Ubuntu 2022.04
+2. Xilinx Alveo U250 (it should be compatible with other similar Alveo cards) - Shell: xilinx_u250_gen3x16_xdma_4_1_202210_1
 
 ## Links & References:
 
@@ -106,8 +148,8 @@ Cite Us:
               AND Ávila-Torres, Diego
               AND Castro-Godínez, Jorge
             }},
-  title = {{CYNQ (v0.1)}},
-  year  = {2023},
+  title = {{CYNQ (v0.2)}},
+  year  = {2024},
   url   = {https://github.com/ECASLab/cynq},
 } 
 ```

docs/About.md

@@ -19,3 +19,10 @@ The current maintainers are:
 
 * Luis G. Leon Vega <[email protected]>
 * Diego Avila Torres <[email protected]>
+
+## Acknowledgements
+
+Thanks to
+
+* AMD HACC programme (ETH Zürich cluster) since it made possible to add the Alveo card support.
+* RidgeRun LLC for facilitating access to a Xilinx Kria KV260 since it made possible to add K26 support.

docs/ClassDiagram.md

@@ -3,10 +3,11 @@
 @startuml
 interface IHardware {
   +{abstract} Reset() -> Status
-  +{abstract} GetDataMover(address) -> IDataMover *
-  +{abstract} GetAccelerator(address) -> IAccelerator *
+  +{abstract} GetDataMover(address = 0) -> IDataMover *
+  +{abstract} GetAccelerator(address: uint64) -> IAccelerator *
+  +{abstract} GetAccelerator(address: string) -> IAccelerator *
   +{static} Create(hw: HardwareArchitecture, bitstream: string, xclbin: string) -> IHardware*
-
+  +{static} Create(hw: HardwareArchitecture, config: string) -> IHardware*
 }
 
 interface IMemory {
@@ -30,12 +31,16 @@ IMemoryType ..o IMemory
 interface IAccelerator {
   {abstract} Start(mode: StartMode) -> Status
   {abstract} Stop() -> Status
+  {abstract} Sync() -> Status
   {abstract} #WriteRegister(address, data: uint8_t*, size: size_t) -> Status
   {abstract} #ReadRegister(address, data: uint8_t*, size: size_t) -> Status
   +Write<T>(address, data: T*, elems: size_t) -> Status
   +Read<T>(address, data: T*, elems: size_t) -> Status
+  +Attach<T>(address, data: T*, elems: size_t) -> Status
+  +Attach(address, mem: std::shared_ptr<IMemory>, elems: size_t) -> Status
   {abstract} GetStatus() -> DeviceStatus
   +{static} Create(impl: IAcceleratorType, addr: uint64) -> IAccelerator*
+  +{static} Create(impl: IAcceleratorType, addr: string) -> IAccelerator*
 }
 
 enum IAcceleratorType {
@@ -100,14 +105,27 @@ enum ExecutionType {
   Async
 }
 
+enum DataMoverType {
+  Stream,
+  MemoryMapped
+}
+
 
 class UltraScale {
   +Reset() -> Status
-  +GetDataMover(address) -> XRTDataMover *
-  +GetAccelerator(address) -> AmdAccelerator *
+  +GetDataMover(address, type : DataMoverType) -> DMADataMover *
+  +GetAccelerator(address: uint64) -> MMIOAccelerator *
   +UltraScale(hw, bitsteam, xclbin)
 }
 
+class Alveo {
+  +Reset() -> Status
+  +GetDataMover(address, type : DataMoverType) -> XRTtDataMover *
+  +GetAccelerator(address: string) -> XRTAccelerator *
+  +UltraScale(hw, bitsteam, xclbin)
+}
+
+
 class XRTMemory {
   #GetHostAddress() -> uint8_t *
   #GetDeviceAddress() -> uint8_t *
@@ -116,13 +134,33 @@ class XRTMemory {
   +XRTMemory(hostptr, devptr)
 }
 
-class XRTAccelerator {
+class MMIOAccelerator {
   Start(mode: StartMode) -> Status
   Stop() -> Status
+  Sync() -> Status
   GetStatus() -> DeviceStatus
   #WriteRegister(address, data: uint8_t*, size: size_t) -> Status
   #ReadRegister(address, data: uint8_t*, size: size_t) -> Status
-  +AmdAccelerator(addr: uint64)
+  +MMIOAccelerator(addr: uint64)
+}
+
+
+class XRTAccelerator {
+  Start(mode: StartMode) -> Status
+  Stop() -> Status
+  Sync() -> Status
+  GetStatus() -> DeviceStatus
+  #SetArgument(position, data: T*) -> Status
+  +XRTAccelerator(name: string)
+}
+
+class DMADataMover {
+  GetBuffer(size: size_t, type: MemoryType) -> XRTMemory *
+  Upload(mem: IMemory, size: size_t, exetype: ExecutionType) -> Status
+  Download(mem: IMemory, size: size_t, exetype: ExecutionType) -> Status
+  Sync() -> Status
+  GetStatus() -> DeviceStatus
+  DMADataMover(addr)
 }
 
 class XRTDataMover {
@@ -131,11 +169,14 @@ class XRTDataMover {
   Download(mem: IMemory, size: size_t, exetype: ExecutionType) -> Status
   Sync() -> Status
   GetStatus() -> DeviceStatus
-  XRTDataMover(addr)
+  XrtDataMover(mem_bank)
 }
 
 UltraScale ..> IHardware
+Alveo ..> IHardware
 XRTMemory ..> IMemory
+MMIOAccelerator ..> IAccelerator
 XRTAccelerator ..> IAccelerator
+DMADataMover ..> IDataMover
 XRTDataMover ..> IDataMover
 @enduml