MSP430 DLL API Documentation  3.14.0.0
MSP430_EnergyTrace.h
Go to the documentation of this file.
1 /*
2  * MSP430_EnergyTrace.h
3  *
4  * API for accessing Energy Trace functionality of MSP430 library.
5  *
6  * Copyright (c) 2004 - 2016 Texas Instruments Incorporated - http://www.ti.com/
7  *
8  * All rights reserved not granted herein.
9  * Limited License.
10  *
11  * Texas Instruments Incorporated grants a world-wide, royalty-free,
12  * non-exclusive license under copyrights and patents it now or hereafter
13  * owns or controls to make, have made, use, import, offer to sell and sell ("Utilize")
14  * this software subject to the terms herein. With respect to the foregoing patent
15  * license, such license is granted solely to the extent that any such patent is necessary
16  * to Utilize the software alone. The patent license shall not apply to any combinations which
17  * include this software, other than combinations with devices manufactured by or for TI (“TI Devices”).
18  * No hardware patent is licensed hereunder.
19  *
20  * Redistributions must preserve existing copyright notices and reproduce this license (including the
21  * above copyright notice and the disclaimer and (if applicable) source code license limitations below)
22  * in the documentation and/or other materials provided with the distribution
23  *
24  * Redistribution and use in binary form, without modification, are permitted provided that the following
25  * conditions are met:
26  *
27  * * No reverse engineering, decompilation, or disassembly of this software is permitted with respect to any
28  * software provided in binary form.
29  * * any redistribution and use are licensed by TI for use only with TI Devices.
30  * * Nothing shall obligate TI to provide you with source code for the software licensed and provided to you in object code.
31  *
32  * If software source code is provided to you, modification and redistribution of the source code are permitted
33  * provided that the following conditions are met:
34  *
35  * * any redistribution and use of the source code, including any resulting derivative works, are licensed by
36  * TI for use only with TI Devices.
37  * * any redistribution and use of any object code compiled from the source code and any resulting derivative
38  * works, are licensed by TI for use only with TI Devices.
39  *
40  * Neither the name of Texas Instruments Incorporated nor the names of its suppliers may be used to endorse or
41  * promote products derived from this software without specific prior written permission.
42  *
43  * DISCLAIMER.
44  *
45  * THIS SOFTWARE IS PROVIDED BY TI AND TI’S LICENSORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
46  * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
47  * IN NO EVENT SHALL TI AND TI’S LICENSORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
48  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
49  * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
50  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
51  * POSSIBILITY OF SUCH DAMAGE.
52  */
53 
54 #include "MSP430.h"
55 
56 /*
57 Record format
58 -------------
59 
60 The default record format for operation mode 1 for the MSP430FR5859 is 22bytes for each record consisting of:
61 [8byte header][8byte device State][4byte current I in nA][2byte voltage V in mV][4byte energy E in uWsec= 100 nJ]
62 
63 Where the header consists of:
64 [1byte eventID][7byte timestamp in usec]
65 
66 The eventID defines the number of arguments following the header.
67  eventID = 1 : I     value,  32 bits current
68  eventID = 2 : V     value,  16 bits voltage
69  eventID = 3 : I & V values, 32 bits current, 16 bits voltage
70  eventID = 4 : S     value,  64 bits state (default type for ET_PROFILING_DSTATE)
71  eventID = 5 : S & I values, 64 bits state, 32 bits current
72  eventID = 6 : S & V values, 64 bits state, 16 bits voltage
73  eventID = 7 : S & I & V & E values, 64 bits state, 32 bits current, 16 bits voltage, 32 bits energy (default type for ET_PROFILING_ANALOG_DSTATE)
74  eventID = 8 : I & V & E values, 32 bits current, 16 bits voltage, 32 bits energy (default type for ET_PROFILING_ANALOG)
75  eventID = 9 : S & I & V values, 64 bits state, 32 bits current, 16 bits voltage
76 
77 
78 Recommended initialisation settings & sequence
79 ----------------------------------------------
80 
81 1. For MSP430 microcontrollers with JSTATE register (e.g. MSP430FR5969)
82 
83 EnergyTraceSetup = { ET_PROFILING_ANALOG_DSTATE, // Gives callbacks of with eventID 7
84  ET_PROFILING_10K, // N/A
85  ET_ALL, // Gives all JSTATE information
86  ET_EVENT_WINDOW_100, // N/A
87  ET_CALLBACKS_ONLY_DURING_RUN } // Callbacks are sent only when target MCU is executing code
88 
89 Recommended sequence
90  MSP430_Initialize()
91  MSP430_VCC(XYZ)
92  MSP430_Configure(INTERFACE_MODE, XYZ)
93  MSP430_OpenDevice("","",0,0x00000000,0x00000000)
94  MSP430_EnableEnergyTrace(EnergyTraceSetup, EnergyTraceCallbacks, Handle)
95  MSP430_Run(RUN_TO_BREAKPOINT, 0) or MSP430_Run(FREE_RUN, 0)
96  ..
97  <process EnergyTraceCallbacks>
98  ..
99  MSP430_State(State,1,CPUCycles)
100  MSP430_DisableEnergyTrace(Handle)
101  MSP430_Close(0)
102 
103 2. For MSP430 microcontrollers without JSTATE register
104 
105 EnergyTraceSetup = { ET_PROFILING_ANALOG, // Gives callbacks of with eventID 8
106  ET_PROFILING_10K, // N/A
107  ET_ALL, // N/A
108  ET_EVENT_WINDOW_100, // N/A
109  ET_CALLBACKS_ONLY_DURING_RUN } // Callbacks are sent only when target MCU is executing code
110 
111 Recommended sequence
112  MSP430_Initialize()
113  MSP430_VCC(XYZ)
114  MSP430_EnableEnergyTrace(EnergyTraceSetup, EnergyTraceCallbacks, Handle)
115  MSP430_Run(RUN_TO_BREAKPOINT, 0) or MSP430_Run(FREE_RUN, 0) or MSP430_Run(FREE_RUN, 1)
116  ..
117  <process EnergyTraceCallbacks>
118  ..
119  MSP430_State(State,1,CPUCycles)
120  MSP430_DisableEnergyTrace(Handle)
121  MSP430_Close(0)
122 
123 3. For analog sampling without target code download and execution
124 
125 EnergyTraceSetup = { ET_PROFILING_ANALOG, // Gives callbacks of with eventID 8
126  ET_PROFILING_10K, // N/A
127  ET_ALL, // N/A
128  ET_EVENT_WINDOW_100, // N/A
129  ET_CALLBACKS_CONTINUOUS } // Callbacks are continuously
130 
131 Recommended sequence
132  MSP430_Initialize()
133  MSP430_VCC(XYZ)
134  MSP430_EnableEnergyTrace(EnergyTraceSetup, EnergyTraceCallbacks, Handle)
135  ..
136  <process EnergyTraceCallbacks>
137  ..
138  MSP430_DisableEnergyTrace(Handle)
139  MSP430_Close(0)
140 
141 Optional
142 --------
143 To enable higher resolution current sampling, set "MSP430_Configure(ENERGYTRACE_CURRENTDRIVE, 1)" before calling "MSP430_VCC(XYZ)".
144 
145 */
146 
147 #ifndef _MSP430_ENERGYTRACE_H_
148 #define _MSP430_ENERGYTRACE_H_
149 
150 #ifdef __cplusplus
151 extern "C" {
152 #endif
153 
154 // Push style interface
155 
156 // EnergyTrace mode selector
157 typedef enum ETMode
158 {
159  ET_PROFILING_ANALOG, // Time-driven device state profiling (analog measurement only)
160  ET_PROFILING_DSTATE, // Time-driven device state profiling (digital state only)
161  ET_PROFILING_ANALOG_DSTATE, // Time-driven device state profiling (analog measurement and digital state)
162  ET_EVENT_ANALOG, // Event-triggered device state capturing (analog measurement only)
163  ET_EVENT_DSTATE, // Event-triggered device state capturing (digital state only)
164  ET_EVENT_ANALOG_DSTATE, // Event-triggered device state capturing (analog measurement and digital state)
165 } ETMode_t;
166 
167 // Sample frequency (callbacks will be triggered according to this frequency)
169 {
170  ET_PROFILING_OFF, // no sampling of device state
176  ET_PROFILING_100K, // 100kHz
178 
179 // EnergyTrace recording format selector
181 {
182  // defines how much Device State information is reported.
183  // For Wolverine the Device State is the content of the
184  // JTAG Device State Register (64bits in total)
185  // Comment below are true for Wolverine, but might differ for newer devices in the future.
186  // The record format needs to be synchronized with the information in the device specific XML files.
187  ET_POWER_MODE_ONLY, // bits 63 - 52
189  ET_ALL // all 64 bits (bit 32 and not available mod bits must be masked out for further processing)
191 
192 // EnergyTrace event-triggered profiling window size
193 typedef enum ETEvent_window
194 {
195  // the number of samples (plus/minus) around the event trigger which will be pushed
196  // to the debugger (actually the size of the ringbuffer for analog measurement)
197  ET_EVENT_WINDOW_25, // 25 samples of current and voltage
201  ET_EVENT_WINDOW_1000, // 1000 -"-
203 
204 
205 // EnergyTrace callback mode
206 typedef enum ETCallback_mode
207 {
208  // Callbacks can be sent either continuous (e.g. for analog sampling)
209  // or only when the target MCU is executing code (e.g. run to breakpoint or free run)
210  ET_CALLBACKS_CONTINUOUS, // Callbacks are sent after MSP430_EnableEnergyTrace is called
211  ET_CALLBACKS_ONLY_DURING_RUN, // Callbacks are sent after MSP430_EnableEnergyTrace is called
212  // and the target MCU is executing code
214 
215 
216 // EnergyTrace setup information
217 typedef struct EnergyTraceSetup_tag
218 {
219  // Time-driven device state profiling
220  ETMode_t ETMode; // defines the operation mode
221  ETProfiling_samplingFreq_t ETFreq; // device state sampling frequency
222  ETProfilingDState_recFormat_t ETFormat; // format of the device state information
223 
224  // Event-triggered device state capturing
225  ETEvent_window_t ETSampleWindow;
226 
227  // Generic
228  ETCallback_mode_t ETCallback; // callback style
229 
231 
233 {
244 
245 typedef void( *PushDataFn )( void* pContext, const uint8_t* pBuffer, uint32_t nBufferSize );
246 
247 // Currently implemented error messages (in order of priority, since several errors could be present in parallel)
248 // "Unsupported debugger" Debugger does not support analog or dstate profiling
249 // "Unsupported device" Device or device variant does not support dstate profiling
250 // "USB voltage out of specification" USB voltage not sufficient for target power supply
251 // "Debugger overcurrent detected" Debugger overcurrent condition detected
252 // "Generic debugger error" Generic debugger malfunction detected
253 typedef void( *ErrorOccurredFn )( void* pContext, const char* pszErrorText );
254 
256 {
257  // Context data defined by the client to be passed to the callback functions
258  void* pContext;
259 
260  // Called to push new data to the client
262 
263  // Called when an error has occurred
265 
267 
268 typedef void* EnergyTraceHandle;
269 
270 // Enables EnergyTrace with the given setup configuration and callback functions.
271 // Returns a handle that can be used to disable profiling
272 // If this returns an error, then MSP430_Error_Number()/MSP430_Error_String() can fetch
273 // the error message
274 DLL430_SYMBOL STATUS_T WINAPI MSP430_EnableEnergyTrace(
275  const EnergyTraceSetup* setup, // in
276  const EnergyTraceCallbacks* callbacks, // in
277  EnergyTraceHandle* handle ); // out
278 
279 // Reset EnergyTrace session associated with the passed in handle
280 DLL430_SYMBOL STATUS_T WINAPI MSP430_DisableEnergyTrace( const EnergyTraceHandle handle );
281 
282 // Reset EnergyTrace Buffers and Processors
283 // Function should be called before collecting new EnergyTrace data
284 DLL430_SYMBOL STATUS_T WINAPI MSP430_ResetEnergyTrace( const EnergyTraceHandle handle );
285 
286 #ifdef __cplusplus
287 }
288 #endif
289 
290 #endif // _MSP430_ENERGYTRACE_H_
ETCallback_mode_t ETCallback
Definition: MSP430_EnergyTrace.h:228
Definition: MSP430_EnergyTrace.h:197
ETMode_t ETMode
Definition: MSP430_EnergyTrace.h:220
Definition: MSP430_EnergyTrace.h:189
ErrorOccurredFn pErrorOccurredFn
Definition: MSP430_EnergyTrace.h:264
Definition: MSP430_EnergyTrace.h:171
struct EnergyTraceCallbacks_tag EnergyTraceCallbacks
void(* ErrorOccurredFn)(void *pContext, const char *pszErrorText)
Definition: MSP430_EnergyTrace.h:253
Definition: MSP430_EnergyTrace.h:240
This file contains the Application Programming Interface (API) to access an MSP430 microcontroller vi...
Definition: MSP430_EnergyTrace.h:170
DLL430_SYMBOL STATUS_T WINAPI MSP430_DisableEnergyTrace(const EnergyTraceHandle handle)
PushDataFn pPushDataFn
Definition: MSP430_EnergyTrace.h:261
Definition: MSP430_EnergyTrace.h:172
Definition: MSP430_EnergyTrace.h:242
enum ETCallback_mode ETCallback_mode_t
ETProfiling_samplingFreq
Definition: MSP430_EnergyTrace.h:168
Definition: MSP430_EnergyTrace.h:255
ETCallback_mode
Definition: MSP430_EnergyTrace.h:206
Definition: MSP430_EnergyTrace.h:187
Definition: MSP430_EnergyTrace.h:173
Definition: MSP430_EnergyTrace.h:235
Definition: MSP430_EnergyTrace.h:211
Definition: MSP430_EnergyTrace.h:161
Definition: MSP430_EnergyTrace.h:164
struct EnergyTraceSetup_tag EnergyTraceSetup
Definition: MSP430_EnergyTrace.h:234
Definition: MSP430_EnergyTrace.h:176
void * pContext
Definition: MSP430_EnergyTrace.h:258
DLL430_SYMBOL STATUS_T WINAPI MSP430_ResetEnergyTrace(const EnergyTraceHandle handle)
Definition: MSP430_EnergyTrace.h:198
ETEvent_window_t ETSampleWindow
Definition: MSP430_EnergyTrace.h:225
DLL430_SYMBOL STATUS_T WINAPI MSP430_EnableEnergyTrace(const EnergyTraceSetup *setup, const EnergyTraceCallbacks *callbacks, EnergyTraceHandle *handle)
Definition: MSP430_EnergyTrace.h:160
ETProfiling_samplingFreq_t ETFreq
Definition: MSP430_EnergyTrace.h:221
Definition: MSP430_EnergyTrace.h:237
Definition: MSP430_EnergyTrace.h:162
Definition: MSP430_EnergyTrace.h:200
Definition: MSP430_EnergyTrace.h:239
Definition: MSP430_EnergyTrace.h:238
Definition: MSP430_EnergyTrace.h:159
void(* PushDataFn)(void *pContext, const uint8_t *pBuffer, uint32_t nBufferSize)
Definition: MSP430_EnergyTrace.h:245
void * EnergyTraceHandle
Definition: MSP430_EnergyTrace.h:268
Definition: MSP430_EnergyTrace.h:217
ETProfilingDState_recFormat
Definition: MSP430_EnergyTrace.h:180
int32_t STATUS_T
this is the definition for the DLL functions return value
Definition: MSP430.h:181
enum ETProfiling_samplingFreq ETProfiling_samplingFreq_t
EnergyTraceEventID_tag
Definition: MSP430_EnergyTrace.h:232
enum ETProfilingDState_recFormat ETProfilingDState_recFormat_t
Definition: MSP430_EnergyTrace.h:236
enum ETEvent_window ETEvent_window_t
Definition: MSP430_EnergyTrace.h:175
Definition: MSP430_EnergyTrace.h:174
ETEvent_window
Definition: MSP430_EnergyTrace.h:193
Definition: MSP430_EnergyTrace.h:199
ETMode
Definition: MSP430_EnergyTrace.h:157
ETProfilingDState_recFormat_t ETFormat
Definition: MSP430_EnergyTrace.h:222
Definition: MSP430_EnergyTrace.h:210
Definition: MSP430_EnergyTrace.h:201
Definition: MSP430_EnergyTrace.h:188
Definition: MSP430_EnergyTrace.h:163
enum ETMode ETMode_t
enum EnergyTraceEventID_tag EnergyTraceEventID
Definition: MSP430_EnergyTrace.h:241