MSP430 DLL API Documentation
3.9.1.2
Main Page
Classes
Files
File List
File Members
DLL430_v3
include
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)
168
typedef
enum
ETProfiling_samplingFreq
169
{
170
ET_PROFILING_OFF
,
// no sampling of device state
171
ET_PROFILING_100
,
// 100Hz
172
ET_PROFILING_1K
,
// 1kHz
173
ET_PROFILING_5K
,
// 5kHz
174
ET_PROFILING_10K
,
// 10kHz
175
ET_PROFILING_50K
,
// 50kHz
176
ET_PROFILING_100K
,
// 100kHz
177
}
ETProfiling_samplingFreq_t
;
178
179
// EnergyTrace recording format selector
180
typedef
enum
ETProfilingDState_recFormat
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
188
ET_POWER_MODE_CODE_PROFILING
,
// bits 63 - 33
189
ET_ALL
// all 64 bits (bit 32 and not available mod bits must be masked out for further processing)
190
}
ETProfilingDState_recFormat_t
;
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
198
ET_EVENT_WINDOW_50
,
// 50 -"-
199
ET_EVENT_WINDOW_100
,
// 100 -"-
200
ET_EVENT_WINDOW_500
,
// 500 -"-
201
ET_EVENT_WINDOW_1000
,
// 1000 -"-
202
}
ETEvent_window_t
;
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
213
}
ETCallback_mode_t
;
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
230
}
EnergyTraceSetup
;
231
232
typedef
enum
EnergyTraceEventID_tag
233
{
234
ET_EVENT_CURR
= 1,
235
ET_EVENT_VOLT
= 2,
236
ET_EVENT_CURR_VOLT
= 3,
237
ET_EVENT_STATE
= 4,
238
ET_EVENT_STATE_CURR
= 5,
239
ET_EVENT_STATE_VOLT
= 6,
240
ET_EVENT_STATE_VOLT_CURR
= 7,
241
ET_EVENT_CURR_VOLT_ENERGY
= 8,
242
ET_EVENT_ALL
= 9,
243
}
EnergyTraceEventID
;
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
255
typedef
struct
EnergyTraceCallbacks_tag
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
261
PushDataFn
pPushDataFn
;
262
263
// Called when an error has occurred
264
ErrorOccurredFn
pErrorOccurredFn
;
265
266
}
EnergyTraceCallbacks
;
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_
Generated on Wed Nov 30 2016 12:57:53 for MSP430 DLL API Documentation by
1.8.4