Add comments

4 files changed, 152 insertions, 13 deletions

diff --git a/README b/README
index 7e41793..70b462b 100644
--- a/README
+++ b/README
@@ -1 +1,4 @@
+
+
 # apt install ocl-icd-opencl-dev
+# apt install libgmp3-dev
diff --git a/source/universal.h b/source/universal.h
index 5de857f..fad2f66 100644
--- a/source/universal.h
+++ b/source/universal.h
@@ -1,9 +1,18 @@
-//
-//  library.h
-//  lib-gpu-verify
-//
-//  Created by Cedric Zwahlen on 07.01.2024.
-//
+/*
+ * universal.h
+ * This file is part of lib-gpu-verify.
+ *
+ * lib-gpu-verify is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * lib-gpu-verify is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ */
 
 #ifndef universal_h
 #define universal_h
@@ -12,14 +21,9 @@
 #include <time.h>
 #include <stdint.h>
 
-//#define GPUV_BIT_LENGTH 2048 // put in enum
 
 
 
-void gpuv_prepare_gcry(void);
-
-// new
-
 struct gpuv_public_key;
 
 struct gpuv_signature_message;
@@ -44,21 +48,151 @@ enum GPUV_BIT_LENGTH {
     
 };
 
+/**
+ * @brief Prepare gcry library.
+ *
+ * This function must be called at the beginning of the program, if at any point the CPU mode should be used.
+ * If your program already initialises gcry, calling this function is not necessary.
+ *
+ */
+void gpuv_prepare_gcry(void);
+
+/**
+ *
+ * @param arg1 pointer to arbitrary user data
+ * @param arg2 1 if all signatures are valid, 0 if at least one signature is false
+ * @param arg3 the time taken to verify the signatures
+ * @param arg4 the length of the res array
+ * @param arg5 a pointer to the result array. A bitmask containing the verification result for each signature. If a bit at position x is 1, signature x is valid, otherwise signature x is not valid.
+ *
+ * @return 0 on success. 1 on error.
+ */
+typedef void (*gpuv_cls)(void *cls, int valid, struct timespec time, unsigned long len, uint32_t *res);
+
+/**
+ * @brief Initialise a info struct.
+ *
+ * Provides an struct that contains information about the GPUs and capabilities of the system. If no GPU is available, NULL is returned.
+ *
+ * @param arg1 which kernel to use
+ * @param arg2 what length of RSA key
+ *
+ * @return An initialised info struct pointer
+ */
 struct gpuv_info * gpuv_init(enum GPUV_VARIANT variant, enum GPUV_BIT_LENGTH bit_length);
 
+/**
+ * @brief Initialise a batch struct.
+ *
+ * Prepares and allocates a batch struct, used to store references to public keys, signatures their corresponding messages.
+ *
+ * @return An initialised batch struct pointer
+ */
 struct gpuv_batch * gpuv_prepare_batch(void);
+
+/**
+ * @brief Add a single signature message pair to a batch.
+ *
+ * Add a signature message pair to a batch. The struct is copied, so it may be freed after adding it to the batch.
+ *
+ * @param arg1 the batch to which to add the pair
+ * @param arg2 the pair to add
+ *
+ * @return 0 on success. 1 on failure to allocate more storage.
+ */
 int gpuv_add_to_batch(struct gpuv_batch * batch, struct gpuv_signature_message * sigmem);
+
+/**
+ * @brief Initialise a signature message struct.
+ *
+ * Prepare and initialise a single signature message pair.
+ *
+ * @param arg1 the public key with which the signature should be associated.
+ *
+ * @return An initialised signature message struct pointer
+ */
 struct gpuv_signature_message * gpuv_prepare_sig_msg(struct gpuv_public_key *pubkey);
+
+/**
+ * @brief Add a signature to a signature message.
+ *
+ * Add a signature to a signature message structure. 
+ *
+ * @param arg1 the signature message structure pointer to add the signature to
+ * @param arg2 the length of the signature in words. For the Montgomery kernel and CPU, the word length is expected to be 64 bits, for the Regular kernel the word length is expected to be 32 bits.
+ * @param arg3 a pointer to the signature. The least significant word should the first word pointed to. Do not free it until gpuv_prepare is called.
+ *
+ */
 void gpuv_add_signature(struct gpuv_signature_message * sig_msg, unsigned long len, void *s);
+
+/**
+ * @brief Add a message to a signature message.
+ *
+ * Add a message to a signature message structure.
+ *
+ * @param arg1 the signature message structure pointer to add the message to
+ * @param arg2 the length of the message in words. For the Montgomery kernel and CPU, the word length is expected to be 64 bits, for the Regular kernel the word length is expected to be 32 bits.
+ * @param arg3 a pointer to the message. The least significant word should the first word pointed to. Do not free it until gpuv_prepare is called.
+ *
+ */
 void gpuv_add_message(struct gpuv_signature_message * sig_msg, unsigned long len, void *m);
