Documentation/Introduction : overview of the ArtLPC project
Copyright (c) 2005-2007 Garth Zeglin

This file is part of ArtLPC, distributed under the terms of
the GNU General Public License version 2 or later.

/****************************************************************/

                            ArtLPC 

The ArtLPC project is the name I have given to the body of code I am
developing in support of my art projects using LPC2000 series
microcontrollers from nxp (formerly Philips).  The result is a
self-contained set of library codes suitable for writing standalone
embedded programs.

My main motivation for writing this was a desire to have the simplest
possible software architecture for writing simple embedded
controllers; bugs can become exceedingly opaque in this context.
Using in-circuit JTAG debugging can help but is still laborious.  And
while I was gathering code and bootstrapping my first application, I
decided to also pick and choose the API which I would find most
natural.  I also wanted maximal portability to 32-bit desktop machines
to allow debugging all device-independent code using the normal OS X
and Linux gcc and gdb.  These features have made it generally possible
to debug my systems without needing in-circuit JTAG debugging.

The name was chosen to hint at the potential suitability of this code
for other artists to use; it has been kept simple and clear so that a
moderately capable C programmer could write an embedded system.

This first open release is a subset of the full ArtLPC code.  It is
just sufficient to support the balancing robot project I am developing
at the Carnegie Mellon University Robotics Institute.

The best documentation is the code itself.  All API is subject to
change in future releases.  Further releases may include more
functionality; I've decided to limit the amount of code I'm willing to
support for the time being.

There is no lack of other code available for these chips. There are
several full real-time operating systems available, notably FreeRTOS
and eCos, and various libc implementations including newlib, uClibc,
and dietlibc.

Most of this code should be compatible with other systems; it has not
been tested under eCos, FreeRTOS, etc., but I wouldn't expect any
intrinsic problems except where identical symbols exist or with
interrupt handling.

================  libstd  ======================================

libstd is a replacement for libc which offers device-independent I/O
and other support routines.  It includes some standard libc routines,
but also equivalent functionality in an idiosyncratic API designed to
follow Scheme conventions.

The obvious disadvantage is the unfamilarity of the function
nomenclature for non-Scheme programmers.  The advantage is a more
consistent and logical interface for character streams.

The implementations of standard libc functions are chosen for small
size and clarity over efficiency.  For example, the usual word
optimizations are not included in memcpy, so it is relatively slow,
although the small size of the typical memory on a LPC2xxx target
makes that less of an issue.  Optimizations will be introduced as
needed, but the emphasis will still be on clarity.

The libc functions should conform to the libc API in all cases;
libc-like functions which vary from the standard have been given
different names.

The true intention of this code is as a support library for an actual
Scheme implementation, which is not yet included in the public release
of ArtLPC.

================  libLPC2xxx  ==================================

libLPC2xxx is a library of device support for multiple variants of the
LPC2000 series microcontrollers and typical external hardware.  It has
a redundant set of functionality in some cases to allow an application
to use the simplest implementation needed.  The best example is the
serial port; it can be polled or interrupt driven, accessed using libc
functions or a character device port abstraction, and output generated
using primitive routines or a formatted output function.

================  library configuration ========================

The libraries are compiled individually for each application.  This is
an idea borrowed to a degree from eCos; it allows the entire source to
be configurable for each application.  This simplifys the run time
code and minimizes the amount of dynamic configuration in favor of
static compile-time setup.  Since the overall code base is still
fairly small, it doesn't impose a huge penalty on rebuilding from
scratch.

To a degree, it makes the code more complicated by incorporating a lot
of conditional compilation.  However, in many cases the configuration
can be accomplished by providing multiple implementations rather than
conditional code and letting the user specify their preference by
choice of access functions.

Another principle is that of static allocation; library routines do
not assume the presence of a run-time memory allocator, and either
operate on user-supplied buffers, static data areas, or globals.  The
library includes at least one dynamic memory allocator available to
user code, although many control applications can get by easily with
just static allocation. (The full-blown system includes a
garbage-collected heap, not yet publicly released.)

Each function is either generally portable to any 32-bit integer
system or specific to LPC2xxx chips.  Probably some of this would work
on other ARM7 microcontroller families, but the code is simpler by
being specific.

================================================================

