Plugin Index 

Plugin System
    Plugin Index
        Bcd
            Bcd Configuration
        Button
            Button Configuration
             2 State Button Setting
        Button Block
            Button Block Configuration
        Digital Voltmeter
            Digital Voltmeter Configuration
        Led
            Led Configuration
        Led Block
            Led Block Configuration
        Signal Generator
            Signal Generator Configuration
        Stop Watch
            Stop Watch Configuration
        I2C  EEPROM
            I2C  EEPROM Logging
             I2C  EEPROM Configuration
        Logic Analyzer
            Logic Analyzer Configuration
        LCD

BCD Project
Button Project
Button Block Project
Led Project
Led Block Project
Digital Voltmeter Project
Signal Generator Project
Stop Watch Project

I2C EEPROM Project
Logic Analyzer Project

Appendix A: Plugin API
Appendix B: Daves Plugin Writing Guide
Legal Information

Plugin System

SourceBoost IDE features an extendable plugin system where each plugin emulates a physical device connected to the target. The standard SourceBoost IDE installation includes the BCD, Button, Button Block, Led and Led Block plugins. Other plugins are available to download as separate installations from http://www.sourceboost.com:

7 segment and 12 segment display with decoding 
Single button
Block of 8 buttons
Single LED
Block of 8 LEDs
Digital voltmeter
Signal generator
Stop watch
 IC serial EEPROM
Logic analyzer
lcd_pl3 (7K) LCD
voltsrc (4K) Analogue Voltage Source

 

tip (1K)Double clicking the title bar on any plugin will cause its window to toggle between nested and floating. 

   Docked

Floating

 

Plugin Descriptions

 

 BCD 

plugin_bcd (2K) The BCD plugin simulates a double digit 7 or 12 segment LED and decoding circuitry that converts from  8 bit binary coded decimal to decimal, or from binary to hexadecimal dependent on configuration of the plugin.

BCD  Configuration

To configure,  right click on the plugin window and select configure.  A popup like this will appear:
  • The port the plugin reads from is selected by the "Connect bcd to: "entry box.  All of the pins on that port are read as inputs to the plugin. (outputs from the MCU)

  • The colour of the digit may be set to green, red, yellow, or blue.

  • A radio button select between Bcd (digital) and Hex (hexadecimal) output. 
     If Bcd is selected, data delivered to the port must be in binary coded decimal  format.  If Hex is selected standard binary is needed.

tip (1K)  If Bcd is selected, data delivered to the port must be in binary coded decimal  format for the display to read properly.

 

Bcd Example Project (sources can be found in the "plugin_examples" directory)

 

Button

The button is a simulated switch connected to a pin as an input device.
When activated it causes the selected pin to go to a  high state

 

Button Configuration

  • To configure,  right click on the plugin window and select configure.  A popup like this will appear:

  • The port and pin number stimulated are set by the "Connect button to: " entry box.

  • The button may be given a label that will be displayed on the button.

 

2 State Button Setting

This setting behaves the same for the button and button block plugins.

  Off

On

A check box will make the button behave in one of two ways:

When not checked it will act as a momentary switch, only closing while  pressed.

When checked it must be pushed to turn on, and then pushed again to turn off.

Button Example Project (sources can be found in the "plugin_examples" directory)

 

 

Button Block 

The Button Block simulates a group of labeled switches connected to a port.

 

Button Block Configuration

To configure,  right click on the plugin window and select configure.  A popup like this will appear:
  • The port  stimulated are set by the "Connect buttons to: " entry box.

  • The buttons may be given individual labels that will be displayed on the button.

The 2 State Button Setting are the same as for the button plugin.

Button Block Example Project (sources can be found in the "plugin_examples" directory)

 

 

Led 

plugin_led (1K) The Led plugin simulates a single Led connected to a pin.  

 

Led  Configuration

  • To configure,  right click on the plugin window and select configure.  

  • A popup like this will appear:The port and pin the Led is stimulated by is set by the "Connect leds to: " entry box.

  • The Led shape and colour can also be chosen .

 

 

Led Example Project (sources can be found in the "plugin_examples" directory)

 

 

Led Block

plugin_led8 (1K) The Led Block simulates a block of 8 Leds connected to one port.

 