+/**
+ * @brief Prepare a public key struct.
+ *
+ * Prepare and initialise a single public key struct.
+ *
+ * @param arg1 the public exponent
+ * @param arg2 the length of the modulus in words. For the Montgomery kernel and CPU, the word length is expected to be 64 bits, for the Regular kernel the word length is expected to be 32 bits.
+ * @param arg3 a pointer to the modulus. The least significant word should the first word pointed to. Do not free it until gpuv_prepare is called.
+ *
+ */
 struct gpuv_public_key * gpuv_prepare_pubkey(unsigned long e, unsigned long len_n, void *n);
-//gpuv_get_pubkey(MONTGOMERY, exp_buf[i], len, &n_buf[len * i]);
 
+/**
+ * @brief Free a batch struct.
+ *
+ * Freeing a batch also releases all associated public key structures.
+ *
+ */
 void gpuv_free_batch(struct gpuv_batch * batch);
+
+/**
+ * @brief Free a state struct.
+ *
+ */
 void gpuv_free_state(struct gpuv_state * state);
 
+/**
+ * @brief Prepare a state struct.
+ *
+ * Prepare and initialise a state object. When using the Montgomery Kernel, this function performs precalculations.
+ *
+ * @param arg1 a vaild state struct pointer
+ *
+ * @return An initialised state struct pointer
+ */
 struct gpuv_state * gpuv_prepare(struct gpuv_info *info, struct gpuv_batch * batch);
-int gpuv_start(struct gpuv_state *state, void (*cls)(void *, int, struct timespec, unsigned long, uint32_t *), void * arg, struct gpuv_batch *batch);
+
+/**
+ * @brief Verify the batch of signatures.
+ *
+ * Begin verifying the signatures in the batch. If calculations are to be performed on the GPU, this function returns immediately.
+ *
+ * @param arg1 a valid state containing the signatures to verify and a reference to an info structure
+ * @param arg2 a closure that is called once the kernel has processed the signatures in the batch
+ * @param arg3 a pointer to custom user data that is passed to cls.
+ * @param arg4 the batch to process.
+ *
+ * @return 0 on success. 1 on error.
+ */
+int gpuv_start(struct gpuv_state *state, gpuv_cls cls, void * arg, struct gpuv_batch *batch);
+
+/**
+ * @brief Free an info struct.
+ *
+ */
 void gpuv_finish(struct gpuv_info * info);
 
+
+
 #endif /* universal_h */
diff --git a/xcode/lib-gpu-verify.xcodeproj/project.pbxproj b/xcode/lib-gpu-verify.xcodeproj/project.pbxproj
index bd54dfb..10bee1f 100755
--- a/xcode/lib-gpu-verify.xcodeproj/project.pbxproj
+++ b/xcode/lib-gpu-verify.xcodeproj/project.pbxproj
@@ -51,6 +51,7 @@
 		6AC553242B2E174900046AB7 /* gpuv-montg.cl */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.opencl; path = "gpuv-montg.cl"; sourceTree = "<group>"; };
 		6AC553272B2E17C800046AB7 /* gpuv-montg.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; name = "gpuv-montg.h"; path = "../source/gpuv-montg.h"; sourceTree = "<group>"; };
 		6AC553282B2E17C800046AB7 /* gpuv-montg.c */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.c; name = "gpuv-montg.c"; path = "../source/gpuv-montg.c"; sourceTree = "<group>"; };
+		6AD715F92B5177AC0044FCB7 /* README */ = {isa = PBXFileReference; lastKnownFileType = text; name = README; path = ../README; sourceTree = "<group>"; };
 		6AF748792ADADEBD00D58E08 /* lib-gpu-verify.c */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.c; name = "lib-gpu-verify.c"; path = "../source/lib-gpu-verify.c"; sourceTree = "<group>"; };
 		C3770EFC0E6F1138009A5A77 /* OpenCL.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = OpenCL.framework; path = /System/Library/Frameworks/OpenCL.framework; sourceTree = "<absolute>"; };
 /* End PBXFileReference section */
@@ -122,6 +123,7 @@
 				6ABC2E832B231DFF00033B90 /* util.c */,
 				6AF748792ADADEBD00D58E08 /* lib-gpu-verify.c */,
 				6AC553282B2E17C800046AB7 /* gpuv-montg.c */,
+				6AD715F92B5177AC0044FCB7 /* README */,
 			);
 			name = Sources;
 			sourceTree = "<group>";
diff --git a/xcode/lib-gpu-verify.xcodeproj/project.xcworkspace/xcuserdata/cedriczwahlen.xcuserdatad/UserInterfaceState.xcuserstate b/xcode/lib-gpu-verify.xcodeproj/project.xcworkspace/xcuserdata/cedriczwahlen.xcuserdatad/UserInterfaceState.xcuserstate
index a90b230..225aaa5 100644
--- a/xcode/lib-gpu-verify.xcodeproj/project.xcworkspace/xcuserdata/cedriczwahlen.xcuserdatad/UserInterfaceState.xcuserstate
+++ b/xcode/lib-gpu-verify.xcodeproj/project.xcworkspace/xcuserdata/cedriczwahlen.xcuserdatad/UserInterfaceState.xcuserstate