Added connection assertion and moved msgPrintControl to key

README.md

@@ -17,9 +17,48 @@ The full inheritance chain for two different motor drivers "a" and "b" looks lik
 `asynController -> sinqController -> bController`
 `asynAxis -> sinqAxis -> bAxis`
 
-Those inheritance chains are created at runtime by loading shared libraries. Therefore, it is important to load compatible versions. At SINQ, the versioning numbers follow the SemVer standard (https://semver.org/lang/de/). For example, if driver "a" depends on version 2.1.0 of "sinqMotor", then it is safe to use "sinqMotor" 2.5.3 since 2.5.3 is backwards compatible to 2.1.0. However, it is not allowed to use e.g. version 1.9.0 or 2.0.0 or 3.0.1 instead. For more details on SemVer, please refer to the official documentation.
+Those inheritance chains are created at runtime by loading shared libraries. These libraries must be compatible to each other (see next section).
 
-To find out which version of sinqMotor is needed by driver "a", refer to its Makefile (line `sinqMotor_VERSION=x.x.x`, where x.x.x is the minimum required version).
+### Versioning
+
+In order to make sure the shared libraries are compatible to each other, we use the "require" framework extension for EPICS (https://github.com/paulscherrerinstitute/require). If a shared library has another library as a dependency, it is checked whether the latter is already loaded. If yes, the loaded version is considered compatible if:
+
+1) no specific version was required by the former library
+2) the already loaded version matches the required version exactly
+3) major and minor numbers are the same and already loaded patch number is equal to the required one or higher
+4) major numbers are the same and already loaded minor number is higher than the required one
+5) the already loaded version is a test version and the required version is not a test version
+These rules are in complicance with the SemVer standard (https://semver.org/lang/de/)
+
+If the dependency hasn't been loaded yet, it is loaded now. In case no specific version is required, the latest numbered version is used.
+
+Because these rules are checked sequentially for each required dependency and no unloading is performed, it is important to consider the order of required libraries. Consider the following example:
+
+```
+require "libDriverA" # sinqMotor 1.2 is specified as a dependency
+require "libDriverB" # sinqMotor 1.0 is specified as a dependency
+```
+`require` first checks the dependencies of `libDriverA` and sees that `sinqMotor 1.2` is required. It therefore load `sinqMotor 1.2` and then `libDriverA`. Now the next `require` starts analyzing the dependencies of `libDriverB` and sees that `sinqMotor 1.0` is required. Since `sinqMotor 1.2` is already loaded, rule 4) is applied and `libDriverB` is assumed to be compatible with `sinqMotor 1.2` as well (which it should be according to SemVer).
+
+When the order is inverted, the following happens:
+```
+require "libDriverB" # sinqMotor 1.0 is specified as a dependency
+require "libDriverA" # sinqMotor 1.2 is specified as a dependency
+```
+`require` first checks the dependencies of `libDriverB` and sees that `sinqMotor 1.0` is required. It therefore load `sinqMotor 1.0` and then `libDriverB`. Now the next `require` starts analyzing the dependencies of `libDriverA` and sees that `sinqMotor 1.2` is required. Since `sinqMotor 1.0` is already loaded, `require` cannot load `sinqMotor 1.2`. Therefore the IOC startup is aborted with an error message.
+
+In order to make the setup script more robust, it is therefore recommended to explicitly add a dependency version which is compatible to all required libraries:
+
+```
+require "sinqMotor", "1.2"
+require "libDriverB" # sinqMotor 1.0 is specified as a dependency
+require "libDriverA" # sinqMotor 1.2 is specified as a dependency
+```
+The IOC startup now succeeds because we made sure the higher version is loaded first. 
+
+Please see the README.md of https://github.com/paulscherrerinstitute/require for more details.
+
+To find out which version of sinqMotor is needed by a driver, refer to its Makefile (line `sinqMotor_VERSION=x.x.x`, where x.x.x is the minimum required version).
 
 ### IOC startup script
 

db/sinqMotor.db

@@ -54,6 +54,18 @@ record(calc, "$(INSTR)$(M):StatusProblem")
     field(CALC, "A >> 9")
 }
 