Led  Block Configuration

 

  • To configure,  right click on the plugin window and select configure.  A popup like this will appear:
  • The port the Leds are stimulated by is set by the "Connect leds to: " entry box.

  • The Leds shape and colour can also be chosen .

  • The port the Leds are stimulated by is set by the "Connect leds to: " entry box.

  • The Leds shape and colour can also be chosen .

 

Led Block Example Project (sources can be found in the "plugin_examples" directory)

 

 

Digital Voltmeter

This plugin simulates a digital voltmeter reading the voltage on one pin.

 

Digital Volt Meter Configuration

To configure,  right click on the plugin window and select configure.  
A popup like this will appear:
Select the pin to read the voltage from.

 

Digital Voltmeter Project (sources can be found in the "plugin_examples" directory)

 

 

Signal Generator

The Signal Generator plugin simulates a signal function generator used to provide specifically defined signal to one input pin.

 

Signal Generator Configuration

One of four possible wave forms to be generated is selected that can be modified with three slider bars:

The pin to send the signal to must be selected.

tip (1K) To make very fine adjustments, click on the desired slider, then use the up and down arrow keys to change the value.

tip (1K) If the output of the signal generator is limited between 0V and 5V. If the waveform amplitude + DC offset goes outside this range, wave form will be clipped.

Signal Generator Project (sources can be found in the "plugin_examples" directory)

 

 

Stop Watch 

The stop watch  can be used to measure time between events  measured in both milliseconds and clocks ticks.

 

Stop Watch Configuration and Use

The stop watch can be started or stopped either manually or automatically.  

To manually time an interval step to point where the timing is to begin and press the "Manual Start" button, then step to point where the timing is to end and press the "Manual Stop" button Time intervals can be measured very precisely using this method.

Timing can be triggered automatically by selecting a start and stop source.  A radio button selects between when the signal on the pin is rising or falling.  another radio button allows the user to determine if the event is timed the first time it happens (One Shot) or every time it happens (Repeat).

Any combination of automatic and manual can be used to start or stop the timing.

Stop Watch Project (sources can be found in the "plugin_examples" directory)

 

 

IC EEPROM 

This plugin simulates a Electrically Programmable Read Only Memory chip that is programmed using the Inter-Integrated Circuit. (IC) serial protocol.  With the IC EEPROM plugin you can simulate a basic IC EEPROM device such as the 24LC256. 

IC was developed by Phillips electronic in the 1980s so chips would have a simple method of communicating with just a two wire bus. For more information about the IC protocol see the Phillips website or the Microchip 24AA256/24LC256/24FC256 datasheet

The following operations are supported by the plug-in.

The Information Bar is the bar across the bottom of the plugin window.  
The Information Bar shows current  information about the plug-in such as:

IC EEPROM logging

tip (1K) When the Follow button is pressed the text displayed will follow the newest line being logged.

The data can be saved to file by  right clicking on the plugin window and selecting "save log to file"

 

IC EEPROM Configuration

To configure,  right click on the plugin window and select configure.  A popup like this will appear:

 

Selecting "Configure..." will bring up a popup like this:

 

  • The Serial Data/ Serial Clock are configured by selecting the the proper port and pin numbers for each. (SCL = Serial Clock; SDA Serial Data)   Select "Pull-Up Data & Clock on start" to enable communications upon plugin reset.

  • Colours used for the grid and information bar can be adjusted under the heading "Grid View".

 

tip (1K) The Slave address configured here must match the slave address used in the code in order for the read or write operations to occur.

 

I2C EEPROM  Example Project (sources can be found in the "plugin_examples" directory)

 

 

Logic Analyzer

A logic analyzer is used to plot a graphical  representation of a ports input and output states against time.  The high and low state are the only one represented; the high impedance state is not represented 

tip (1K)The in and out setting are from the MCUs perspective, not from the logic analyzers.  In the example below, pin B2 should be configured as an input taking stimulus from the logic analyzer while pin B3 is providing data that is being recorded by the logic analyzer. 

 

Logic Analyzer Configuration

To configure,  right click on the plugin window and select configure.
A popup like this will appear:

 

Logic Analyzer Project (sources can be found in the "plugin_examples" directory)

 

 

 

LCD

The LCD plugin simulates the industry standard Hitachi HD44780 LCD controller and an LCD display in a choice of different display sizes. The HD44780 display controller has a parallel interface that consists of 8 data lines and three control lines. Look here for more information about the LCD plugin.

tip (1K)Sample projects that illustrate how to interface to lLCD using 4 and 8 bit interface can be found in the "plugin_examples\lcd" directory. 

 

