// vim:set syntax=asciidoc:
= The mpssespi Package













== Introduction

Future Technology Devices International, Ltd. (R)
http://www.ftdichip.com[(FTDI)]
produces a series of USB to serial converter chips that are popular for
interfacing a variety of systems across a USB bus.
................................................................................
Further,
it is possible to interface multiple SPI peripherals to the same FTDI USB to
serial converter chip and channel semantics would be further strained to
support that concept.
So this package provides a rather more direct interface to +libMPSSE-SPI+
functions.

The commands provided by the +mpssespi+ package were chosen to match those
of the ``C'' functions provided by the
http://www.ftdichip.com/Support/Documents/AppNotes/AN_178_User%20Guide%20for%20LibMPSSE-SPI.pdf[library].
However,
the commands do _not_ copy the signature of the library functions
exactly.
Some of the library functions require configuration data be passed at
each invocation.
This is tedious, especially considering that much of the configuration
information does not change for a given hardware arrangement.
Consequently,
this package provides a means of storing the necessary configuration
information as a set of defaults and commands will use that configuration
information where required by the underlying +libMPSSE-SPI+ ``C'' functions.
Commands are provided to specify and examine the configuration information
in keeping with the usual conventions of Tcl packages for introspection.

In the next section we discuss the data that the +mpssespi+ package stores.
That is followed by the commands the package provides.

== Package Data
................................................................................
This package is written in the _thread neutral_ style,
_i.e._ this package may be loaded into multiple interpreters
simultaneously.
Since the FTDI library calls use blocking I/O,
some applications may find it necessary to perform the I/O in a
separate thread to prevent blocking other activities within the application.
Although one would anticipate the I/O blocking time to be very small
for SPI bus devices,




the ability to use threads or separate interpreters is still useful
and requires little additional code to implement.
To accomplish thread neutrality,
package data is held in memory that is associated with the interpreter
and _not_ as static ``C'' variables.
Tcl provides facilities just for this purpose.

................................................................................
<4> +transferOptions+ are the default options used during read and writes
if the caller does not specify any.

As is conventional in Tcl,
resources outside of the interpreter are represented as simple strings
(_e.g._ file channels)
and extension commands then map these arbitrary strings into the
resource information that they represent.
In the +mpssespi+ package,
the open SPI channels of +libMPSSE-SPI+ are
represented by strings of the form +mpssespi<number>+,
where +<number>+ is replaced by one or more decimal digits.
The +NewHandleMapping()+ function below creates these handles and
sets up the hash table for mapping the handle string names to the
required information.

(((functions, NewHandleMapping)))

[source,c]
----
<<utility functions>>=
static Tcl_Obj *
................................................................................
                Tcl_GetString(handleName))) ;
        return TCL_ERROR ;
    }
}
----
<1> We do allow for a +NULL+ value of the +chanConfigPtr+ parameter.
This allows a lookup just to verify the channel name.


== Package Commands

With all the preliminaries out of the way,
we now turn our attention to the package commands themself.
The commands and their names were chose to map directly to the
``C'' functions provided by +libMPSSE-SPI+.
................................................................................
The commands are not a _rote_ mapping as we have discussed,
particularly in handling configuration information.

=== Get Number of Channels

(((commands,getNumChannels)))

One of the first calls that an application would make to to
obtain the number of potential FTDI SPI channels attached.
Until a channel is actually open,
+libMPSSE-SPI+ references them via indices.
Those indices start at 0 and run up to the number of attached channels
minus one (_i.e._ in traditional ``C'' array indexing style).
The +getNumChannels+ command is a direct invocation of
the +SPI_GetNumChannels()+ library function.

................................................................................
+::mpssespi getNumChannels+

The command returns an integer value that
is the the number of SPI channels available.
*****

This is usually the first command that an application would invoke.
It is necessary to determine if there are any properly connected
devices and if so, the valid range of channel indices.





(((functions, GetNumChannelsProc)))

[source,c]
----
<<command procedures>>=
static int
................................................................................
    result = SetStatusResult(interp, status) ;     /* <2> */
    if (result == TCL_OK) {
        Tcl_SetObjResult(interp, Tcl_NewLongObj(numChannels)) ;
    }
    return result ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::getNumChannels", GetNumChannelsProc,
        clientData, NULL) ;







----
<1> Support for testing the package code without a FTDI device installed.
<2> Translating +libMPSSE-SPI+ returned status values to meaningful
Tcl interpreter results is accomplished in one place <<error-handling,below>>.

We will follow the pattern established above for the commands.
First we present the source code to the command
followed by the statement to create the command.








We will also establish a pattern of including +tcltest+ test code
along with the package implementation.
Testing an attached peripheral device poses special challenges.
We must make assumptions about what is connected.
Replicating the testing environment may be difficult for others.
So to overcome some of these difficulties,
................................................................................

