ISF  2.1
Intelligent Sensing Framework for Kinetis with Processor Expert
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
isf_ci_stream.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright (c) 2014, Freescale Semiconductor, Inc.
4  *
5 */
6 
7 /*!
8  * @file isf_ci_stream.h
9  * @brief ISF Command Interpreter (CI) stream protocol header file.
10  *
11  */
12 
13 #ifndef ISF_CI_STREAM_H_
14 #define ISF_CI_STREAM_H_
15 
16 
17 #include "isf.h"
18 
19 
20 
21 
22 /*!
23  * @brief CI host stream command.
24  *
25  * @details The host indicates which command the stream protocol runs.
26  * ::ci_commands_stream_enum is used to identify this command. The maximum
27  * number of possible commands is 128 represented by 7 bits.
28  *
29 */
30 typedef enum
31 {
32  /*! The host resets the stream protocol which deletes all instances. */
34 
35  /*! The host enables stream data updates. */
37 
38  /*! The host enables stream data updates. */
40 
41  /*! The host creates a stream. */
43 
44  /*! The host deletes a stream. */
46 
47  /*! The host resets a stream trigger. */
49 
50  /*! The host enables CRC generation in the stream packet. */
52 
53  /*! The host disables CRC generation in the stream packet. */
55 
56  /*! The host requests to get the current number of streams. */
58 
59  /*! The host requests the trigger state of a given stream ID. */
61 
62  /*! The host requests to get the stream configuration of a given stream ID. */
64 
65  /*! The host requests to get the first stream ID. */
67 
68  /*! The host requests to get the next stream ID. */
70 
71  /*! Maximum currently defined CI stream commands. */
73 
74  /*! Maximum number of possible CI stream commands is 128 (7-bits). */
75 
77 
78 
79 
80 /*! @brief These are the CI stream protocol errors provided to the host.
81  *
82  * @details Any errors identified by the stream protocol are returned
83  * to the host. These errors may be passed back to the host from the
84  * application. There are 7 bits allocated to contain error status
85  * resulting in 128 possible different status values.
86  *
87  * Bit6 of the status byte is used to indicate error condition. If
88  * bit6 = 1, then the value in bit0-5 contains the specific error
89  * condition. If bit6 = 0, then the value in bit0-5 contains the
90  * specific status.
91 */
92 
93 #define CI_STATUS_STREAM_SPECIFIC_STATUS (0xBF) // Bit6 cleared
94 #define CI_STATUS_STREAM_SPECIFIC_ERROR (0x40) // Bit6 set
95 
96 typedef enum
97 {
98 
99 
100  // --------------------------------------
101  // General protocol status.
102 
103  /*! This status indicates a success. */
105 
106  /*! This error indicates a general error. */
108 
109 
110 
111  // --------------------------------------
112  // Stream specific status
113 
114  /*! This status indicates data was sent to the host. */
116 
117  /*! This indicates the dataset ID does not exists. */
119 
120  /*! This indicates end of the stream list has been reached. */
122 
123 
124  // --------------------------------------
125  // Stream specific error status
126 
127  /*! This error indicates an invalid host command. */
129 
130  /*! This error indicates one or more invalid parameters. */
132 
133  /*! This error indicates invalid number of parameters. */
135 
136  /*! This error indicates no streams exists. */
138 
139  /*! This error indicates a given pointer is NULL. */
141 
142  /*! This error indicates the stream ID does not exists. */
144 
145  /*! This error indicates the stream ID already exists. */
147 
148  /*! This error indicates the dataset ID does not exists. */
150 
151  /*! This error indicates the dataset ID already exists. */
153 
154  /*! This error indicates the dataset length is invalid (zero). */
156 
157  /*! This error indicates the number of elements is invalid (zero). */
159 
160  /*! This error indicates out of memory condition. */
162 
163  /*! This error indicates an error in sending data to the host. */
165 
166  /*! This error indicates the CRC check failed. */
168 
169 
170  /*! The maximum possible status value. */
172 
174 
175 
176 
177 /*! @brief Stream control: enable/disable CRC generation/checking. */
178 #define STREAM_CRC_ENABLED (1)
179 #define STREAM_CRC_DISABLED (0)
180 
181 
182 
183 
184 /*! @brief This structure contains the stream element information.
185  *
186  * @details The stream element structure contains information of a
187  * dataset that includes an ID, the byte length, and the byte offset.
188  * Stream elements are part of the stream configuration structure.
189  *
190  */
191 typedef struct __attribute__ ((__packed__)) _ci_stream_element
192 {
193  /*! Dataset ID */
194  uint8 datasetID;
195 
196  /*! Length in bytes of the dataset */
197  uint16 length;
198 
199  /*! Offset n bytes of the dataset */
200  uint16 offset;
201 
203 
204 
205 
206 
207 /*! @brief This structure contains the stream configuration
208  * information.
209  *
210  * @details The stream configuration structure contains information
211  * about the stream that includes the stream ID, number of elements,
212  * trigger masks, and element list.
213  *
214  */
215 typedef struct __attribute__ ((__packed__)) _ci_stream_config
216 {
217 
218  /*! Stream ID */
219  uint8 streamID;
220 
221  /*! Number of elements */
222  uint8 numElements;
223 
224  /*! Buffer containing the trigger mask bytes */
225  uint8 *pTriggerMask;
226 
227  /*! Buffer containing the element list */
228  ci_stream_element_t *pElementList;
229 
231 
232 
233 
234 
235 /*!
236  *
237  * @brief This API creates a stream.
238  *
239  * @details This API creates a stream with the given parameters. It dynamically
240  * allocates memory to create a buffer to store all the information required
241  * to operation the stream.
242  *
243  *
244  * @param [in] aStreamID Stream ID value.
245  *
246  * @param [in] aNumElements The number of elements or datasets in the stream.
247  *
248  * @param [in] apTriggerMask Pointer to the trigger mask buffer. This buffer
249  * consists if an array of byte(s) with each bit corresponding
250  * a dataset in the element list. Bit 0 of the first trigger byte
251  * corresponds to the first dataset in apElementList. Bit 1 of
252  * the first trigger byte corresponds to the second dataset in
253  * apElementList and so on. Each trigger byte can respresent up
254  * to 8 datasets in apElementList.
255  *
256  * During the creation process, the data from this buffer
257  * is copied over to the stream being created.
258  *
259  * @param [in] apElementList Pointer to a buffer containing a list of datasets.
260  * Each dataset is defined in the list as follows:
261  *
262  * Offset Size Description
263  * 0 1 byte Dataset ID
264  * 1 2 bytes Length, msb first
265  * 3 2 bytes Offset, msb first
266  *
267  * During the creation process, the data from this buffer is
268  * copied over to the stream being created.
269  *
270  * @return isf_ci_stream_create() returns a value of type
271  * ::isf_status_t providing the status of the stream creation
272  * operation.
273  *
274  * @retval ::ISF_SUCCESS The stream was created successfully.
275  *
276  * @retval ::CI_STATUS_STREAM_ERR_NULL_POINTER The apTriggerMask and/or
277  * the apElementList pointers are NULL.
278  *
279  * @retval ::CI_STATUS_STREAM_ERR_INVALID_NUM_PARM The number of parameter
280  * bytes provided to create the stream is not sufficient.
281  *
282  * @retval ::CI_STATUS_STREAM_ERR_NUMELEMENTS_INVALID The aNumElements
283  * value is zero.
284  *
285  * @retval ::CI_STATUS_STREAM_ERR_STREAMID_EXISTS The aStreamID
286  * value specifies a stream ID that already exists.
287  *
288  * @retval ::CI_STATUS_STREAM_ERR_OUT_OF_MEMORY The system is out
289  * of memory and the stream cannot be created.
290  *
291  *
292  * @constraints The following constraints must be observed when using
293  * this function. If these constraints are not met, this
294  * API returns an error.
295  * @li aStreamID must refer to a stream that does NOT exists.
296  * @li apTriggerMask and apElementList must not be NULL.
297  * @li aNumElements must not be zero.
298  *
299  * @reentrant Yes.
300  *
301  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
302  *
303 */
304 isf_status_t isf_ci_stream_create(uint8 aStreamID, uint8 aNumElements, uint8 *apTriggerMask, ci_stream_element_t *apElementList);
305 
306 
307 
308 
309 
310 /*!
311  *
312  * @brief This API updates the data of a dataset.
313  *
314  * @details This API updates the data of the given dataset ID. The data is
315  * updated under two conditions that must exist:
316  *
317  * - The dataset ID exists in a stream. Streams can contain multiple
318  * datasets with the same ID and these datasets may have lengths
319  * and offsets that are the same or different.
320  *
321  * - The dataset region as defined in the stream overlaps with the given
322  * region provided in the parameters.
323  *
324  * If a dataset in any streams meet these conditions, the overlapped region
325  * of the dataset data is updated and the trigger state bit associated with
326  * the dataset ID is cleared. If all trigger state bits of the stream is
327  * cleared, the data is sent to the host if stream update is enabled.
328  *
329  *
330  * @param [in] aDataSetID ID of the dataset to update
331  *
332  * @param [in] aLength The byte length of data to update.
333  *
334  * @param [in] aOffset The offset of the data to update. It references the
335  * offset of the data buffer that the application makes
336  * available to the host.
337  *
338  * @param [in] apSrc Pointer to the source of the data to perform the
339  * update. If the dataset ID matches and the data region
340  * overlaps, the source data is copied to the stream buffer.
341  *
342  * @return isf_ci_stream_update_data() returns a value of type
343  * ::isf_status_t providing the status of the data update
344  * operation.
345  *
346  * @retval ::ISF_SUCCESS Dataset(s) data were updated. No data was
347  * sent to the host because not all trigger state bits are
348  * cleared.
349  *
350  * @retval ::CI_STATUS_STREAM_ERR_NULL_POINTER The apSrc is NULL.
351  *
352  * @retval ::CI_STATUS_STREAM_ERR_DATASET_LENGTH_INVALID The aLength
353  * value is zero.
354  *
355  * @retval ::CI_STATUS_STREAM_ERR_SENDDATA_TO_HOST An error was
356  * encountered in sending data to the host.
357  *
358  * @retval ::CI_STATUS_STREAM_DATASETID_NOTUSED The dataset ID
359  * was not found in any streams. No data was updated.
360  *
361  * @retval ::CI_STATUS_STREAM_DATA_UPDATE An update data packet was
362  * sent to the host.
363  *
364  *
365  * @constraints The following constraints must be observed when using
366  * this function. If these constraints are not met, this
367  * API returns an error.
368  * @li aDataSetID must refer to a dataset that exists.
369  * @li aLength must not be zero.
370  * @li apSrc must not be NULL.
371  *
372  * @reentrant Yes.
373  *
374  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
375  *
376 */
377 isf_status_t isf_ci_stream_update_data(uint8 aDataSetID, uint16 aLength, uint16 aOffset, uint8 *apSrc);
378 
379 
380 
381 
382 /*!
383  *
384  * @brief This API deletes the given stream ID.
385  *
386  * @details This API deletes the given stream ID. Its memory is
387  * deallocated and the stream linked list is reordered.
388  *
389  * @param [in] aStreamID Stream ID value of the stream to delete.
390  *
391  * @return isf_ci_stream_delete() returns a value of type
392  * ::isf_status_t providing the status of the stream
393  * creation operation.
394  *
395  * @retval ::ISF_SUCCESS The stream ID was found and the stream
396  * deleted.
397  *
398  * @retval ::CI_STATUS_STREAM_ERR_STREAM_NOEXISTS The aStreamID
399  * value specifies a stream ID that does not exists.
400  *
401  *
402  * @constraints The following constraints must be observed when using
403  * this function. If these constraints are not met, this
404  * API returns an error.
405  * @li aStreamID must refer to a stream that exists.
406  *
407  * @reentrant Yes.
408  *
409  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
410  *
411 */
413 
414 
415 /*!
416  *
417  * @brief This API resets the trigger bits of the the given stream ID.
418  *
419  * @details This API resets the trigger state of the given stream ID.
420  * The trigger state is set to the trigger mask that was provided
421  * during stream creation.
422  *
423  * @param aStreamID Stream ID value of the stream to reset
424  * the trigger state.
425  *
426  * @return isf_ci_stream_reset_trigger() returns a value of type
427  * ::isf_status_t providing the status of the stream
428  * creation operation.
429  *
430  * @retval ::ISF_SUCCESS The stream ID was found and its
431  * trigger state reset to the trigger mask.
432  *
433  * @retval ::CI_STATUS_STREAM_ERR_STREAM_NOEXISTS The aStreamID
434  * value specifies a stream ID that does not exists.
435  *
436  *
437  * @constraints The following constraints must be observed when using
438  * this function. If these constraints are not met, this
439  * API returns an error.
440  * @li aStreamID must refer to a stream that exists.
441  *
442  * @reentrant Yes.
443  *
444  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
445  *
446 */
448 
449 
450 
451 /*!
452  *
453  * @brief This API gets the stream configuration of the specified stream ID.
454  *
455  * @param [in] aStreamID Stream ID value of the configuration to retrieve.
456  *
457  * @return isf_ci_stream_get_config() returns a pointer of the type
458  * ::ci_stream_config_t of the configuration associated with
459  * the given stream ID. The pointer value is NULL if the
460  * configuration does not exists.
461  *
462  * @constraints The following constraints must be observed when using
463  * this function. If these constraints are not met, this
464  * API returns an error.
465  * @li aStreamID must refer to a stream that exists. If
466  * the stream does not exists, a NULL value is returned.
467  *
468  * @reentrant Yes.
469  *
470  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
471  *
472 */
474 
475 
476 
477 /*!
478  *
479  * @brief This API returns the trigger state of the given stream ID.
480  *
481  * @details This API returns the trigger state bytes of the given
482  * stream ID. The trigger state is copied to the trigger buffer
483  * provided by the caller.
484  *
485  *
486  * @param [in] aStreamID Stream ID value of the stream to get
487  * the trigger state.
488  *
489  * @param [in,out] apTrigger Pointer to the trigger byte array. The
490  * trigger state of the stream is copied to this byte
491  * array. This value is NULL if the stream ID does not
492  * exists. The caller must provide an array large enough
493  * to hold all of the trigger bytes.
494  *
495  * Each bit in the trigger byte corresponds to a dataset.
496  *
497  * @return isf_ci_stream_get_trigger() returns a value of type
498  * ::isf_status_t providing the status of the stream
499  * creation operation.
500  *
501  * @retval ::ISF_SUCCESS The stream ID was found and its
502  * trigger state reset to the trigger mask.
503  *
504  * @retval ::CI_STATUS_STREAM_ERR apTrigger is NULL.
505  *
506  * @retval ::CI_STATUS_STREAM_ERR_STREAM_NOEXISTS The aStreamID
507  * value specifies a stream ID that does not exists.
508  *
509  *
510  * @constraints The following constraints must be observed when using
511  * this function. If these constraints are not met, this
512  * API returns an error.
513  * @li aStreamID must refer to a stream that exists.
514  * @li apTrigger must not be NULL.
515  *
516  * @reentrant Yes.
517  *
518  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
519  *
520 */
521 isf_status_t isf_ci_stream_get_trigger(uint8 aStreamID, uint8 *apTrigger);
522 
523 
524 
525 /*!
526  *
527  * @brief This API returns the number of streams.
528  *
529  * @details This API returns the number of streams that currently exists.
530  *
531  * @return isf_ci_stream_get_num_streams() returns the number
532  * of streams that currently exists.
533  *
534  * @constraints None
535  *
536  * @reentrant Yes.
537  *
538  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
539  *
540 */
542 
543 
544 
545 
546 /*!
547  *
548  * @brief This API returns the configuration of the first stream in the
549  * linked list.
550  *
551  * @details This API returns a pointer to the configuration of the
552  * first stream in the linked list. If no stream exists, NULL is returned.
553  *
554  * @return isf_ci_stream_get_first() returns a pointer to
555  * the configuration of the first stream.
556  *
557  * @constraints None
558  *
559  * @reentrant Yes.
560  *
561  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
562  *
563  * @see isf_ci_stream_get_next()
564 */
566 
567 
568 /*!
569  *
570  * @brief This API returns the configuration of the next stream in the
571  * linked list.
572  *
573  * @details This API returns a pointer to the configuration of the
574  * next stream in the linked list. The stream returned is the next stream
575  * in the list from the previous isf_ci_stream_get_first() or
576  * isf_ci_stream_get_next() call. If no stream exists, NULL is returned.
577  *
578  *
579  * @return isf_ci_stream_get_next() returns a pointer to
580  * the configuration of the next stream in the linked list.
581  *
582  * @constraints None
583  *
584  * @reentrant Yes.
585  *
586  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
587  *
588  * @see isf_ci_stream_get_next()
589 */
591 
592 
593 
594 /*!
595  *
596  * @brief This API sets the cyclic redundancy check (CRC) code generation
597  * to the requested state.
598  *
599  * @details This API is used to enable or disable the CRC state. If enabled,
600  * CRC code is generated and sent as part of any data packets going to the
601  * host for the stream protocol. Also, any packet received from the host
602  * is expected to have a CRC bytes that are checked against the received data.
603  * If disabled, no CRC data is generated for packets going to the host and no
604  * CRC check is performed for packets received from the host.
605  *
606  * The CRC used by the stream protocol is the CCITT CRC16. This method uses
607  * two bytes (16-bit). If CRC bytes are generated for a data packet destined
608  * for the host, the bytes are placed at the end of the packet but before the
609  * end marker byte (0x7E). The same CRC byte placement is expected of data
610  * packets from the host to the stream protocol.
611  *
612  * If CRC is enabled by the host using the CI_CMD_STREAM_ENABLE_CRC command,
613  * the response packet to the host for this command will have the CRC bytes
614  * as part of the packet.
615  *
616  * If CRC is disabled by the host using the CI_CMD_STREAM_DISABLE_CRC command,
617  * the response packet to the host for this command will NOT have the CRC bytes
618  * as part of the packet.
619  *
620  * @param [in] acrcEnable Requested state of CRC.
621  * ::STREAM_CRC_ENABLED to enable CRC generation and checking.
622  * ::STREAM_CRC_DISABLED to disabke CRC generation and checking.
623  *
624  * @return None
625  *
626  * @constraints None
627  *
628  * @reentrant Yes.
629  *
630  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
631  *
632  * @see isf_ci_stream_get_next()
633 */
634 void isf_ci_stream_set_CRC(boolean acrcEnable);
635 
636 
637 
638 /*! @brief This is a CI stream protocol intialization callback function pointer.
639  *
640  * @details A callback that implements the initialization for the CI stream
641  * protocol.
642  *
643  * @param [in] aprotocolID The protocol ID assigned to the protocol.
644  * The protocol initialization function is required to
645  * save the ID and include the ID in data packets sent
646  * back to the host.
647  *
648  * @param [in] apInitData Pointer to the user defined data.
649  *
650  * @retval ::ISF_SUCCESS The initialization callback completed
651  * successfully.
652  *
653  * @retval ::ISF_ERR_LIB_INIT The initialization callback
654  * failed to initialize.
655  *
656  * @Constraints None
657  *
658  * @Reentrant No
659  *
660  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
661  *
662  * @see isf_status_t
663  *
664  */
665 isf_status_t ci_stream_init(uint8 aprotocolID, void *apInitData);
666 
667 
668 
669 /*! @brief This is a CI stream protocol callback function pointer.
670  *
671  * @details A callback that implements the CI stream protocol.
672  * This callback is invoked if a packet is received with a protocol
673  * ID matching the ID that was assigned to this protocol during
674  * initialization.
675  *
676  *
677  * @param [in] anumBytes The number of bytes that the host has
678  * sent to the protocol. The data resides in the
679  * apSrc buffer.
680  *
681  * @param [in] apSrc Pointer to the received data from the host.
682  *
683  * @param [in,out] apnumDestBytes As an input, this parameter specifies
684  * maxinum size of the destination buffer apDest. As an
685  * output this parameter specifies the actual size of
686  * the number of bytes used in the buffer apDest.
687  *
688  * @param [out] apDest Pointer to the processed data.
689  *
690  * @retval The callback function returns the protocol ID value of
691  * the next protocol to be invoked. If no more protocols
692  * are to be called, the callback function returns a zero
693  * to notify the CI to sends the destination buffer to the
694  * host.
695  *
696  * @Constraints The following constraints must be observed when using
697  * this function. If these constraints are not met, this
698  * API returns an error.
699  * @li anumSrcBytes must be equal to or greater than the
700  * minimum number of bytes the specific protocol may
701  * require. This requirement is protocol dependent.
702  *
703  * @Reentrant No
704  *
705  * @libs libisf_core_m0p.a, libisf_core_m4f.a, libisf_core_m4.a
706  *
707  * @see isf_status_t
708  *
709  */
710 isf_status_t ci_protocol_CB_stream(uint32 anumBytes, uint8 *apSrc, uint32 *apnumDestBytes, uint8 *apDest);
711 
712 
713 #endif // ISF_CI_STREAM_H_
714 
715 
716 
717 
718 
719 
720 
721 
722 
723 
724 
725 
unsigned char uint8
This defines uint8 as unsigned char.
Definition: isf_types.h:18
ci_response_stream_enum
Definition: isf_ci_stream.h:96
isf_status_t isf_ci_stream_reset_trigger(uint8 aStreamID)
This API resets the trigger bits of the the given stream ID.
unsigned long uint32
This defines uint32 as unsigned long.
Definition: isf_types.h:36
ci_stream_config_t * isf_ci_stream_get_first(void)
This API returns the configuration of the first stream in the linked list.
ci_stream_config_t * isf_ci_stream_get_config(uint8 aStreamID)
This API gets the stream configuration of the specified stream ID.
ci_stream_config_t * isf_ci_stream_get_next(void)
This API returns the configuration of the next stream in the linked list.
isf_status_t isf_ci_stream_delete(uint8 aStreamID)
This API deletes the given stream ID.
uint8 isf_ci_stream_get_num_streams(void)
This API returns the number of streams.
void isf_ci_stream_set_CRC(boolean acrcEnable)
This API sets the cyclic redundancy check (CRC) code generation to the requested state.
isf_status_t isf_ci_stream_create(uint8 aStreamID, uint8 aNumElements, uint8 *apTriggerMask, ci_stream_element_t *apElementList)
This API creates a stream.
ci_stream_config_t
#define CI_STATUS_STREAM_SPECIFIC_ERROR
Definition: isf_ci_stream.h:94
Main ISF header file. Contains code common to all ISF components.
#define CI_STATUS_STREAM_SPECIFIC_STATUS
These are the CI stream protocol errors provided to the host.
Definition: isf_ci_stream.h:93
ci_stream_element_t
ci_commands_stream_enum
CI host stream command.
Definition: isf_ci_stream.h:30
unsigned short uint16
This defines uint16 as unsigned short.
Definition: isf_types.h:27
isf_status_t isf_ci_stream_get_trigger(uint8 aStreamID, uint8 *apTrigger)
This API returns the trigger state of the given stream ID.
int32 isf_status_t
ISF return status type.
Definition: isf.h:51
struct __attribute__((__packed__)) _ci_stream_element
This structure contains the stream element information.
isf_status_t ci_protocol_CB_stream(uint32 anumBytes, uint8 *apSrc, uint32 *apnumDestBytes, uint8 *apDest)
This is a CI stream protocol callback function pointer.
isf_status_t isf_ci_stream_update_data(uint8 aDataSetID, uint16 aLength, uint16 aOffset, uint8 *apSrc)
This API updates the data of a dataset.
isf_status_t ci_stream_init(uint8 aprotocolID, void *apInitData)
This is a CI stream protocol intialization callback function pointer.