[alf] Introduce implicit locking option for SC sequence services

Author: kostorr

README.md

@@ -80,11 +80,14 @@ The services are DIM RPC services. Every RPC is called with a string and expects
     * Operations may be:
     * An SCA command and data pair (e.g. `0x0000f00d,0x0000cafe`)
     * A wait operation (e.g. `30,wait`)
+    * An instruction to execute the sequence atomically (`lock` - needs to lead the sequence)
 * Returns:
   * Sequence of SCA command and SCA read pairs, and wait confirmations
+  * No entries for `lock` directives
 
 * Example:
   * DIM input: `0x00000010,0x00000011\n3\n0x000000020,0x00000021`
+  * DIM input (atomic): `lock\n0x00000010,0x00000011\n3\n0x000000020,0x00000021`
   * DIM output: `0x00000010,0x00000111\n3\n0x00000020,0x00000221\n`
 
 ##### SWT_SEQUENCE
@@ -94,14 +97,17 @@ The services are DIM RPC services. Every RPC is called with a string and expects
     * `write` with SWT prefix (e.g. `0x0000f00d,write`)
     * `reset` (without SWT word)
     * `read` with optional TimeOut prefix (e.g. `2,read`)
+    * `lock` which instructs ALF to execute the sequence atomically (needs to lead the sequence)
 * Returns:
   * Sequence of SWT output as follows:
     * `write` always retuns `0`
     * `read` returns the SWT words present in the CRU SWT FIFO
     * `reset` returns nothing
+    * `lock` returns nothing
 
 * Example:
   * DIM input `reset\n0x0000000000badc0ffee,write\nread\n0xbadf00d,write\n4,read`
+  * DIM input (atomic) `lock\nreset\n0x0000000000badc0ffee,write\nread\n0xbadf00d,write\n4,read`
   * DIM output `0\n0x0000000000badc0ffee\n0\n0x000000000000badf00d\n`
 
 ##### IC_SEQUENCE
@@ -111,13 +117,16 @@ The services are DIM RPC services. Every RPC is called with a string and expects
     * Operations may be:
     * Address, Value and `write`
     * Address and `read`
+    * `lock` which instructs ALF to execute the sequence atomically (needs to lead the sequence)
 
 * Returns:
   * Value on `write` (echo)
   * Value on `read`
+  * Nothing on `lock`
 
 * Example:
   * DIM input: `0x54,0xff,write\n0x54,read`
+  * DIM input (atomic): `lock\n0x54,0xff,write\n0x54,read`
   * DIM output: `0x000000ff\n0x000000ff\n`
 
 ##### IC_GBT_I2C_WRITE

apps/AlfClient.cxx