++serialnumber++::
    A string value giving the serial number of the channel.

++description++::
    A string value giving a description of the channel.
*****















----
<<command procedures>>=
static int
GetChannelInfoProc(
    ClientData clientData,
    Tcl_Interp *interp,
................................................................................
    return result ;

errout:
    Tcl_DecrRefCount(infoObj) ;
    return TCL_ERROR ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::getChannelInfo", GetChannelInfoProc,
        clientData, NULL) ;







----
<1> Argument parsing and processing.
<2> Invoke +SPI_GetChannelInfo()+.
<3> Convert the returned values into a Tcl dictionary.
<4> Okay, for all you +goto+ whiners out there. Yes, there will be ++goto++s
in the code. But note, they always jump *forward* in the code
(never backward as that is truly just wrong)
................................................................................
                handle) ;       /* <1> */
        Tcl_SetObjResult(interp, handleName) ;
    }

    return result ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::openChannel", OpenChannelProc,
        clientData, NULL) ;







----
<1> We finally see a channel information function invocation.
Note that the +clientData+ argument to the command function is being
cast to a pointer to a +mpssespi+  package specific object.
The command creation code arranges for that value to be passed to each
of the commands in the package.
We will see how that happens <<load-initialization, below>>,
................................................................................
It turns out that there are alot of configuration options for a SPI
channel.
So we have created some <<config-cmds,configuration commands>>
to deal with reading and updating the channel configuration.

So after opening a channel it is necessary to initialize it.
If you wish to change the configuration used for the initialization,
then you can set different configuration values before invoking
the +initChannel+ command.
Otherwise,
you end up with the <<default-config, default configuration>>.

*****
+::mpssespi initChannel+ _?handle?_

................................................................................
        chanConfig->isInitialized = 1 ;     /* <3> */
        Tcl_ResetResult(interp) ;
    }

    return result ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::initChannel", InitChannelProc,
        clientData, NULL) ;







----
<1> Here we see how the package information (as passed via the +clientData+
argument) is used to map the channel handle back to information that
is needed to invoke +libMPSSE-SPI+ functions.
We will see this pattern often in the other commands.
<2> Note that initializing the channel does not use all of the configuration
information that we are holding.
................................................................................
(((commands,getChannelConfig)))

[[config-cmds,configuration commands]]

We can no long postpone dealing with channel configuration.
There are two main pieces of configuration information.
One part deals with configuring the channel as is done in
+SPI_InitChanne()+ and
the other part is used as part of each SPI bus transaction.

We first present the +getChannelConfig+ command.
This allows us to introspect the configuration that is being stored.

*****
+::mpssespi getChannelConfig+ _handle_

_handle_::
    A +mpssespi+ channel handle as returned from a successful call to
    the +openChannel+ command.
................................................................................
    Tcl_DecrRefCount(pinObj) ;

errorout:
    Tcl_DecrRefCount(configObj) ;
    return TCL_ERROR ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::getChannelConfig",
        GetChannelConfigProc, clientData, NULL) ;







----
<1> +GetDirectionDict()+ is discussed <<pin-direction-configuration, below>>.
<2> +GetPinValueDict()+ is also discussed <<pin-direction-configuration, below>>.
<3> Constants of the form +SPI_TRANSFER_OPTIONS_XXX+ are found in
the +libMPSSE_spi.h+ header file.

[source,tcl]
................................................................................
    return TCL_OK ;

errorout:
    Tcl_DecrRefCount(keyObj) ;
    return TCL_ERROR ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::setChannelConfig",
        SetChannelConfigProc, clientData, NULL) ;







----
<1> Here we take a copy of the channel configuration.
As we decode the input dictionary argument, the values are placed in this
copy.
<2> Missing keys are just silently ignored.
<3> Since transfer options may also be given on commands that
cause SPI bus transactions,
................................................................................
        DeleteHandleMapping(pkgInfo, handleObj) ; /* <1> */
        Tcl_ResetResult(interp) ;
    }

    return result ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::closeChannel", CloseChannelProc,
        clientData, NULL) ;







----
<1> We clean up the handle mapping and configuration information here.

[source,tcl]
----
<<closeChannel tests>>=
test closeChannel-1.0 {
................................................................................
    } else {
        Tcl_DecrRefCount(inputObj) ;
    }

    return result ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::readChannel", ReadChannelProc,
        clientData, NULL) ;







----
<1> The returned result will be a byte array.
The length is determined by how much data was requested.
<2> For bit transfers, if the number of bits transferred is not a
byte multiple, then we shift the residual bits to the upper part
of the byte.
This recognizes that the order is most significant bits first and
................................................................................
    if (result == TCL_OK) {
        Tcl_SetObjResult(interp, Tcl_NewIntObj(xferActual)) ;
    }

    return result ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::writeChannel", WriteChannelProc,
        clientData, NULL) ;







----

One minor complication in writing is we need to make sure that if
the user has specified that the units of transfer is to be _bits_
that he has given us a buffer that contains at least that many bits.
For transfers in _bytes_ units, we can simply take the lenght of the
tranfer.
................................................................................
    } else {
        Tcl_DecrRefCount(inputObj) ;
    }

    return result ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::readWriteChannel",
        ReadWriteChannelProc, clientData, NULL) ;







----

[source,tcl]
----
<<readWriteChannel tests>>=
test readWriteChannel-1.0 {
    read/write a channel
................................................................................
    if (result == TCL_OK) {
        Tcl_SetObjResult(interp, Tcl_NewBooleanObj(busyStatus)) ;
    }

    return result ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::isBusy", IsBusyProc, clientData,
        NULL) ;







----

[source,tcl]
----
<<isBusy tests>>=
test isBusy-1.0 {
    check if a channel is busy
................................................................................
    if (result == TCL_OK) {
        Tcl_ResetResult(interp) ;
    }

    return result ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::changeCS", ChangeCSProc, clientData,
        NULL) ;







----

[source,tcl]
----
<<changeCS tests>>=
test changeCS-1.0 {
    change config options
................................................................................
    if (result == TCL_OK) {
        Tcl_ResetResult(interp) ;
    }

    return result ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::writeGPIO", WriteGPIOProc,
        clientData, NULL) ;







----
<1> The function for handling I/O pin directions and values were
also used for setting configuration information.

[source,tcl]
----
<<writeGPIO tests>>=
................................................................................
        return TCL_ERROR ;
    }

    Tcl_SetObjResult(interp, valueDict) ;
    return TCL_OK ;
}





<<command creation>>=
Tcl_CreateObjCommand(interp, "::mpssespi::readGPIO", ReadGPIOProc,
        clientData, NULL) ;







----

[source,tcl]
----
<<readGPIO tests>>=
test readGPIO-1.0 {
    input GPIO values
................................................................................
DLLEXPORT       /* <1> */
int
Mpssespi_Init(
    Tcl_Interp *interp)
{
    ClientData clientData ;
    Tcl_Namespace *ns ;



    if (Tcl_InitStubs(interp, TCL_VERSION, 0) == NULL) {
        return TCL_ERROR ;
    }

    clientData = NewMPSSEPkgInfo(interp) ;  /* <2> */

................................................................................

    <<namespace creation>>
    <<command creation>>
    <<ensemble creation>>

    <<package configuration>>

    Tcl_PkgProvide(interp, "mpssespi", PACKAGE_VERSION) ;
    return TCL_OK ;





}
----
<1> Needed to build under Windows.
<2> We create new package specific storage and pass it's pointer as the
+clientData+ to each command procedure.

=== Creating the Package Namespace
................................................................................
[source,c]
----
<<static data>>=
static char const mpssespi_ns_name[] = "::mpssespi" ;

<<namespace creation>>=
ns = Tcl_CreateNamespace(interp, mpssespi_ns_name, NULL, NULL) ;

----



We build the ensemble command by exporting all the commands in the
namespace and then creating the ensemble.



[source,c]
----
<<ensemble creation>>=
if (Tcl_Export(interp, ns, "*", 0) != TCL_OK) {
    return TCL_ERROR ;

}
(void)Tcl_CreateEnsemble(interp, mpssespi_ns_name, ns, TCL_ENSEMBLE_PREFIX) ;
----

==== Unloading

Unloading is supported and we use this as a good place to call the library
clean up function.

................................................................................
of package configuration in formation.

Here we support keys of +pkgname+, +version+ and +copyright+.

[source,c]
----
<<static data>>=
#if TCL_MAJOR_VERSION >= 8 && TCL_MINOR_VERSION >= 5
static Tcl_Config mpssespi_config[] = {
    {"pkgname", PACKAGE_NAME},
    {"version", PACKAGE_VERSION},
    {"copyright",
"This software is copyrighted 2014 by G. Andrew Mangogna.\
 Terms and conditions for use are distributed with the source code."},
    {NULL, NULL}
} ;
#endif
----

We must register the configuration information.

[source,c]
----
<<package configuration>>=
#       if TCL_MAJOR_VERSION >= 8 && TCL_MINOR_VERSION >= 5
    Tcl_RegisterConfig(interp, PACKAGE_NAME, mpssespi_config, "iso8859-1") ;
#       endif
----

== Source Organization

This document is a literate program.
As you have seen it contains both description and source
code to the package.
................................................................................
<<command procedures>>

/*
 * EXTERNAL FUNCTION DEFINITIONS
 */
<<initialization>>

#if TCL_MAJOR_VERSION >= 8 && TCL_MINOR_VERSION >= 5
<<unloading>>
#endif /* TCL_MAJOR_VERSION >= 8 && TCL_MINOR_VERSION >= 5 */
----

=== Test Source

A +tcltest+ source file can be extracted starting at the +mpssespi.test+ root.

[source,tcl]
................................................................................
        csactive high
    }
    mpssespi initChannel $spichan       ; # <1>

    for {set address 0} {$address < 16} {incr address} {
        set data [expr {$address + 3}]
        puts "writing address $address, data = $data"
        set bindata [binary format S $data]
        write_byte $spichan $address $bindata
    }

    for {set address 0} {$address < 16} {incr address} {
        set bindata [read_byte $spichan $address]
        binary scan $bindata Su $bindata data
        puts "reading address $address, data = $data"
    }

    mpssespi closeChannel $spichan
}