+# If the value of this PV is 0, the according axis is currently disconnected from the controller.
+# Trying to give commands to a disconnected axis will result in an error message in the IOC shell
+# This record is coupled to the parameter library via motorConnected_ -> MOTOR_CONNECTED.
+record(longin, "$(INSTR)$(M):Connected")
+{
+    field(DTYP, "asynInt32")
+    field(INP,  "@asyn($(CONTROLLER),$(AXIS)) MOTOR_CONNECTED")
+    field(SCAN, "I/O Intr")
+    field(PINI, "NO")
+    field(INIT, "1")
+}
+
 # Call the reset function of the corresponding sinqAxis
 # This record is coupled to the parameter library via motorReset_ -> MOTOR_RESET.
 record(longout, "$(INSTR)$(M):Reset") {

src/msgPrintControl.cpp

@@ -2,11 +2,13 @@
 #include <unordered_map>
 
 msgPrintControlKey::msgPrintControlKey(char *controller, int axisNo,
-                                       const char *functionName, int line) {
+                                       const char *functionName, int line,
+                                       size_t maxRepetitions) {
     controller_ = controller;
     axisNo_ = axisNo;
     line_ = line;
     functionName_ = functionName;
+    maxRepetitions_ = maxRepetitions;
 }
 
 void msgPrintControlKey::format(char *buffer, size_t bufferSize) {
@@ -16,10 +18,6 @@ void msgPrintControlKey::format(char *buffer, size_t bufferSize) {
 
 // =============================================================================
 
-msgPrintControl::msgPrintControl(size_t maxRepetitions) {
-    maxRepetitions_ = maxRepetitions;
-}
-
 bool msgPrintControl::shouldBePrinted(msgPrintControlKey &key, bool wantToPrint,
                                       asynUser *pasynUser) {
 
@@ -34,12 +32,12 @@ bool msgPrintControl::shouldBePrinted(msgPrintControlKey &key, bool wantToPrint,
         */
         if (map_.find(key) != map_.end()) {
             size_t repetitions = map_[key];
-            if (repetitions < maxRepetitions_) {
+            if (repetitions < key.maxRepetitions_) {
                 // Number of allowed repetitions not exceeded -> Printing the
                 // message is ok.
                 map_[key] = repetitions + 1;
                 return true;
-            } else if (repetitions == maxRepetitions_) {
+            } else if (repetitions == key.maxRepetitions_) {
                 // Reached number of allowed repetitions -> Printing the message
                 // is ok, but further trys are rejected.
                 char formattedKey[100] = {0};
@@ -88,7 +86,8 @@ bool msgPrintControl::shouldBePrinted(msgPrintControlKey &key, bool wantToPrint,
 
 bool msgPrintControl::shouldBePrinted(char *portName, int axisNo,
                                       const char *functionName, int line,
-                                      bool wantToPrint, asynUser *pasynUser) {
+                                      bool wantToPrint, asynUser *pasynUser,
+                                      size_t maxRepetitions) {
     msgPrintControlKey key =
         msgPrintControlKey(portName, axisNo, functionName, __LINE__);
     return shouldBePrinted(key, wantToPrint, pasynUser);

src/msgPrintControl.h

@@ -1,6 +1,8 @@
 #ifndef msgPrintControl_H
 #define msgPrintControl_H
 
+#define DefaultMaxRepetitions 4
+
 #include <asynDriver.h>
 #include <string.h>
 #include <string>
@@ -21,8 +23,15 @@ class msgPrintControlKey {
     const char *functionName_;
     int line_;
 
+    /**
+     * @brief Maximum number of times a message is printed before it is
+     * suppressed. This number is not used as part of the hash.
+     *
+     */
+    size_t maxRepetitions_;
+
     msgPrintControlKey(char *controller_, int axisNo, const char *fileName,
-                       int line);
+                       int line, size_t maxRepetitions = DefaultMaxRepetitions);
 
     bool operator==(const msgPrintControlKey &other) const {
         return axisNo_ == other.axisNo_ && line_ == other.line_ &&
@@ -73,8 +82,6 @@ template <> struct hash<msgPrintControlKey> {
  */
 class msgPrintControl {
   public:
-    msgPrintControl(size_t maxRepetitions);
-
     /**
      * @brief Checks if the error message associated with "key" has been printed
      * more than `this->maxRepetitions_` times in a row. If yes, returns false,
@@ -115,7 +122,8 @@ class msgPrintControl {
      * @param pasynUser
      */
     bool shouldBePrinted(char *controller, int axisNo, const char *functionName,
-                         int line, bool wantToPrint, asynUser *pasynUser);
+                         int line, bool wantToPrint, asynUser *pasynUser,
+                         size_t maxRepetitions = DefaultMaxRepetitions);
 
     /**
      * @brief Reset the error message count incremented in `shouldBePrinted` for
@@ -129,13 +137,6 @@ class msgPrintControl {
      */
     void resetCount(msgPrintControlKey &key, asynUser *pasynUser);
 
-    /**
-     * @brief Maximum number of times a message is printed before it is
-     * suppressed.
-     *
-     */
-    size_t maxRepetitions_;
-
     char *getSuffix();
 
   private:

src/sinqAxis.cpp

@@ -67,6 +67,18 @@ sinqAxis::sinqAxis(class sinqController *pC, int axisNo)
         exit(-1);
     }
 
+    // Assume that the motor is connected initially
+    status = setIntegerParam(pC_->motorConnected(), 1);
+    if (status != asynSuccess) {
+        asynPrint(pC_->pasynUser(), ASYN_TRACE_ERROR,
+                  "Controller \"%s\", axis %d => %s, line %d:\nFATAL ERROR "
+                  "(setting a parameter value failed "
+                  "with %s)\n. Terminating IOC",
+                  pC->portName, axisNo_, __PRETTY_FUNCTION__, __LINE__,
+                  pC_->stringifyAsynStatus(status));
+        exit(-1);
+    }
+
     // We assume that the motor has no status problems initially
     status = setIntegerParam(pC_->motorStatusProblem(), 0);
     if (status != asynSuccess) {
@@ -113,6 +125,7 @@ sinqAxis::sinqAxis(class sinqController *pC, int axisNo)
 }
 
 asynStatus sinqAxis::poll(bool *moving) {
+
     // Local variable declaration
     asynStatus pl_status = asynSuccess;
     asynStatus poll_status = asynSuccess;
@@ -283,6 +296,11 @@ asynStatus sinqAxis::move(double position, int relative, double minVelocity,
         return status;
     }
 
+    status = assertConnected();
+    if (status != asynSuccess) {
+        return status;
+    }
+
     // Since the move command was successfull, we assume that the motor has
     // started its movement.
     status = setIntegerParam(pC_->motorStatusHomed(), 0);
@@ -350,6 +368,11 @@ asynStatus sinqAxis::home(double minVelocity, double maxVelocity,
                                              __LINE__);
         }
 
+        status = assertConnected();
+        if (status != asynSuccess) {
+            return status;
+        }
+
         // Update the motor record
         return callParamCallbacks();
 
@@ -363,11 +386,16 @@ asynStatus sinqAxis::home(double minVelocity, double maxVelocity,
                                              __LINE__);
         }
 
+        status = assertConnected();
+        if (status != asynSuccess) {
+            return status;
+        }
+
         // Update the motor record
         return callParamCallbacks();
     } else {
         // Bubble up all other problems
-        return status;
+        return assertConnected();
     }
 }
 
@@ -378,6 +406,7 @@ asynStatus sinqAxis::doHome(double minVelocity, double maxVelocity,
 
 asynStatus sinqAxis::reset() {
     asynStatus status = doReset();
+
     if (status == asynSuccess) {
         // Perform some fast polls
         pC_->lock();
@@ -390,6 +419,12 @@ asynStatus sinqAxis::reset() {
         }
         pC_->unlock();
     }
+
+    asynStatus pl_status = assertConnected();
+    if (pl_status != asynSuccess) {
+        return pl_status;
+    }
+
     return status;
 }
 
@@ -443,6 +478,25 @@ asynStatus sinqAxis::setMotorPosition(double motorPosition) {
     return status;
 }
 
+asynStatus sinqAxis::assertConnected() {
+    asynStatus status = asynSuccess;
+    int connected = 0;
+
+    status = pC_->getIntegerParam(axisNo(), pC_->motorConnected(), &connected);
+    if (status != asynSuccess) {
+        return pC_->paramLibAccessFailed(status, "motorConnected", axisNo(),
+                                         __PRETTY_FUNCTION__, __LINE__);
+    }
+
+    if (connected == 0) {
+        asynPrint(pC_->pasynUser(), ASYN_TRACE_ERROR,
+                  "Controller \"%s\", axis %d => %s, line "
+                  "%d:\nAxis is not connected, all commands are ignored.\n",
+                  pC_->portName, axisNo(), __PRETTY_FUNCTION__, __LINE__);
+    }
+    return asynSuccess;
+}
+
 asynStatus sinqAxis::setVeloFields(double velo, double vbas, double vmax) {
     asynStatus status = asynSuccess;
     int variableSpeed = 0;

src/sinqAxis.h

@@ -348,6 +348,16 @@ class epicsShareClass sinqAxis : public asynMotorAxis {
      */
     asynStatus setMotorPosition(double motorPosition);
 
+    /**
+     * @brief Check if the axis is not connected and print a corresponding error
+     * message
+     *
+     * This method is meant to be used at the end of "interactive" function
+     * calls such as move, home, stop etc which can be manually triggered from
+     * the IOC shell or from the channel access protocol.
+     */
+    asynStatus assertConnected();
+
   protected:
     // Internal variables used in the movement timeout watchdog
     time_t expectedArrivalTime_;
@@ -357,7 +367,7 @@ class epicsShareClass sinqAxis : public asynMotorAxis {
     bool watchdogMovActive_;
     // Store the motor target position for the movement time calculation
     double targetPosition_;
-    
+
     bool wasMoving_;
 
     /*

src/sinqController.cpp

@@ -48,7 +48,7 @@ sinqController::sinqController(const char *portName,
           ASYN_CANBLOCK | ASYN_MULTIDEVICE,
           1,     // autoconnect
           0, 0), // Default priority and stack size
-      msgPrintControl_(4) {
+      msgPrintControl_() {
 
     asynStatus status = asynSuccess;
 
@@ -170,6 +170,16 @@ sinqController::sinqController(const char *portName,
         exit(-1);
     }
 
+    status = createParam("MOTOR_CONNECTED", asynParamInt32, &motorConnected_);
+    if (status != asynSuccess) {
+        asynPrint(this->pasynUserSelf, ASYN_TRACE_ERROR,
+                  "Controller \"%s\" => %s, line %d:\nFATAL ERROR (creating a "
+                  "parameter failed with %s).\nTerminating IOC",
+                  portName, __PRETTY_FUNCTION__, __LINE__,
+                  stringifyAsynStatus(status));
+        exit(-1);
+    }
+
     /*
     We need to introduce 2 new parameters in order to write the limits from the
     driver to the EPICS record. See the comment in sinqController.h next to

src/sinqController.h

@@ -285,6 +285,7 @@ class epicsShareClass sinqController : public asynMotorController {
     int motorCanSetSpeed() { return motorCanSetSpeed_; }
     int motorLimitsOffset() { return motorLimitsOffset_; }
     int motorForceStop() { return motorForceStop_; }
+    int motorConnected() { return motorConnected_; }
     int motorVeloFromDriver() { return motorVeloFromDriver_; }
     int motorVbasFromDriver() { return motorVbasFromDriver_; }
     int motorVmaxFromDriver() { return motorVmaxFromDriver_; }
@@ -335,6 +336,9 @@ class epicsShareClass sinqController : public asynMotorController {
     int maxSubsequentTimeouts_;
     bool maxSubsequentTimeoutsExceeded_;
 
+    /*
+    See the documentation in db/sinqMotor.db for the following integers
+    */
 #define FIRST_SINQMOTOR_PARAM motorMessageText_
     int motorMessageText_;
     int motorReset_;
@@ -345,6 +349,7 @@ class epicsShareClass sinqController : public asynMotorController {
     int motorCanSetSpeed_;
     int motorLimitsOffset_;
     int motorForceStop_;
+    int motorConnected_;
     /*
     These parameters are here to write values from the hardware to the EPICS
     motor record. Using motorHighLimit_ / motorLowLimit_ does not work: