MSP430 DLL API Documentation  3.9.1.2
MSP430.h
Go to the documentation of this file.
1 /*
2  * MSP430.h
3  *
4  * API for accessing MSP430 devices via JTAG.
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 
155 #ifndef MSP430_H
156 #define MSP430_H
157 
158 
159 #include <DLL430_SYMBOL.h>
160 #include <stdint.h>
161 
162 #if defined(_WIN32) || defined(_WIN64)
163 #include <windows.h>
164 #endif
165 
166 #if defined(__cplusplus)
167 extern "C" {
168 #endif
169 
170 #ifndef MSP430_TYPES
171 #define MSP430_TYPES
172 
174 typedef int32_t STATUS_T;
175 
179 typedef enum STATUS_CODE {
181  STATUS_OK = 0,
182 } STATUS_CODE_t;
183 
187 #pragma pack(1)
188 typedef union DEVICE_T {
191  uint8_t buffer[172];
192  struct
193  {
195  uint16_t endian;
197  uint16_t id;
199  uint8_t string[32];
201  uint16_t mainStart;
203  uint16_t infoStart;
205  uint16_t ramEnd;
207  uint16_t nBreakpoints;
209  uint16_t emulation;
211  uint16_t clockControl;
213  uint16_t lcdStart;
215  uint16_t lcdEnd;
217  uint16_t vccMinOp;
219  uint16_t vccMaxOp;
221  uint16_t hasTestVpp;
223  uint16_t ramStart;
225  uint16_t ram2Start;
227  uint16_t ram2End;
229  uint16_t infoEnd;
231  uint32_t mainEnd;
233  uint16_t bslStart;
235  uint16_t bslEnd;
237  uint16_t nRegTrigger;
239  uint16_t nCombinations;
241  uint8_t cpuArch;
243  uint8_t jtagId;
245  uint16_t coreIpId;
247  uint32_t deviceIdPtr;
249  uint16_t eemVersion;
253  uint16_t nBreakpointsDma;
255  uint16_t TrigerMask;
259  uint16_t nStateStorage;
261  uint16_t nCycleCounter;
265  uint16_t nSequencer;
267  uint16_t HasFramMemroy;
269  uint16_t mainSegmentSize;
274  uint32_t structSize;
276  uint32_t info32BitStart;
278  uint32_t info32BitEnd;
280  uint32_t ram32BitStart;
282  uint32_t ram32BitEnd;
286  uint32_t ram32BitBandEnd;
288  uint32_t main32BitStart;
290  uint32_t main32BitEnd;
292  uint32_t debug32BitStart;
294  uint32_t debug32BitEnd;
296  uint32_t bsl32BitStart;
298  uint32_t bsl32BitEnd;
303  };
304 } DEVICE_T_t;
305 #pragma pack()
306 
307 
309 #define DEVICE_UNKNOWN 0
310 
311 typedef enum CPU_ARCH_TYPE
312 {
318 
320 {
324 
325 typedef enum READ_WRITE {
326  WRITE = 0,
327  READ = 1,
328 } READ_WRITE_t;
329 
330 typedef enum ENABLE_DISABLE {
331  DISABLE = 0,
332  ENABLE = 1,
334 
336 typedef enum RESET_METHOD {
337  PUC_RESET = (1 << 0),
338  RST_RESET = (1 << 1),
339  VCC_RESET = (1 << 2),
340  FORCE_RESET = (1 << 3),
341 
355 
356 
358 typedef enum ERASE_TYPE {
361  ERASE_ALL = 2,
364 } ERASE_TYPE_t;
365 
367 typedef enum CONFIG_MODE {
374  SET_MDB_BEFORE_RUN = 9,
378 
393  // just used internal for the device code of L092 and C092
395  // set true to write the external SPI image of the L092
397  // set DEBUG_LPM_X true to start debugging of LPMx.5
398  // this will start polling for LPMX.5 events if a system notify callback was
399  // previously set using MSP430_SET_SYSTEM_NOTIFY_CALLBACK()
401  // Configure JTAG speed
403  // total device erase including IP protection
405  // Enable the CURRENTDRIVE FINE EnergyTrace Mode, for measuring small currents
407  //Enable software breakpoints
409 } CONFIG_MODE_t;
410 
412 typedef enum INTERFACE_TYPE {
413  JTAG_IF = 0,
417  UNDEF_IF = 4,
423 
425 typedef enum INTERFACE_SPEED {
426  FAST = 0,
427  MEDIUM = 1,
428  SLOW = 2
430 
432 typedef enum FILE_TYPE {
436 } FILE_TYPE_t;
437 
438 #define ERROR_DEFINITIONS \
439  ERROR_DEF(NO_ERR, "No error") \
440  ERROR_DEF(INITIALIZE_ERR, "Could not initialize device interface") \
441  ERROR_DEF(CLOSE_ERR, "Could not close device interface") \
442  ERROR_DEF(PARAMETER_ERR, "Invalid parameter(s)") \
443  ERROR_DEF(NO_DEVICE_ERR, "Could not find device (or device not supported)") \
444  ERROR_DEF(DEVICE_UNKNOWN_ERR, "Unknown device") \
445  ERROR_DEF(READ_MEMORY_ERR, "Could not read device memory") \
446  ERROR_DEF(WRITE_MEMORY_ERR, "Could not write device memory") \
447  ERROR_DEF(READ_FUSES_ERR, "Could not read device configuration fuses") \
448  ERROR_DEF(CONFIGURATION_ERR, "Incorrectly configured device; device derivative not supported") \
449  ERROR_DEF(VCC_ERR, "Could not set device Vcc") \
450  ERROR_DEF(RESET_ERR, "Could not reset device") \
451  ERROR_DEF(PRESERVE_RESTORE_ERR, "Could not preserve/restore device memory") \
452  ERROR_DEF(FREQUENCY_ERR, "Could not set device operating frequency") \
453  ERROR_DEF(ERASE_ERR, "Could not erase device memory") \
454  ERROR_DEF(BREAKPOINT_ERR, "Could not set device breakpoint") \
455  ERROR_DEF(STEP_ERR, "Could not single step device") \
456  ERROR_DEF(RUN_ERR, "Could not run device (to breakpoint)") \
457  ERROR_DEF(STATE_ERR, "Could not determine device state") \
458  ERROR_DEF(EEM_OPEN_ERR, "Could not open Enhanced Emulation Module") \
459  ERROR_DEF(EEM_READ_ERR, "Could not read Enhanced Emulation Module register") \
460  ERROR_DEF(EEM_WRITE_ERR, "Could not write Enhanced Emulation Module register") \
461  ERROR_DEF(EEM_CLOSE_ERR, "Could not close Enhanced Emulation Module") \
462  ERROR_DEF(FILE_OPEN_ERR, "File open error") \
463  ERROR_DEF(FILE_DETECT_ERR, "File type could not be identified") \
464  ERROR_DEF(FILE_END_ERR, "File end error") \
465  ERROR_DEF(FILE_IO_ERR, "File input/output error") \
466  ERROR_DEF(FILE_DATA_ERR, "File data error") \
467  ERROR_DEF(VERIFY_ERR, "Verification error") \
468  ERROR_DEF(BLOW_FUSE_ERR, "Could not secure the device") \
469  ERROR_DEF(FUSE_BLOWN_ERR, "The Debug Interface to the device has been secured") \
470  ERROR_DEF(INTEL_HEX_CODE_ERR, "Error within Intel Hex file") \
471  ERROR_DEF(WRITE_REGISTER_ERR, "Could not write device Register") \
472  ERROR_DEF(READ_REGISTER_ERR, "Could not read device Register") \
473  ERROR_DEF(INTERFACE_SUPPORT_ERR, "Not supported by selected Interface or Interface is not initialized") \
474  ERROR_DEF(COMM_ERR, "Interface Communication error") \
475  ERROR_DEF(NO_EX_POWER, "No external power supply detected") \
476  ERROR_DEF(LOW_EX_POWER, "External power too low") \
477  ERROR_DEF(EX_POWER_OK, "External power detected") \
478  ERROR_DEF(HIGH_EX_POWER, "External power too high") \
479  ERROR_DEF(SELFTEST_ERR, "Hardware Self Test Error") \
480  ERROR_DEF(FLASH_TIMEOUT_ERR, "Fast Flash Routine experienced a timeout") \
481  ERROR_DEF(THREAD_ERR, "Could not create thread for polling") \
482  ERROR_DEF(EEM_INIT_ERR, "Could not initialize Enhanced Emulation Module") \
483  ERROR_DEF(RESOURCE_ERR, "Insufficient resources") \
484  ERROR_DEF(CLK_CTRL_ERR, "No clock control emulation on connected device") \
485  ERROR_DEF(STATE_STOR_ERR, "No state storage buffer implemented on connected device") \
486  ERROR_DEF(READ_TRACE_ERR, "Could not read trace buffer") \
487  ERROR_DEF(VAR_WATCH_EN_ERR, "Enable the variable watch function") \
488  ERROR_DEF(SEQUENCER_ERR, "No trigger sequencer implemented on connected device") \
489  ERROR_DEF(SEQ_ENABLE_ERR, "Could not read sequencer state - Sequencer is disabled") \
490  ERROR_DEF(CLR_SEQ_TRIGGER, "Could not remove trigger - Used in sequencer") \
491  ERROR_DEF(SET_SEQ_TRIGGER, "Could not set combination - Trigger is used in sequencer") \
492  ERROR_DEF(SPMA_ACTIVE_ERR, "System Protection Module A is enabled - Device locked") \
493  ERROR_DEF(SPMA_INVALID_KEY_ERR, "Invalid SPMA key was passed to the target device - Device locked") \
494  ERROR_DEF(SPMA_MAX_TRIALS, "Device does not accept any further SPMA keys - Device locked") \
495  ERROR_DEF(USB_FET_BSL_ACTIVE_ERR, "MSP-FET430UIF Firmware erased - Bootloader active") \
496  ERROR_DEF(USB_FET_NOT_FOUND_ERR, "Could not find MSP-FET430UIF on specified COM port") \
497  ERROR_DEF(USB_FET_BUSY_ERR, "MSP-FET430UIF is already in use") \
498  ERROR_DEF(THREAD_ACTIVE_ERR, "EEM polling thread is already active") \
499  ERROR_DEF(THREAD_TERMINATE_ERR, "Could not terminate EEM polling thread") \
500  ERROR_DEF(UNLOCK_BSL_ERR, "Could not unlock BSL memory segments") \
501  ERROR_DEF(BSL_MEMORY_LOCKED_ERR, "Could not perform access, BSL memory segments are protected") \
502  ERROR_DEF(FOUND_OTHER_DEVICE, "Another device as selected was found") \
503  ERROR_DEF(WRONG_PASSWORD, "Could not enable JTAG wrong password") \
504  ERROR_DEF(UPDATE_MULTIPLE_UIF_ERR, "Only one UIF must be connected during update to v3") \
505  ERROR_DEF(CDC_UIF_ERR, "CDC-USB-FET-Driver was not installed. Please install the driver") \
506  ERROR_DEF(UIF_MANUAL_POWERCYCLE_NEEDED, "Manual reboot of USB-FET needed ! PLEASE unplug and reconnect your USB-FET!!") \
507  ERROR_DEF(INTERNAL_ERR, "Internal error") \
508  ERROR_DEF(FETRECOVERY_NEEDED, "One of the connected MSP-FETs / eZ-FETs debuggers needs recovery") \
509  ERROR_DEF(WRITE_EXTERNAL_MEM_ERR, "One of the connected MSP-FETs / eZ-FETs debuggers needs recovery") \
510  ERROR_DEF(FEATURE_NOT_SUPPORTED, "Feature not supported") \
511  ERROR_DEF(RECOVERY_MULTIPLE_UIF, "Only one MSP-FET / eZ-FET must be connected during recovery") \
512  ERROR_DEF(RECOVERY_FAILED, "MSP-FET / eZ-FET recovery failed") \
513  ERROR_DEF(UPDATE_CORE_ERR, "MSP-FET / eZ-FET core(communication layer) update failed") \
514  ERROR_DEF(UPDATE_MODULE_ERR, "MSP-FET / eZ-FET legacy module update failed") \
515  ERROR_DEF(ET_NOT_SUPPORTED, "EnergyTrace is not supported by the selected debugger") \
516  ERROR_DEF(HARDWARE_STATE_UNKNOWN, "Hardware State is unknown") \
517  ERROR_DEF(DEVICE_CRC_WRONG, "Device configuration data inconsistent. Please discontinue using/replace target device.") \
518  ERROR_DEF(EEM_NOT_ACCESSIBLE, "EEM module not accessible while running in Ultra Low Power Debug Mode - Deactivate Ultra Low Power Debug mode to enable this feature") \
519  ERROR_DEF(REMOVE_SOFTWARE_BREAKPOINT_ERR, "Failed to remove software breakpoints, please reprogram target device") \
520  ERROR_DEF(TRIGGER_CONFLICT_ERR, "Trigger configuration conflicts with existing triggers") \
521  ERROR_DEF(TARGET_RUNNING_ERR, "Operation not possible while device is running") \
522  ERROR_DEF(INCOMPATIBLE_WITH_SW_BREAKPOINT_API, "This function can not be used when software breakpoints are enabled") \
523  ERROR_DEF(SPEED_CONFIG_ERR, "JTAG/SBW speed configuration failed") \
524  ERROR_DEF(SWBP_CRITICAL_INSTRUCTION, "Software breakpoint can't be set (followed by critical value)") \
525  ERROR_DEF(ET_NOT_SUPPORTED_DEVICE, "EnergyTrace is not supported by selected MSP430 device") \
526  ERROR_DEF(ET_NOT_SUPPORTED_ULP_DEBUG, "EnergyTrace requires Ultra-Low Power debug / LPMx.5 enabled") \
527  ERROR_DEF(LEGACY_DEVICE_ERR, "Legacy version of silicon used, which is no longer supported. Please contact TI to obtain a newer version.") \
528  ERROR_DEF(SECURE_NOT_SUPPORTED_ERR, "Secure device via the IDE is not supported. See Device User Guide for further information.") \
529  ERROR_DEF(CYCLE_COUNTER_CONFLICT, "Cycle counter is in basic mode. Set to advanced mode to use this function.") \
530  ERROR_DEF(NO_LPT_SUPPORT, "Parallel port FET (MSP-FETP430IF) is no longer supported.") \
531  ERROR_DEF(WRONG_TARGET_ARCHITECTURE, "Wrong target architecture was selected – Valid architectures are MSP430 or MSP432_M4.") \
532  ERROR_DEF(MSP432_TOTAL_ERASE, "Mass erase executed. Please power-cycle your device and restart the debug session.") \
533  ERROR_DEF(POSSIBLE_OVERCURRENT, "Your connected hardware might drain too much power from the debugger.This results in an overcurrent.") \
534  ERROR_DEF(FET_UPDATE_FAILED, "MSP Tool firmware update failed. Please ensure the USB or Backchannel UART connection is not in use.") \
535  ERROR_DEF(INTERFACE_SUPPORT_ERR_MSP432, "MSP432 devices are not supported using the MSPFET430-UIF") \
536  ERROR_DEF(DAP_LOCK_WRONG_PROTOCOL, "DAP is locked or wrong debug protocol selected.") \
537  ERROR_DEF(DEVICE_DB_ERR, "Device database not loaded.") \
538  ERROR_DEF(INVALID_ERR, "Invalid error number")
539 
541 #define ERROR_DEF(errorEnum, errorString) errorEnum,
543 #undef ERROR_DEF
544 
545 // System events
546 typedef enum SYSTEM_EVENT_MSP
547 {
563 
564 typedef void (* SYSTEM_NOTIFY_CALLBACK) (SYSTEM_EVENT_MSP_t MySystemEvent);
565 
566 #endif /* MSP430_TYPES */
567 
568 // Functions. -----------------------------------------------------------------
585 DLL430_SYMBOL STATUS_T WINAPI MSP430_SET_SYSTEM_NOTIFY_CALLBACK(SYSTEM_NOTIFY_CALLBACK parSystemNotifyCallback);
586 
587 // Functions. -----------------------------------------------------------------
606 DLL430_SYMBOL STATUS_T WINAPI MSP430_SetTargetArchitecture(TARGET_ARCHITECTURE_t architecture);
607 
608 /*
609 \fn STATUS_T MSP430_LoadDeviceDb(const char* file);
610 
611 \brief Load the device database from XML archive.
612 
613 \param file: The filename of a zip archive containing the device info files.
614 
615 \return STATUS_OK: The device info was loaded.
616 \n STATUS_ERROR: The device info was not loaded.
617 */
618 DLL430_SYMBOL STATUS_T WINAPI MSP430_LoadDeviceDb(const char* file);
619 
620 
629 DLL430_SYMBOL STATUS_T WINAPI MSP430_ClearDeviceDb();
630 
676 DLL430_SYMBOL STATUS_T WINAPI MSP430_Initialize(const char* port, int32_t* version);
677 
694 DLL430_SYMBOL STATUS_T WINAPI MSP430_Close(int32_t vccOff);
695 
696 
704 DLL430_SYMBOL STATUS_T WINAPI MSP430_GetJtagID(int32_t* JtagId);
705 
723 DLL430_SYMBOL STATUS_T WINAPI MSP430_GetFoundDevice(uint8_t* FoundDevice, int32_t count);
724 
758 DLL430_SYMBOL STATUS_T WINAPI MSP430_OpenDevice(const char* Device, const char* Password, int32_t PwLength,int32_t DeviceCode, int32_t setId);
759 
760 
779 DLL430_SYMBOL STATUS_T WINAPI MSP430_Device(int32_t localDeviceId, uint8_t* buffer, int32_t count);
780 
826 DLL430_SYMBOL STATUS_T WINAPI MSP430_Configure(int32_t mode, int32_t value);
827 
851 DLL430_SYMBOL STATUS_T WINAPI MSP430_VCC(int32_t voltage);
852 
853 
871 DLL430_SYMBOL STATUS_T WINAPI MSP430_GetCurVCCT(int32_t* voltage);
872 
897 DLL430_SYMBOL STATUS_T WINAPI MSP430_GetExtVoltage(int32_t* voltage, int32_t* state);
898 
899 
930 DLL430_SYMBOL STATUS_T WINAPI MSP430_Reset(int32_t method, int32_t execute, int32_t releaseJTAG);
931 
971 DLL430_SYMBOL STATUS_T WINAPI MSP430_Erase(int32_t type, int32_t address, int32_t length);
972 
1002 DLL430_SYMBOL STATUS_T WINAPI MSP430_Memory(int32_t address, uint8_t* buffer, int32_t count, int32_t rw);
1003 
1004 #define MSP430_Read_Memory(ADDRESS, BUFFER, COUNT) MSP430_Memory(ADDRESS, BUFFER, COUNT, READ)
1005 #define MSP430_Write_Memory(ADDRESS, BUFFER, COUNT) MSP430_Memory(ADDRESS, BUFFER, COUNT, WRITE)
1006 
1025 DLL430_SYMBOL STATUS_T WINAPI MSP430_Secure(void);
1026 
1050 #if ! defined(uController)
1051 DLL430_SYMBOL STATUS_T WINAPI MSP430_ReadOutFile(int32_t wStart, int32_t wLength, const char* lpszFileName, int32_t iFileType);
1052 #endif
1053 
1095 #if ! defined(uController)
1096 DLL430_SYMBOL STATUS_T WINAPI MSP430_ProgramFile(const char* File, int32_t eraseType, int32_t verifyMem);
1097 #endif
1098 
1126 #if ! defined(uController)
1127 DLL430_SYMBOL STATUS_T WINAPI MSP430_VerifyFile(const char* File);
1128 #endif
1129 
1152 DLL430_SYMBOL STATUS_T WINAPI MSP430_VerifyMem(int32_t StartAddr, int32_t Length, const uint8_t* DataArray);
1153 
1175 DLL430_SYMBOL STATUS_T WINAPI MSP430_EraseCheck(int32_t StartAddr, int32_t Length);
1176 
1187 DLL430_SYMBOL int32_t WINAPI MSP430_Error_Number(void);
1188 
1199 #if ! defined(uController)
1200 DLL430_SYMBOL const char* WINAPI MSP430_Error_String(int32_t errorNumber);
1201 #endif
1202 
1217 #if ! defined(uController)
1218 DLL430_SYMBOL STATUS_T WINAPI MSP430_GetNumberOfUsbIfs(int32_t* Number);
1219 #endif
1220 
1247 #if ! defined(uController)
1248 DLL430_SYMBOL STATUS_T WINAPI MSP430_GetNameOfUsbIf(int32_t Idx, char** Name, int32_t* Status);
1249 #endif
1250 
1260 DLL430_SYMBOL STATUS_T WINAPI MSP430_GetInterface_Type(enum INTERFACE_TYPE* type);
1261 
1262 #if defined(__cplusplus)
1263 }
1264 #endif
1265 
1266 #endif // MSP430_H