# Run the example
main
----
<1> We copy the configuration information from the example.
Note this chip uses an active high chip select.

















== Special Linux Considerations

Most modern version of Linux use *udev* as the means of handling
hot plugged devices.
Associated with *udev* are a set of rules that determine how devices
are handled.
................................................................................
For example, leaving out the +ATTR\{serial}== ...+, clause will
cause the rule to match all FTDI devices.
You can consult the many posting on the Internet about writing +udev+ rules.
The example above is just to get you started thinking about what would
be needed to make the file permissions work smoothly in your particular
configuration.













== Known Problems

[[known-problems, known problems]]
As of version 1.0,
it seems that invoking the +readWriteChannel+ command using transfer
units of +bytes+ does not function properly.
The SPI bus transactions are not correct.

// vim:set syntax=asciidoc:
= The mpssespi Package

[abstract]
--
This document is a literate program for the +mpssespi+ Tcl package.
As a literate program it contains both a discussion of the details
of the package as well as the implementation source code.
The +mpssespi+ package provides a Tcl interface to the FTDI
libMPSSE-SPI library.
This library is used to interface FTDI USB to serial converter chips
to SPI bus peripheral components allowing the peripherals
to be controlled across a USB interface.
--

== Introduction

Future Technology Devices International, Ltd. (R)
http://www.ftdichip.com[(FTDI)]
produces a series of USB to serial converter chips that are popular for
interfacing a variety of systems across a USB bus.
................................................................................
Further,
it is possible to interface multiple SPI peripherals to the same FTDI USB to
serial converter chip and channel semantics would be further strained to
support that concept.
So this package provides a rather more direct interface to +libMPSSE-SPI+
functions.

The names of the commands provided by the +mpssespi+ package were chosen to
match those of the ``C'' functions provided by the
http://www.ftdichip.com/Support/Documents/AppNotes/AN_178_User%20Guide%20for%20LibMPSSE-SPI.pdf[library].
However,
the commands do _not_ copy the signature of the library functions
exactly.
Some of the library functions require configuration data be passed at
each invocation.
This is tedious, especially considering that much of the configuration
information does not change for a given hardware arrangement.
Consequently,
this package provides a means of storing the necessary configuration
information as a set of defaults and commands will use that configuration
information where required by the underlying +libMPSSE-SPI+ functions.
Commands are provided to specify and examine the configuration information
in keeping with the usual conventions of Tcl packages for introspection.

In the next section we discuss the data that the +mpssespi+ package stores.
That is followed by the commands the package provides.

== Package Data
................................................................................
This package is written in the _thread neutral_ style,
_i.e._ this package may be loaded into multiple interpreters
simultaneously.
Since the FTDI library calls use blocking I/O,
some applications may find it necessary to perform the I/O in a
separate thread to prevent blocking other activities within the application.
Although one would anticipate the I/O blocking time to be very small
for SPI bus devicesfootnote:[Recall that the SPI bus is clocked
_synchronously_ and its operation does not really depend upon
the peripheral device even being present.
Consequently, the I/O time is simply the time associated with
the number of bits clocked onto and off of the SPI bus.],
the ability to use threads or separate interpreters is still useful
and requires little additional code to implement.
To accomplish thread neutrality,
package data is held in memory that is associated with the interpreter
and _not_ as static ``C'' variables.
Tcl provides facilities just for this purpose.

................................................................................
<4> +transferOptions+ are the default options used during read and writes
if the caller does not specify any.

As is conventional in Tcl,
resources outside of the interpreter are represented as simple strings
(_e.g._ file channels)
and extension commands then map these arbitrary strings into the
extension specific resource information they represent.
In the +mpssespi+ package,
the open SPI channels of +libMPSSE-SPI+ are
represented by strings of the form +mpssespi<number>+,
where +<number>+ is replaced by one or more decimal digits.
The +NewHandleMapping()+ function below creates these handles and
sets up the hash table for mapping the handle string names to the
channel information.