@@ -152,7 +152,8 @@ class AlfClient : public AliceO2::Common::Program
     Logger::get().log() << "[REGISTER] Wrote: " << Util::formatValue(wValue) << " Read: " << Util::formatValue(rValue) << endm;
 
     if (mOptions.swt) {
-      auto swtOut = swtSequence.write({ std::make_pair("0x0000000000000000000", "write"),
+      auto swtOut = swtSequence.write({ std::make_pair("", "lock"),
+                                        std::make_pair("0x0000000000000000000", "write"),
                                         std::make_pair("", "reset"),
                                         std::make_pair("0x0000000000000000000", "write"),
                                         std::make_pair("0x000000001234", "write"),

include/Alf/Ic.h

@@ -47,7 +47,7 @@ class Ic
  public:
   /// Struct holding the IC address and data pair; useful to AlfServer
   struct IcData {
-    uint32_t address;
+    uint32_t address = 0x0;
     uint32_t data = 0x0;
   };
 
@@ -115,7 +115,8 @@ class Ic
   /// Enum for the different IC operation types
   enum Operation { Read,
                    Write,
-                   Error };
+                   Error,
+                   Lock };
 
   /// Executes an IC sequence
   /// \param ops A vector of Data and Operations pairs

include/Alf/Sca.h

@@ -52,7 +52,8 @@ class Sca
   /// Enum for the different SCA operation types as seen from DIM RPCs
   enum Operation { Command,
                    Wait,
-                   Error };
+                   Error,
+                   Lock };
 
   /// Internal constructor for the AlfServer
   /// \param link AlfLink holding useful information coming from the AlfServer class

include/Alf/Swt.h

@@ -58,7 +58,8 @@ class Swt
   enum Operation { Read,
                    Write,
                    Reset,
-                   Error };
+                   Error,
+                   Lock };
 
   /// Internal constructor for the ALF server
   /// \param link AlfLink holding useful information coming from the AlfServer class

src/AlfClient.h

@@ -135,7 +135,11 @@ class ScaSequenceRpc : DimRpcInfoWrapper
   {
     std::stringstream buffer;
     for (size_t i = 0; i < sequence.size(); ++i) {
-      buffer << sequence[i].first << pairSeparator() << sequence[i].second;
+      if (sequence[i].first != "") {
+        buffer << sequence[i].first << pairSeparator() << sequence[i].second;
+      } else {
+        buffer << sequence[i].second;
+      }
       if (i + 1 < sequence.size()) {
         buffer << argumentSeparator();
       }
@@ -246,7 +250,11 @@ class IcSequenceRpc : DimRpcInfoWrapper
   {
     std::stringstream buffer;
     for (size_t i = 0; i < sequence.size(); ++i) {
-      buffer << sequence[i].first << pairSeparator() << sequence[i].second;
+      if (sequence[i].first != "") {
+        buffer << sequence[i].first << pairSeparator() << sequence[i].second;
+      } else {
+        buffer << sequence[i].second;
+      }
       if (i + 1 < sequence.size()) {
         buffer << argumentSeparator();
       }

src/AlfServer.cxx

@@ -84,7 +84,14 @@ std::string AlfServer::scaBlobWrite(const std::string& parameter, AlfLink link)
   std::vector<std::string> stringPairs = Util::split(parameter, argumentSeparator());
   std::vector<std::pair<Sca::Operation, Sca::Data>> scaPairs = parseStringToScaPairs(stringPairs);
   Sca sca = Sca(link);
-  return sca.writeSequence(scaPairs);
+
+  bool lock = false;
+  // Check if the operation should be locked
+  if (scaPairs[0].first == Sca::Operation::Lock) {
+    scaPairs.erase(scaPairs.begin());
+    lock = true;
+  }
+  return sca.writeSequence(scaPairs, lock);
 }
 
 std::string AlfServer::swtBlobWrite(const std::string& parameter, AlfLink link)
@@ -93,7 +100,14 @@ std::string AlfServer::swtBlobWrite(const std::string& parameter, AlfLink link)
   std::vector<std::string> stringPairs = Util::split(parameter, argumentSeparator());
   std::vector<std::pair<Swt::Operation, Swt::Data>> swtPairs = parseStringToSwtPairs(stringPairs);
   Swt swt = Swt(link);
-  return swt.writeSequence(swtPairs);
+
+  bool lock = false;
+  // Check if the operation should be locked
+  if (swtPairs[0].first == Swt::Operation::Lock) {
+    swtPairs.erase(swtPairs.begin());
+    lock = true;
+  }
+  return swt.writeSequence(swtPairs, lock);
 }
 
 std::string AlfServer::icBlobWrite(const std::string& parameter, AlfLink link)
@@ -102,7 +116,14 @@ std::string AlfServer::icBlobWrite(const std::string& parameter, AlfLink link)
   std::vector<std::string> stringPairs = Util::split(parameter, argumentSeparator());
   std::vector<std::pair<Ic::Operation, Ic::Data>> icPairs = parseStringToIcPairs(stringPairs);
   Ic ic = Ic(link);
-  return ic.writeSequence(icPairs);
+
+  bool lock = false;
+  // Check if the operation should be locked
+  if (icPairs[0].first == Ic::Operation::Lock) {
+    icPairs.erase(icPairs.begin());
+    lock = true;
+  }
+  return ic.writeSequence(icPairs, lock);
 }
 
 std::string AlfServer::icGbtI2cWrite(const std::string& parameter, AlfLink link)
@@ -249,23 +270,38 @@ std::vector<uint32_t> AlfServer::stringToRegisterPair(const std::string stringPa
 std::pair<Sca::Operation, Sca::Data> AlfServer::stringToScaPair(const std::string stringPair)
 {
   std::vector<std::string> scaPair = Util::split(stringPair, pairSeparator());
-  if (scaPair.size() != 2) {
-    BOOST_THROW_EXCEPTION(
-      AlfException() << ErrorInfo::Message("SCA command-data pair not formatted correctly"));
-  }
 
   Sca::Data data;
   Sca::Operation operation;
 
-  if (scaPair[scaPair.size() - 1] == "wait") {
+  if (scaPair.size() < 1 || scaPair.size() > 2) {
+    BOOST_THROW_EXCEPTION(
+      AlfException() << ErrorInfo::Message("SCA command-data pair not formatted correctly"));
+  }
+
+  if (scaPair[scaPair.size() - 1] == "lock") {
+    operation = Sca::Operation::Lock;
+    if (scaPair.size() != 1) {
+      BOOST_THROW_EXCEPTION(
+        AlfException() << ErrorInfo::Message("Too many arguments for LOCK operation"));
+    }
+  } else if (scaPair[scaPair.size() - 1] == "wait") {
     operation = Sca::Operation::Wait;
+    if (scaPair.size() != 2) {
+      BOOST_THROW_EXCEPTION(
+        AlfException() << ErrorInfo::Message("Too few arguments for WAIT operation"));
+    }
     try {
       data = std::stoi(scaPair[0]);
     } catch (const std::exception& e) {
       BOOST_THROW_EXCEPTION(SwtException() << ErrorInfo::Message("SCA Wait Time provided cannot be converted to int"));
     }
   } else { // regular sca command
     operation = Sca::Operation::Command;
+    if (scaPair.size() != 2) {
+      BOOST_THROW_EXCEPTION(
+        AlfException() << ErrorInfo::Message("Too few arguments for SCA command-data pair"));
+    }
     Sca::CommandData commandData;
     commandData.command = Util::stringToHex(scaPair[0]);
     commandData.data = Util::stringToHex(scaPair[1]);
@@ -286,7 +322,13 @@ std::pair<Swt::Operation, Swt::Data> AlfServer::stringToSwtPair(const std::strin
 
   Swt::Operation operation;
 
-  if (swtPair[swtPair.size() - 1] == "read") {
+  if (swtPair[swtPair.size() - 1] == "lock") {
+    operation = Swt::Operation::Lock;
+    if (swtPair.size() == 2) {
+      BOOST_THROW_EXCEPTION(
+        AlfException() << ErrorInfo::Message("Too many arguments for LOCK operation"));
+    }
+  } else if (swtPair[swtPair.size() - 1] == "read") {
     operation = Swt::Operation::Read;
   } else if (swtPair[swtPair.size() - 1] == "write") {
     operation = Swt::Operation::Write;
@@ -342,15 +384,23 @@ std::pair<Swt::Operation, Swt::Data> AlfServer::stringToSwtPair(const std::strin
 std::pair<Ic::Operation, Ic::Data> AlfServer::stringToIcPair(const std::string stringPair)
 {
   std::vector<std::string> icPair = Util::split(stringPair, pairSeparator());
-  if (icPair.size() != 2 && icPair.size() != 3) {
+  if (icPair.size() < 1 || icPair.size() > 3) {
     BOOST_THROW_EXCEPTION(
       AlfException() << ErrorInfo::Message("IC pair not formatted correctly"));
   }
 
   Ic::Operation icOperation;
+  Ic::IcData icData;
 
   // Parse IC operation
-  if (icPair[icPair.size() - 1] == "read") {
+  if (icPair[icPair.size() - 1] == "lock") {
+    icOperation = Ic::Operation::Lock;
+    if (icPair.size() > 1) {
+      BOOST_THROW_EXCEPTION(
+        AlfException() << ErrorInfo::Message("Too many arguments for LOCK operation"));
+    }
+    return std::make_pair(icOperation, icData); // no data to parse, return immediately
+  } else if (icPair[icPair.size() - 1] == "read") {
     icOperation = Ic::Operation::Read;
     if (icPair.size() == 3) {
       BOOST_THROW_EXCEPTION(
@@ -398,8 +448,6 @@ std::pair<Ic::Operation, Ic::Data> AlfServer::stringToIcPair(const std::string s
     }
   }
 
-  Ic::IcData icData;
-
   std::stringstream ss;
   ss << std::setw(4) << std::setfill('0') << hexAddress;