Clarify EM, SDOserver, SDOclient and LSSmaster callback functions.

callback functions called also from SDO_blockTransferInProgress.
Clarify timerNext_us parameter to CO_process() function.

301/CO_Emergency.h

@@ -390,9 +390,11 @@ CO_ReturnError_t CO_EM_init(
 /**
  * Initialize Emergency callback function.
  *
- * Function initializes optional callback function, which executes after
- * error condition is changed. Function may wake up external task,
- * which processes mainline CANopen functions.
+ * Function initializes optional callback function, which should immediately
+ * start processing of CO_EM_process() function.
+ * Callback is called from CO_errorReport() or CO_errorReset() function. Those
+ * functions are fast and may be called from any thread. Callback should
+ * immediately start mainline thread, which calls CO_EM_process() function.
  *
  * @param em This object.
  * @param object Pointer to object, which will be passed to pFunctSignal(). Can be NULL

301/CO_SDOclient.c

@@ -708,9 +708,14 @@ CO_SDOclient_return_t CO_SDOclientDownload(
             else if (SDO_C->block_seqno >= SDO_C->block_blksize) {
                 SDO_C->state = SDO_STATE_BLOCKDOWNLOAD_BLOCK_ACK;
             }
-            else if (timerNext_us != NULL) {
-                /* Set timerNext_us to 0 to inform OS to call this function again without delay. */
-                *timerNext_us = 0;
+            else {
+                /* Inform OS to call this function again without delay. */
+                if (timerNext_us != NULL) {
+                    *timerNext_us = 0;
+                }
+                if (SDO_C->pFunctSignal != NULL) {
+                    SDO_C->pFunctSignal(SDO_C->functSignalObject);
+                }
             }
 
             /*  tx data */

301/CO_SDOclient.h

@@ -195,11 +195,13 @@ CO_ReturnError_t CO_SDOclient_init(
 
 
 /**
- * Initialize SDOclientRx callback function.
+ * Initialize SDOclient callback function.
  *
- * Function initializes optional callback function, which is called after new
- * message is received from the CAN bus. Function may wake up external task,
- * which processes mainline CANopen functions.
+ * Function initializes optional callback function, which should immediately
+ * start processing of CO_SDOclientDownload() or CO_SDOclientUpload() function.
+ * Callback is called after SDOclient message is received from the CAN bus or
+ * when new call without delay is necessary (exchange data with own SDO server
+ * or SDO block transfer is in progress).
  *
  * @param SDOclient This object.
  * @param object Pointer to object, which will be passed to pFunctSignal(). Can be NULL

301/CO_SDOserver.c

@@ -1438,10 +1438,13 @@ int8_t CO_SDO_process(
             /* send response */
             CO_CANsend(SDO->CANdevTx, SDO->CANtxBuff);
 
-            /* Set timerNext_us to 0 to inform OS to call this function again without delay. */
+            /* Inform OS to call this function again without delay. */
             if (timerNext_us != NULL) {
                 *timerNext_us = 0;
             }
+            if (SDO->pFunctSignal != NULL) {
+                SDO->pFunctSignal(SDO->functSignalObject);
+            }
 
             /* don't call CO_FLAG_CLEAR, so return directly */
             return 1;

301/CO_SDOserver.h

@@ -785,9 +785,10 @@ CO_ReturnError_t CO_SDO_init(
 /**
  * Initialize SDOrx callback function.
  *
- * Function initializes optional callback function, which is called after new
- * message is received from the CAN bus. Function may wake up external task,
- * which processes mainline CANopen functions.
+ * Function initializes optional callback function, which should immediately
+ * start processing of CO_SDO_process() function.
+ * Callback is called after SDOserver message is received from the CAN bus or
+ * when new call without delay is necessary (SDO block transfer is in progress).
  *
  * @param SDO This object.
  * @param object Pointer to object, which will be passed to pFunctSignal(). Can be NULL

305/CO_LSSmaster.c

@@ -96,7 +96,7 @@ static void CO_LSSmaster_receive(void *object, void *msg)
 
         CO_FLAG_SET(LSSmaster->CANrxNew);
 
-        /* Optional signal to RTOS, which can resume task, which handles SDO client. */
+        /* Optional signal to RTOS, which can resume task, which handles further processing. */
         if(LSSmaster->pFunctSignal != NULL) {
             LSSmaster->pFunctSignal(LSSmaster->functSignalObject);
         }

305/CO_LSSmaster.h

@@ -187,9 +187,10 @@ void CO_LSSmaster_changeTimeout(
 /**
  * Initialize LSSmasterRx callback function.
  *
- * Function initializes optional callback function, which is called after new
- * message is received from the CAN bus. Function may wake up external task,
- * which processes mainline CANopen functions.
+ * Function initializes optional callback function, which should immediately
+ * start further LSS processing. Callback is called after LSS message is
+ * received from the CAN bus. It should signal the RTOS to resume corresponding
+ * task.
  *
  * @param LSSmaster This object.
  * @param object Pointer to object, which will be passed to pFunctSignal(). Can be NULL

CANopen.h

@@ -282,12 +282,17 @@ CO_ReturnError_t CO_CANopenInit(uint8_t nodeId);
  * @param co CANopen object.
  * @param timeDifference_us Time difference from previous function call in
  *                          microseconds.
- * @param timerNext_us [out] info to OS - maximum delay after function
+ * @param timerNext_us [out] info to OS - maximum delay time after this function
  *        should be called next time in [microseconds]. Value can be used for OS
- *        sleep time. Initial value must be set to something, 50000us typically.
- *        Output will be equal or lower to initial value. If there is new object
- *        to process, delay should be suspended and this function should be
- *        called immediately. Parameter is ignored if NULL.
+ *        sleep time. Initial value must be set to maximum interval time.
+ *        Output will be equal or lower to initial value. Calculation is based
+ *        on various timers which expire in known time. Parameter should be
+ *        used in combination with callbacks configured with
+ *        CO_EM_initCallback() and CO_SDO_initCallback(). Those callbacks should
+ *        also trigger calling of CO_process() function.
+ *
+ *        This is experimental feature and can be used for energy saving in case
+ *        of low traffic on CAN bus. Parameter is ignored if NULL.
  *
  * @return #CO_NMT_reset_cmd_t from CO_NMT_process().
  */

doc/CHANGELOG.md

@@ -17,7 +17,7 @@ Change Log
 - Rename in CO_driver_target.h: `IS_CANrxNew` -> `CO_FLAG_READ`, `SET_CANrxNew` -> `CO_FLAG_SET`, `CLEAR_CANrxNew` -> `CO_FLAG_CLEAR`
 - CO_driver.h file, function `CO_CANrxBufferInit()`, last argument (callback) changed from `(*pFunct)(void *object, const CO_CANrxMsg_t *message)` to `void (*CANrx_callback)(void *object, void *message)`. New functions are defined in `CO_driver_target.h` file: `CO_CANrxMsg_readIdent()`, `CO_CANrxMsg_readDLC()` and `CO_CANrxMsg_readData()`.
 - It is necessary to manually update CO_OD.c file - it must include: `301/CO_driver.h`, `CO_OD.h` and `301/CO_SDOserver.h`.
-- Added `void *object` argument to CO_*_initCallback() functions.
+- Added `void *object` argument to CO_*_initCallback() functions. API clarified. Callback functions called also from SDO_blockTransferInProgress.
 ### Changed SocketCAN
 - ./stack/socketCAN removed from the project, ./stack/Neuberger-socketCAN moved to ./socketCAN
 - driver API updated