/** * @file GoAcceleratorMgr.h * @brief Declares the GoAcceleratorMgr class public interfaces. * * @internal * Copyright (C) 2018-2021 by LMI Technologies Inc. * Licensed under the MIT License. * Redistributed files must retain the above copyright notice. * * The SDK Accelerator Manager object allows SDK clients to accelerate more than * one sensor within a single platform. SDK client can build its own accelerator * application using the SDK Accelerator Manager. The SDK Accelerator Manager * provides a mechanism for the SDK client to receive event updates from the * Accelerator Manager. * * A brief description of how to use the SDK Accelerator Manager follows. * Note the description omits error checking and parameters to focus on the * call sequences. * * A. Initializing the Accelerator Manager. * Here is sample code showing how to initialize the Accelerator Manager and how * to start it running. * * kStatus kCall MyApp_UpdateHandler(MyAppClass MyApp, kPointer caller, GoAcceleratorMgrAccelUpdate* update) * { * printf( * "Sensor %u event - %d\n", * update->sensorId, * update->accelEvent); * } * * // Construct the Accelerator Manager. * GoAcceleratorMgr_Construct(); * * // Set up the update handler so the SDK client can receive events * // from the Accelerator Manager. This step is optional. * GoAcceleratorMgr_SetAccelUpdateHandler(MyApp_UpdateHandler, MyApp); * * // Must give the Accelerator Manager the system object before starting it. * GoSystem system = kNULL; * * GoSystem_Construct(&system, ...); * GoAcceleratorMgr_SetSystem(system); * * // Now start the Accelerator Manager. * GoAcceleratorMgr_Start(); * * // Set the range of port numbers any time as long as no sensor is configured * // for acceleration. This is an optional step to change the default * // range. See the section on changing the port range for more details. * GoAcceleratorMgr_SetPortRange(startPort, endPort); * * B. Accelerating a Sensor. * * // Set up the parameters in a GoAcceleratorMgrSensorParam structure and * // call the accelerate interface. * GoAcceleratorMgrSensorParam param; * k32u sensorId = 12345; * * if (useAutomaticAllocation) * { * param.ports.controlPort = 0; * param.ports.upgradePort = 0; * param.ports.healthPort = 0; * param.ports.privateDataPort = 0; * param.ports.publicDataPort = 0; * param.ports.webPort = 0; * } * else * { * // Manually specify ports that the SDK client is allowed to set up * // TCP/IP connections through a network to the accelerated sensor. * // This example assumes ports 4000 and up are available for use. * param.ports.controlPort = 4000; * param.ports.upgradePort = 4001; * param.ports.healthPort = 4002; * param.ports.privateDataPort = 4003; * param.ports.publicDataPort = 4004; * param.ports.webPort = 4005; * } * // Assume okay to use any IPv4 address (ie. 0.0.0.0). * // Otherwise choose one of the accelerator platform's network interface * // IP address. * param.platforIpAddress = kIpAddress_AnyV4(); * * GoAcceleratorMgr_Accelerate(sensorId, ¶m); * * C. Decelerating (Unaccelerating) a Sensor. * * k32u sensorId = 12345; * * GoAcceleratorMgr_Decelerate(sensorId); * * D. Get the List of Sensors Managed by the Accelerator Manager. * * kArrayList sensorList = kNULL; * * kArrayList_Construct(&sensorList, kTypeOf(GoAcceleratorMgrSensorInfo), 0, kObject_Alloc(myApp)); * GoAcceleratorMgr_ListSensors(sensorList); * * E. Get the port range limits and change the port range. * * k16u startLimit; * k16u endLimit; * k16u minNumPorts; * k16u userStartPort; * k16u userEndPort; * * // Some code initializes userStartPort and userEndPort. * userStartPort = 4000; * userEndPort = 4010; * * // Get the min and max values of the port range and the minimum number * // of ports within the port range to help with user configuration * // validation. * GoAcceleratorMgr_GetPortRangeLimits(startLimit, endLimit, minNumPorts); * * if ((userStartPort >= startLimit) && (userEndPort <= endLimit) && * ((userEndPort - userStartPort + 1) >= minNumPorts) * { * GoAcceleratorMgr_SetPortRange(userStartPort, userEndPort); * } * else * { * printf("Invalid user port range\n"); * } * * F. Get current port range. * * k16u startPort; * k16u endPort; * * GoAcceleratorMgr_GetPortRange(&startPort, &endPort); * * G. Get the number of sensors managed by the Accelerator Manager. * * if (GoAcceleratorMgr_AccelSensorCount() > 0) * { * printf("Sensors configured for acceleration\n"); * } * else * { * printf("No sensors configured for acceleration\n"); * } * */ #ifndef GO_ACCELERATOR_MGR_H #define GO_ACCELERATOR_MGR_H #include // Don't know why need to explicitly include GoSystem header file again // here when GoSdk.h already includes it. If this is not done, compile fails // to find GoSystem declaration!? #include #include /** * @class GoAcceleratorMgr * @extends kObject * @ingroup GoSdk * @brief Represents an GoAcceleratorMgr instance. */ typedef kObject GoAcceleratorMgr; /** * @class GoAcceleratorMgr * @extends kValue * @ingroup GoSdk * @brief Represents an GoAcceleratorMgr events passed into the acceleration * update callback handler bound in by SDK client. * Meaning of the events are: * - GO_ACCELERATOR_MGR_EVENT_ACCELERATING - Sensor acceleration is in progress. * - GO_ACCELERATOR_MGR_EVENT_ACCELERATED: - Sensor is accelerated successfully. * - GO_ACCELERATOR_MGR_EVENT_DECELERATING: - Sensor deceleration is in progress. * - GO_ACCELERATOR_MGR_EVENT_DECELERATED: - Sensor is no longer accelerated. * - GO_ACCELERATOR_MGR_EVENT_STOPPED: - Sensor acceleration stopped or failed to start. * - GO_ACCELERATOR_MGR_EVENT_DISCONNECTED: - Accelerated sensor is disconnected from network. * - GO_ACCELERATOR_MGR_EVENT_PROCESS_STOPPED: - Special case for the STOPPED event to indicate acceleration * was in progress but terminated unexpectedly. * This stop reason differs from other stop reasons, * such as firmware mismatch etc. */ typedef enum GoAcceleratorMgrAccelEvents { GO_ACCELERATOR_MGR_EVENT_ACCELERATING = 0, GO_ACCELERATOR_MGR_EVENT_ACCELERATED, GO_ACCELERATOR_MGR_EVENT_DECELERATING, GO_ACCELERATOR_MGR_EVENT_DECELERATED, GO_ACCELERATOR_MGR_EVENT_STOPPED, GO_ACCELERATOR_MGR_EVENT_DISCONNECTED, GO_ACCELERATOR_MGR_EVENT_PROCESS_STOPPED } GoAcceleratorMgrAccelEvents; /** * @struct GoAcceleratorMgrAccelUpdate * @extends kValue * @ingroup GoSdk * @brief Structure to hold data for the acceleration update handler. */ typedef struct GoAcceleratorMgrAccelUpdate { k32u sensorId; GoAcceleratorMgrAccelEvents accelEvent; } GoAcceleratorMgrAccelUpdate; /** * @struct GoAcceleratorMgrSensorParam * @extends kValue * @ingroup GoSdk * @brief Structure to hold user configuration parameters from SDK client * for a sensor that is to be accelerated. */ typedef struct GoAcceleratorMgrSensorParam { GoAccelSensorPortAllocPorts ports; kIpAddress platformIpAddress; // Bind an accelerated sensor to this accelerator host interface IP address. } GoAcceleratorMgrSensorParam; /** * @struct GoAcceleratorMgrSensorBackup * @extends kValue * @ingroup GoSdk * @brief Structure to provide the original unaccelerated sensor information to the SDK client. * This is useful for reaching the sensor object while it is being accelerated, or * if there are errors during acceleration, or after stopping acceleration. */ typedef struct GoAcceleratorMgSensorBackup { GoAccelSensorPortAllocPorts ports; GoAddressInfo sensorAddressInfo; } GoAcceleratorMgrSensorBackup; /** * @struct GoAcceleratorMgrSensorInfo * @extends kValue * @ingroup GoSdk * @brief Structure to return accelerated sensor information to SDK client. * The param field contains information received from the SDK client, except if * SDK client requested automatic port selection. In this case, the ports in the * param field are the ports selected by the SDK for the SDK client. */ typedef struct GoAcceleratorMgrSensorInfo { k32u sensorId; GoSensorAccelStatus status; GoAcceleratorMgrSensorParam param; GoAcceleratorMgrSensorBackup backup; } GoAcceleratorMgrSensorInfo; /** * Constructs the accelerator manager object * * @public @memberof GoAcceleratorMgr * @version Introduced in firmware 5.2.18.3 * @param manager Address of uninitialized manager object. * @param allocator Allocator object (kNULL for fallback allocator). * @return Operation status. */ GoFx(kStatus) GoAcceleratorMgr_Construct(GoAcceleratorMgr* manager, kAlloc allocator); /** * Assigns the SDK GoSystem object to the accelerator manager object. This must be * done before starting the accelerator manager. * * @public @memberof GoAcceleratorMgr * @version Introduced in firmware 5.2.18.3 * @param manager GoAcceleratorMgr object. * @param system Instance of GoSystem * @return Operation status. */ GoFx(kStatus) GoAcceleratorMgr_SetSystem(GoAcceleratorMgr manager, GoSystem system); /** * Starts the accelerator manager object after it has been configured. * * @public @memberof GoAcceleratorMgr * @version Introduced in firmware 5.2.18.3 * @param manager GoAcceleratorMgr object. * @return Operation status. */ GoFx(kStatus) GoAcceleratorMgr_Start(GoAcceleratorMgr manager); /** * Accelerate the specified sensor with the given set of parameters. * The parameter structure contains the accelerator host IP address to * associate with the accelerated sensor, and the ports the accelerated * sensor should use to communicate with the SDK client. * If the SDK client wishes to have the GoAcceleratorMgr dynamically/automatically * allocate the port numbers from within the configured port range, * the SDK client must set all the ports in the parameter structure to * zero (0). * Any non-zero value for a port in the port parameter list is treated * as if the client is providing ALL the port numbers to use. If the * client provided port numbers are valid, then they will be used by * the accelerated sensor. * The "param" structure is modified to store actual ports selected if * SDK client chose dynamic/automatic port allocation. * * @public @memberof GoAcceleratorMgr * @version Introduced in firmware 5.2.18.3 * @param manager GoAcceleratorMgr object. * @param sensorId Identifier of the sensor. * @param param Pointer to parameter structure for accelerating the sensor. * @return Operation status. */ GoFx(kStatus) GoAcceleratorMgr_Accelerate(GoAcceleratorMgr manager, k32u sensorId, GoAcceleratorMgrSensorParam* param); /** * Decelerate (unaccelerate) a sensor. * * @public @memberof GoAcceleratorMgr * @version Introduced in firmware 5.2.18.3 * @param manager GoAcceleratorMgr object. * @param sensorId Identifier of the sensor. * @return Operation status. */ GoFx(kStatus) GoAcceleratorMgr_Decelerate(GoAcceleratorMgr manager, k32u sensorId); /** * Get a list of accelerated sensors. The list is returned in an array list * of GoAcceleratorMgrSensorInfo. Caller must construct the kArrayList and * pass the it as an argument to this API. The API will fill this list. * * Each entry includes the set of ports used by the accelerated sensor. * If the client had specified the ports to use, then the list entry's * set of ports should be the same as the client specified ports. * If the client had specified the Accelerator Manager dynamically * allocate ports from the configured port range, then the list entry's * set of ports contains the ports allocated to the sensor. * The current acceleration status of the sensor is returned in the * list entry for each sensor. * * @public @memberof GoAcceleratorMgr * @version Introduced in firmware 5.2.18.3 * @param manager GoAcceleratorMgr object. * @param sensorList Array list of GoAcceleratorMgrSensorInfo for each * accelerated sensor. * @return Operation status. */ GoFx(kStatus) GoAcceleratorMgr_ListSensors(GoAcceleratorMgr manager, kArrayList sensorList); /** * Set up the update handler so that the SDK client can receive events * from the Accelerator Manager about a sensor. This step is optional. If update handler * is not bound in, then client will not receive any event notifications. * Update handler is called with a pointer to GoAcceleratorMgrAccelUpdate which * contains event information about a sensor. * The update handler does not free the memory for the GoAcceleratorMgrAccelUpdate * structure. * * @public @memberof GoAcceleratorMgr * @version Introduced in firmware 5.2.18.3 * @param manager GoAcceleratorMgr object. * @param function Update callback handler function. * @param context SDK client context for the callback handler. * It is a pointer to GoAcceleratorMgrAccelUpdate. * @return Operation status. */ GoFx(kStatus) GoAcceleratorMgr_SetAccelUpdateHandler(GoAcceleratorMgr manager, kCallbackFx function, kPointer context); /** * Set the range of port numbers used to communicate with the accelerated * sensors. Changes to the port range is allowed only if no sensor is * configured for acceleration. * Changing the port range is optional if the client application can use * the default port range. * The port numbers range must be within the port range limits (see * GoAcceleratorMgr_GetPortRangeLimits()). * Configure the port range if your network places limits on what ports are * permitted for communication use or if some range of ports is known to be used * by another application. * * @public @memberof GoAcceleratorMgr * @version Introduced in firmware 5.2.18.3 * @param manager GoAcceleratorMgr object. * @param startPort Starting port number in the range * @param endPort Last port number in the range. * @return Operation status. */ GoFx(kStatus) GoAcceleratorMgr_SetPortRange(GoAcceleratorMgr manager, k16u startPort, k16u endPort); /** * Get the range of port numbers to assign to accelerated sensors. * The ports within the port range are used by the Accelerator Manager * to allocate ports for the accelerated sensors. * * @public @memberof GoAcceleratorMgr * @version Introduced in firmware 5.2.18.3 * @param manager GoAcceleratorMgr object. * @param startPort Returns the starting port number in the range * @param endPort Returns the last port number in the range. * @return Operation status. */ GoFx(kStatus) GoAcceleratorMgr_GetPortRange(GoAcceleratorMgr manager, k16u* startPort, k16u* endPort); /** * Get the min and max values of the port range and the minimum number * of ports within the port range. These limits are the default port range. * The upper limit is set to just below the start of the ephemeral port * range that are available for use by any network application. * * @public @memberof GoAcceleratorMgr * @version Introduced in firmware 5.2.18.3 * @param manager GoAcceleratorMgr object. * @param startLimit Returns the limit for the starting port number in the range * @param endLimit Returns the limit for the last port number in the range. * @param minNumPorts Returns the minimum number of ports that the range must support. * @return Operation status. */ GoFx(kStatus) GoAcceleratorMgr_GetPortRangeLimits(GoAcceleratorMgr manager, k16u* startLimit, k16u* endLimit, k16u* minNumPorts); /** * Get the number of sensors which the accelerator manager has been configured * to accelerate. The count includes sensors whose acceleration may have failed * for whatever reason. * This is a convenient interface to find out how many sensors have * been configured without having to get the list of sensors. This count * should match the number of successful calls to GoAcceleratorMgr_Accelerate() * less successful calls to GoAcceleratorMgr_Decelerate(). * * @public @memberof GoAcceleratorMgr * @version Introduced in firmware 5.2.18.3 * @param manager GoAcceleratorMgr object. * @return Number of sensors configured for acceleration. */ GoFx(kSize) GoAcceleratorMgr_AccelSensorCount(GoAcceleratorMgr manager); #include #endif // GO_ACCELERATOR_MGR_H