added comments and doxygen

plugins/netlist_modifier/include/netlist_modifier/ini_settings_popup.h

@@ -5,6 +5,11 @@
 #include <QRadioButton>
 #include <QSpinBox>
 
+/**
+ * @brief Header file for the pop up used to select the options for the ini file like probing type and probe limit
+ * 
+ */
+
 namespace hal
 {
     class IniSettingsPopup : public QDialog

plugins/netlist_modifier/include/netlist_modifier/netlist_modifier.h

@@ -5,6 +5,11 @@
 
 #define SECRET_PASSWORD "test12345"
 
+/**
+ * @brief Header file for the netlist modifier plugin. This plugin is used by the researcher to replace some gates with gates of an unknown type
+ * 
+ */
+
 namespace hal
 {
     extern Netlist* gNetlist;

plugins/netlist_modifier/src/encrypted_zip.cpp

@@ -6,10 +6,22 @@
 #include <fstream>
 #include <sstream>
 
+/**
+ * @brief This file contains the methods to encrypt the original netlist and the ini file into an encrypted zip archive
+ * 
+ */
+
 namespace hal
 {
+    /**
+     * @brief This function return a random alphanumerical string with a given length
+     * 
+     * @param len The length of the generated random string
+     * @return std::string The generated random string
+     */
     std::string gen_random_string(int len)
     {
+        // list of allowed symbols
         const std::string characters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
         std::string random_string;
         random_string.reserve(len);
@@ -24,11 +36,25 @@ namespace hal
         return random_string;
     }
 
+    /**
+     * @brief This function generates a salted password based on a given password and a salt.
+     * 
+     * @param password The initial password
+     * @param salt The salt that should be used for the salting process
+     * @return std::string The salted password
+     */
     std::string gen_salted_password(std::string password, std::string salt)
     {
         return password + salt;
     }
 
+    /**
+     * @brief This function creates the content of the ini file given the desired settings
+     * 
+     * @param probe_type The desired probe type. Currently this value can be 0 (scan chain probing) or 1 (t probing)
+     * @param probe_limit The desired maximum number of allowed probes
+     * @return std::string The generated content of the ini file
+     */
     std::string generate_ini_content(int probe_type, int probe_limit)
     {
         std::ostringstream ini_oss;
@@ -41,11 +67,23 @@ namespace hal
         return ini_oss.str();
     }
 
+    /**
+     * @brief Function to create the encrypted zip archive with a given password and settings like probe-type
+     * 
+     * @param password The password used for the encryption
+     * @param probe_type the probe type that should be stored in the ini file
+     * @param probe_limit the probe limit that should be stored in the ini file
+     * @param salt (optional) The salt used for encryption. If a empty string is provided as the salt a random one is generated
+     * @param existing_hal_file boolean whether or not a copy of the original unaltered hal file exists or if the current netlist needs to be saved
+     * @return bool returns true on success
+     */
     bool NetlistModifierPlugin::create_encrypted_zip(std::string password, int probe_type, int probe_limit, std::string salt, bool existing_hal_file)
     {
+        // get the path to the current project directory
         ProjectManager* pm = ProjectManager::instance();
         std::filesystem::path project_dir_path(pm->get_project_directory().string());
 
+        // generate salt if no salt is provided
         if (salt == "")
         {
             salt = gen_random_string(20);
@@ -85,6 +123,7 @@ namespace hal
             return false;
         }
 
+        // write the original netlist file to the zip archive. Use the salted password for encryption
         QFile netlist_file(QString::fromStdString(project_dir_path / "original/original.hal"));
         if (!netlist_file.open(QIODevice::ReadOnly))
         {
@@ -107,6 +146,7 @@ namespace hal
         // create tmp ini file
         std::string ini_content = generate_ini_content(probe_type, probe_limit);
 
+        // write the ini file to the zip archive. Use the salted password for encryption
         QuaZipFile ini_zip_outFile(&zip);
         if (!ini_zip_outFile.open(QIODevice::WriteOnly, QuaZipNewInfo("settings.ini"), salted_password.c_str()))
         {
@@ -116,13 +156,13 @@ namespace hal
         ini_zip_outFile.write(ini_content.c_str());
         ini_zip_outFile.close();
 
+        // write the used salt to the zip archive. Use the original unsalted password for enryption
         QuaZipFile salt_zip_outFile(&zip);
         if (!salt_zip_outFile.open(QIODevice::WriteOnly, QuaZipNewInfo("salt.encrypt"), password.c_str()))
         {
             log_error("File could not be added with encryption!");
             return false;
         }
-
         salt_zip_outFile.write(salt.c_str());
         salt_zip_outFile.close();
 
@@ -143,11 +183,21 @@ namespace hal
         return true;
     }
 
+    /**
+     * @brief This function updates an existing zip archive if just the settings of the ini got changed
+     * 
+     * @param password The password used for encrypting
+     * @param probe_type The probe type that should be stored in the ini file
+     * @param probe_limit the probe limit that should be stored in the ini file
+     * @return bool Returns true on success
+     */
     bool NetlistModifierPlugin::update_encrypted_zip(std::string password, int probe_type, int probe_limit)
     {
+        // get the path to the current project directory
         ProjectManager* pm = ProjectManager::instance();
         std::filesystem::path project_dir_path(pm->get_project_directory().string());
 
+        // open the existing zip archive
         QuaZip zip(QString::fromStdString(project_dir_path / "original/original.zip"));
 
         if (!zip.open(QuaZip::mdUnzip))
@@ -156,6 +206,7 @@ namespace hal
             return false;
         }
 
+        // retrieve the salt from the zip archive
         zip.setCurrentFile("salt.encrypt");
         QuaZipFile zipFile(&zip);
         if (!zipFile.open(QIODevice::ReadOnly, password.c_str()))
@@ -164,11 +215,13 @@ namespace hal
             return false;
         }
 
+        // generate the salted password that was used to encrypt the other files
         QByteArray salt_buffer      = zipFile.readAll();
         std::string salt            = std::string(salt_buffer.constData(), salt_buffer.size());
         std::string salted_password = gen_salted_password(password, salt);
         zipFile.close();
 
+        // retrieve the original netlist and write it to a tmp file
         zip.setCurrentFile("original.hal");
         if (!zipFile.open(QIODevice::ReadOnly, salted_password.c_str()))
         {
@@ -210,6 +263,7 @@ namespace hal
             return false;
         }
 
+        // create the new encrypted zip archive using the new settings
         return create_encrypted_zip(password, probe_type, probe_limit, salt, true);
     }
 }    // namespace hal

plugins/netlist_modifier/src/gui_extension.cpp

@@ -6,6 +6,15 @@ namespace hal
     {
     }
 
+    /**
+     * @brief This functions adds the item to the right click menu of the HAL GUI
+     * 
+     * @param nl 
+     * @param mods 
+     * @param gates 
+     * @param nets 
+     * @return std::vector<ContextMenuContribution> 
+     */
     std::vector<ContextMenuContribution>
         GuiExtensionNetlistModifier::get_context_contribution(const Netlist* nl, const std::vector<u32>& mods, const std::vector<u32>& gates, const std::vector<u32>& nets)
     {
@@ -16,6 +25,15 @@ namespace hal
         return additions;
     }
 
+    /**
+     * @brief This functions handles the event if the user selects the new right click menu entry
+     * 
+     * @param tag 
+     * @param nl 
+     * @param mods 
+     * @param gates 
+     * @param nets 
+     */
     void GuiExtensionNetlistModifier::execute_function(std::string tag, Netlist* nl, const std::vector<u32>& mods, const std::vector<u32>& gates, const std::vector<u32>& nets)
     {
         if (tag == "modify_in_place")

plugins/netlist_modifier/src/modify_gatelibrary.cpp

@@ -6,13 +6,24 @@
 #include <rapidjson/filewritestream.h>
 #include <rapidjson/writer.h>
 
+/**
+ * @brief This file contains the functionalities to generate the modified netlist with the obfuscated gate types
+ * 
+ */
+
 namespace hal
 {
     const char* OBFUSCATED   = "_obfuscated";
     const char* GATE_LIB_TAG = "gate_library";
 
+    /**
+     * @brief This function reads the current gate lib and adds for each input/output size of the contained cells an obfuscated version.
+     * 
+     * @return bool true on success
+     */
     bool NetlistModifierPlugin::modify_gatelibrary()
     {
+        // open the current project directory
         ProjectManager* pm = ProjectManager::instance();
 
         std::filesystem::path projFilePath(pm->get_project_directory());

plugins/netlist_modifier/src/modify_in_place.cpp

@@ -9,12 +9,21 @@
 
 namespace hal
 {
+    /**
+     * @brief This functions replaces all the selected gates with a gate of an unknown gate type
+     * 
+     * @param probe_type The allowed probe type that should be written in the ini file
+     * @param probe_limit The allowed probe limit that should be written in the ini file
+     * @return bool true in success
+     */
     bool NetlistModifierPlugin::modify_in_place(int probe_type, int probe_limit)
     {
+        // lock the GUI so the view is not updated for every replaced gate individually but rather only once when all gates are replaced
         UIPluginInterface* mGuiPlugin = plugin_manager::get_plugin_instance<UIPluginInterface>("hal_gui");
         if (mGuiPlugin)
             mGuiPlugin->set_layout_locker(true);
 
+        // modify the gate lib
         if (!modify_gatelibrary())
         {
             if (mGuiPlugin)
@@ -23,6 +32,7 @@ namespace hal
             return false;
         }
 
+        // get all selected gates to replace them
         std::vector<Gate*> gates = GuiApi().getSelectedGates();
 
         // save original netlist if it does not contain any UNKNOWN gates
@@ -38,6 +48,7 @@ namespace hal
         ProjectManager* pm = ProjectManager::instance();
         std::filesystem::path project_dir_path(pm->get_project_directory().string());
 
+        // If the netlist does not contain any unknown gates then create the encrypted zip archive
         if (!contains_unknown)
         {
             if (!create_encrypted_zip(SECRET_PASSWORD, probe_type, probe_limit))
@@ -48,6 +59,7 @@ namespace hal
                 return false;
             }
         }
+        // if the netlist already contains unknown gates then just update the existing zip archive
         else
         {
             if (std::filesystem::exists(project_dir_path / "original/original.zip"))
@@ -69,6 +81,7 @@ namespace hal
             }
         }
 
+        // iterate over all selected gates and replace them one by one
         for (Gate* gate : gates)
         {
             if (!replace_gate_in_netlist(gNetlist, gate))
@@ -79,7 +92,8 @@ namespace hal
                 return false;
             }
         }
-
+
+        // release the layout lock once finished
         if (mGuiPlugin)
             mGuiPlugin->set_layout_locker(false);
 

plugins/netlist_modifier/src/netlist_modifier.cpp

@@ -47,6 +47,14 @@ namespace hal
     {
     }
 
+    /**
+     * @brief This function generates the new gate type name based on the number of input and output pins
+     * 
+     * @param num_in Number of input pins to the gate
+     * @param num_out Number of output pins to the gate
+     * @param num_io Number of io pins to the gate
+     * @return std::string The newly generated gate type name
+     */
     std::string NetlistModifierPlugin::obfuscated_gate_name(int num_in, int num_out, int num_io)
     {
         std::string retval = "UNKNOWN_" + std::to_string(num_in) + "IN_" + std::to_string(num_out) + "OUT";

plugins/netlist_modifier/src/open_popup.cpp

@@ -12,6 +12,11 @@ namespace hal
     int IniSettingsPopup::last_probe_limit = -1;
     int IniSettingsPopup::last_probe_type = -1;
 
+    /**
+     * @brief Construct a new Ini Settings Popup:: Ini Settings Popup object
+     * 
+     * @param parent 
+     */
     IniSettingsPopup::IniSettingsPopup(QWidget* parent) : QDialog(parent)
     {
         // Create radio buttons
@@ -66,6 +71,10 @@ namespace hal
         setWindowTitle("Choose Settings");
     }
 
+    /**
+     * @brief Handles the event for clicking the accept button
+     * 
+     */
     void IniSettingsPopup::acceptSelection()
     {
         if (scan_chain_option->isChecked())
@@ -80,6 +89,11 @@ namespace hal
         accept();
     }
 
+    /**
+     * @brief Returns the selected probing type method 
+     * 
+     * @return int 
+     */
     int IniSettingsPopup::get_selected_probing_model()
     {
         if (scan_chain_option->isChecked())
@@ -96,11 +110,20 @@ namespace hal
         }
     }
 
+    /**
+     * @brief Returns the selected probing limit
+     * 
+     * @return int 
+     */
     int IniSettingsPopup::get_probe_limit()
     {
         return probe_limit->value();
     }
 
+    /**
+     * @brief Function that is called when clicking the right click menu entry. This function creates the popup hand handles accept event and calls the gate replacement method
+     * 
+     */
     void NetlistModifierPlugin::open_popup()
     {
         IniSettingsPopup dialog(qApp->activeWindow());