Generic Design (#47)

.github/workflows/rust.yml

@@ -0,0 +1,24 @@
+name: Rust
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Run lint
+      run: cargo fmt --check
+    - name: Run clippy lint
+      run: cargo clippy --all-targets --all-features
+    - name: Build
+      run: cargo build --verbose

.gitignore

@@ -0,0 +1,15 @@
+*DS_STORE*
+*DS_Store*
+.vscode/
+/.idea
+target
+cmake-build-debug
+build
+Cargo.lock
+
+## misc 
+Cargo.lock
+*DS_STORE*
+*DS_Store*
+*.csv
+.env

Cargo.toml

@@ -0,0 +1,37 @@
+[package]
+name = "ingo-fpga"
+version = "0.1.0"
+edition = "2021"
+# build = false
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+libc = "0.2.126"
+ark-algebra-intro = "0.3.0"
+ark-ec = "0.3.0"
+ark-std = "0.3.0"
+ark-ff = "0.3.0"
+ark-bls12-377 = "0.3.0"
+ark-bn254 = "0.3.0"
+ark-bls12-381 = "0.3.0"
+env_logger = "0.10.0"
+log = "0.4.0"
+packed_struct = "0.10"
+anyhow = "1.0.68"
+csv = "1.1"
+serde = { version = "1", features = ["derive"] }
+num = "0.4"
+strum = "0.24"
+strum_macros = "0.24"
+rand = "0.8.5"
+criterion = "0.4.0"
+lazy_static = "1.4.0"
+bindgen = "0.64.0"
+dotenv = "0.15.0"
+rayon = "1.6.1"
+serde_json = { version = "1.0" }
+serde-hex = "0.1.0"
+thiserror = "1.0"
+num-bigint = "0.4"
+num-traits = "0.2.15"

README.md

@@ -0,0 +1,138 @@
+# Read/Write to Device in Rust
+
+**Disclaimer:** This release is aimed at extending the design and handling of HW, this design isn’t backward compatible with previous and F1 support is currently broken, will be fixed in short time.
+:fire: More Ingonyama AWS F1 AFIs will be public soon, stay tuned!
+
+This Rust package offers a basic AXI infrastructure and the ability to work with user logic through custom modules.
+The custom modules provided are designed for [MSM](src/ingo_msm) and [Poseidon hash](src/ingo_hash) and allow for the loading of user logic onto an FPGA.
+
+In addition to supporting our binary, this library allows work with custom builds using warpshell https://github.com/Quarky93/warpshell.
+
+## New Design
+
+The new design is based on the idea of how a pool connection works with a database. Accordingly, this level includes interaction with a specific connection, and all things concerning connection selection, multiple connections, as well as state machines should be performed by a management layer.
+
+On the connection side, we can provide an API to retrieve any necessary data (including firewall status, current task number, etc.) for management. The main design components are described below.
+
+### DriverClient
+
+The [DriverClient](src/driver_client/) module is designed to establish a connection between the FPGA/AWS and a known type of card, such as the C1100 card. It does not possess any knowledge about primitives.
+
+The [DriverClient](src/driver_client/) provides basic IO methods and can load a binary, as well as provide specific and debug information about current HW. For a specific card type, the [DriverConfig](src/driver_client/dclient.rs) remains the same and can be accessed using the `driver_client_c1100_cfg` function.
+
+It is important to note that the high-level management layer determines which client and primitive should be used. The [DriverClient](src/driver_client/) can be overused in this process.
+
+How to create a new connection:
+
+```rust
+let dclient = DriverClient::new(&id, DriverConfig::driver_client_c1100_cfg());
+```
+
+### DriverPrimitive
+
+To simplify the process of using different primitives, the [DriverPrimitiveClient](src/driver_client/) was created. It is a wrapper around a [DriverClient](src/driver_client/) connection and includes the necessary configuration data for the primitive, an implementation of a common trait called [DriverPrimitiveClient](src/driver_client/), and public and private methods that are only valid for that primitive.
+
+The configuration (e.g. for msm there are addresses space and curve description) for each primitive is provided based on the type of primitive, so there is no need to configure this manually on the high-level manager layer.
+
+To create a new primitive instance for MSM, for example, one would use the following code:
+
+```rust
+let dclient = DriverClient::new(&id, DriverConfig::driver_client_c1100_cfg());
+let driver = msm_api::MSMClient::new(
+ msm_api::MSMInit {
+ mem_type: msm_api::PointMemoryType::DMA,
+ is_precompute: false,
+ curve: msm_api::Curve::BLS381,
+ },
+ dclient,
+);
+```
+
+The [DriverPrimitiveClient](src/driver_client/) is a trait that includes the basic functions of interaction with HW regarding calculations on a particular primitive. It can work with any type of data, whether it is a basic type or a tuple. The trait includes functions for initialization, setting input data, waiting for results, and getting results.
+
+For data encapsulation, methods specific to each primitive can be divided into public (mainly methods for retrieving data from a particular offset) and private (methods for recording data or retrieving specific data for internal calculations).
+
+### General Example of usage
+
+We will refer to any type of primitive as `DriverPrimitiveClient` to show generality. And any abbreviation for a specific primitive will be replaced by `dpc` (e.g. `dpc_api` can be `msm_api` )
+
+```rust
+ let dclient = DriverClient::new(&id, DriverConfig::driver_client_c1100_cfg());
+ let driver = dpc_api:: DriverPrimitiveClient::new(dpc_api::dpc_type, dclient);
+
+ let params = driver.get_loaded_binary_parameters();
+ let params_parse = dpc_api::DPCImageParametrs::parse_image_params(params[1]);
+
+ let _ = driver.initialize(dpc_param);
+ let _ = driver.set_data(dpc_input);
+ driver.wait_result();
+ let dpc_res = driver.result(None).unwrap().unwrap();
+```
+
+## MSM (Multi Scalar Multiplication) Module
+
+This module supports three curves (BLS12_377, BLS12_381, BN254) and two types of point storage on HW: DMA and HBM.
+
+This function sets data for compute MSM and has three different cases depending on the input parameters.
+
+1. DMA only mode: - Addres for point in [`MSMConfig`].
+
+```rust
+MSMInput = {
+    points: Some(points),
+    scalars,
+    nof_elements: msm_size,
+    hbm_point_addr: None,
+}
+```
+
+2. HBM mode set points to HBM and scalars by DMA: points will be loaded on hbm at address `hbm_addr` with an `offset`.
+
+```rust
+MSMInput = {
+    points: Some(points),
+    scalars,
+    nof_elements: msm_size,
+    hbm_point_addr: Some(hbm_addr, offset),
+}
+```
+
+3. HBM mode set only scalars: points were loaded in previous iteretion on HBM.
+
+```rust
+MSMInput = {
+    points: None,
+    scalars,
+    nof_elements: msm_size,
+    hbm_point_addr: Some(hbm_addr, offset),
+}
+```
+
+## Poseidon Module
+
+## Running tests and benchmark
+
+### MSM (Multi Scalar Multiplication) tests
+
+To run tests for the MSM primitive, use the following command:
+
+```
+
+RUST_LOG=<LEVEL_LOG> cargo test -- <TEST_FILE> -- <TEST_NAME>
+
+```
+
+Also, different tests can require additional parameters:
+`ID` `FILENAME`, and `MSM_SIZE`.
+
+Replace `<LEVEL_LOG>` with the desired log level (e.g. info, debug). Set `FILENAME` with the path to the binary
+file and `ID` with the number of the FPGA slot.
+Also, it's possible to set up a number of points in MSM in the `MSM_SIZE` variable.
+
+If the values of `ID` and `MSM_SIZE` are not provided, they will be defaulted to `ID=0` and `MSM_SIZE=8192`.
+
+### Poseidon tests
+
+```
+
+```

configs/c1100_cfg.json

@@ -0,0 +1,12 @@
+{
+    "ctrl_baseaddr": "0x00000000",
+    "ctrl_cms_baseaddr": "0x04000000",
+    "ctrl_qspi_baseaddr": "0x04040000",
+    "ctrl_hbicap_baseaddr": "0x04050000",
+    "ctrl_mgmt_ram_baseaddr": "0x04060000",
+    "ctrl_firewall_baseaddr": "0x04070000",
+    "dma_firewall_baseaddr": "0x04080000",
+    "ctrl_dfx_decoupler_baseaddr": "0x04090000",
+    "dma_baseaddr": "0x0000000000000000",
+    "dma_hbicap_baseaddr": "0x1000000000000000"
+}

configs/msm_bls377_dma_cfg.json

@@ -0,0 +1,7 @@
+{
+    "result_point_size": 144,
+    "point_size": 96,
+    "scalar_size": 32,
+    "dma_scalars_addr": "0x0000020000000000",
+    "dma_points_addr": "0x0000010000000000"
+}

configs/msm_bls377_hbm_cfg.json

@@ -0,0 +1,6 @@
+{
+    "result_point_size": 144,
+    "point_size": 96,
+    "scalar_size": 32,
+    "dma_scalars_addr": "0x0000020000000000"
+}

configs/msm_bls381_dma_cfg.json

@@ -0,0 +1,7 @@
+{
+    "result_point_size": 144,
+    "point_size": 96,
+    "scalar_size": 32,
+    "dma_scalars_addr": "0x0000020000000000",
+    "dma_points_addr": "0x0000010000000000"
+}

configs/msm_bls381_hbm_cfg.json

@@ -0,0 +1,6 @@
+{
+    "result_point_size": 144,
+    "point_size": 96,
+    "scalar_size": 32,
+    "dma_scalars_addr": "0x0000020000000000"
+}

configs/msm_bn254_dma_cfg.json

@@ -0,0 +1,7 @@
+{
+    "result_point_size": 96,
+    "point_size": 64,
+    "scalar_size": 32,
+    "dma_scalars_addr": "0x0000010000000000",
+    "dma_points_addr": "0x0000000000000000"
+}