(((functions, NewHandleMapping)))

[source,c]
----
<<utility functions>>=
static Tcl_Obj *
................................................................................
                Tcl_GetString(handleName))) ;
        return TCL_ERROR ;
    }
}
----
<1> We do allow for a +NULL+ value of the +chanConfigPtr+ parameter.
This allows a lookup just to verify the channel name.
However, this is not a feature of the function used in the package.

== Package Commands

With all the preliminaries out of the way,
we now turn our attention to the package commands themself.
The commands and their names were chose to map directly to the
``C'' functions provided by +libMPSSE-SPI+.
................................................................................
The commands are not a _rote_ mapping as we have discussed,
particularly in handling configuration information.

=== Get Number of Channels

(((commands,getNumChannels)))

One of the first things that an application should determine is the
the number of attached FTDI SPI channels.
Until a channel is actually open,
+libMPSSE-SPI+ references them via indices.
Those indices start at 0 and run up to the number of attached channels
minus one (_i.e._ in traditional ``C'' array indexing style).
The +getNumChannels+ command is a direct invocation of
the +SPI_GetNumChannels()+ library function.

................................................................................
+::mpssespi getNumChannels+

The command returns an integer value that
is the the number of SPI channels available.
*****

This is usually the first command that an application would invoke.
It is necessary to determine the valid range of channel indices.
Note that if there are multiple channels attached,
this call still does not tell you enough information to determine
to which channel the peripheral is attached.
All you can determine here by this command is the total number
of attached channels.

(((functions, GetNumChannelsProc)))

[source,c]
----
<<command procedures>>=
static int
................................................................................
    result = SetStatusResult(interp, status) ;     /* <2> */
    if (result == TCL_OK) {
        Tcl_SetObjResult(interp, Tcl_NewLongObj(numChannels)) ;
    }
    return result ;
}

<<static data>>=
static char const getNumChannelsCmdName[] = "::mpssespi::getNumChannels" ;
static char const getNumChannelsName[] = "getNumChannels" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, getNumChannelsCmdName, GetNumChannelsProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, getNumChannelsName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(getNumChannelsName, -1),
        Tcl_NewStringObj(getNumChannelsCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----
<1> Support for testing the package code without a FTDI device installed.
<2> Translating +libMPSSE-SPI+ returned status values to meaningful
Tcl interpreter results is accomplished in one place <<error-handling,below>>.

We will follow the pattern established above for the commands.
First we present the source code to the command
followed by the statements to create the command.
For this package,
we export all the commands and will then create a +namespace ensemble+
command that has the same name as the namespace where the commands
reside.
We will also supply an ensemble mapping dictionary.
The intent of all of this is to allow the ensemble of the package
to be extended at the script level.

We will also establish a pattern of including +tcltest+ test code
along with the package implementation.
Testing an attached peripheral device poses special challenges.
We must make assumptions about what is connected.
Replicating the testing environment may be difficult for others.
So to overcome some of these difficulties,
................................................................................

++serialnumber++::
    A string value giving the serial number of the channel.

++description++::
    A string value giving a description of the channel.
*****

The information given by this command can be used to determine which
SPI channel is connected to a particular peripheral.
By some experimentation of hot plugging and unplugging the FTDI converter,
you should be able to determine the serial number or location ID
of the channel attached to your peripheral.
The details of this are, of course, specific to your hardware arrangement
but once determined it is a simple script to search the channel
information of all the attached SPI channels for the one connected to
your peripheral.
It is also quite common to have only a single FTDI converter attached.
In this case, finding the correct channel is trivial.
The reason all this is necessary is that we must know the index of
the channel we wish to open and those indices are not predetermined.

----
<<command procedures>>=
static int
GetChannelInfoProc(
    ClientData clientData,
    Tcl_Interp *interp,
................................................................................
    return result ;

errout:
    Tcl_DecrRefCount(infoObj) ;
    return TCL_ERROR ;
}

<<static data>>=
static char const getChannelInfoCmdName[] = "::mpssespi::getChannelInfo" ;
static char const getChannelInfoName[] = "getChannelInfo" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, getChannelInfoCmdName, GetChannelInfoProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, getChannelInfoName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(getChannelInfoName, -1),
        Tcl_NewStringObj(getChannelInfoCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----
<1> Argument parsing and processing.
<2> Invoke +SPI_GetChannelInfo()+.
<3> Convert the returned values into a Tcl dictionary.
<4> Okay, for all you +goto+ whiners out there. Yes, there will be ++goto++s
in the code. But note, they always jump *forward* in the code
(never backward as that is truly just wrong)
................................................................................
                handle) ;       /* <1> */
        Tcl_SetObjResult(interp, handleName) ;
    }

    return result ;
}

