Gocator API

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-2020 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>
155 #include <GoSdk/Internal/GoAccelSensorPortAlloc.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 */
200 typedef struct GoAcceleratorMgrAccelUpdate
201 {
202 k32u sensorId;
203 GoAcceleratorMgrAccelEvents accelEvent;
204 } GoAcceleratorMgrAccelUpdate;
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 */
213 typedef struct GoAcceleratorMgrSensorParam
214 {
215 GoAccelSensorPortAllocPorts ports;
216 kIpAddress platformIpAddress; // Bind an accelerated sensor to this accelerator host interface IP address.
217 } GoAcceleratorMgrSensorParam;
218
219 /**
220 * @struct GoAcceleratorMgrSensorInfo
221 * @extends kValue
222 * @ingroup GoSdk
223 * @brief Structure to return accelerated sensor information to SDK client.
224 * The param field contains information received from the SDK client, except if
225 * SDK client requested automatic port selection. In this case, the ports in the
226 * param field are the ports selected by the SDK for the SDK client.
227 */
228 typedef struct GoAcceleratorMgrSensorInfo
229 {
230 k32u sensorId;
231 GoSensorAccelStatus status;
232 GoAcceleratorMgrSensorParam param;
233 } GoAcceleratorMgrSensorInfo;
234
235 /**
236 * Constructs the accelerator manager object
237 *
238 * @public @memberof GoAcceleratorMgr
239 * @version Introduced in firmware 5.2.18.3
240 * @param manager Address of uninitialized manager object.
241 * @param allocator Allocator object (kNULL for fallback allocator).
242 * @return Operation status.
243 */
244 GoFx(kStatus) GoAcceleratorMgr_Construct(GoAcceleratorMgr* manager, kAlloc allocator);
245
246 /**
247 * Assigns the SDK GoSystem object to the accelerator manager object. This must be
248 * done before starting the accelerator manager.
249 *
250 * @public @memberof GoAcceleratorMgr
251 * @version Introduced in firmware 5.2.18.3
252 * @param manager GoAcceleratorMgr object.
253 * @param system Instance of GoSystem
254 * @return Operation status.
255 */
256 GoFx(kStatus) GoAcceleratorMgr_SetSystem(GoAcceleratorMgr manager, GoSystem system);
257
258 /**
259 * Starts the accelerator manager object after it has been configured.
260 *
261 * @public @memberof GoAcceleratorMgr
262 * @version Introduced in firmware 5.2.18.3
263 * @param manager GoAcceleratorMgr object.
264 * @return Operation status.
265 */
266 GoFx(kStatus) GoAcceleratorMgr_Start(GoAcceleratorMgr manager);
267
268 /**
269 * Accelerate the specified sensor with the given set of parameters.
270 * The parameter structure contains the accelerator host IP address to
271 * associate with the accelerated sensor, and the ports the accelerated
272 * sensor should use to communicate with the SDK client.
273 * If the SDK client wishes to have the GoAcceleratorMgr dynamically/automatically
274 * allocate the port numbers from within the configured port range,
275 * the SDK client must set all the ports in the parameter structure to
276 * zero (0).
277 * Any non-zero value for a port in the port parameter list is treated
278 * as if the client is providing ALL the port numbers to use. If the
279 * client provided port numbers are valid, then they will be used by
280 * the accelerated sensor.
281 * The "param" structure is modified to store actual ports selected if
282 * SDK client chose dynamic/automatic port allocation.
283 *
284 * @public @memberof GoAcceleratorMgr
285 * @version Introduced in firmware 5.2.18.3
286 * @param manager GoAcceleratorMgr object.
287 * @param sensorId Identifier of the sensor.
288 * @param param Pointer to parameter structure for accelerating the sensor.
289 * @return Operation status.
290 */
291 GoFx(kStatus) GoAcceleratorMgr_Accelerate(GoAcceleratorMgr manager, k32u sensorId, GoAcceleratorMgrSensorParam* param);
292
293 /**
294 * Decelerate (unaccelerate) a sensor.
295 *
296 * @public @memberof GoAcceleratorMgr
297 * @version Introduced in firmware 5.2.18.3
298 * @param manager GoAcceleratorMgr object.
299 * @param sensorId Identifier of the sensor.
300 * @return Operation status.
301 */
302 GoFx(kStatus) GoAcceleratorMgr_Decelerate(GoAcceleratorMgr manager, k32u sensorId);
303
304 /**
305 * Get a list of accelerated sensors. The list is returned in an array list
306 * of GoAcceleratorMgrSensorInfo. Caller must construct the kArrayList and
307 * pass the it as an argument to this API. The API will fill this list.
308 *
309 * Each entry includes the set of ports used by the accelerated sensor.
310 * If the client had specified the ports to use, then the list entry's
311 * set of ports should be the same as the client specified ports.
312 * If the client had specified the Accelerator Manager dynamically
313 * allocate ports from the configured port range, then the list entry's
314 * set of ports contains the ports allocated to the sensor.
315 * The current acceleration status of the sensor is returned in the
316 * list entry for each sensor.
317 *
318 * @public @memberof GoAcceleratorMgr
319 * @version Introduced in firmware 5.2.18.3
320 * @param manager GoAcceleratorMgr object.
321 * @param sensorList Array list of GoAcceleratorMgrSensorInfo for each
322 * accelerated sensor.
323 * @return Operation status.
324 */
325 GoFx(kStatus) GoAcceleratorMgr_ListSensors(GoAcceleratorMgr manager, kArrayList sensorList);
326
327 /**
328 * Set up the update handler so that the SDK client can receive events
329 * from the Accelerator Manager about a sensor. This step is optional. If update handler
330 * is not bound in, then client will not receive any event notifications.
331 * Update handler is called with a pointer to GoAcceleratorMgrAccelUpdate which
332 * contains event information about a sensor.
333 * The update handler does not free the memory for the GoAcceleratorMgrAccelUpdate
334 * structure.
335 *
336 * @public @memberof GoAcceleratorMgr
337 * @version Introduced in firmware 5.2.18.3
338 * @param manager GoAcceleratorMgr object.
339 * @param function Update callback handler function.
340 * @param context SDK client context for the callback handler.
341 * It is a pointer to GoAcceleratorMgrAccelUpdate.
342 * @return Operation status.
343 */
344 GoFx(kStatus) GoAcceleratorMgr_SetAccelUpdateHandler(GoAcceleratorMgr manager, kCallbackFx function, kPointer context);
345
346 /**
347 * Set the range of port numbers used to communicate with the accelerated
348 * sensors. Changes to the port range is allowed only if no sensor is
349 * configured for acceleration.
350 * Changing the port range is optional if the client application can use
351 * the default port range.
352 * The port numbers range must be within the port range limits (see
353 * GoAcceleratorMgr_GetPortRangeLimits()).
354 * Configure the port range if your network places limits on what ports are
355 * permitted for communication use or if some range of ports is known to be used
356 * by another application.
357 *
358 * @public @memberof GoAcceleratorMgr
359 * @version Introduced in firmware 5.2.18.3
360 * @param manager GoAcceleratorMgr object.
361 * @param startPort Starting port number in the range
362 * @param endPort Last port number in the range.
363 * @return Operation status.
364 */
365 GoFx(kStatus) GoAcceleratorMgr_SetPortRange(GoAcceleratorMgr manager, k16u startPort, k16u endPort);
366
367 /**
368 * Get the range of port numbers to assign to accelerated sensors.
369 * The ports within the port range are used by the Accelerator Manager
370 * to allocate ports for the accelerated sensors.
371 *
372 * @public @memberof GoAcceleratorMgr
373 * @version Introduced in firmware 5.2.18.3
374 * @param manager GoAcceleratorMgr object.
375 * @param startPort Returns the starting port number in the range
376 * @param endPort Returns the last port number in the range.
377 * @return Operation status.
378 */
379 GoFx(kStatus) GoAcceleratorMgr_GetPortRange(GoAcceleratorMgr manager, k16u* startPort, k16u* endPort);
380
381 /**
382 * Get the min and max values of the port range and the minimum number
383 * of ports within the port range. These limits are the default port range.
384 * The upper limit is set to just below the start of the ephemeral port
385 * range that are available for use by any network application.
386 *
387 * @public @memberof GoAcceleratorMgr
388 * @version Introduced in firmware 5.2.18.3
389 * @param manager GoAcceleratorMgr object.
390 * @param startLimit Returns the limit for the starting port number in the range
391 * @param endLimit Returns the limit for the last port number in the range.
392 * @param minNumPorts Returns the minimum number of ports that the range must support.
393 * @return Operation status.
394 */
395 GoFx(kStatus) GoAcceleratorMgr_GetPortRangeLimits(GoAcceleratorMgr manager, k16u* startLimit, k16u* endLimit, k16u* minNumPorts);
396
397 /**
398 * Get the number of sensors which the accelerator manager has been configured
399 * to accelerate. The count includes sensors whose acceleration may have failed
400 * for whatever reason.
401 * This is a convenient interface to find out how many sensors have
402 * been configured without having to get the list of sensors. This count
403 * should match the number of successful calls to GoAcceleratorMgr_Accelerate()
404 * less successful calls to GoAcceleratorMgr_Decelerate().
405 *
406 * @public @memberof GoAcceleratorMgr
407 * @version Introduced in firmware 5.2.18.3
408 * @param manager GoAcceleratorMgr object.
409 * @return Number of sensors configured for acceleration.
410 */
411 GoFx(kSize) GoAcceleratorMgr_AccelSensorCount(GoAcceleratorMgr manager);
412
413 #include <GoSdk/GoAcceleratorMgr.x.h>
414
415 #endif // GO_ACCELERATOR_MGR_H
GoAcceleratorMgr::GoAcceleratorMgr_SetAccelUpdateHandler
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...
k32u
GoSystem
Represents a system of Gocator devices.
kPointer
GoAcceleratorMgr::GoAcceleratorMgr_SetSystem
kStatus GoAcceleratorMgr_SetSystem(GoAcceleratorMgr manager, GoSystem system)
Assigns the SDK GoSystem object to the accelerator manager object.
GoSdk.h
Includes all Gocator SDK headers.
k16u
GoAcceleratorMgr::GoAcceleratorMgr_Construct
kStatus GoAcceleratorMgr_Construct(GoAcceleratorMgr *manager, kAlloc allocator)
Constructs the accelerator manager object.
kSize
kAlloc
kIpAddress
GoAcceleratorMgr::GoAcceleratorMgr_Accelerate
kStatus GoAcceleratorMgr_Accelerate(GoAcceleratorMgr manager, k32u sensorId, GoAcceleratorMgrSensorParam *param)
Accelerate the specified sensor with the given set of parameters.
GoAccelSensorPortAlloc.h
Declares the GoAccelSensorPortAlloc class.
GoAcceleratorMgr::GoAcceleratorMgr_AccelSensorCount
kSize GoAcceleratorMgr_AccelSensorCount(GoAcceleratorMgr manager)
Get the number of sensors which the accelerator manager has been configured to accelerate.
GoAcceleratorMgr::GoAcceleratorMgr_ListSensors
kStatus GoAcceleratorMgr_ListSensors(GoAcceleratorMgr manager, kArrayList sensorList)
Get a list of accelerated sensors.
GoAcceleratorMgrSensorParam
Structure to hold user configuration parameters from SDK client for a sensor that is to be accelerate...
Definition: GoAcceleratorMgr.h:213
GoAcceleratorMgr::GoAcceleratorMgr_Decelerate
kStatus GoAcceleratorMgr_Decelerate(GoAcceleratorMgr manager, k32u sensorId)
Decelerate (unaccelerate) a sensor.
GoSensorAccelStatus
Represents the acceleration status of a sensor that is available or being accelerated by the local ho...
GoAcceleratorMgr::GoAcceleratorMgr_GetPortRangeLimits
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.
GoAcceleratorMgr::GoAcceleratorMgr_SetPortRange
kStatus GoAcceleratorMgr_SetPortRange(GoAcceleratorMgr manager, k16u startPort, k16u endPort)
Set the range of port numbers used to communicate with the accelerated sensors.
GoAcceleratorMgrSensorInfo
Structure to return accelerated sensor information to SDK client. The param field contains informatio...
Definition: GoAcceleratorMgr.h:228
GoAcceleratorMgrAccelUpdate
Structure to hold data for the acceleration update handler.
Definition: GoAcceleratorMgr.h:200
GoSystem.h
Declares the GoSystem class.
GoAcceleratorMgr::GoAcceleratorMgr_Start
kStatus GoAcceleratorMgr_Start(GoAcceleratorMgr manager)
Starts the accelerator manager object after it has been configured.
kArrayList
kObject
kStatus
GoAcceleratorMgr::GoAcceleratorMgr_GetPortRange
kStatus GoAcceleratorMgr_GetPortRange(GoAcceleratorMgr manager, k16u *startPort, k16u *endPort)
Get the range of port numbers to assign to accelerated sensors.
GoAcceleratorMgr
Represents an GoAcceleratorMgr instance.