ISF  2.1
Intelligent Sensing Framework for Kinetis with Processor Expert
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
ci_protocol_stream.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright (c) 2014, Freescale Semiconductor, Inc.
4  *
5 */
6 
7 /*!
8  * @file ci_protocol_stream.h
9  * @brief Command Interpreter (CI) stream protocol header file.
10  *
11  */
12 
13 #ifndef CI_STREAM_H_
14 #define CI_STREAM_H_
15 
16 
17 #include "isf_target.h"
18 #include "isf.h"
19 #include "isf_ci_stream.h"
20 
21 
22 
23 /*! @brief Defines the number of bytes to store the protocol ID. */
24 #define CI_STREAM_PROTOCOL_ID_BYTESIZE (sizeof(uint8))
25 
26 /*! @brief Defines the number of bytes to store the stream ID. */
27 #define CI_STREAM_OUTPUTPACKET_STREAMID_BYTESIZE (sizeof(uint8))
28 
29 /*! @brief Defines the number of bytes to store the data set ID. */
30 #define CI_STREAM_DATASET_ID_BYTESIZE (sizeof(uint8))
31 
32 /*! @brief Defines the number of bytes to store the length of the output packet data. */
33 #define CI_STREAM_OUTPUTPACKET_LENGTH_BYTESIZE (sizeof(uint16))
34 
35 /*! @brief Defines the number of bytes to specify the number of elements. */
36 #define CI_STREAM_NUMELEMENTS_BYTESIZE (sizeof(uint8))
37 
38 /*! @brief Defines the number of bytes for 16-bit CRC value. */
39 #define STREAM_CRC_BYTESIZE (sizeof(uint16))
40 
41 
42 
43 // ------------------------------------------------------------
44 // Stream protocol to communicate with host.
45 
46 
47 /*! @brief Defines the number of bytes for host command. */
48 #define STREAM_PROTOCOL_CMD_BYTESIZE (1)
49 
50 /*! @brief Defines the number of bytes for command status. */
51 #define STREAM_PROTOCOL_CMD_STATUS_BYTESIZE (1)
52 
53 /*! @brief Defines the minimum number of bytes of a received host packet. */
54 #define STREAM_PROTOCOL_RECV_MIN_BYTESIZE (STREAM_PROTOCOL_CMD_BYTESIZE)
55 
56 /*! @brief Defines the number of bytes for host subcommand. */
57 #define STREAM_PROTOCOL_SUBCMD_BYTESIZE (1)
58 
59 
60 
61 /*! @brief Defines the minimum number of response bytes to the host
62  * not including CRC. Do not add CRC bytes into this number as CRC byte
63  * number is added dynamically dedpending on whether host has enabled CRC
64  * or not.
65  *
66  * The minimum response data are:
67  *
68  * 1 byte: Stream protocol ID
69  * 1 byte: Status byte, Command Complete (COCO) bit and 7-bit status
70  * 1 byte: Echo of host command
71 */
72 #define STREAM_PROTOCOL_RESP_MIN_BYTESIZE (3)
73 
74 
75 /*! @brief Defines the number of bytes to store the length of the response
76  * data. If there are no response data, then the data length bytes are
77  * not included in the response packet.
78  */
79 #define STREAM_PROTOCOL_RESP_RESPDATALENGTH_BYTESIZE (2)
80 
81 
82 /*! @brief Defines the fixed array size of the response buffer array.
83  * The size specified is sufficient for most commands. If a larger
84  * size is required, a dynamically allocated buffer is used.
85  *
86  * The typical size of the default response array needs to be
87  * set to accommodate:
88  *
89  * STREAM_PROTOCOL_RESP_MIN_BYTESIZE - minimum response data size
90  * STREAM_PROTOCOL_RESP_RESPDATALENGTH_BYTESIZE - needed if there is response data
91  * Response data - in most cases one byte. The host command to get trigger
92  * bytes uses the default buffer. In this case the number of
93  * trigger bytes will be no more than several bytes.
94  *
95  * Currently, the only command that requires a dynamically allocated
96  * buffer is the CI_CMD_STREAM_GETINFO_STREAM_CONFIG command.
97  */
98 #define STREAM_PROTOCOL_RESP_DEFAULT_ARRAY_BYTESIZE ( \
99  STREAM_PROTOCOL_RESP_MIN_BYTESIZE \
100  + STREAM_PROTOCOL_RESP_RESPDATALENGTH_BYTESIZE \
101  + 16)
102 
103 
104 /*! @brief Defines the indexes of the command response array to the host.
105  *
106  * The minimum command response packet contains the following:
107  *
108  * - 1 byte, stream protocol ID (not to be confused with the stream ID)
109  * - 1 byte, COCO/status byte
110  * - 1 byte, echo of the command that this response corresponds to.
111  *
112  * If the response contains returning data, the response packet contains
113  * the data bytes following:
114  *
115  * - 2 bytes, length of the data in bytes, msb first
116  * - X bytes, the data bytes
117  *
118  */
119 #define STREAM_PROTOCOL_RESP_INDEX_PROTOCOLID (0)
120 #define STREAM_PROTOCOL_RESP_INDEX_COCO_STAT (1)
121 #define STREAM_PROTOCOL_RESP_INDEX_CMD_ECHO (2)
122 #define STREAM_PROTOCOL_RESP_INDEX_NUMDATA_MSB (3)
123 #define STREAM_PROTOCOL_RESP_INDEX_NUMDATA_LSB (4)
124 #define STREAM_PROTOCOL_RESP_INDEX_DATASTART (5)
125 
126 
127 
128 /*! @brief Defines the indexes of the stream data update buffer
129  * (output packet).
130  *
131  * The stream data update packet contains the following:
132  *
133  * - 1 byte, stream protocol ID (not to be confused with the stream ID)
134  * - 1 byte, COCO/status byte
135  * - 1 byte, stream ID
136  * - 2 bytes, data length (dataset ID / data)
137  *
138  * Note that the data length specifies the number of bytes
139  * of the output format which contains the dataset ID followed
140  * by the number of bytes for that dataset. There could be
141  * multiple number of datasets per stream.
142  *
143  */
144 #define STREAM_PROTOCOL_OUTPUTPACKET_INDEX_PROTOCOLID (0)
145 #define STREAM_PROTOCOL_OUTPUTPACKET_INDEX_COCO_STAT (1)
146 #define STREAM_PROTOCOL_OUTPUTPACKET_INDEX_STREAMID (2)
147 #define STREAM_PROTOCOL_OUTPUTPACKET_INDEX_LENGTH_MSB (3)
148 #define STREAM_PROTOCOL_OUTPUTPACKET_INDEX_LENGTH_LSB (4)
149 
150 
151 
152 /*! @brief STREAM COCO bit position and mask. */
153 #define STREAM_COCO_BIT (7) // Bit position (starting at 0)
154 #define STREAM_COCO_BIT_MASK (1 << STREAM_COCO_BIT)
155 
156 
157 /*! @brief Stream protocol control: enable/disable data update. */
158 #define STREAM_PROTOCOL_DATA_ENABLED (1)
159 #define STREAM_PROTOCOL_DATA_DISABLED (0)
160 
161 
162 /*! @brief Macros to access buffer received from host. */
163 #define ci_stream_get_host_cmd(pSrc) (pSrc[0] & 0xFF)
164 #define ci_stream_get_host_data(pSrc) (pSrc[1])
165 
166 
167 /*! @ brief Macros to access parameters for:
168  * CI_CMD_STREAM_CREATE_STREAM
169  */
170 #define cmd_createstream_get_streamID(pSrc) (pSrc[0])
171 #define cmd_createstream_get_numelements(pSrc) (pSrc[1])
172 #define cmd_createstream_get_trigmask_ptr(pSrc) (&pSrc[2])
173 
174 
175 
176 
177 /*!
178  * @brief Stream protocol control register 1 Structure.
179  *
180  * enable_stream_data : 0 - Stream data disabled, 1 - Stream data enabled
181  * enable_crc : 0 - CRC generation/checking disabled, 1 - CRC enabled
182  * reserved1 : Reserved Bits
183  *
184  * @struct ci_stream_ctrl_reg1_t
185  */
186 typedef union {
188  struct {
189  uint8 enable_stream_data :1; // Enable/disable stream data update
190  uint8 enable_crc :1; // CRC enable/disable
191  uint8 reserved1 :6; // Reserved
192  } Bits;
194 
195 
196 
197 /*!
198  * @brief Stream protocol registers Structure. Contains stream protocol
199  * control registers.
200  *
201  * @struct ci_stream_regs_t
202  */
203 typedef struct
204 {
205  ci_stream_ctrl_reg1_t StreamCtrlReg1; // Control register 1
207 
208 
209 
210 
211 /*!
212  * @brief Stream instance structure is used internally to encapsulate
213  * the information of a stream and the current trigger state of the
214  * dataset(s) belonging to that stream. It also contains a pointer
215  * to the next stream to create a single linked list of streams.
216  *
217  * @struct ci_stream_instance_t
218  */
219 typedef struct __attribute__ ((__packed__)) _ci_stream_instance
220 {
221 
222  ci_stream_config_t *pStreamConfig; // Configuration for this stream
223 
224  uint8 *pStreamBuffer; // Pointer to stream data buffer which contains all
225  // necessary data to be sent to the host. This
226  // includes:
227  // - Stream protocol ID
228  // - COCO/status
229  // - Stream ID
230  // - Data length (of all dataset ID(s) and length(s) associated with those IDs)
231  // - Dataset ID(s) and data for each dataset
232 
233  uint8 *pTriggerState; // Current trigger state. When initialized, the trigger mask
234  // from the stream configuration is copied to the trigger state.
235  // Each bit corresponds to a dataset.
236  // Bit meaning:
237  // 1 - data for the dataset has NOT been updated
238  // 0 - data for the dataset is ready to be sent to the host
239 
240  struct _ci_stream_instance *pNextInstance; // Pointer to the next stream instance, if any. This pointer points
241  // to NULL if this is the last instance in the linked list.
242 
244 
245 
246 
247 
248 #endif // CI_STREAM_H_
ISF board support header files.
unsigned char uint8
This defines uint8 as unsigned char.
Definition: isf_types.h:18
Stream protocol control register 1 Structure.
ISF Command Interpreter (CI) stream protocol header file.
ci_stream_instance_t
ci_stream_config_t
Main ISF header file. Contains code common to all ISF components.
ci_stream_ctrl_reg1_t StreamCtrlReg1
Stream protocol registers Structure. Contains stream protocol control registers.
struct __attribute__((__packed__)) _ci_stream_instance
This structure contains the stream configuration information.