updated docs

ingonyama-zk · Aug 29, 2024 · 7105132 · 7105132
1 parent fb772a4
commit 7105132
Show file tree

Hide file tree

Showing 9 changed files with 72 additions and 62 deletions.
diff --git a/.gitignore b/.gitignore
@@ -17,4 +17,5 @@
 **/Cargo.lock
 **/icicle/build/
 **/wrappers/rust/icicle-cuda-runtime/src/bindings.rs
-**/build/*
+**/build/*
+**tar.gz
diff --git a/docs/docs/icicle/benchmarks.md b/docs/docs/icicle/benchmarks.md
@@ -1,3 +1,3 @@
 # Benchmarks
 
-TODO explain which benchmarks exist, how to run them for a given device
+TODO
diff --git a/docs/docs/icicle/build_your_own_backend.md b/docs/docs/icicle/build_your_own_backend.md
@@ -1,3 +1,3 @@
 # Build Your Own Backend
 
-TODO explain with example how to build a backend for ICICLE V3
+TODO
diff --git a/docs/docs/icicle/faq_and_troubleshooting.md b/docs/docs/icicle/faq_and_troubleshooting.md
@@ -1,4 +1,4 @@
-# FAQ and troubleshooting (TODO)
+# FAQ and troubleshooting
 
 ## Frequently asked questions
 

diff --git a/docs/docs/icicle/install_and_use.md b/docs/docs/icicle/install_and_use.md
@@ -1,17 +1,27 @@
-# Install and use ICICLE
+# Getting started Guide
 
 ## Overview
 
-This page describes the content of a release and how to install and use it.
-Icicle binaries are released for multiple Linux distributions, including Ubuntu 20.04, Ubuntu 22.04, and CentOS 7.
+This guide explains how to start using ICICLE, including installation steps. The typical workflow for a user is:
+
+1. **Install ICICLE or build it from source**: This is explained in this guide. For building from source, refer to the [Build from Source page](./build_from_source.md).
+2. **Follow the [Programmer’s Guide](./programmers_guide/general.md)**: Learn how to use ICICLE APIs.  
+3. **Start using ICICLE APIs on your CPU**: Your application will now use ICICLE on the CPU.
+4. **Accelerate your application on a GPU**: [install the CUDA backend](./install_cuda_backend.md),  load it, and select it in your application ([C++](./programmers_guide/cpp.md#loading-a-backend),[Rust](./programmers_guide/rust.md#loading-a-backend), [Go](./programmers_guide/go.md#loading-a-backend)).
+5. **Run on the GPU**: Once the GPU backend is selected, all subsequent API calls will execute on the GPU.
+6. **Optimize for multi-GPU environments**: Refer to the [Multi-GPU](./multi-device.md) Guide to fully utilize your system’s capabilities.  
+7. **Review memory management**: Revisit the [Memory Management section](./programmers_guide/general.md#device-abstraction) to allocate memory on the device efficiently and try to keep data on the GPU as long as possible.  
+
+
+The rest of this page details the content of a release, how to install it, and how to use it. ICICLE binaries are released for multiple Linux distributions, including Ubuntu 20.04, Ubuntu 22.04, RHEL 8, and RHEL 9.
 
 :::note
-Future releases will also include MacOS and other systems.
+Future releases will also include support for macOS and other systems.
 :::
 
 ## Content of a Release
 
-Each Icicle release includes a tar file, named `icicle30-<distribution>.tar.gz`, where `icicle30` stands for version 3.0. This tar contains icicle-frontend build artifacts  and headers for a specific distribution. The tar file includes the following structure:
+Each ICICLE release includes a tar file named `icicle30-<distribution>.tar.gz`, where `icicle30` indicates version 3.0. This tar file contains ICICLE frontend build artifacts and headers for a specific distribution. The tar file structure includes:
 
 - **`./icicle/include/`**: This directory contains all the necessary header files for using the Icicle library from C++.
 - **`./icicle/lib/`**:
@@ -23,13 +33,13 @@ Each Icicle release includes a tar file, named `icicle30-<distribution>.tar.gz`,
 
 ## installing and using icicle
 
-- Full C++ example here: https://github.com/ingonyama-zk/icicle/tree/yshekel/V3_release_and_install/examples/c++/install-and-use-icicle
-- Full Rust example here: https://github.com/ingonyama-zk/icicle/tree/yshekel/V3_release_and_install/examples/rust/install-and-use-icicle
+- Full C++ example here: https://github.com/ingonyama-zk/icicle/tree/yshekel/V3/examples/c++/install-and-use-icicle
+- Full Rust example here: https://github.com/ingonyama-zk/icicle/tree/yshekel/V3/examples/rust/install-and-use-icicle
 
 (TODO update links to main branch when merged)
 
 1. **Extract and install the Tar Files**:
-   - Download (TODO link to latest release) the appropriate tar files for your distribution (Ubuntu 20.04, Ubuntu 22.04, or UBI 8,9 for RHEL compatible binaries).
+   - [Download](https://github.com/ingonyama-zk/icicle/releases) the appropriate tar files for your distribution (Ubuntu 20.04, Ubuntu 22.04, or UBI 8,9 for RHEL compatible binaries).
    - **Frontend libs and headers** should be installed in default search paths (such as `/usr/lib` and `usr/local/include`) for the compiler and linker to find.
    - **Backend libs** should be installed in `/opt`
    - Extract it to your desired location:
@@ -43,28 +53,28 @@ Each Icicle release includes a tar file, named `icicle30-<distribution>.tar.gz`,
      ```
 
     :::note
-    Installing the frontend is optional. Rust is not using it.
-    You may install to any directory but need to make sure it can be found by the linker at compile and runtime.
+    Installing the frontend is optional for Rust. Rust does not use it.    
     :::
 
     :::tip
-    You can install anywhere and use a link so that it can be easily found as if in the default directory.
+    You may install to any directory, but you need to ensure it can be found by the linker at compile and runtime.
+    You can install anywhere and use a symlink to ensure it can be easily found as if it were in the default directory.
     :::
 
-1. **Linking Your Application**:
+2. **Linking Your Application**:
 
-  Apps need to link to the ICICLE device library and to every field and/or curve libraries. The backend libraries are dynamically loaded at runtime, so not linking to them.
+  Applications need to link to the ICICLE device library and to every field and/or curve library. The backend libraries are dynamically loaded at runtime, so there is no need to link to them.
 
   **C++**
-   - When compiling your C++ application, link against the Icicle libraries:
+   - When compiling your C++ application, link against the ICICLE libraries:
      ```bash
      g++ -o myapp myapp.cpp -licicle_device -licicle_field_bn254 -licicle_curve_bn254
 
      # if not installed in standard dirs, for example /custom/path/, need to specify it
      g++ -o myapp myapp.cpp -I/custom/path/icicle/include -L/custom/path/icicle/lib -licicle_device -licicle_field_bn254 -licicle_curve_bn254 -Wl,-rpath,/custom/path/icicle/lib/
      ```
 
-  - Or via cmake
+   - Or via cmake
     ```cmake
     # Add the executable
     add_executable(example example.cpp)
@@ -87,35 +97,36 @@ Each Icicle release includes a tar file, named `icicle30-<distribution>.tar.gz`,
                           INSTALL_RPATH /custom/path/icicle/lib/)
     ```
 
-    :::tip
-    If you face linkage issues, try `ldd myapp` to see the runtime deps. If ICICLE libs are not found, you need to add the install directory to the search path of the linker. In a development env you can do that using the env variable `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/custom/path/icicle/lib` or similar (for non linux). For deployment, make sure it can be found and avoid `LD_LIBRARY_PATH`.
+  :::tip
+  If you face linkage issues, try ldd myapp to see the runtime dependencies. If ICICLE libs are not found, you need to add the install directory to the search path of the linker. In a development environment, you can do that using the environment variable export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/custom/path/icicle/lib or similar (for non-Linux). For deployment, make sure it can be found and avoid using LD_LIBRARY_PATH.
 
-    Alternatively you can embed the search path on the app as an `rpath` by adding `-Wl,-rpath,/custom/path/icicle/lib/`. This is what is demonstrated above.
-    :::
+  Alternatively, you can embed the search path in the app as an rpath by adding -Wl,-rpath,/custom/path/icicle/lib/. This is demonstrated above.
+  :::
 
   **Rust**
-     - When building the icicle crates, icicle frontend libs are built from source, in addition to the rust bindings. They are installed to `target/<buildtype>/deps/icile` and cargo will link correctly. Note that you still need to install CUDA backend if you have a CUDA GPU.
+     - When building the ICICLE crates, ICICLE frontend libs are built from source, along with the Rust bindings. They are installed to `target/<buildtype>/deps/icicle`, and Cargo will link them correctly. Note that you still need to install the CUDA backend if you have a CUDA GPU.
      - Simply use `cargo build` or `cargo run` and it should link to icicle libs.
 
   **Go** - TODO
 
-:::warning when deploying an application (either C++, Rust or Go), you must make sure to either deploy the icicle libs (that you download or build from source) along the application binaries (as tar, docker image, package manager installer or else) or make sure to install icicle (and the backend) on the target machine. Otherwise the target machine will have linkage issues.
+:::warning
+When deploying an application (whether in C++, Rust, or Go), you must make sure to either deploy the ICICLE libs (that you download or build from source) along with the application binaries (as tar, Docker image, package manager installer, or otherwise) or make sure to install ICICLE (and the backend) on the target machine. Otherwise, the target machine will have linkage issues.
 :::
 
 ## Backend Loading
 
-The Icicle library dynamically loads backend libraries at runtime. By default, it searches for backends in the following order:
+The ICICLE library dynamically loads backend libraries at runtime. By default, it searches for backends in the following order:
 
-1. **Environment Variable**: If the `ICICLE_BACKEND_INSTALL_DIR` environment variable is defined, Icicle will prioritize this location.
+1. **Environment Variable**: If the `ICICLE_BACKEND_INSTALL_DIR` environment variable is defined, ICICLE will prioritize this location.
 2. **Default Directory**: If the environment variable is not set, Icicle will search in the default directory `/opt/icicle/lib/backend`.
 
 :::warning
-If building ICICLE frontend from source, make sure to load a backend that is compatible to the frontend version. CUDA backend libs are forward compatible with newer frontends (e.g. CUDA-backend-3.0 works with ICICLE-3.2). The opposite is not guaranteed.
+If building ICICLE frontend from source, make sure to load a backend that is compatible with the frontend version. CUDA backend libs are forward compatible with newer frontends (e.g., CUDA-backend-3.0 works with ICICLE-3.2). The opposite is not guaranteed.
 :::
 
 If you install in a custom dir, make sure to set `ICICLE_BACKEND_INSTALL_DIR`:
 ```bash
-ICICLE_BACKEND_INSTALL_DIR=path/to/icicle/lib/backend/ myapp # for an executable maypp
+ICICLE_BACKEND_INSTALL_DIR=path/to/icicle/lib/backend/ myapp # for an executable myapp
 ICICLE_BACKEND_INSTALL_DIR=path/to/icicle/lib/backend/ cargo run # when using cargo
 ```
 

diff --git a/docs/docs/icicle/install_cuda_backend.md b/docs/docs/icicle/install_cuda_backend.md
@@ -19,16 +19,17 @@ The CUDA backend requires a valid license to function. There are two CUDA backen
 :::note
 As for now CUDA backend can be accessed without purchasing a license. Ingonyama is hosting a license server that will allow access to anyone.
 By default CUDA backend will try to access this server if no other license is available.
-TO manually specify it, set `export [email protected]`.
+To manually specify it, set `export [email protected]`.
 :::
 
 Licenses are available for purchase [here TODO](#) . After purchasing, you will receive a license key that must be installed on the license-server or node-locked machine.
 For license-server, you will have to tell the application that is using ICICLE, where the server is.
 
-**Specify the license server address:**
+**Specify the license server address or filepath:**
 
 ```
-export ICICLE_LICENSE=port@ip
+export ICICLE_LICENSE=port@ip # for license server
+export ICICLE_LICENSE=/path/to/license # for node locked license
 ```
 
 For further assist , contact our support team for assistance. `[email protected]` (TODO make sure this exists).
diff --git a/docs/docs/icicle/primitives/overview.md b/docs/docs/icicle/primitives/overview.md
@@ -8,7 +8,4 @@ This section of the documentation is dedicated to the main APIs provided by ICIC
 - [NTT](./ntt.md)
 - [Vector Operations](./vec_ops.md)
 - [Polynomials](../polynomials/overview.md)
-- [Keccak Hash](./keccak.md)
-- [Poseidon Hash](./poseidon.md)
-- [Poseidon2 Hash](./poseidon2.md)
-- [Merkle tree builder](./merkle.md)
+- Hashing and commitment schemes coming soon
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -25,7 +25,7 @@ module.exports = {
           items: [
             {
               type: "doc",
-              label: "CUDA Backend (TODO finalize)",
+              label: "CUDA Backend",
               id: "icicle/install_cuda_backend"
             },
             {
@@ -35,7 +35,7 @@ module.exports = {
             },
             {
               type: "doc",
-              label: "Build Your Own Backend (TODO)",
+              label: "Build Your Own Backend",
               id: "icicle/build_your_own_backend"
             },
           ]
@@ -116,21 +116,21 @@ module.exports = {
               label: "Polynomials",
               id: "icicle/polynomials/overview",
             },
-            {
-              type: "doc",
-              label: "Keccak Hash (TODO)",
-              id: "icicle/primitives/keccak",
-            },
-            {
-              type: "doc",
-              label: "Poseidon Hash (TODO)",
-              id: "icicle/primitives/poseidon",
-            },
-            {
-              type: "doc",
-              label: "Poseidon2 Hash (TODO)",
-              id: "icicle/primitives/poseidon2",
-            },
+            // {
+            //   type: "doc",
+            //   label: "Keccak Hash (TODO)",
+            //   id: "icicle/primitives/keccak",
+            // },
+            // {
+            //   type: "doc",
+            //   label: "Poseidon Hash (TODO)",
+            //   id: "icicle/primitives/poseidon",
+            // },
+            // {
+            //   type: "doc",
+            //   label: "Poseidon2 Hash (TODO)",
+            //   id: "icicle/primitives/poseidon2",
+            // },
             {
               type: "category",
               label: "Golang bindings (TODO)",
@@ -217,11 +217,11 @@ module.exports = {
                   label: "Polynomials",
                   id: "icicle/rust-bindings/polynomials",
                 },
-                {
-                  type: "doc",
-                  label: "Keccak Hash (TODO)",
-                  id: "icicle/rust-bindings/keccak",
-                },
+                // {
+                //   type: "doc",
+                //   label: "Keccak Hash (TODO)",
+                //   id: "icicle/rust-bindings/keccak",
+                // },
                 {
                   type: "doc",
                   label: "Multi GPU Support (TODO)",
@@ -238,12 +238,12 @@ module.exports = {
         },
         {
           type: "doc",
-          label: "Benchmarks (TODO)",
+          label: "Benchmarks",
           id: "icicle/benchmarks",
         },
         {
           type: "doc",
-          label: "FAQ and Troubleshooting (TODO)",
+          label: "FAQ and Troubleshooting",
           id: "icicle/faq_and_troubleshooting",
         },
         {

diff --git a/icicle/include/icicle/dispatcher.h b/icicle/include/icicle/dispatcher.h
@@ -117,7 +117,7 @@ class tIcicleObjectDispatcher
   using dispatcher_class_name = tIcicleObjectDispatcher<type, ST_name_##api_name>;                                     \
   void register_##api_name(const std::string& deviceType, std::shared_ptr<type> factory)                               \
   {                                                                                                                    \
-    ICICLE_LOG_DEBUG << " Registering API: device=" << deviceType << ", api=" << #api_name << "<"                      \
-                     << demangle<type> << ">";                                                                         \
+    ICICLE_LOG_VERBOSE << " Registering API: device=" << deviceType << ", api=" << #api_name << "<"                    \
+                       << demangle<type> << ">";                                                                       \
     dispatcher_class_name::Global()._register(deviceType, factory);                                                    \
   }