<<static data>>=
static char const openChannelCmdName[] = "::mpssespi::openChannel" ;
static char const openChannelName[] = "openChannel" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, openChannelCmdName, OpenChannelProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, openChannelName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(openChannelName, -1),
        Tcl_NewStringObj(openChannelCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----
<1> We finally see a channel information function invocation.
Note that the +clientData+ argument to the command function is being
cast to a pointer to a +mpssespi+  package specific object.
The command creation code arranges for that value to be passed to each
of the commands in the package.
We will see how that happens <<load-initialization, below>>,
................................................................................
It turns out that there are alot of configuration options for a SPI
channel.
So we have created some <<config-cmds,configuration commands>>
to deal with reading and updating the channel configuration.

So after opening a channel it is necessary to initialize it.
If you wish to change the configuration used for the initialization,
then you can set different configuration values *before* invoking
the +initChannel+ command.
Otherwise,
you end up with the <<default-config, default configuration>>.

*****
+::mpssespi initChannel+ _?handle?_

................................................................................
        chanConfig->isInitialized = 1 ;     /* <3> */
        Tcl_ResetResult(interp) ;
    }

    return result ;
}

<<static data>>=
static char const initChannelCmdName[] = "::mpssespi::initChannel" ;
static char const initChannelName[] = "initChannel" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, initChannelCmdName, InitChannelProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, initChannelName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(initChannelName, -1),
        Tcl_NewStringObj(initChannelCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----
<1> Here we see how the package information (as passed via the +clientData+
argument) is used to map the channel handle back to information that
is needed to invoke +libMPSSE-SPI+ functions.
We will see this pattern often in the other commands.
<2> Note that initializing the channel does not use all of the configuration
information that we are holding.
................................................................................
(((commands,getChannelConfig)))

[[config-cmds,configuration commands]]

We can no long postpone dealing with channel configuration.
There are two main pieces of configuration information.
One part deals with configuring the channel as is done in
+SPI_InitChannel()+ and
the other part is used for each SPI bus transaction.

We first present the +getChannelConfig+ command.
This allows us to inspect the configuration that is being stored.

*****
+::mpssespi getChannelConfig+ _handle_

_handle_::
    A +mpssespi+ channel handle as returned from a successful call to
    the +openChannel+ command.
................................................................................
    Tcl_DecrRefCount(pinObj) ;

errorout:
    Tcl_DecrRefCount(configObj) ;
    return TCL_ERROR ;
}

<<static data>>=
static char const getChannelConfigCmdName[] = "::mpssespi::getChannelConfig" ;
static char const getChannelConfigName[] = "getChannelConfig" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, getChannelConfigCmdName, GetChannelConfigProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, getChannelConfigName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(getChannelConfigName, -1),
        Tcl_NewStringObj(getChannelConfigCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----
<1> +GetDirectionDict()+ is discussed <<pin-direction-configuration, below>>.
<2> +GetPinValueDict()+ is also discussed <<pin-direction-configuration, below>>.
<3> Constants of the form +SPI_TRANSFER_OPTIONS_XXX+ are found in
the +libMPSSE_spi.h+ header file.

[source,tcl]
................................................................................
    return TCL_OK ;

errorout:
    Tcl_DecrRefCount(keyObj) ;
    return TCL_ERROR ;
}

<<static data>>=
static char const setChannelConfigCmdName[] = "::mpssespi::setChannelConfig" ;
static char const setChannelConfigName[] = "setChannelConfig" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, setChannelConfigCmdName, SetChannelConfigProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, setChannelConfigName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(setChannelConfigName, -1),
        Tcl_NewStringObj(setChannelConfigCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----
<1> Here we take a copy of the channel configuration.
As we decode the input dictionary argument, the values are placed in this
copy.
<2> Missing keys are just silently ignored.
<3> Since transfer options may also be given on commands that
cause SPI bus transactions,
................................................................................
        DeleteHandleMapping(pkgInfo, handleObj) ; /* <1> */
        Tcl_ResetResult(interp) ;
    }

    return result ;
}

<<static data>>=
static char const closeChannelCmdName[] = "::mpssespi::closeChannel" ;
static char const closeChannelName[] = "closeChannel" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, closeChannelCmdName, CloseChannelProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, closeChannelName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(closeChannelName, -1),
        Tcl_NewStringObj(closeChannelCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----
<1> We clean up the handle mapping and configuration information here.

[source,tcl]
----
<<closeChannel tests>>=
test closeChannel-1.0 {
................................................................................
    } else {
        Tcl_DecrRefCount(inputObj) ;
    }

    return result ;
}

