2002-08-06 Theodore A. Roth * doc/api/Makefile.am(EXTRA_DIST): Add new dox files. * doc/api/interrupts.dox: New file. * doc/api/acknowledge.dox: New file. * include/avr/interrupt.h: Added doxy comments. * include/avr/signal.h: Updated doxy comments. Index: doc/api/Makefile.am =================================================================== RCS file: /cvsroot/avr-libc/avr-libc/doc/api/Makefile.am,v retrieving revision 1.11 diff -u -r1.11 Makefile.am --- doc/api/Makefile.am 5 Aug 2002 21:47:34 -0000 1.11 +++ doc/api/Makefile.am 9 Aug 2002 06:57:52 -0000 @@ -37,6 +37,8 @@ EXTRA_DIST = dox.css dox_html_header dox_html_footer \ main_page.dox \ inline_asm.dox \ + interrupts.dox \ + acknowledge.dox \ faq.dox SUFFIXES = .pdf Index: doc/api/acknowledge.dox =================================================================== RCS file: doc/api/acknowledge.dox diff -N doc/api/acknowledge.dox --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ doc/api/acknowledge.dox 9 Aug 2002 06:57:52 -0000 @@ -0,0 +1,55 @@ +/* Copyright (c) 2002 Theodore A. Roth + 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. + + 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 OWNER 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. */ + +/** \page acks Acknowledgments + + This document tries to tie together the labors of a large group of + people. Without these individuals' efforts, we wouldn't have a terrific, + free set of tools to develop AVR projects. We all owe thanks to: + + - The GCC Team, which produced a very capable set of development tools for + an amazing number of platforms and processors. + + - Denis Chertykov [ address@hidden ] for making the AVR-specific changes + to the GNU tools. + + - Denis Chertykov and Marek Michalkiewicz [ address@hidden ] for + developing the standard libraries and startup code for \b AVR-GCC. + + - Uros Platise for developing the AVR programmer tool, \b uisp. + + - Joerg Wunsch [ address@hidden ] for adding all the AVR development + tools to the FreeBSD [ http://www.freebsd.org ] ports tree and for providing + the demo project in [FIXME: hasn't been merged yet, put ref here]. + + - Brian Dean [ address@hidden ] for developing \b avrprog (an alternate + to uisp) and for contributing [FIXME: need to merge section on + avrprog] which describes how to use it. + + - And lastly, all the users who use the software. If nobody used the + software, we probably would be very motivated to continue to develop + it. Keep those bug reports coming. ;-) + +*/ Index: doc/api/interrupts.dox =================================================================== RCS file: doc/api/interrupts.dox diff -N doc/api/interrupts.dox --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ doc/api/interrupts.dox 9 Aug 2002 06:57:52 -0000 @@ -0,0 +1,376 @@ +/* Copyright (c) 1999, 2000, 2001, 2002, Rich Neswold + 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. + + 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 OWNER 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. */ + +/** \defgroup avr_interrupts Interrupts and Signals + +\note This discussion of interrupts and signals was taken from Rich Neswold's +document. See \ref acks. + +It's nearly impossible to find compilers that agree on how to handle interrupt +code. Since the C language tries to stay away from machine dependent details, +each compiler writer is forced to design their method of support. + +In the AVR-GCC environment, the vector table is predefined to point to +interrupt routines with predetermined names. By using the appropriate name, +your routine will be called when the corresponding interrupt occurs. The +device library provides a set of default interrupt routines, which will get +used if you don't define your own. + +Patching into the vector table is only one part of the problem. The compiler +uses, by convention, a set of registers when it's normally executing +compiler-generated code. It's important that these registers, as well as the +status register, get saved and restored. The extra code needed to do this is +enabled by tagging the interrupt function with +__attribute__((interrupt)). + +These details seem to make interrupt routines a little messy, but all these +details are handled by the Interrupt API. An interrupt routine is defined with +one of two macros, INTERRUPT() and SIGNAL(). These macros register and mark +the routine as an interrupt handler for the specified peripheral. The +following is an example definition of a handler for the ADC interrupt. + +\code +#include + +INTERRUPT(SIG_ADC) +{ + // user code here +} +\endcode + +[FIXME: should there be a discussion of writing an interrupt handler in asm?] + +If an unexpected interrupt occurs (interrupt is enabled and no handler is +installed, which usually indicates a bug), then the default action is to reset +the device by jumping to the reset vector. You can override this by supplying +a function named \c __vector_default which should be defined with either +SIGNAL() or INTERRUPT() as such. + +\code +#include + +SIGNAL(__vector_default) +{ + // user code here +} +\endcode + +The interrupt is chosen by supplying one of the symbols in following table. +Note that every AVR device has a different interrupt vector table so some +signals might not be available. Check the data sheet for the device you are +using. + +[FIXME: Fill in the blanks! Gotta read those durn data sheets ;-)] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Signal NameDescription
SIG_2WIRE_SERIAL
SIG_ADCADC Conversion complete
SIG_COMPARATORAnalog Comparator Interrupt
SIG_EEPROM_READYEeprom ready
SIG_FPGA_INTERRUPT0
SIG_FPGA_INTERRUPT1
SIG_FPGA_INTERRUPT10
SIG_FPGA_INTERRUPT11
SIG_FPGA_INTERRUPT12
SIG_FPGA_INTERRUPT13
SIG_FPGA_INTERRUPT14
SIG_FPGA_INTERRUPT15
SIG_FPGA_INTERRUPT2
SIG_FPGA_INTERRUPT3
SIG_FPGA_INTERRUPT4
SIG_FPGA_INTERRUPT5
SIG_FPGA_INTERRUPT6
SIG_FPGA_INTERRUPT7
SIG_FPGA_INTERRUPT8
SIG_FPGA_INTERRUPT9
SIG_INPUT_CAPTURE1Input Capture1 Interrupt
SIG_INPUT_CAPTURE3Input Capture3 Interrupt
SIG_INTERRUPT0External Interrupt0
SIG_INTERRUPT1External Interrupt1
SIG_INTERRUPT2External Interrupt2
SIG_INTERRUPT3External Interrupt3
SIG_INTERRUPT4External Interrupt4
SIG_INTERRUPT5External Interrupt5
SIG_INTERRUPT6External Interrupt6
SIG_INTERRUPT7External Interrupt7
SIG_OUTPUT_COMPARE0Output Compare0 Interrupt
SIG_OUTPUT_COMPARE1AOutput Compare1(A) Interrupt
SIG_OUTPUT_COMPARE1BOutput Compare1(B) Interrupt
SIG_OUTPUT_COMPARE1COutput Compare1(C) Interrupt
SIG_OUTPUT_COMPARE2Output Compare2 Interrupt
SIG_OUTPUT_COMPARE3AOutput Compare3(A) Interrupt
SIG_OUTPUT_COMPARE3BOutput Compare3(B) Interrupt
SIG_OUTPUT_COMPARE3COutput Compare3(C) Interrupt
SIG_OVERFLOW0Overflow0 Interrupt
SIG_OVERFLOW1Overflow1 Interrupt
SIG_OVERFLOW2Overflow2 Interrupt
SIG_OVERFLOW3Overflow2 Interrupt
SIG_PIN
SIG_PIN_CHANGE0
SIG_PIN_CHANGE1
SIG_RDMAC
SIG_SPISPI Interrupt
SIG_SPM_READY
SIG_SUSPEND_RESUME
SIG_TDMAC
SIG_UART0
SIG_UART0_DATAUART(0) Data Register Empty Interrupt
SIG_UART0_RECVUART(0) Receive Complete Interrupt
SIG_UART0_TRANSUART(0) Transmit Complete Interrupt
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Signal Name (continued)Description
SIG_UART1
SIG_UART1_DATAUART(1) Data Register Empty Interrupt
SIG_UART1_RECVUART(1) Receive Complete Interrupt
SIG_UART1_TRANSUART(1) Transmit Complete Interrupt
SIG_UART_DATA
SIG_UART_RECV
SIG_UART_TRANS
SIG_USART0_DATAUSART(0) Data Register Empty Interrupt
SIG_USART0_RECVUSART(0) Receive Complete Interrupt
SIG_USART0_TRANSUSART(0) Transmit Complete Interrupt
SIG_USART1_DATAUSART(1) Data Register Empty Interrupt
SIG_USART1_RECVUSART(1) Receive Complete Interrupt
SIG_USART1_TRANSUSART(1) Transmit Complete Interrupt
SIG_USB_HW
+ +
+ +*/ Index: include/avr/interrupt.h =================================================================== RCS file: /cvsroot/avr-libc/avr-libc/include/avr/interrupt.h,v retrieving revision 1.1 diff -u -r1.1 interrupt.h --- include/avr/interrupt.h 5 Jul 2002 20:38:44 -0000 1.1 +++ include/avr/interrupt.h 9 Aug 2002 06:57:52 -0000 @@ -28,13 +28,76 @@ #include +/** \name Global manipulation of the interrupt flag + + The global interrupt flag is maintained in the I bit of the status + register (SREG). */ + +/address@hidden/ + +/** \def sei() + \ingroup avr_interrupts + + \code#include \endcode + + Enables interrupts by clearing the global interrupt mask. This function + actually compiles into a single line of assembly, so there is no function + call overhead. */ + #define sei() __asm__ __volatile__ ("sei" ::) + +/** \def cli() + \ingroup avr_interrupts + + \code#include \endcode + + Disables all interrupts by clearing the global interrupt mask. This function + actually compiles into a single line of assembly, so there is no function + call overhead. */ + #define cli() __asm__ __volatile__ ("cli" ::) +/address@hidden/ + #ifdef __cplusplus extern "C" { #endif +/** \name Allowing specific system-wide interrupts + + In addition to globally enabling interrupts, each device's particular + interrupt needs to be enabled separately if interrupts for this device are + desired. While some devices maintain their interrupt enable bit inside + the device's register set, external and timer interrupts have system-wide + configuration registers. + + Example: + + \code + // Enable timer 1 overflow interrupts. + timer_enable_int(_BV(TOIE1)); + + // Do some work... + + // Disable all timer interrupts. + timer_enable_int(0); + \endcode + + \note Be careful when you use these functions. If you already have a + different interrupt enabled, you could inadvertantly disable it by + enabling another intterupt. */ + +/address@hidden/ + +/** \ingroup avr_interrupts + + \code#include \endcode + + This function gives access to the \c gimsk register (or \c eimsk register + if using an AVR Mega device). Although this function is essentially the + same as using the outb() function, it does adapt slightly to the type of + device being used. */ + extern inline void enable_external_int (unsigned char ints) { #ifdef EIMSK @@ -46,12 +109,21 @@ #endif } +/** \ingroup avr_interrupts + + \code#include \endcode + + This function modifies the \c timsk register using the outb() function. + The value you pass via \c ints is device specific. */ + extern inline void timer_enable_int (unsigned char ints) { #ifdef TIMSK outb(TIMSK, ints); #endif } + +/address@hidden/ #ifdef __cplusplus } Index: include/avr/signal.h =================================================================== RCS file: /cvsroot/avr-libc/avr-libc/include/avr/signal.h,v retrieving revision 1.2 diff -u -r1.2 signal.h --- include/avr/signal.h 26 Jul 2002 05:49:44 -0000 1.2 +++ include/avr/signal.h 9 Aug 2002 06:57:52 -0000 @@ -26,14 +26,17 @@ #ifndef _AVR_SIGNAL_H_ #define _AVR_SIGNAL_H_ -/** \defgroup avr_signals Signals and Interrupts - \code #include \endcode +/** \name Macros for writing interrupt handler functions */ - FIXME: discuss the SIGNAL() and INTERRUPT() macros. Rich Neswold's - document has a good discussion of this. */ +/address@hidden/ /** \def SIGNAL(signame) - \ingroup avr_signals */ + \ingroup avr_interrupts + + \code#include \endcode + + Introduces an interrupt handler function that runs with global interrupts + initially disabled. */ #ifdef __cplusplus #define SIGNAL(signame) \ @@ -47,7 +50,12 @@ #endif /** \def INTERRUPT(signame) - \ingroup avr_signals */ + \ingroup avr_interrupts + + \code#include \endcode + + Introduces an interrupt handler function that runs with global interrupts + initially enabled. This allows interrupt handlers to be interrupted. */ #ifdef __cplusplus #define INTERRUPT(signame) \ @@ -59,5 +67,7 @@ void signame (void) __attribute__ ((interrupt)); \ void signame (void) #endif + +/address@hidden/ #endif /* _AVR_SIGNAL_H_ */