This chapter will attempt to describe the program structure in the aim to help programmers to understand the way it was designed, to add modules, functionalities as needed.
As you will notice in the next section, the coding conventions used in this project are pretty simples:
protocole_init()
function is used to initialize the protocol module),
guiToto
is a guint
),
This section exposes the modules functions and the relative exported functions, for more details, see the source code which I tried to comment as clearly as possible.
This file is from the fetproxy software (see Bibliography). I used it without any modifications.
It is used to generate the sent frame CRC and to check the received ones.
This module allow the program to communicate with the debugger only focusing on the frame content. It handles the whole low level aspect, from opening the USB device communication (using libftdi, see Bibliography) to managing the data encapsulation.
The exported functions are :
PROTOCOLE_STATUS protocole_init(void);
PROTOCOLE_STATUS protocole_open_device(guint16 vid, guint16 pid);
PROTOCOLE_STATUS protocole_close_device(void);
PROTOCOLE_STATUS protocole_configure_device(PROTOCOLE_CONFIG *pcConfig);
PROTOCOLE_STATUS protocole_send_data(guint8* data, size_t len, gint *sent);
PROTOCOLE_STATUS protocole_send_frame_raw(guint8* data, size_t len, gint *sent);
PROTOCOLE_STATUS protocole_read_data(guint8* buffer, size_t buffer_size, gint* read);
PROTOCOLE_STATUS protocole_read_frame_raw(guint8* buffer, size_t buffer_size, gint* read);
PROTOCOLE_STATUS protocole_flush_buffers(void);
All these functions are declared as DLL_LOCAL
, that means in this program that they are not exported when the shared object is generated; You can only access them from the library.
This modules is a replacement for protocole_ftdi.c when you want to use FTDI D2XX library instead of libftdi (this is mainly used on Windows systems). It uses the same interface and can't be compiled in the same time as protocole_ftdi.c.
This module contains the OLIMEX MSP430 JTAG ISO debugger specific instructions. It handles the debugger state (opened, initialized, closed) and the general commands (Debugger initialization, VCC setting...).
The exported functions are :
OLIMEX_STATUS olimex_initialize(guint32* version);
OLIMEX_STATUS olimex_close(guint8 close_type);
OLIMEX_STATUS olimex_vcc(gfloat fVoltage);
OLIMEX_STATUS olimex_configure(guint mode, guint val);
All these functions are declared as DLL_LOCAL
, that means in this program that they are not exported when the shared object is generated; You can only access them from the library.
This module works with the same device as the precedent, it handles the target device relative functions (Identification, memory access, context reading/writing, execution control...). It works once the debugger is initialized, configured and the target is powered.
The exported functions are :
OLIMEX_STATUS olimex_target_identify(guint *deviceId);
OLIMEX_STATUS olimex_target_reset(guint8 param);
OLIMEX_STATUS olimex_target_state(guint32 *state, guint count, guint32* read);
OLIMEX_STATUS olimex_target_get_context(guint32 *registers, guint regs_count, guint* read_registers);
OLIMEX_STATUS olimex_target_set_context(guint32 *registers, guint regs_count);
OLIMEX_STATUS olimex_target_run(guint32 mode, guint32 param);
OLIMEX_STATUS olimex_target_set_breakpoint(guint32 code, guint32 address);
OLIMEX_STATUS olimex_target_memory(guint32 mem_address, guint8 *data, guint16 data_len, OT_MEMORY_FUNCTION function);
OLIMEX_STATUS olimex_target_erase(guint8 function, guint32 address, guint16 length);
All these functions are declared as DLL_LOCAL
, that means in this program that they are not exported when the shared object is generated; You can only access them from the library.
This module contains the target device relative informations; an array of structure is used to store device informations needed to debug it (CpuX core, Memory location, Flash location, spy-bi-wire support...).
The exported function is:
MSP430_DEVICE msp430_get_device(guint16 devId);
It returns the structure containing the needed data from the device ID.
This part of the library is not really a module, it makes an interface between the other modules and an external program made to work with TI libMSP430 library. All it's functions are exported to be accessed from an external software and provides a common interface to the internal functions.
The exported functions are:
int MSP430_Initialize(CHAR const * port, LONG* version);
int MSP430_Close(LONG vccOff);
int MSP430_Configure(LONG mode, LONG value);
int MSP430_VCC(LONG voltage);
int MSP430_Reset(LONG method, LONG execute, LONG releaseJTAG);
int MSP430_Erase(LONG type, LONG address, LONG length);
int MSP430_Memory(LONG address, CHAR* buffer, LONG count, LONG rw);
int MSP430_Breakpoint(LONG bpNumber, LONG address);
int MSP430_Registers(guint* Regs, LONG Value, guint32 rw);
int MSP430_Run(guint32 mode, guint32 param);
int MSP430_State(guint32* state, guint32 count, guint32* read);
int MSP430_VerifyMem(LONG StartAddr, LONG Length, CHAR *DataArray);
int MSP430_EraseCheck(LONG StartAddr, LONG Length);
LONG MSP430_Error_Number(void);
const CHAR* MSP430_Error_String(LONG errorNumber);
guint32 MSP430_Identify(gint8 *data, gint size, guint32 setId);
If you have been working for this project, it would be great to give us feed back by submitting a patch file that would be integreated in the distribution.
Note: Don't forget to update the ChangeLog file before doing the diff in order to give us a description of your changes.
To do so is quite easy, just extract the original project beside your modified one (for example, get in a directory libfmdll-vX.X and libfmdll-vX.X-by-yourself), and use the diff tool to make a patch file :
diff -Nru libfmdll-vX.X libfmdll-vX.X-by-yourself > libfmdll-vX.X-patch-by-yourself.patch
You then just have to send the generated libfmdll-vX.X-patch-by-yourself.patch file by email.
Submitting a modification from the GIT repository is very easy.
If you did n't added your modification with git add ``Your files'', just type :
git diff > libfmdll-vX.X-patch-by-yourself-git.patch
If you added your modification to your local git (without committing), type :
git diff master > libfmdll-vX.X-patch-by-yourself-git.patch
Then just send an email with the generated patch.
Note: Adding modification without committing gives a better result for the patch file.