<<static data>>=
static char const readChannelCmdName[] = "::mpssespi::readChannel" ;
static char const readChannelName[] = "readChannel" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, readChannelCmdName, ReadChannelProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, readChannelName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(readChannelName, -1),
        Tcl_NewStringObj(readChannelCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----
<1> The returned result will be a byte array.
The length is determined by how much data was requested.
<2> For bit transfers, if the number of bits transferred is not a
byte multiple, then we shift the residual bits to the upper part
of the byte.
This recognizes that the order is most significant bits first and
................................................................................
    if (result == TCL_OK) {
        Tcl_SetObjResult(interp, Tcl_NewIntObj(xferActual)) ;
    }

    return result ;
}

<<static data>>=
static char const writeChannelCmdName[] = "::mpssespi::writeChannel" ;
static char const writeChannelName[] = "writeChannel" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, writeChannelCmdName, WriteChannelProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, writeChannelName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(writeChannelName, -1),
        Tcl_NewStringObj(writeChannelCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----

One minor complication in writing is we need to make sure that if
the user has specified that the units of transfer is to be _bits_
that he has given us a buffer that contains at least that many bits.
For transfers in _bytes_ units, we can simply take the lenght of the
tranfer.
................................................................................
    } else {
        Tcl_DecrRefCount(inputObj) ;
    }

    return result ;
}