Appendix A: Plugin API 1.00

Plugin API Index

Plugin API Overview
PLUGIN_API int plgVersion( void )
PLUGIN_API HWND plgCreate( HWND parent, void* (*SupplyFuncPtr)(const char*))
void GetRegHandle( char* name, HANDLE* hReg )
void GetRegVal( HANDLE hReg, int* val )
void SetRegVal( HANDLE hReg, int val )
void AddRegChangeCallBack( HANDLE hReg, REGCHGCALLBACK pfunc, void* pParam, int iParam )
void RemoveRegChangeCallBack ( HANDLE hReg, REGCHGCALLBACK pfunc, void* pParam, int iParam )
void MakeConnectionToPin( const char* pinName, HANDLE* hConnection )
void ReleaseConnection( HANDLE hConnection )
void SetConnectionR( HANDLE hConnection, int ohm )
void GetPinV( HANDLE hConnection, int* mv )
void AddPinVChangeCallBack( HANDLE hConnection, PINCHGCALLBACK pfunc, void* pParam, int iParam )
void RemovePinVChangeCallBack( HANDLE hConnection, PINCHGCALLBACK pfunc, void* pParam, int iParam )
void GetClk( long* clk )
void Lock( void )
void Unlock( void )
PLUGIN_API BOOL plgStart( void )
PLUGIN_API void plgStop( void )
PLUGIN_API BOOL plgFree( void )
PLUGIN_API LPCTSTR plgName( void )
PLUGIN_API void plgConfigure( HWND parent )
PLUGIN_API int plgSave( BYTE *buf )
PLUGIN_API int plgSaveState( BYTE *buf )
PLUGIN_API BOOL plgLoad( BYTE *buf, int len )
PLUGIN_API BOOL plgLoadState( BYTE *buf, int len )
PLUGIN_API void plgReset( void )
PLUGIN_API void plgStep( short sDirection )
PLUGIN_API void plgClock( long clk, void *pParam )
PLUGIN_API void plgInstr( long clk, void *pParam )
PLUGIN_API void plgClockRate( long lClockRate )

 

Plugin API Overview

The SourceBoost IDE plugin system has an open API described below. Starting from version 2.00 (corresponding to SourceBoost 5.4) API was changed to be compiler independant (CWnd* replaced by HWND). To work, a plugin DLL must be placed into the same directory where the SourceBoost IDE is installed. When SourceBoost IDE starts it scans its installation directory and loads all plugin DLLs found there.

A SourceBoost IDE plugin is an event driven system where each of its interfaces correspond to an event. Not all interfaces described here are required for a plugin. Only plgVersion, plgCreate, plgFree and plgName must be implemented. Others are optional.

The Plugin API uses the concept of pins and connections. The simulated processor core has pins that provide connection points to the outside world - just like the real device. Each pin can have zero or more connections made to it. When a pin has connections made to it, the simulator computes the pin voltage based on the interaction of the applied voltages and impedances.

 

PLUGIN_API int plgVersion( void )

Return api version. Must return 200 which means version 2.00.

PLUGIN_API HWND plgCreate( HWND parent, void* (*SupplyFuncPtr)(const char*))
parent[in] HWND that will be the parent of the plugin window.
SupplyFuncPtr[in] pointer to a function used by plugin to get pointers to functions used to access data in simulator

Creates plugin window and returns its HWND. 
Don't access simulator from this function since when this interface gets called the simulator object doesn't exist.

Use the SupplyFuncPtr in conjuction with the ResolveFuncPtrs function declare in the pluginAPI header file.
The key here is the use it to resolve the functions, ResolveFuncPtrs returns true if successful eg:
...
if ( ResolveFuncPtrs( SupplyFuncPtr ) ) // resolve function pointers

    // all function pointers resolve - complete initialization
    ..
}
else
{
    // Handle error - initialization needs aborting
    ...
}

Once the function pointers have been resolved the following can be called else where in the code:

void GetRegHandle( char* name, HANDLE* hReg ) 

Get register handle from a register name.

void GetRegVal( HANDLE hReg, int* val )

Get register value.

void SetRegVal( HANDLE hReg, int val )

Set register value.

void AddRegChangeCallBack( HANDLE hReg, REGCHGCALLBACK pfunc, void* pParam, int iParam )

Register a callback function that gets called when register hReg is changed.

