Gocator API
 All Classes Files Functions Variables Typedefs Macros Modules Pages
GoAcceleratorMgr.h
Go to the documentation of this file.
1 /**
2  * @file GoAcceleratorMgr.h
3  * @brief Declares the GoAcceleratorMgr class public interfaces.
4  *
5  * @internal
6  * Copyright (C) 2018-2021 by LMI Technologies Inc.
7  * Licensed under the MIT License.
8  * Redistributed files must retain the above copyright notice.
9  *
10  * The SDK Accelerator Manager object allows SDK clients to accelerate more than
11  * one sensor within a single platform. SDK client can build its own accelerator
12  * application using the SDK Accelerator Manager. The SDK Accelerator Manager
13  * provides a mechanism for the SDK client to receive event updates from the
14  * Accelerator Manager.
15  *
16  * A brief description of how to use the SDK Accelerator Manager follows.
17  * Note the description omits error checking and parameters to focus on the
18  * call sequences.
19  *
20  * A. Initializing the Accelerator Manager.
21  * Here is sample code showing how to initialize the Accelerator Manager and how
22  * to start it running.
23  *
24  * kStatus kCall MyApp_UpdateHandler(MyAppClass MyApp, kPointer caller, GoAcceleratorMgrAccelUpdate* update)
25  * {
26  * printf(
27  * "Sensor %u event - %d\n",
28  * update->sensorId,
29  * update->accelEvent);
30  * }
31  *
32  * // Construct the Accelerator Manager.
33  * GoAcceleratorMgr_Construct();
34  *
35  * // Set up the update handler so the SDK client can receive events
36  * // from the Accelerator Manager. This step is optional.
37  * GoAcceleratorMgr_SetAccelUpdateHandler(MyApp_UpdateHandler, MyApp);
38  *
39  * // Must give the Accelerator Manager the system object before starting it.
40  * GoSystem system = kNULL;
41  *
42  * GoSystem_Construct(&system, ...);
43  * GoAcceleratorMgr_SetSystem(system);
44  *
45  * // Now start the Accelerator Manager.
46  * GoAcceleratorMgr_Start();
47  *
48  * // Set the range of port numbers any time as long as no sensor is configured
49  * // for acceleration. This is an optional step to change the default
50  * // range. See the section on changing the port range for more details.
51  * GoAcceleratorMgr_SetPortRange(startPort, endPort);
52  *
53  * B. Accelerating a Sensor.
54  *
55  * // Set up the parameters in a GoAcceleratorMgrSensorParam structure and
56  * // call the accelerate interface.
57  * GoAcceleratorMgrSensorParam param;
58  * k32u sensorId = 12345;
59  *
60  * if (useAutomaticAllocation)
61  * {
62  * param.ports.controlPort = 0;
63  * param.ports.upgradePort = 0;
64  * param.ports.healthPort = 0;
65  * param.ports.privateDataPort = 0;
66  * param.ports.publicDataPort = 0;
67  * param.ports.webPort = 0;
68  * }
69  * else
70  * {
71  * // Manually specify ports that the SDK client is allowed to set up
72  * // TCP/IP connections through a network to the accelerated sensor.
73  * // This example assumes ports 4000 and up are available for use.
74  * param.ports.controlPort = 4000;
75  * param.ports.upgradePort = 4001;
76  * param.ports.healthPort = 4002;
77  * param.ports.privateDataPort = 4003;
78  * param.ports.publicDataPort = 4004;
79  * param.ports.webPort = 4005;
80  * }
81  * // Assume okay to use any IPv4 address (ie. 0.0.0.0).
82  * // Otherwise choose one of the accelerator platform's network interface
83  * // IP address.
84  * param.platforIpAddress = kIpAddress_AnyV4();
85  *
86  * GoAcceleratorMgr_Accelerate(sensorId, &param);
87  *
88  * C. Decelerating (Unaccelerating) a Sensor.
89  *
90  * k32u sensorId = 12345;
91  *
92  * GoAcceleratorMgr_Decelerate(sensorId);
93  *
94  * D. Get the List of Sensors Managed by the Accelerator Manager.
95  *
96  * kArrayList sensorList = kNULL;
97  *
98  * kArrayList_Construct(&sensorList, kTypeOf(GoAcceleratorMgrSensorInfo), 0, kObject_Alloc(myApp));
99  * GoAcceleratorMgr_ListSensors(sensorList);
100  *
101  * E. Get the port range limits and change the port range.
102  *
103  * k16u startLimit;
104  * k16u endLimit;
105  * k16u minNumPorts;
106  * k16u userStartPort;
107  * k16u userEndPort;
108  *
109  * // Some code initializes userStartPort and userEndPort.
110  * userStartPort = 4000;
111  * userEndPort = 4010;
112  *
113  * // Get the min and max values of the port range and the minimum number
114  * // of ports within the port range to help with user configuration
115  * // validation.
116  * GoAcceleratorMgr_GetPortRangeLimits(startLimit, endLimit, minNumPorts);
117  *
118  * if ((userStartPort >= startLimit) && (userEndPort <= endLimit) &&
119  * ((userEndPort - userStartPort + 1) >= minNumPorts)
120  * {
121  * GoAcceleratorMgr_SetPortRange(userStartPort, userEndPort);
122  * }
123  * else
124  * {
125  * printf("Invalid user port range\n");
126  * }
127  *
128  * F. Get current port range.
129  *
130  * k16u startPort;
131  * k16u endPort;
132  *
133  * GoAcceleratorMgr_GetPortRange(&startPort, &endPort);
134  *
135  * G. Get the number of sensors managed by the Accelerator Manager.
136  *
137  * if (GoAcceleratorMgr_AccelSensorCount() > 0)
138  * {
139  * printf("Sensors configured for acceleration\n");
140  * }
141  * else
142  * {
143  * printf("No sensors configured for acceleration\n");
144  * }
145  *
146  */
147 #ifndef GO_ACCELERATOR_MGR_H
148 #define GO_ACCELERATOR_MGR_H
149 
150 #include <GoSdk/GoSdk.h>
151 // Don't know why need to explicitly include GoSystem header file again
152 // here when GoSdk.h already includes it. If this is not done, compile fails
153 // to find GoSystem declaration!?
154 #include <GoSdk/GoSystem.h>
156 
157 /**
158  * @class GoAcceleratorMgr
159  * @extends kObject
160  * @ingroup GoSdk
161  * @brief Represents an GoAcceleratorMgr instance.
162  */
163 typedef kObject GoAcceleratorMgr;
164 
165 /**
166 * @class GoAcceleratorMgr
167 * @extends kValue
168 * @ingroup GoSdk
169 * @brief Represents an GoAcceleratorMgr events passed into the acceleration
170 * update callback handler bound in by SDK client.
171 * Meaning of the events are:
172 * - GO_ACCELERATOR_MGR_EVENT_ACCELERATING - Sensor acceleration is in progress.
173 * - GO_ACCELERATOR_MGR_EVENT_ACCELERATED: - Sensor is accelerated successfully.
174 * - GO_ACCELERATOR_MGR_EVENT_DECELERATING: - Sensor deceleration is in progress.
175 * - GO_ACCELERATOR_MGR_EVENT_DECELERATED: - Sensor is no longer accelerated.
176 * - GO_ACCELERATOR_MGR_EVENT_STOPPED: - Sensor acceleration stopped or failed to start.
177 * - GO_ACCELERATOR_MGR_EVENT_DISCONNECTED: - Accelerated sensor is disconnected from network.
178 * - GO_ACCELERATOR_MGR_EVENT_PROCESS_STOPPED: - Special case for the STOPPED event to indicate acceleration
179 * was in progress but terminated unexpectedly.
180 * This stop reason differs from other stop reasons,
181 * such as firmware mismatch etc.
182 */
183 typedef enum GoAcceleratorMgrAccelEvents
184 {
185  GO_ACCELERATOR_MGR_EVENT_ACCELERATING = 0,
186  GO_ACCELERATOR_MGR_EVENT_ACCELERATED,
187  GO_ACCELERATOR_MGR_EVENT_DECELERATING,
188  GO_ACCELERATOR_MGR_EVENT_DECELERATED,
189  GO_ACCELERATOR_MGR_EVENT_STOPPED,
190  GO_ACCELERATOR_MGR_EVENT_DISCONNECTED,
191  GO_ACCELERATOR_MGR_EVENT_PROCESS_STOPPED
192 } GoAcceleratorMgrAccelEvents;
193 
194 /**
195 * @struct GoAcceleratorMgrAccelUpdate
196 * @extends kValue
197 * @ingroup GoSdk
198 * @brief Structure to hold data for the acceleration update handler.
199 */
201 {
202  k32u sensorId;
203  GoAcceleratorMgrAccelEvents accelEvent;
205 
206 /**
207 * @struct GoAcceleratorMgrSensorParam
208 * @extends kValue
209 * @ingroup GoSdk
210 * @brief Structure to hold user configuration parameters from SDK client
211 * for a sensor that is to be accelerated.
212 */
214 {
215  GoAccelSensorPortAllocPorts ports;
216  kIpAddress platformIpAddress; // Bind an accelerated sensor to this accelerator host interface IP address.
218 
219 /**
220 * @struct GoAcceleratorMgrSensorBackup
221 * @extends kValue
222 * @ingroup GoSdk
223 * @brief Structure to provide the original unaccelerated sensor information to the SDK client.
224 * This is useful for reaching the sensor object while it is being accelerated, or
225 * if there are errors during acceleration, or after stopping acceleration.
226 */
227 typedef struct GoAcceleratorMgSensorBackup
228 {
229  GoAccelSensorPortAllocPorts ports;
230  GoAddressInfo sensorAddressInfo;
232 
233 /**
234 * @struct GoAcceleratorMgrSensorInfo
235 * @extends kValue
236 * @ingroup GoSdk
237 * @brief Structure to return accelerated sensor information to SDK client.
238 * The param field contains information received from the SDK client, except if
239 * SDK client requested automatic port selection. In this case, the ports in the
240 * param field are the ports selected by the SDK for the SDK client.
241 */
243 {
244  k32u sensorId;
245  GoSensorAccelStatus status;
249 
250 /**
251 * Constructs the accelerator manager object
252 *
253 * @public @memberof GoAcceleratorMgr
254 * @version Introduced in firmware 5.2.18.3
255 * @param manager Address of uninitialized manager object.
256 * @param allocator Allocator object (kNULL for fallback allocator).
257 * @return Operation status.
258 */
259 GoFx(kStatus) GoAcceleratorMgr_Construct(GoAcceleratorMgr* manager, kAlloc allocator);
260 
261 /**
262 * Assigns the SDK GoSystem object to the accelerator manager object. This must be
263 * done before starting the accelerator manager.
264 *
265 * @public @memberof GoAcceleratorMgr
266 * @version Introduced in firmware 5.2.18.3
267 * @param manager GoAcceleratorMgr object.
268 * @param system Instance of GoSystem
269 * @return Operation status.
270 */
272 
273 /**
274 * Starts the accelerator manager object after it has been configured.
275 *
276 * @public @memberof GoAcceleratorMgr
277 * @version Introduced in firmware 5.2.18.3
278 * @param manager GoAcceleratorMgr object.
279 * @return Operation status.
280 */
282 
283 /**
284 * Accelerate the specified sensor with the given set of parameters.
285 * The parameter structure contains the accelerator host IP address to
286 * associate with the accelerated sensor, and the ports the accelerated
287 * sensor should use to communicate with the SDK client.
288 * If the SDK client wishes to have the GoAcceleratorMgr dynamically/automatically
289 * allocate the port numbers from within the configured port range,
290 * the SDK client must set all the ports in the parameter structure to
291 * zero (0).
292 * Any non-zero value for a port in the port parameter list is treated
293 * as if the client is providing ALL the port numbers to use. If the
294 * client provided port numbers are valid, then they will be used by
295 * the accelerated sensor.
296 * The "param" structure is modified to store actual ports selected if
297 * SDK client chose dynamic/automatic port allocation.
298 *
299 * @public @memberof GoAcceleratorMgr
300 * @version Introduced in firmware 5.2.18.3
301 * @param manager GoAcceleratorMgr object.
302 * @param sensorId Identifier of the sensor.
303 * @param param Pointer to parameter structure for accelerating the sensor.
304 * @return Operation status.
305 */
307 
308 /**
309 * Decelerate (unaccelerate) a sensor.
310 *
311 * @public @memberof GoAcceleratorMgr
312 * @version Introduced in firmware 5.2.18.3
313 * @param manager GoAcceleratorMgr object.
314 * @param sensorId Identifier of the sensor.
315 * @return Operation status.
316 */
318 
319 /**
320 * Get a list of accelerated sensors. The list is returned in an array list
321 * of GoAcceleratorMgrSensorInfo. Caller must construct the kArrayList and
322 * pass the it as an argument to this API. The API will fill this list.
323 *
324 * Each entry includes the set of ports used by the accelerated sensor.
325 * If the client had specified the ports to use, then the list entry's
326 * set of ports should be the same as the client specified ports.
327 * If the client had specified the Accelerator Manager dynamically
328 * allocate ports from the configured port range, then the list entry's
329 * set of ports contains the ports allocated to the sensor.
330 * The current acceleration status of the sensor is returned in the
331 * list entry for each sensor.
332 *
333 * @public @memberof GoAcceleratorMgr
334 * @version Introduced in firmware 5.2.18.3
335 * @param manager GoAcceleratorMgr object.
336 * @param sensorList Array list of GoAcceleratorMgrSensorInfo for each
337 * accelerated sensor.
338 * @return Operation status.
339 */
341 
342 /**
343 * Set up the update handler so that the SDK client can receive events
344 * from the Accelerator Manager about a sensor. This step is optional. If update handler
345 * is not bound in, then client will not receive any event notifications.
346 * Update handler is called with a pointer to GoAcceleratorMgrAccelUpdate which
347 * contains event information about a sensor.
348 * The update handler does not free the memory for the GoAcceleratorMgrAccelUpdate
349 * structure.
350 *
351 * @public @memberof GoAcceleratorMgr
352 * @version Introduced in firmware 5.2.18.3
353 * @param manager GoAcceleratorMgr object.
354 * @param function Update callback handler function.
355 * @param context SDK client context for the callback handler.
356 * It is a pointer to GoAcceleratorMgrAccelUpdate.
357 * @return Operation status.
358 */
359 GoFx(kStatus) GoAcceleratorMgr_SetAccelUpdateHandler(GoAcceleratorMgr manager, kCallbackFx function, kPointer context);
360 
361 /**
362 * Set the range of port numbers used to communicate with the accelerated
363 * sensors. Changes to the port range is allowed only if no sensor is
364 * configured for acceleration.
365 * Changing the port range is optional if the client application can use
366 * the default port range.
367 * The port numbers range must be within the port range limits (see
368 * GoAcceleratorMgr_GetPortRangeLimits()).
369 * Configure the port range if your network places limits on what ports are
370 * permitted for communication use or if some range of ports is known to be used
371 * by another application.
372 *
373 * @public @memberof GoAcceleratorMgr
374 * @version Introduced in firmware 5.2.18.3
375 * @param manager GoAcceleratorMgr object.
376 * @param startPort Starting port number in the range
377 * @param endPort Last port number in the range.
378 * @return Operation status.
379 */
380 GoFx(kStatus) GoAcceleratorMgr_SetPortRange(GoAcceleratorMgr manager, k16u startPort, k16u endPort);
381 
382 /**
383 * Get the range of port numbers to assign to accelerated sensors.
384 * The ports within the port range are used by the Accelerator Manager
385 * to allocate ports for the accelerated sensors.
386 *
387 * @public @memberof GoAcceleratorMgr
388 * @version Introduced in firmware 5.2.18.3
389 * @param manager GoAcceleratorMgr object.
390 * @param startPort Returns the starting port number in the range
391 * @param endPort Returns the last port number in the range.
392 * @return Operation status.
393 */
394 GoFx(kStatus) GoAcceleratorMgr_GetPortRange(GoAcceleratorMgr manager, k16u* startPort, k16u* endPort);
395 
396 /**
397 * Get the min and max values of the port range and the minimum number
398 * of ports within the port range. These limits are the default port range.
399 * The upper limit is set to just below the start of the ephemeral port
400 * range that are available for use by any network application.
401 *
402 * @public @memberof GoAcceleratorMgr
403 * @version Introduced in firmware 5.2.18.3
404 * @param manager GoAcceleratorMgr object.
405 * @param startLimit Returns the limit for the starting port number in the range
406 * @param endLimit Returns the limit for the last port number in the range.
407 * @param minNumPorts Returns the minimum number of ports that the range must support.
408 * @return Operation status.
409 */
410 GoFx(kStatus) GoAcceleratorMgr_GetPortRangeLimits(GoAcceleratorMgr manager, k16u* startLimit, k16u* endLimit, k16u* minNumPorts);
411 
412 /**
413 * Get the number of sensors which the accelerator manager has been configured
414 * to accelerate. The count includes sensors whose acceleration may have failed
415 * for whatever reason.
416 * This is a convenient interface to find out how many sensors have
417 * been configured without having to get the list of sensors. This count
418 * should match the number of successful calls to GoAcceleratorMgr_Accelerate()
419 * less successful calls to GoAcceleratorMgr_Decelerate().
420 *
421 * @public @memberof GoAcceleratorMgr
422 * @version Introduced in firmware 5.2.18.3
423 * @param manager GoAcceleratorMgr object.
424 * @return Number of sensors configured for acceleration.
425 */
427 
428 #include <GoSdk/GoAcceleratorMgr.x.h>
429 
430 #endif // GO_ACCELERATOR_MGR_H
kStatus GoAcceleratorMgr_SetAccelUpdateHandler(GoAcceleratorMgr manager, kCallbackFx function, kPointer context)
Set up the update handler so that the SDK client can receive events from the Accelerator Manager abou...
Represents a system of Gocator devices.
kStatus GoAcceleratorMgr_SetSystem(GoAcceleratorMgr manager, GoSystem system)
Assigns the SDK GoSystem object to the accelerator manager object.
Includes all Gocator SDK headers.
kStatus GoAcceleratorMgr_Construct(GoAcceleratorMgr *manager, kAlloc allocator)
Constructs the accelerator manager object.
kStatus GoAcceleratorMgr_Accelerate(GoAcceleratorMgr manager, k32u sensorId, GoAcceleratorMgrSensorParam *param)
Accelerate the specified sensor with the given set of parameters.
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.
Definition: GoAcceleratorMgr.h:227
Declares the GoAccelSensorPortAlloc class.
kSize GoAcceleratorMgr_AccelSensorCount(GoAcceleratorMgr manager)
Get the number of sensors which the accelerator manager has been configured to accelerate.
kStatus GoAcceleratorMgr_ListSensors(GoAcceleratorMgr manager, kArrayList sensorList)
Get a list of accelerated sensors.
Structure to hold user configuration parameters from SDK client for a sensor that is to be accelerate...
Definition: GoAcceleratorMgr.h:213
kStatus GoAcceleratorMgr_Decelerate(GoAcceleratorMgr manager, k32u sensorId)
Decelerate (unaccelerate) a sensor.
Represents the acceleration status of a sensor that is available or being accelerated by the local ho...
kStatus GoAcceleratorMgr_GetPortRangeLimits(GoAcceleratorMgr manager, k16u *startLimit, k16u *endLimit, k16u *minNumPorts)
Get the min and max values of the port range and the minimum number of ports within the port range...
kStatus GoAcceleratorMgr_SetPortRange(GoAcceleratorMgr manager, k16u startPort, k16u endPort)
Set the range of port numbers used to communicate with the accelerated sensors.
Structure to return accelerated sensor information to SDK client. The param field contains informatio...
Definition: GoAcceleratorMgr.h:242
Structure to hold data for the acceleration update handler.
Definition: GoAcceleratorMgr.h:200
Declares the GoSystem class.
kStatus GoAcceleratorMgr_Start(GoAcceleratorMgr manager)
Starts the accelerator manager object after it has been configured.
kStatus GoAcceleratorMgr_GetPortRange(GoAcceleratorMgr manager, k16u *startPort, k16u *endPort)
Get the range of port numbers to assign to accelerated sensors.
Represents an GoAcceleratorMgr instance.
Sensor network address settings.
Definition: GoSdkDef.h:788