<<static data>>=
static char const readWriteChannelCmdName[] = "::mpssespi::readWriteChannel" ;
static char const readWriteChannelName[] = "readWriteChannel" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, readWriteChannelCmdName, ReadWriteChannelProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, readWriteChannelName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(readWriteChannelName, -1),
        Tcl_NewStringObj(readWriteChannelCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----

[source,tcl]
----
<<readWriteChannel tests>>=
test readWriteChannel-1.0 {
    read/write a channel
................................................................................
    if (result == TCL_OK) {
        Tcl_SetObjResult(interp, Tcl_NewBooleanObj(busyStatus)) ;
    }

    return result ;
}

<<static data>>=
static char const isBusyCmdName[] = "::mpssespi::isBusy" ;
static char const isBusyName[] = "isBusy" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, isBusyCmdName, IsBusyProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, isBusyName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(isBusyName, -1),
        Tcl_NewStringObj(isBusyCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----

[source,tcl]
----
<<isBusy tests>>=
test isBusy-1.0 {
    check if a channel is busy
................................................................................
    if (result == TCL_OK) {
        Tcl_ResetResult(interp) ;
    }

    return result ;
}

<<static data>>=
static char const changeCSCmdName[] = "::mpssespi::changeCS" ;
static char const changeCSName[] = "changeCS" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, changeCSCmdName, ChangeCSProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, changeCSName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(changeCSName, -1),
        Tcl_NewStringObj(changeCSCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----

[source,tcl]
----
<<changeCS tests>>=
test changeCS-1.0 {
    change config options
................................................................................
    if (result == TCL_OK) {
        Tcl_ResetResult(interp) ;
    }

    return result ;
}

<<static data>>=
static char const writeGPIOCmdName[] = "::mpssespi::writeGPIO" ;
static char const writeGPIOName[] = "writeGPIO" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, writeGPIOCmdName, WriteGPIOProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, writeGPIOName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(writeGPIOName, -1),
        Tcl_NewStringObj(writeGPIOCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----
<1> The function for handling I/O pin directions and values were
also used for setting configuration information.

[source,tcl]
----
<<writeGPIO tests>>=
................................................................................
        return TCL_ERROR ;
    }

    Tcl_SetObjResult(interp, valueDict) ;
    return TCL_OK ;
}

<<static data>>=
static char const readGPIOCmdName[] = "::mpssespi::readGPIO" ;
static char const readGPIOName[] = "readGPIO" ;

<<command creation>>=
Tcl_CreateObjCommand(interp, readGPIOCmdName, ReadGPIOProc,
        clientData, NULL) ;
if (Tcl_Export(interp, ns, readGPIOName, 0) != TCL_OK) {
    goto errorout ;
}
if (Tcl_DictObjPut(interp, mapObj, Tcl_NewStringObj(readGPIOName, -1),
        Tcl_NewStringObj(readGPIOCmdName, -1)) != TCL_OK) {
    goto errorout ;
}
----

[source,tcl]
----
<<readGPIO tests>>=
test readGPIO-1.0 {
    input GPIO values
................................................................................
DLLEXPORT       /* <1> */
int
Mpssespi_Init(
    Tcl_Interp *interp)
{
    ClientData clientData ;
    Tcl_Namespace *ns ;
    Tcl_Obj *mapObj ;
    Tcl_Command cmdToken ;

    if (Tcl_InitStubs(interp, TCL_VERSION, 0) == NULL) {
        return TCL_ERROR ;
    }

    clientData = NewMPSSEPkgInfo(interp) ;  /* <2> */

................................................................................

    <<namespace creation>>
    <<command creation>>
    <<ensemble creation>>

    <<package configuration>>

    Tcl_PkgProvide(interp, PACKAGE_NAME, PACKAGE_VERSION) ;
    return TCL_OK ;

errorout:
    Tcl_DecrRefCount(mapObj) ;
    Tcl_DeleteNamespace(ns) ;
    return TCL_ERROR ;
}
----
<1> Needed to build under Windows.
<2> We create new package specific storage and pass it's pointer as the
+clientData+ to each command procedure.

=== Creating the Package Namespace
................................................................................
[source,c]
----
<<static data>>=
static char const mpssespi_ns_name[] = "::mpssespi" ;

<<namespace creation>>=
ns = Tcl_CreateNamespace(interp, mpssespi_ns_name, NULL, NULL) ;
mapObj = Tcl_NewDictObj() ;     /* <1> */
----
<1> We also obtain a dictionary object that is used to create
the ensemble command mapping.



Once all the commands have been created and exported,
we can create the ensemble command and install the command map.

[source,c]
----
<<ensemble creation>>=
cmdToken = Tcl_CreateEnsemble(interp, mpssespi_ns_name, ns, TCL_ENSEMBLE_PREFIX) ;
if (Tcl_SetEnsembleMappingDict(interp, cmdToken, mapObj) != TCL_OK) {
    goto errorout ;
}

----

==== Unloading

Unloading is supported and we use this as a good place to call the library
clean up function.

................................................................................
of package configuration in formation.

Here we support keys of +pkgname+, +version+ and +copyright+.

[source,c]
----
<<static data>>=

static Tcl_Config mpssespi_config[] = {
    {"pkgname", PACKAGE_NAME},
    {"version", PACKAGE_VERSION},
    {"copyright",
"This software is copyrighted 2014 by G. Andrew Mangogna.\
 Terms and conditions for use are distributed with the source code."},
    {NULL, NULL}
} ;

----

We must register the configuration information.

[source,c]
----
<<package configuration>>=

    Tcl_RegisterConfig(interp, PACKAGE_NAME, mpssespi_config, "iso8859-1") ;

----

== Source Organization

This document is a literate program.
As you have seen it contains both description and source
code to the package.
................................................................................
<<command procedures>>

/*
 * EXTERNAL FUNCTION DEFINITIONS
 */
<<initialization>>


<<unloading>>

----

=== Test Source

A +tcltest+ source file can be extracted starting at the +mpssespi.test+ root.

[source,tcl]
................................................................................
        csactive high
    }
    mpssespi initChannel $spichan       ; # <1>

    for {set address 0} {$address < 16} {incr address} {
        set data [expr {$address + 3}]
        puts "writing address $address, data = $data"
        set bindata [binary format S $data]     ; # <2>
        write_byte $spichan $address $bindata
    }

    for {set address 0} {$address < 16} {incr address} {
        set bindata [read_byte $spichan $address]
        binary scan $bindata Su $bindata data   ; # <3>
        puts "reading address $address, data = $data"
    }

    mpssespi closeChannel $spichan
}

# Run the example
main
----
<1> We copy the configuration information from the example.
Note this chip uses an active high chip select.
<2> The SPI bus deals in raw binary data. The contents of the +data+
variable, like all things in Tcl, is represented as a string.
<3> Conversely, the data read from the SPI bus is binary and
needs to be scanned to obtain a Tcl string representation.

This example is very simple, as most examples are.
It also follows the design flow of the original ``C'' program
from FTDI.
My suggestion for users of this package is to create chip specific
packages that deal with the commands and transaction as
required for the specific chip.
That chip specific package would then use the +mpssespi+ package
to perform the actual SPI bus transactions.
It's worth sorting through the chip data sheet and encoding the
particular way a chip works into a package so that you can
get on with other matters.

== Special Linux Considerations

Most modern version of Linux use *udev* as the means of handling
hot plugged devices.
Associated with *udev* are a set of rules that determine how devices
are handled.
................................................................................
For example, leaving out the +ATTR\{serial}== ...+, clause will
cause the rule to match all FTDI devices.
You can consult the many posting on the Internet about writing +udev+ rules.
The example above is just to get you started thinking about what would
be needed to make the file permissions work smoothly in your particular
configuration.

Another problem you may have when loading the package is occurs if
the +D2XX+ library is not found.
In that case, there will be a core dump with the following message:

----
../../Infra/src/ftdi_infra.c:243:Init_libMPSSE(): NULL expression encountered
----

It may be necessary to set the value of the +LD_LIBRARY_PATH+ environment
variable to include the directory where the driver is installed.
FTDI installation instruction place the driver in +/usr/local/lib+.

== Known Problems

[[known-problems, known problems]]
As of version 1.0,
it seems that invoking the +readWriteChannel+ command using transfer
units of +bytes+ does not function properly.
The SPI bus transactions are not correct.