void RemoveRegChangeCallBack( HANDLE hReg, REGCHGCALLBACK pfunc, void* pParam, int iParam )

Unregister a callback function that gets called when register hReg gets changed.

void MakeConnectionToPin( const char* pinName, HANDLE* hConnection )

Apply a connection to a pin using this pin name. The pin handle will be in the hConnection upon function return. Making a connection is just like connecting wires to this pin.

void ReleaseConnection( HANDLE hConnection )

Release a connection and pin handle. Releasing the connection takes the applied voltage away, only release if the connection to the pin is no longer required - releasing is just like pulling the wires out.

void SetConnectionV( HANDLE hConnection, int mv )

Set voltage on pin.

void SetConnectionR( HANDLE hConnection, int ohm )

Set the externally applied voltage levels impedance. 0 means that pin voltage is exactly the external voltage value. -1 means infinite impedance so the pin voltage is whatever is generated inside the PIC. When driving a pin from outside use typically 5 to 50 ohm and when trying to read the voltage on a pin 10M ohm:
...
SetConnectionR( hConnection, 50 ); // for typical instrument drive
SetConnectionR( hConnection, 10000000 ); // for typical instrument input load

void GetPinV( HANDLE hConnection, int* mv )

Get pin voltage.

void AddPinVChangeCallBack( HANDLE hConnection, PINCHGCALLBACK pfunc, void* pParam, int iParam )

Register a callback function that gets called when pin voltage gets changed. pParam and iParam are passed through to the function that is callback. These can help simplify some of the plugin coding.

void RemovePinVChangeCallBack( HANDLE hConnection, PINCHGCALLBACK pfunc, void* pParam, int iParam )

Unregister a callback function that gets called when pin voltage gets changed. The parameter list here must match that used when AddPinVChangeCallBack function was called, or the callback will not be removed.

void GetClk( long* clk )

Get the current CPU clock value.

void Lock( void )

Lock simulator. This should be called when simulator access functions get called as a result of GUI activity. The locking process causes the simulator to effectively stop, so the plugin can access simulator data with fear of it changing. Also while the simulator is locked non of the callback functions get called. 
Functions in the plugin that get called through the callback mechanism do not need to called the lock function before using the simulator access functions

void Unlock( void )

Unlock simulator. This function is complementary to the the Lock function. This function should be called after the simulator data access functions have been called to allow the simulator to resume execution.

PLUGIN_API BOOL plgStart( void )

This interface gets called either when a debug session gets started and this plugin window is visible or when this plugin window gets visible during a debug session. Perform all necessary initialization that requires assess to the simulator (i.e. getting handles to the registers and pins and registering callbacks).

PLUGIN_API void plgStop( void )

This interface gets called either when a debug session gets stopped and this plugin window is visible or when this plugin window gets closed during a debug session. Perform all necessary un-initialization that requires assess to the simulator (i.e. releaseing handles to the registers and pins and un-registering callbacks).

PLUGIN_API BOOL plgFree( void )

Called when ide exits to give a plugin change to do necessary cleanups. Don't access simulator from this function since when this interface gets called the simulator object doesn't exist.

PLUGIN_API LPCTSTR plgName( void )

Plugin should return its name. This name will be used in the plugin window title and plugin menu.

PLUGIN_API void plgConfigure( HWND parent )
parent[in] HWND that will be the parent of the plugin configure dialog

Plugin is expected to show a dialog where its parameters get configured by a user.

PLUGIN_API int plgSave( BYTE *buf )
buf[in] pointer to a memory buffer to store the plugin settings

Plugin should use this interface to store its settings that are persistant between plugin creations. Such settings may be for example a pin name this plugin is connected to or its colour. If this function gets called with a NULL parameter plugin should just return the size of a buffer enough to store its state data. If buf is not NULL that it's a pointer to buffer where plugin should store its settings data. Ide will save this information in the registry.

PLUGIN_API int plgSaveState( BYTE *buf )
buf[in] pointer to a memory buffer to store the plugin state

Plugin should use this interface if it needs to handle step back and store its state data required to recreate its state when a step back occurs. If this function gets called with a NULL parameter plugin should just return the size of a buffer enough to store its state data. If buf is not NULL that it's a pointer to buffer where plugin should store its state data. Ide will save this information in the registry.

PLUGIN_API BOOL plgLoad( BYTE *buf, int len )
buf[in] pointer to a memory buffer with the plugin settings
len[in] size of the memory buffer

