fix: Add a docs/examples/ folder to fix #1021 for old releases.

This patch cures issue #1021 (404 for asmdemp.c etc.) for the
existing HTML online documentations in docs/ by adding an examples/
folder parallel to the

dosc/avr-libc-user-manual-<version>/

folders.

The obvious drawback is that all versions of the documentation are
using the same examples/ folder, hence there should be a proper fix
for future releases.

Author: sprintersb

.gitignore

@@ -39,4 +39,6 @@ doc/api/malloc-x1.png
 doc/api/malloc-std.png
 doc/api/malloc-x2.png
 
+!docs/examples/*/Makefile
+
 __pycache__

docs/examples/asmdemo/Makefile

@@ -0,0 +1,221 @@
+# Hey Emacs, this is a -*- makefile -*-
+
+# AVR-GCC Makefile template, derived from the WinAVR template (which
+# is public domain), believed to be neutral to any flavor of "make"
+# (GNU make, BSD make, SysV make)
+
+
+MCU = attiny13
+#MCU = attiny45
+FORMAT = ihex
+TARGET = asmdemo
+SRC = $(TARGET).c
+ASRC = isrs.S
+OPT = s
+
+# Name of this Makefile (used for "make depend").
+MAKEFILE = Makefile
+
+# Compiler flag to set the C Standard level.
+# c89   - "ANSI" C
+# gnu89 - c89 plus GCC extensions
+# c99   - ISO C99 standard (not yet fully implemented)
+# gnu99 - c99 plus GCC extensions
+CSTANDARD = -std=gnu99
+
+# Place -D or -U options here
+CDEFS =
+
+# Place -I options here
+CINCS =
+
+
+CDEBUG = -g
+CWARN = -Wall -Wstrict-prototypes
+CTUNING = -funsigned-char -funsigned-bitfields -fpack-struct -fshort-enums
+#CEXTRA = -Wa,-adhlns=$(<:.c=.lst)
+CFLAGS = $(CDEBUG) $(CDEFS) $(CINCS) -O$(OPT) $(CWARN) $(CSTANDARD) $(CEXTRA)
+
+
+#ASFLAGS = -Wa,-adhlns=$(<:.S=.lst),-gstabs
+
+
+#Additional libraries.
+
+# Minimalistic printf version
+PRINTF_LIB_MIN = -Wl,-u,vfprintf -lprintf_min
+
+# Floating point printf version (requires MATH_LIB = -lm below)
+PRINTF_LIB_FLOAT = -Wl,-u,vfprintf -lprintf_flt
+
+PRINTF_LIB =
+
+# Minimalistic scanf version
+SCANF_LIB_MIN = -Wl,-u,vfscanf -lscanf_min
+
+# Floating point + %[ scanf version (requires MATH_LIB = -lm below)
+SCANF_LIB_FLOAT = -Wl,-u,vfscanf -lscanf_flt
+
+SCANF_LIB =
+
+MATH_LIB = -lm
+
+# External memory options
+
+# 64 KB of external RAM, starting after internal RAM (ATmega128!),
+# used for variables (.data/.bss) and heap (malloc()).
+#EXTMEMOPTS = -Wl,-Tdata=0x801100,--defsym=__heap_end=0x80ffff
+
+# 64 KB of external RAM, starting after internal RAM (ATmega128!),
+# only used for heap (malloc()).
+#EXTMEMOPTS = -Wl,--defsym=__heap_start=0x801100,--defsym=__heap_end=0x80ffff
+
+EXTMEMOPTS =
+
+#LDMAP = $(LDFLAGS) -Wl,-Map=$(TARGET).map,--cref
+LDFLAGS = $(EXTMEMOPTS) $(LDMAP) $(PRINTF_LIB) $(SCANF_LIB) $(MATH_LIB)
+
+
+# Programming support using avrdude. Settings and variables.
+
+AVRDUDE_PROGRAMMER = stk500v2
+AVRDUDE_PORT = /dev/cuaa1
+
+AVRDUDE_WRITE_FLASH = -U flash:w:$(TARGET).hex
+#AVRDUDE_WRITE_EEPROM = -U eeprom:w:$(TARGET).eep
+
+
+# Uncomment the following if you want avrdude's erase cycle counter.
+# Note that this counter needs to be initialized first using -Yn,
+# see avrdude manual.
+#AVRDUDE_ERASE_COUNTER = -y
+
+# Uncomment the following if you do /not/ wish a verification to be
+# performed after programming the device.
+#AVRDUDE_NO_VERIFY = -V
+
+# Increase verbosity level.  Please use this when submitting bug
+# reports about avrdude. See <http://savannah.nongnu.org/projects/avrdude>
+# to submit bug reports.
+#AVRDUDE_VERBOSE = -v -v
+
+AVRDUDE_BASIC = -p $(MCU) -P $(AVRDUDE_PORT) -c $(AVRDUDE_PROGRAMMER)
+AVRDUDE_FLAGS = $(AVRDUDE_BASIC) $(AVRDUDE_NO_VERIFY) $(AVRDUDE_VERBOSE) $(AVRDUDE_ERASE_COUNTER)
+
+
+CC = avr-gcc
+OBJCOPY = avr-objcopy
+OBJDUMP = avr-objdump
+SIZE = avr-size
+NM = avr-nm
+AVRDUDE = avrdude
+REMOVE = rm -f
+MV = mv -f
+
+# Define all object files.
+OBJ = $(SRC:.c=.o) $(ASRC:.S=.o)
+
+# Define all listing files.
+LST = $(ASRC:.S=.lst) $(SRC:.c=.lst)
+
+# Combine all necessary flags and optional flags.
+# Add target processor to flags.
+ALL_CFLAGS = -mmcu=$(MCU) -I. $(CFLAGS)
+ALL_ASFLAGS = -mmcu=$(MCU) -I. -x assembler-with-cpp $(ASFLAGS)
+
+
+# Default target.
+all: build
+
+build: elf hex eep
+
+elf: $(TARGET).elf
+hex: $(TARGET).hex
+eep: $(TARGET).eep
+lss: $(TARGET).lss
+sym: $(TARGET).sym
+
+
+# Program the device.
+program: $(TARGET).hex $(TARGET).eep
+	$(AVRDUDE) $(AVRDUDE_FLAGS) $(AVRDUDE_WRITE_FLASH) $(AVRDUDE_WRITE_EEPROM)
+
+
+
+
+# Convert ELF to COFF for use in debugging / simulating in AVR Studio or VMLAB.
+COFFCONVERT=$(OBJCOPY) --debugging \
+--change-section-address .data-0x800000 \
+--change-section-address .bss-0x800000 \
+--change-section-address .noinit-0x800000 \
+--change-section-address .eeprom-0x810000
+
+
+coff: $(TARGET).elf
+	$(COFFCONVERT) -O coff-avr $(TARGET).elf $(TARGET).cof
+
+
+extcoff: $(TARGET).elf
+	$(COFFCONVERT) -O coff-ext-avr $(TARGET).elf $(TARGET).cof
+
+
+.SUFFIXES: .elf .hex .eep .lss .sym
+
+.elf.hex:
+	$(OBJCOPY) -O $(FORMAT) -R .eeprom $< $@
+
+.elf.eep:
+	-$(OBJCOPY) -j .eeprom --set-section-flags=.eeprom="alloc,load" \
+	--change-section-lma .eeprom=0 -O $(FORMAT) $< $@
+
+# Create extended listing file from ELF output file.
+.elf.lss:
+	$(OBJDUMP) -h -S $< > $@
+
+# Create a symbol table from ELF output file.
+.elf.sym:
+	$(NM) -n $< > $@
+
+
+
+# Link: create ELF output file from object files.
+$(TARGET).elf: $(OBJ)
+	$(CC) $(ALL_CFLAGS) $(OBJ) --output $@ $(LDFLAGS)
+
+
+# Compile: create object files from C source files.
+.c.o:
+	$(CC) -c $(ALL_CFLAGS) $< -o $@
+
+
+# Compile: create assembler files from C source files.
+.c.s:
+	$(CC) -S $(ALL_CFLAGS) $< -o $@
+
+
+# Assemble: create object files from assembler source files.
+.S.o:
+	$(CC) -c $(ALL_ASFLAGS) $< -o $@
+
+
+
+# Target: clean project.
+clean:
+	$(REMOVE) $(TARGET).hex $(TARGET).eep $(TARGET).cof $(TARGET).elf \
+	$(TARGET).map $(TARGET).sym $(TARGET).lss \
+	$(OBJ) $(LST) $(SRC:.c=.s) $(SRC:.c=.d)
+
+depend:
+	if grep '^# DO NOT DELETE' $(MAKEFILE) >/dev/null; \
+	then \
+		sed -e '/^# DO NOT DELETE/,$$d' $(MAKEFILE) > \
+			$(MAKEFILE).$$$$ && \
+		$(MV) $(MAKEFILE).$$$$ $(MAKEFILE); \
+	fi
+	echo '# DO NOT DELETE THIS LINE -- make depend depends on it.' \
+		>> $(MAKEFILE); \
+	$(CC) -M -mmcu=$(MCU) $(CDEFS) $(CINCS) $(SRC) $(ASRC) >> $(MAKEFILE)
+
+.PHONY:	all build elf hex eep lss sym program coff extcoff clean depend
+
+

docs/examples/asmdemo/asmdemo.c

@@ -0,0 +1,144 @@
+/*
+ * ----------------------------------------------------------------------------
+ * "THE BEER-WARE LICENSE" (Revision 42):
+ * Joerg Wunsch wrote this file.  As long as you retain this notice you
+ * can do whatever you want with this stuff. If we meet some day, and you think
+ * this stuff is worth it, you can buy me a beer in return.        Joerg Wunsch
+ * ----------------------------------------------------------------------------
+ *
+ * Demo combining C and assembly source files.
+ *
+ * This demo implements an RC model type PWM decoder.  The incoming
+ * PWM signal consists of a pulse sequence with a pulse width of 920
+ * microseconds up to 2120 microseconds (1520 microseconds being the
+ * neutral point).  Depending on the value of the decoded incoming
+ * PWM, an outgoing PWM is controlled between 0 and 100 %.
+ *
+ * The project is intended to be run on an ATtiny13 that has only one
+ * timer channel (timer 0), so both the incoming signal discrimination
+ * as well as the outgoing PWM need to run on the same timer.
+ *
+ * For verification purposes, the same project can also be run on an
+ * ATtiny25/45/85, where timer 1 can be used to evaluate the incoming
+ * PWM signal, and timer 0 to generate the outgoing PWM.  In that
+ * case, no additional assembly code is needed.
+ */
+
+/*
+ * This is the main C source file for the demo.
+ */
+#include <avr/interrupt.h>
+#include <avr/io.h>
+#include <avr/sleep.h>
+
+#include "project.h"
+
+volatile uint16_t pwm_incoming;
+volatile struct
+{
+  uint8_t pwm_received: 1;
+}
+intbits;
+
+void
+ioinit(void)
+{
+  counter_hi = 0;
+  flags = 0;
+
+  /*
+   * Timer 0 runs as phase-correct PWM at full clock, OC0B connects to
+   * the PWM engine.
+   */
+  TCCR0A = (1 << COM0B1) | (1 << WGM00);
+  TCCR0B = (1 << CS00);
+  OCR0A = 255;
+
+#if defined(__AVR_ATtiny13__)
+  TIMSK0 = (1 << TOIE0) | (1 << OCIE0A);
+
+# define F_CPU 1200000ul
+  /* Minimal PWM pulse width is 920 us. */
+# define MIN_PWM_VAL ((920ul * F_CPU) / 1000000ul)
+  /* Maximal PWM pulse width is 2120 us */
+# define MAX_PWM_VAL ((2120ul * F_CPU) / 1000000ul)
+
+#elif defined(__AVR_ATtiny25__) ||\
+	defined(__AVR_ATtiny45__) ||\
+	defined(__AVR_ATtiny85__)
+
+# define F_CPU 1000000ul
+  /*
+   * We use a prescaler of 16 here to avoid the 32-bit calculations
+   * below.
+   */
+  /* Minimal PWM pulse width is 920 us. */
+# define MIN_PWM_VAL ((920ul * F_CPU) / 16 / 1000000ul)
+  /* Maximal PWM pulse width is 2120 us */
+# define MAX_PWM_VAL ((2120ul * F_CPU) / 16 / 1000000ul)
+
+#else
+# error "Don't know how to run on your MCU_TYPE."
+#endif
+
+  PCMSK = (1 << 4);
+  GIFR = (1 << PCIF);
+  GIMSK = (1 << PCIE);
+
+  DDRB = (1 << PB1);
+  PORTB = 0;
+
+  sei();
+}
+
+#if defined(__AVR_ATtiny25__) ||\
+	defined(__AVR_ATtiny45__) ||\
+	defined(__AVR_ATtiny85__)
+ISR(PCINT0_vect)
+{
+  uint8_t tcnt1;
+
+  if (PINB & (1 << 4))
+    {
+      /* Start timer 1 with a prescaler of 16. */
+      TCNT1 = 0;
+      TCCR1 = (1 << CS12) | (1 << CS10);
+      return;
+    }
+
+  /* Stop timer 1, current value is pulse width. */
+  tcnt1 = TCNT1;
+  TCCR1 = 0;
+  GIMSK &= ~(1 << PCIE);
+
+  pwm_incoming = tcnt1;
+  intbits.pwm_received = 1;
+}
+#endif /* ATtinyX5 */
+
+int
+main(void)
+{
+
+  ioinit();
+
+  for (;;)
+    {
+      if (intbits.pwm_received)
+	{
+	  intbits.pwm_received = 0;
+#if defined(__AVR_ATtiny13__)
+	  if (pwm_incoming < MIN_PWM_VAL)
+	    pwm_incoming = MIN_PWM_VAL;
+	  else if (pwm_incoming > MAX_PWM_VAL)
+	    pwm_incoming = MAX_PWM_VAL;
+	  OCR0B = (pwm_incoming - MIN_PWM_VAL) * 255ul / (MAX_PWM_VAL - MIN_PWM_VAL);
+#else
+	  OCR0B = (pwm_incoming - MIN_PWM_VAL) * 255u / (MAX_PWM_VAL - MIN_PWM_VAL);
+#endif
+	  GIFR = (1 << PCIF);
+	  GIMSK |= (1 << PCIE);
+	}
+      sleep_mode();
+    }
+}