avrxserialio_documentation.txt

the operate system used for AVR chips

Sept, 14, 2005
Larry Barello ([e-mail])

Example code for buffered and non-buffered serial I/O for AvrX.  This code base
includes the new AvrX FIFO facility, which requires AvrX 2.6f for avr-gcc-3.4.3

As far as I could test (i.e. not very far) the serial i/o routines should
compile for most varients of AVR available (that are suitable for AvrX...)  If
one doesn't, it should be a minor change to the file AvrBufferedSerial.c or
AvrSimpleSerial.c to correct the group, or add a new MCU group to the #defines
for the usarts.  The test code was checked out on the following processors:

	at90s8515	(classic)
	atmega8		(generic)
	atmega16
	atmega128	(large)

Although the code is pretty simple there are bound to be minor issues with other
processor groups.  When building the example code MAKE SURE TO DO A CLEAN BUILD.
Sometimes when changing processors not all files are rebuilt and odd things can
happen.

The sample application is SerialExample.c.  You can configure it to use USART0,
USART1 or both (assuming 1 exists!) The demo prints a string to the respective
port and waits for the user to type some stuff back in.  The demo also
illustrates how to use the GCC libc stdio facility (printf)

The makefile allows two versions of the demo to be built: simple and buffered.
In the simple case all buffering is provided by the hardware, or, in the case of
the AVR double buffered (you actually get three since the s/r receiving a
character acts like the third buffer - although it does get over ridden.

Manifest:
	SerialExample.c		Sample application
	AvrXSerial.h		Header file for serial i/o interface
	AvrXSimpleSerial.c	Simple non-bufferred AvrX blocking routines
	AvrXBufferedSerial.c	Buffered AvrX routines
	makefile

Notes on declaration and usage of SerialIO routines

	There are two flavors of serial I/O drivers.  Both are fixed 8 bit, no
	parity, one stop bit drivers.  Those parameters are easy to change in the
	code.

	AvrXBufferedSerial.c

	Uses AvrXFifo to create buffered serial streams for both input and
	output.  The amount of data buffered is the size of the fifo. Additional
	received characters will be lost.

	AvrXSimpleSerial.c

	Implements simple AvrX semaphore mediated serial i/o. There is no
	buffering beyond what is provided by the USART hardware. Depending upon
	the processor being used, the code can effectively buffer up to three
	characters on receive and two on transmit (classic processors are not
	double buffered).

	AvrXSerial.h

	Header file for serial i/o routines.  Used to control which serial port
	is used (if the chip supports more than one) and size of fifo buffers,
	if used.  By default, all available USART ports are used.

User Interface:

	void InitSerialIo0(unsigned int ubrr)
	int get_c0()	// Non-blocking, returns -1 if empty
	int get_char0()	// Blocking
	int put_c0()	// Non-blocking, return -1 if full
	int put_char0()	// Blocking

	void InitSerialIo1(unsigned int ubrr)
	int get_c1()	// Non-blocking
	int get_char1()	// Blocking
	int put_c1()	// Non-blocking
	int put_char1()	// Blocking

	The header file defines generic interface aliases for the routines when
	only one port is enabled.

	void InitSerialIo()
	int get_c()	// Non-blocking, returns -1
	int get_char()	// Blocking
	int put_c()	// Non-blocking
	int put_char()	// Blocking

	Most modern AVR processor support CLK/16 and CLK/8 baud rate generator
	values. The default is CLK/8 since that gives more flexibility in baud
	rate selection.  For processors that do not support CLK/8, the header
	file automatically redefines the divisor to CLK/16.  There is a handy
	macro provided to generate the proper UBRR value based upon the CPUCLK,
	Baud rate and Clock divisor:

	BAUD(baud_rate)

	e.g.	InitSerialIo0(BAUD(38400));

	See AvrXSerialIo.h for details.

EXAMPLE APPLICATION

	SerialExample.c

	This application has a task with a timeout.  It prints a message and
	then waits 5 seconds for the user to type something in. At the end of
	the delay it prints out whatever was typed in.

	There are two tasks, one for each serial port.  The code only enables
	tasks for enabled serial ports.

	It is interesting to link the sample with buffered and non-buffered
	serial routines.  The non-buffered routines clearly illustrate the
	hardware buffering of the USART.  Classic AVR chips have a single
	buffer.  Newer mega chips have double buffering as well as the ability
	to keep a third character in the shift register.

	With the buffered serial I/O only characters received and successfully
	buffered are printed. All others are lost.

	This example also shows how to use GCC stdio facility.  Using default
	Printf (scanf, etc) adds about 2kb to the load image.  However, once
	loaded the library can be used to simplify many parsing & formatting
	chores. Also included are two minimal string print routines.  Usage for
	those are illustrated in task1.  When only port1 is enabled, the load
	image size reduces considerably because stdio is not linked in.

MAKEFILE

	The default target builds both the simple and buffered versions of the
	example.  "make program" will attempt to program an STK500 with the
	target listed at the beginning of the makefile. "

	"make program TARGET=AvrXSimpleSerial" or "make program TARGET=AvrXBufferedSerial"
	will program the respective targets.

	Other make options:

	make clean		- deletes default target compiled modules
	make clean TARGET=... 	- deletes compiled modules for that target.
	make			- builds both targets
	make all		- just builds the default target