| 1 |
/* Copyright (c) 2006, Joerg Wunsch |
| 2 |
All rights reserved. |
| 3 |
|
| 4 |
Redistribution and use in source and binary forms, with or without |
| 5 |
modification, are permitted provided that the following conditions are met: |
| 6 |
|
| 7 |
* Redistributions of source code must retain the above copyright |
| 8 |
notice, this list of conditions and the following disclaimer. |
| 9 |
|
| 10 |
* Redistributions in binary form must reproduce the above copyright |
| 11 |
notice, this list of conditions and the following disclaimer in |
| 12 |
the documentation and/or other materials provided with the |
| 13 |
distribution. |
| 14 |
|
| 15 |
* Neither the name of the copyright holders nor the names of |
| 16 |
contributors may be used to endorse or promote products derived |
| 17 |
from this software without specific prior written permission. |
| 18 |
|
| 19 |
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| 20 |
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 21 |
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 22 |
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE |
| 23 |
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| 24 |
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| 25 |
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| 26 |
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| 27 |
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| 28 |
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| 29 |
POSSIBILITY OF SUCH DAMAGE. */ |
| 30 |
|
| 31 |
/* $Id$ */ |
| 32 |
|
| 33 |
/** \defgroup asmdemo Combining C and assembly source files |
| 34 |
\ingroup demos |
| 35 |
|
| 36 |
For time- or space-critical applications, it can often be desirable to |
| 37 |
combine C code (for easy maintenance) and assembly code (for maximal |
| 38 |
speed or minimal code size) together. This demo provides an example |
| 39 |
of how to do that. |
| 40 |
|
| 41 |
The objective of the demo is to decode radio-controlled model PWM |
| 42 |
signals, and control an output PWM based on the current input signal's |
| 43 |
value. The incoming PWM pulses follow a standard encoding scheme |
| 44 |
where a pulse width of 920 microseconds denotes one end of the scale |
| 45 |
(represented as 0 % pulse width on output), and 2120 microseconds mark |
| 46 |
the other end (100 % output PWM). Normally, multiple channels would |
| 47 |
be encoded that way in subsequent pulses, followed by a larger gap, so |
| 48 |
the entire frame will repeat each 14 through 20 ms, but this is |
| 49 |
ignored for the purpose of the demo, so only a single input PWM |
| 50 |
channel is assumed. |
| 51 |
|
| 52 |
The basic challenge is to use the cheapest controller available for |
| 53 |
the task, an ATtiny13 that has only a single timer channel. As this |
| 54 |
timer channel is required to run the outgoing PWM signal generation, |
| 55 |
the incoming PWM decoding had to be adjusted to the constraints set by |
| 56 |
the outgoing PWM. |
| 57 |
|
| 58 |
As PWM generation toggles the counting direction of timer 0 between up |
| 59 |
and down after each 256 timer cycles, the current time cannot be |
| 60 |
deduced by reading TCNT0 only, but the current counting direction of |
| 61 |
the timer needs to be considered as well. This requires servicing |
| 62 |
interrupts whenever the timer hits \e TOP (255) and \e BOTTOM (0) to |
| 63 |
learn about each change of the counting direction. For PWM |
| 64 |
generation, it is usually desired to run it at the highest possible |
| 65 |
speed so filtering the PWM frequency from the modulated output signal |
| 66 |
is made easy. Thus, the PWM timer runs at full CPU speed. This |
| 67 |
causes the overflow and compare match interrupts to be triggered each |
| 68 |
256 CPU clocks, so they must run with the minimal number of processor |
| 69 |
cycles possible in order to not impose a too high CPU load by these |
| 70 |
interrupt service routines. This is the main reason to implement the |
| 71 |
entire interrupt handling in fine-tuned assembly code rather than in |
| 72 |
C. |
| 73 |
|
| 74 |
In order to verify parts of the algorithm, and the underlying |
| 75 |
hardware, the demo has been set up in a way so the pin-compatible but |
| 76 |
more expensive ATtiny45 (or its siblings ATtiny25 and ATtiny85) could |
| 77 |
be used as well. In that case, no separate assembly code is required, |
| 78 |
as two timer channels are avaible. |
| 79 |
|
| 80 |
\section asmdemo_hw Hardware setup |
| 81 |
|
| 82 |
The incoming PWM pulse train is fed into PB4. It will generate a pin |
| 83 |
change interrupt there on eache edge of the incoming signal. |
| 84 |
|
| 85 |
The outgoing PWM is generated through OC0B of timer channel 0 (PB1). |
| 86 |
For demonstration purposes, a LED should be connected to that pin |
| 87 |
(like, one of the LEDs of an STK500). |
| 88 |
|
| 89 |
The controllers run on their internal calibrated RC oscillators, 1.2 |
| 90 |
MHz on the ATtiny13, and 1.0 MHz on the ATtiny45. |
| 91 |
|
| 92 |
\section asmdemo_code A code walkthrough |
| 93 |
|
| 94 |
\subsection asmdemo_main asmdemo.c |
| 95 |
|
| 96 |
After the usual include files, two variables are defined. The first |
| 97 |
one, \c pwm_incoming is used to communicate the most recent |
| 98 |
pulse width detected by the incoming PWM decoder up to the main loop. |
| 99 |
|
| 100 |
The second variable actually only constitutes of a single bit, |
| 101 |
<tt>intbits.pwm_received</tt>. This bit will be set whenever the |
| 102 |
incoming PWM decoder has updated <tt>pwm_incoming</tt>. |
| 103 |
|
| 104 |
Both variables are marked \e volatile to ensure their readers will |
| 105 |
always pick up an updated value, as both variables will be set by |
| 106 |
interrupt service routines. |
| 107 |
|
| 108 |
The function \c ioinit() initializes the microcontroller peripheral |
| 109 |
devices. In particular, it starts timer 0 to generate the outgoing |
| 110 |
PWM signal on OC0B. Setting OCR0A to 255 (which is the \e TOP value |
| 111 |
of timer 0) is used to generate a timer 0 overflow A interrupt on the |
| 112 |
ATtiny13. This interrupt is used to inform the incoming PWM decoder |
| 113 |
that the counting direction of channel 0 is just changing from up to |
| 114 |
down. Likewise, an overflow interrupt will be generated whenever the |
| 115 |
countdown reached \e BOTTOM (value 0), where the counter will again |
| 116 |
alter its counting direction to upwards. This information is needed |
| 117 |
in order to know whether the current counter value of \c TCNT0 is to |
| 118 |
be evaluated from bottom or top. |
| 119 |
|
| 120 |
Further, \c ioinit() activates the pin-change interrupt \c PCINT0 on |
| 121 |
any edge of PB4. Finally, PB1 (OC0B) will be activated as an output |
| 122 |
pin, and global interrupts are being enabled. |
| 123 |
|
| 124 |
In the ATtiny45 setup, the C code contains an ISR for \c PCINT0. At |
| 125 |
each pin-change interrupt, it will first be analyzed whether the |
| 126 |
interrupt was caused by a rising or a falling edge. In case of the |
| 127 |
rising edge, timer 1 will be started with a prescaler of 16 after |
| 128 |
clearing the current timer value. Then, at the falling edge, the |
| 129 |
current timer value will be recorded (and timer 1 stopped), the |
| 130 |
pin-change interrupt will be suspended, and the upper layer will be |
| 131 |
notified that the incoming PWM measurement data is available. |
| 132 |
|
| 133 |
Function \c main() first initializes the hardware by calling |
| 134 |
\c ioinit(), and then waits until some incoming PWM value is |
| 135 |
available. If it is, the output PWM will be adjusted by computing |
| 136 |
the relative value of the incoming PWM. Finally, the pin-change |
| 137 |
interrupt is re-enabled, and the CPU is put to sleep. |
| 138 |
|
| 139 |
|
| 140 |
\subsection asmdemo_project project.h |
| 141 |
|
| 142 |
In order for the interrupt service routines to be as fast as possible, |
| 143 |
some of the CPU registers are set aside completely for use by these |
| 144 |
routines, so the compiler would not use them for C code. This is |
| 145 |
arranged for in <tt>project.h</tt>. |
| 146 |
|
| 147 |
The file is divided into one section that will be used by the assembly |
| 148 |
source code, and another one to be used by C code. The assembly part |
| 149 |
is distinguished by the preprocessing macro \c __ASSEMBLER__ (which |
| 150 |
will be automatically set by the compiler front-end when preprocessing |
| 151 |
an assembly-language file), and it contains just macros that give |
| 152 |
symbolic names to a number of CPU registers. The preprocessor will |
| 153 |
then replace the symbolic names by their right-hand side definitions |
| 154 |
before calling the assembler. |
| 155 |
|
| 156 |
In C code, the compiler needs to see variable declarations for these |
| 157 |
objects. This is done by using declarations that bind a variable |
| 158 |
permanently to a CPU register (see \ref faq_regbind). Even in case |
| 159 |
the C code never has a need to access these variables, declaring the |
| 160 |
register binding that way causes the compiler to not use these |
| 161 |
registers in C code at all. |
| 162 |
|
| 163 |
The \c flags variable needs to be in the range of r16 through r31 as |
| 164 |
it is the target of a <em>load immediate</em> (or \c SER) instruction |
| 165 |
that is not applicable to the entire register file. |
| 166 |
|
| 167 |
|
| 168 |
\subsection asmdemo_isrs isrs.S |
| 169 |
|
| 170 |
This file is a preprocessed assembly source file. The C preprocessor |
| 171 |
will be run by the compiler front-end first, resolving all \c \#include, |
| 172 |
\c \#define etc. directives. The resulting program text will then be |
| 173 |
passed on to the assembler. |
| 174 |
|
| 175 |
As the C preprocessor strips all C-style comments, preprocessed |
| 176 |
assembly source files can have both, C-style (<tt>/</tt><tt>* ... *</tt><tt>/</tt>, |
| 177 |
<tt>// ...</tt>) as well as assembly-style (<tt>; ...</tt>) comments. |
| 178 |
|
| 179 |
At the top, the IO register definition file <tt>avr/io.h</tt> and the |
| 180 |
project declaration file <tt>project.h</tt> are included. The |
| 181 |
remainder of the file is conditionally assembled only if the target |
| 182 |
MCU type is an ATtiny13, so it will be completely ignored for the |
| 183 |
ATtiny45 option. |
| 184 |
|
| 185 |
Next are the two interrupt service routines for timer 0 compare A |
| 186 |
match (timer 0 hits \e TOP, as OCR0A is set to 255) and timer 0 |
| 187 |
overflow (timer 0 hits \e BOTTOM). As discussed above, these are kept |
| 188 |
as short as possible. They only save \c SREG (as the flags will be |
| 189 |
modified by the \c INC instruction), increment the \c counter_hi |
| 190 |
variable which forms the high part of the current time counter (the |
| 191 |
low part is formed by querying \c TCNT0 directly), and clear or set |
| 192 |
the variable \c flags, respectively, in order to note the current |
| 193 |
counting direction. The \c RETI instruction terminates these |
| 194 |
interrupt service routines. Total cycle count is 8 CPU cycles, so |
| 195 |
together with the 4 CPU cycles needed for interrupt setup, and the 2 |
| 196 |
cycles for the RJMP from the interrupt vector to the handler, these |
| 197 |
routines will require 14 out of each 256 CPU cycles, or about 5 % of |
| 198 |
the overall CPU time. |
| 199 |
|
| 200 |
The pin-change interrupt \c PCINT0 will be handled in the final part |
| 201 |
of this file. The basic algorithm is to quickly evaluate the current |
| 202 |
system time by fetching the current timer value of \c TCNT0, and |
| 203 |
combining it with the overflow part in \c counter_hi. If the counter |
| 204 |
is currently counting down rather than up, the value fetched from |
| 205 |
\c TCNT0 must be negated. Finally, if this pin-change interrupt was |
| 206 |
triggered by a rising edge, the time computed will be recorded as the |
| 207 |
start time only. Then, at the falling edge, this start time will be |
| 208 |
subracted from the current time to compute the actual pulse width seen |
| 209 |
(left in \c pwm_incoming), and the upper layers are informed of the |
| 210 |
new value by setting bit 0 in the \c intbits flags. At the same time, |
| 211 |
this pin-change interrupt will be disabled so no new measurement can |
| 212 |
be performed until the upper layer had a chance to process the current |
| 213 |
value. |
| 214 |
|
| 215 |
|
| 216 |
\section asmdemo_src The source code |
| 217 |
|
| 218 |
\htmlonly |
| 219 |
<ul> |
| 220 |
<li><a href="../examples/asmdemo/asmdemo.c">asmdemo.c</a></li> |
| 221 |
<li><a href="../examples/asmdemo/project.h">project.h</a></li> |
| 222 |
<li><a href="../examples/asmdemo/isrs.S">isrs.S</a></li> |
| 223 |
</ul> |
| 224 |
\endhtmlonly |
| 225 |
|
| 226 |
\latexonly |
| 227 |
The source code is installed under |
| 228 |
|
| 229 |
\texttt{\$prefix/share/doc/avr-libc/examples/asmdemo/}, |
| 230 |
|
| 231 |
where \texttt{\$prefix} is a configuration option. For Unix |
| 232 |
systems, it is usually set to either \texttt{/usr} or |
| 233 |
\texttt{/usr/local}. |
| 234 |
\endlatexonly |
| 235 |
|
| 236 |
*/ |