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_protocol.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_protocol.h
9  * @brief Command Interpreter (CI) Protocol header file.
10  *
11  */
12 
13 #ifndef CI_PROTOCOL_H_
14 #define CI_PROTOCOL_H_
15 
16 
17 #include "isf.h"
18 
19 /*! @brief These are the CI protocol IDs.
20  *
21  * @details CI protocol ID defined here should not be used by
22  * user applications. The user can add custom protocol ID values that
23 */
24 typedef enum
25 {
26  /*! This protocol ID is reserved and must not be used. */
27  CI_PROTOCOL_ID_NULL = 0, /* Reserved, do not modify. */
28 
29  /*! This protocol ID is for the legacy mailbox interface. This protocol ID is
30  * reserved and must not be used. */
31  CI_PROTOCOL_ID_MBOX = 1, /* Reserved, do not modify. */
32 
34 
35  /*! This protocol ID is the maximum that the user can defined for custom protocol. */
36  CI_PROTOCOL_ID_MAX = 255 /* Maximum value of 255. */
37 
39 
40 
41 
42 
43 /*!
44  * @brief Define the number of bytes for the protocol ID.
45  * Do not modify.
46  */
47 #define CI_PROTOCOL_ID_SIZE (1)
48 
49 /*!
50  * @brief Define offset to where protocol data begins of the send/receive buffer that skips
51  * pass the protocol id. Do not modify.
52  */
53 #define CI_PROTOCOL_DATA_OFFSET (1)
54 
55 /*!
56  * @brief Define the index of the send/receive buffer of where the protocol ID resides.
57  * Do not modify.
58  */
59 #define CI_PROTOCOL_ID_INDEX (0)
60 
61 /*!
62  * @brief Define the minimum number of bytes for the CI wrapper that encapsulates
63  * the protocol data.
64  */
65 #define CI_MIN_RX_BYTES (CI_PROTOCOL_ID_SIZE) // Just the protocol ID is required.
66 
67 
68 /*!
69  * @brief Define the maximum allowable CI protocols.
70  */
71 #define CI_MAX_PROTOCOL (CI_PROTOCOL_ID_MAX)
72 
73 
74 
75 /*! @brief This is a CI protocol callback function pointer.
76  *
77  * @details A callback that implements a user defined CI protocol.
78  * This callback is invoked if a packet is received with a protocol
79  * ID matching the ID that was assigned to this protocol during
80  * initialization.
81  *
82  *
83  * @param [in] anumSrcBytes The number of bytes that the host has
84  * sent to the protocol. The data resides in the
85  * apSrc buffer.
86  *
87  * @param [in] apSrc Pointer to the received data from the host.
88  *
89  * @param [in,out] apnumDestBytes As an input, this parameter specifies
90  * maxinum size of the destination buffer apDest. As an
91  * output this parameter specifies the actual size of
92  * the number of bytes used in the buffer apDest.
93  *
94  * @param [out] apDest Pointer to the processed data.
95  *
96  * @retval The callback function returns the protocol ID value of
97  * the next protocol to be invoked. If no more protocols
98  * are to be called, the callback function returns a zero
99  * to notify the CI to sends the destination buffer to the
100  * host.
101  *
102  * @Constraints The following constraints must be observed when using
103  * this function. If these constraints are not met, this
104  * API returns an error.
105  * @li anumSrcBytes must be equal to or greater than the
106  * minimum number of bytes the specific protocol may
107  * require. This requirement is protocol dependent.
108  *
109  * @Reentrant No
110  *
111  * @Libs isf_ci.lib
112  *
113  * @see isf_status_t
114  *
115  */
116 typedef isf_status_t (*ci_protocol_callback_funcp_t)(uint32 anumSrcBytes, uint8 *apSrc, uint32 *apnumDestBytes, uint8 *apDest);
117 
118 
119 
120 /*! @brief This is a CI protocol intialization callback function pointer.
121  *
122  * @details A callback that implements the initialization for a user
123  * defined CI protocol.
124  *
125  * @param [in] aprotocolID The protocol ID assigned to the protocol.
126  * The protocol initialization function is required to
127  * save the ID and include the ID in data packets sent
128  * back to the host.
129  *
130  * @param [in] apInitData Pointer to the user defined data.
131  *
132  * @retval ::ISF_SUCCESS The initialization callback completed
133  * successfully.
134  *
135  * @retval ::ISF_ERR_LIB_INIT The initialization callback
136  * failed to initialize.
137  *
138  * @Constraints None
139  *
140  * @Reentrant No
141  *
142  * @Libs isf_ci.lib
143  *
144  * @see isf_status_t
145  *
146  */
147 typedef isf_status_t (*ci_protocol_init_funcp_t)(uint8 aprotocolID, void *apInitData);
148 
149 
150 
151 /*!
152  * @brief This structure binds a protocol ID to a set of related functions and data.
153  * When a packet is received from the host, the CI task will invoke the callback that
154  * is associated with the protocol ID that is part of the CI packet header.
155  *
156  * @struct ci_protocol_t
157 */
158 typedef struct
159 {
160  ci_protocol_init_funcp_t *pProtocolInit; //! Protocol initialization
161  ci_protocol_callback_funcp_t *pProtocolCB; //! Callback function associated with the protocol ID
162  uint32 destBufferSize; //! Protocol destination buffer size.
163  uint8 protcolID; //! Protocol ID associated with the callback function.
164 } ci_protocol_t;
165 
166 
167 /*!
168  * @brief This is the pointer to the user defined data structure to be passed into the
169  * ci_protocol_init_funcp_t function during protocol initialization.
170  *
171  * @typedef ci_protocol_initdata_ptr_t
172 */
174 
175 
176 
177 
178 
179 
180 
181 #endif /* CI_PROTOCOL_H_ */
unsigned char uint8
This defines uint8 as unsigned char.
Definition: isf_types.h:18
isf_status_t(* ci_protocol_init_funcp_t)(uint8 aprotocolID, void *apInitData)
This is a CI protocol intialization callback function pointer.
void * ci_protocol_initdata_ptr_t
This is the pointer to the user defined data structure to be passed into the ci_protocol_init_funcp_t...
unsigned long uint32
This defines uint32 as unsigned long.
Definition: isf_types.h:36
uint8 protcolID
Protocol destination buffer size.
ci_protocol_callback_funcp_t * pProtocolCB
Protocol initialization.
uint32 destBufferSize
Callback function associated with the protocol ID.
Main ISF header file. Contains code common to all ISF components.
ci_protocol_init_funcp_t * pProtocolInit
int32 isf_status_t
ISF return status type.
Definition: isf.h:51
This structure binds a protocol ID to a set of related functions and data. When a packet is received ...
isf_status_t(* ci_protocol_callback_funcp_t)(uint32 anumSrcBytes, uint8 *apSrc, uint32 *apnumDestBytes, uint8 *apDest)
This is a CI protocol callback function pointer.
ci_protocol_id_internal_enum
These are the CI protocol IDs.