Tree [73743d] release/20120618 /
History



File Date Author Commit
demos 2012-06-08 Peter A. Bigot Peter A. Bigot [89eac7] demos/clocks: add RF2500T support
lib 2012-05-20 Peter A. Bigot Peter A. Bigot [eec28c] dpasm.inc: remove .ident generated due to elfos.h
scripts 2012-01-18 Peter A. Bigot Peter A. Bigot [316e10] capture: support 9600-baud serial (non-HID) cap...
support 2012-06-18 Peter A. Bigot Peter A. Bigot [73743d] Update version number and release notes
template 2011-12-11 Peter A. Bigot Peter A. Bigot [c46594] Update to current variable names
tests 2012-01-14 Peter A. Bigot Peter A. Bigot [0e9e19] Rename TEST430_INHIBIT_PUTCHAR to TEST430_INHIB...
.gitignore 2011-12-24 Peter A. Bigot Peter A. Bigot [aa7a1f] Ignore various derived files
LICENSE 2011-11-26 Peter A. Bigot Peter A. Bigot [3cac2a] Add copyright and BSD-3-Clause references
Makefile.common 2012-06-01 Peter A. Bigot Peter A. Bigot [2c0a37] Makefile.common: support TEST430_MEMORY_MODEL a...
README.txt 2011-12-07 Peter A. Bigot Peter A. Bigot [380ada] Move template out of test area since it does no...
RELEASES.TXT 2012-06-18 Peter A. Bigot Peter A. Bigot [73743d] Update version number and release notes

Read Me

*********************
The Test430 Framework
*********************

`test430 <https://sourceforge.net/projects/mspgcc/files/test430/>`_ is a
build environment framework for simple tests and demonstrations, primarily
intended for MSP430 development in a POSIX shell environment.  It is used
for the regression suite for the `MSP430 GNU Toolchain
<http://sourceforge.net/projects/mspgcc/>`_ and for other packages.  It
provides a board-independent framework supporting display via serial output,
display via LED, and high-precision timing (where supported).

.. contents::

Basic Steps
===========

* Define the environment variable ``TEST430_ROOT`` to the absolute path to
  the directory holding a test430 release.

* Ensure you have a modern version of the `pyserial
  <http://pyserial.sourceforge.net/>`_ package, and the `pyusb
  <http://pyusb.sourceforge.net/>`_ package.

* Look at the examples in the ``tests`` subdirectory, and read the comments
  in ``Makefile.common``, ``lib/make/*.inc``, and ``support/test430.h``.

* Create new tests by copying the files in ``${TEST430_ROOT}/template`` to a
  new directory and modifying them.

* File bug reports on the `mspgcc SourceForge project
  <https://sourceforge.net/tracker/?func=browse&group_id=42303&atid=432701>`_.

* Track development/enhancements using the repository at
  git://mspgcc.git.sourceforge.net/gitroot/mspgcc/test430

Design
======
 
Although test430 is currently targeted at platforms using the Texas
Instruments MSP430 processor, it could easily be used for other
microcontrollers.  For development involving more powerful processors,
existing solutions such as `CUnit <http://cunit.sourceforge.net/>`_ are
more appropriate.  Its development was born of a violent rejection of
DejaGNU, for the same sort of reasons that were elegantly and independently
summarized by `Ian Lance Taylor <http://www.airs.com/blog/archives/499>`_.

Guiding principles for test430 included:

* Support the "natural" workflow within a POSIX shell: independent stages
  including build, install, execute, capture test output, validate results

* Trivialize creation of a new test: inherited shared material from
  somewhere else without distracting from the issue at hand

* Support varying aspects of the test, such as compilation flags, from the
  command line without modifying configuration files

* Provide a facility to execute a suite of tests in batch format with an
  overall pass/fail summary

* Enable a variety of test models, including unit tests, validation of
  intermediate results (object files, assembler output), and demonstration
  programs

test430 relies heavily on conditional directives and text processing
functions provide by the GNU Make infrastructure.  An example of a complete
Makefile for a test is::

 BUG_ID=3383737
 CHECK=demo
 include $(TEST430_ROOT)/Makefile.common

All other code is inherited from test430.  Among other capabilities, a
developer can:

* Run ``make`` to remove old derived files, build the test program, and run
  it.

* Run ``make test.lst`` to obtain an interleaved source/assembler listing of
  the test source.

* Run ``make clean program`` to rebuild the application and program it onto
  the the target hardware

* Run ``make bug-browse`` to bring up bug 3383737 with the (default) MSPGCC
  project to see what the test is expected to demonstrate.  Customization to
  support multiple bug repositories is simple and documented in
  ``lib/make/bug-url.inc``.

* Run ``make native`` to build the test application on the host.

* Run ``make MCU=msp430f2274`` to run the test on an RF2500T instead of the
  default MSP430 Experimenter's board.

A brief overview of some features is below; for the reset, read the
``Makefile.common`` which drives the test build process, and review the
test430 Python support module in ``lib/python/test430``.

test430 support features
========================

By default each test application will be linked to an object file test430.o
which provides commonly-used functionality.  The related functions and
macros are declared in ``test430.h``, which is in $(TEST430_ROOT)/support
and can be included in any source file without special configuration.

The ``test430_initialize`` function should be invoked at the start of the
test main routine.  This will disable the watchdog time, and configure the
board so that the LEDs and printf() both work.  It will also emit a sequence
of marker strings that are used by the capture program to synchronize with
the test output.

The ``test430_finalize`` function should be invoked at the end of the test
main routine.  It will display the summary of results, and emit a sequence
of marker strings that are used by the capture program to identify the end
of the test output.

If you want to use the build infrastructure, but not the runtime
infrastructure, use the following pattern in your test Makefile::

 # Inhibit build/link of test430 runtime infrastructure
 TEST430_O=

See ``tests/noruntime`` for an example.

mspdebug wrapper
================

Python code which invokes mspdebug in a subshell is used to support
capturing the complete output of the test program, by holding the MCU in
reset, starting to collect serial output, and releasing the MCU.  Without
this sort of synchronization, the test output may begin before an external
program can start to capture the data.

The capabilities in test430 python module may also be used for other
applications that require programmatic interaction with a running mspdebug
session.  (Yes, this does repeat the same error made by DejaGNU, but was far
more expedient than implementing a Python API to mspdebug.)

License
=======

Copyright (c) 2011, Peter A. Bigot

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

* Neither the name of the software nor the names of its contributors may be
  used to endorse or promote products derived from this software without
  specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.