INTRODUCTION
Starting with version gpsim-0.20.0, support for external modules has been added. This allows gpsim to create a full simulation environment that extends beyond just a PIC. It also provides for users to create their own simulation modules without having to be aware of the detailed internals of gpsim.
The module approach attempts to leverage off the gpsim infrastructure. The definition of a pic processor is now derived from a `module'. A module can have pins just like a PIC. The node infrastructure for connecting stimuli to gpsim I/O pins has been extended to now include the module I/O pins. Break points and internal module events can be traced just like they are in a real pic. A stimulus can be connected to a module. In fact, although I haven't tried it, gpsim can almost simulate a module with no PIC present!
Several example modules have been created and serve as example templates. These are found in the ./modules/ subdirectory. In addition, examples may also be found in the ./examples/14bit/ subdirectory that illustrate how the modules can be used.
HOW DO I LOAD A MODULE?
A new command called 'module' has been added to gpsim.
Straight from gpsim:
gpsim> help module
module [ [load module_type [module_name]] | [lib lib_name] | [list] |
[[dump | pins] module_name] ]
If no options are specified, then the currently defined module(s)
will be displayed. This is the same as the `module list' command.
The `module load lib_name' tells gpsim to search for the module
library called `lib_name' and to load it. (Note that the format of
module libraries is exactly the same as a Linux shared library. This
means that the module library should reside in a path available to
dlopen(). Please see the README.MODULES in the gpsim distribution.
To instantiate a new module, then type
module module_type module_name
where module_type refers to a specific module in a module library
and module_name is the user name assigned to it.
Information about a module can be displayed by the commad
module module_name [dump | pins]
where module_name is the name that you assigned when the module
was instantiated. The optional dump and pins identifiers specify
the information you wish to display (dump is the default).
examples:
module // Display the modules you've already defined.
module lib my_mods.so // Load the module library called my_mods.
module list // Display the list of modules supported.
module load lcd my_lcd // Create an instance of an 'lcd'
module pins my_lcd // Display the pin states of an instantiated module
module load lcd lcd2x20 // Create a new module.
module load led start_light // and another.
As you can see, there's a whole lot of stuff packed into this new command.
HOW DO I CREATE MY OWN MODULE?
Probably the best place to begin is to find a pre-existing module that is close to the one you wish to create and then make copy it and make changes.
(basic structure of modules)
HOW DO I CREATE A LIBRARY FOR MY MODULES?
Without a doubt, the best thing to do is copy the way gpsim does it.
The distributions for the LED and the Logic modules is probably the best place to begin. There are many details that I can't satisfactory cover in the scope of this document.
In the example module libraries you'll find two major sections. First there's something I've called the `module manager'. This is a necessary managerial layer that provides the dynamic interface. Second is the module section that defines a module's behavior.
Module Manager
The module manager provides the dynamic link support.
There are several mandatory functions:
get_mod_list()
This function returns a pointer to the list of modules that are supported in the library.
/*********************************************************
- mod_list - Display all of the modules in this library. *
- This is a required function for gpsim compliant libraries. */
Module_Types * get_mod_list(void)
{
return available_modules;
}
For this to work of course, a list called `available_modules' of type Module_Types must be declared. From the Led library, the list is only one deep and looks like so:
/*
class Module_Types
{
public:
char names[2];
Module (module_constructor) (void);
};
/
Module_Types available_modules[] =
{
{ "led_7Segments", "led", Led_7Segments::construct},
{ 0,0,0} // indicates there are no more modules
};
The first two parameters are names that the module may be called. The last parameter is a pointer to a static member function of the module. gpsim will call this function to create a new module.
Note the all 0's module. This marks the end of the list.
more...
Shared Libraries
The link between modules and gpsim is `dynamic'. Which is to say, when gpsim is compiled it knows nothing about a specific module. Similarly, when a module is compiled it is done so indepently of gpsim. The module compilation depends on gpsim only to the degree of using the include files provided. The module compilation however does not include a step at which it is linked with gpsim. Is that clear? I guess the point to understand, is that gpsim and the modules are built separately.
Now, when gpsim loads a module, it will open the `shared library' in which it is contained. The infrastructure of shared libraries is defined by the OS and not by gpsim. Consequently, there are a few details that have to be managed before the shared libraries will work properly.
(ldconfig)
$ more /etc/ld.so.conf
/usr/X11R6/lib
/usr/i486-linux-libc5/lib
/usr/local/lib
/usr/lib