Plugin should initialized itself from the data pointed by buf.

PLUGIN_API BOOL plgLoadState( BYTE *buf, int len )
buf[in] pointer to a memory buffer with the plugin state
len[in] size of the memory buffer

Plugin should use this interface if it needs to handle step back and store its state data required to recreate its state when a step back occurs and if it implements the plgSaveState interface. Plugin should initialized itself from the data pointed by buf.

PLUGIN_API void plgReset( void )

Called when target is being reset

PLUGIN_API void plgStep( short sDirection )
sDirection[in] stepping direction: 0 - forward, 1 - backward

Called when code is being stepped (over, in, back or out).

PLUGIN_API void plgClock( long clk, void *pParam )
clk[in] target clock
pParam[in] reserved

Called every clock cycle.

PLUGIN_API void plgInstr( long clk, void *pParam )
clk[in] target clock
pParam[in] reserved

Called every time an instruction is executed.

PLUGIN_API void plgClockRate( long lClockRate )
lClockRate[in] simulation clock rate in Hz

Called at start of debugging and when the target clock rate is changed.

 

Appendix B: Daves Plugin Writing Guide 
(by David Hobday)

Follow these and you should end up with a happy plugin, don't use these and you may end up with deadlocks, and you plugin will become most unpopular.

Q) What can easily cause problems when writing a plugin?
A) Multi-threading is the problem, separate threads of execution can do there own thing in there own time. They can share data, which is where the danger is created. Two threads could be changing the same variable at the same time, this can cause data to become corrupt, and may crash the system.

Q) How do I make good multithreading code?
A) Using lock objects allows one thread to flag to another that it has exclusive access to an object. This prevents two threads from accessing the same data at exactly the same time.

Q) How do I lock the simulator during access from my plugin?
A) Use the Lock function, and after the access is complete use the Unlock function. The Lock function effectively pauses or blocks the simulator thread until the Unlock function is called.

Q) What is a deadlock?
A) It is the result of multiple locks being shared by multiple threads. Put simply if thread A is waiting for thread B and thread B is waiting for thread A, then the threads are going no where - they are deadlocked.

Q) What creates deadlocks in a pluging?
A) The simulator runs its own thread of execution. On various events the simulator will callback the plugin to "let it know" that something has happened. If SourceBoost IDE GUI thread locks has the GUI locked and tries to access the simulator, and simulator is calling back a plugin, and the plugin tries access some GUI functions, the plugin waits forever, and so does GUI thread - I hope thats clear.

Q) How do I avoid a deadlock in a plugin?
A) Follow Dave's carefully, and hopefully deadlocks at least will be avoided.

Daves Concepts

If you like your C++ programming then create some classes based on the following, that makes it clearer and easier to implement the rules:

Dave's Plugin Rules

1) VIEW means a class or group of functions and data that can repaint the display. This code is only ever called by the GUI thread.

2) DATA means a class or group of functions and data that holds and operates on key plugin data. The key data is that which the plugin reads or writes to the simulator. For example the voltage applied to a pin of the simulated target device.

3) VIEW can access DATA, DATA should provided access functions for this purpose (this helps to keep it clear and obvious).

4) DATA implements lock/unlock on VIEW accessed functions.

DATA needs no lock/unlock around simulator callback-only accessed functions. This is because the simulator thread will never be in these, when VIEW GUI thread is modifying data (because of the lock function stopping simulator at a know point).

5) Changes in DATA can cause GUI updates indirectly by DATA posting messages using the thread safe Windows API function postmessage. When VIEW processes theses it can safely read DATA through its access function as DATA has locks in place.

 

Legal Information

  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

  THE AUTHOR RESERVES THE RIGHT TO REJECT ANY LICENSE (REGISTRATION) REQUEST WITHOUT EXPLAINING THE REASONS WHY SUCH REQUEST HAS BEEN REJECTED. IN CASE YOUR LICENSE (REGISTRATION) REQUEST GETS REJECTED YOU MUST STOP USING THE SourceBoost IDE, C2C-PLUS, C2C++, P2C-plus and BoostC COMPILERS AND REMOVE THE WHOLE SourceBoost IDE INSTALLATION FROM YOUR COMPUTER.


http://www.sourceboost.com
Copyright 2003-2006 Pavel Baranov
Copyright 2003 Mark Duren