Bootloaders/Printer/BootloaderPrinter.c

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2014.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2014  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaims all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *
  33  *  Main source file for the Printer class bootloader. This file contains the complete bootloader logic.
  34  */
  35
  36 #include "BootloaderPrinter.h"
  37
  38 /** LUFA Printer Class driver interface configuration and state information. This structure is
  39  *  passed to all Printer Class driver functions, so that multiple instances of the same class
  40  *  within a device can be differentiated from one another.
  41  */
  42 USB_ClassInfo_PRNT_Device_t TextOnly_Printer_Interface =
  43         {
  44                 .Config =
  45                         {
  46                                 .InterfaceNumber          = INTERFACE_ID_Printer,
  47                                 .DataINEndpoint           =
  48                                         {
  49                                                 .Address          = PRINTER_IN_EPADDR,
  50                                                 .Size             = PRINTER_IO_EPSIZE,
  51                                                 .Banks            = 1,
  52                                         },
  53                                 .DataOUTEndpoint =
  54                                         {
  55                                                 .Address          = PRINTER_OUT_EPADDR,
  56                                                 .Size             = PRINTER_IO_EPSIZE,
  57                                                 .Banks            = 1,
  58                                         },
  59                                 .IEEE1284String =
  60                                         "MFG:Generic;"
  61                                         "MDL:Generic_/_Text_Only;"
  62                                         "CMD:1284.4;"
  63                                         "CLS:PRINTER",
  64                         },
  65         };
  66
  67 /** Intel HEX parser state machine state information, to track the contents of
  68  *  a HEX file streamed in as a sequence of arbitrary bytes.
  69  */
  70 struct
  71 {
  72         /** Current HEX parser state machine state. */
  73         uint8_t  ParserState;
  74         /** Previously decoded numerical byte of data. */
  75         uint8_t  PrevData;
  76         /** Currently decoded numerical byte of data. */
  77         uint8_t  Data;
  78         /** Indicates if both bytes that correspond to a single decoded numerical
  79          *  byte of data (HEX encodes values in ASCII HEX, two characters per byte)
  80          *  have been read.
  81          */
  82         bool     ReadMSB;
  83         /** Intel HEX record type of the current Intel HEX record. */
  84         uint8_t  RecordType;
  85         /** Numerical bytes of data remaining to be read in the current record. */
  86         uint8_t  DataRem;
  87         /** Checksum of the current record received so far. */
  88         uint8_t  Checksum;
  89         /** Starting address of the last addressed FLASH page. */
  90         uint32_t PageStartAddress;
  91         /** Current 32-bit byte extended base address in FLASH being targeted. */
  92         uint32_t CurrBaseAddress;
  93         /** Current 32-bit byte address in FLASH being targeted. */
  94         uint32_t CurrAddress;
  95 } HEXParser;
  96
  97 /** Indicates if there is data waiting to be written to a physical page of
  98  *  memory in FLASH.
  99  */
 100 static bool PageDirty = false;
 101
 102 /** Flag to indicate if the bootloader should be running, or should exit and allow the application code to run
 103  *  via a soft reset. When cleared, the bootloader will abort, the USB interface will shut down and the application
 104  *  started via a forced watchdog reset.
 105  */
 106 static bool RunBootloader = true;
 107
 108 /** Magic lock for forced application start. If the HWBE fuse is programmed and BOOTRST is unprogrammed, the bootloader
 109  *  will start if the /HWB line of the AVR is held low and the system is reset. However, if the /HWB line is still held
 110  *  low when the application attempts to start via a watchdog reset, the bootloader will re-start. If set to the value
 111  *  \ref MAGIC_BOOT_KEY the special init function \ref Application_Jump_Check() will force the application to start.
 112  */
 113 uint16_t MagicBootKey ATTR_NO_INIT;
 114
 115
 116 /** Special startup routine to check if the bootloader was started via a watchdog reset, and if the magic application
 117  *  start key has been loaded into \ref MagicBootKey. If the bootloader started via the watchdog and the key is valid,
 118  *  this will force the user application to start via a software jump.
 119  */
 120 void Application_Jump_Check(void)
 121 {
 122         bool JumpToApplication = false;
 123
 124         #if (BOARD == BOARD_LEONARDO)
 125                 /* Enable pull-up on the IO13 pin so we can use it to select the mode */
 126                 PORTC |= (1 << 7);
 127                 Delay_MS(10);
 128
 129                 /* If IO13 is not jumpered to ground, start the user application instead */
 130                 JumpToApplication = ((PINC & (1 << 7)) != 0);
 131
 132                 /* Disable pull-up after the check has completed */
 133                 PORTC &= ~(1 << 7);
 134         #elif ((BOARD == BOARD_XPLAIN) || (BOARD == BOARD_XPLAIN_REV1))
 135                 /* Disable JTAG debugging */
 136                 JTAG_DISABLE();
 137
 138                 /* Enable pull-up on the JTAG TCK pin so we can use it to select the mode */
 139                 PORTF |= (1 << 4);
 140                 Delay_MS(10);
 141
 142                 /* If the TCK pin is not jumpered to ground, start the user application instead */
 143                 JumpToApplication = ((PINF & (1 << 4)) != 0);
 144
 145                 /* Re-enable JTAG debugging */
 146                 JTAG_ENABLE();
 147         #else
 148                 /* Check if the device's BOOTRST fuse is set */
 149                 if (boot_lock_fuse_bits_get(GET_HIGH_FUSE_BITS) & FUSE_BOOTRST)
 150                 {
 151                         /* If the reset source was not an external reset or the key is correct, clear it and jump to the application */
 152                         if (!(MCUSR & (1 << EXTRF)) || (MagicBootKey == MAGIC_BOOT_KEY))
 153                           JumpToApplication = true;
 154
 155                         MCUSR &= ~(1 << EXTRF);
 156                 }
 157         #endif
 158
 159         /* Don't run the user application if the reset vector is blank (no app loaded) */
 160         bool ApplicationValid = (pgm_read_word_near(0) != 0xFFFF);
 161
 162         /* If a request has been made to jump to the user application, honor it */
 163         if (JumpToApplication && ApplicationValid)
 164         {
 165                 /* Turn off the watchdog */
 166                 MCUSR &= ~(1 << WDRF);
 167                 wdt_disable();
 168
 169                 /* Clear the boot key and jump to the user application */
 170                 MagicBootKey = 0;
 171
 172                 // cppcheck-suppress constStatement
 173                 ((void (*)(void))0x0000)();
 174         }
 175 }
 176
 177 /**
 178  * Converts a given input byte of data from an ASCII encoded HEX value to an integer value.
 179  *
 180  * \note Input HEX bytes are expected to be in uppercase only.
 181  *
 182  * \param[in] Byte  ASCII byte of data to convert
 183  *
 184  * \return Integer converted value of the input ASCII encoded HEX byte of data, or -1 if the
 185  *         input is not valid ASCII encoded HEX.
 186  */
 187 static int8_t HexToDecimal(const char Byte)
 188 {
 189         if ((Byte >= 'A') && (Byte <= 'F'))
 190           return (10 + (Byte - 'A'));
 191         else if ((Byte >= '0') && (Byte <= '9'))
 192           return (Byte - '0');
 193
 194         return -1;
 195 }
 196
 197 /**
 198  * Flushes a partially written page of data to physical FLASH, if a page
 199  * boundary has been crossed.
 200  *
 201  * \note If a page flush occurs the global HEX parser state is updated.
 202  */
 203 static void FlushPageIfRequired(void)
 204 {
 205         /* Abort if no data has been buffered for writing to the current page */
 206         if (!PageDirty)
 207           return;
 208
 209         /* Flush the FLASH page to physical memory if we are crossing a page boundary */
 210         uint32_t NewPageStartAddress = (HEXParser.CurrAddress & ~(SPM_PAGESIZE - 1));
 211         if (HEXParser.PageStartAddress != NewPageStartAddress)
 212         {
 213                 boot_page_write(HEXParser.PageStartAddress);
 214                 boot_spm_busy_wait();
 215
 216                 HEXParser.PageStartAddress = NewPageStartAddress;
 217
 218                 PageDirty = false;
 219         }
 220 }
 221
 222 /**
 223  * Parses an input Intel HEX formatted stream one character at a time, loading
 224  * the data contents into the device's internal FLASH memory.
 225  *
 226  * \param[in] ReadCharacter  Next input ASCII byte of data to parse
 227  */
 228 static void ParseIntelHEXByte(const char ReadCharacter)
 229 {
 230         /* Reset the line parser while waiting for a new line to start */
 231         if ((HEXParser.ParserState == HEX_PARSE_STATE_WAIT_LINE) || (ReadCharacter == ':'))
 232         {
 233                 HEXParser.Checksum     = 0;
 234                 HEXParser.CurrAddress  = HEXParser.CurrBaseAddress;
 235                 HEXParser.ReadMSB      = false;
 236
 237                 /* ASCII ':' indicates the start of a new HEX record */
 238                 if (ReadCharacter == ':')
 239                   HEXParser.ParserState = HEX_PARSE_STATE_BYTE_COUNT;
 240
 241                 return;
 242         }
 243
 244         /* Only allow ASCII HEX encoded digits, ignore all other characters */
 245         int8_t ReadCharacterDec = HexToDecimal(ReadCharacter);
 246         if (ReadCharacterDec < 0)
 247           return;
 248
 249         /* Read and convert the next nibble of data from the current character */
 250         HEXParser.Data    = (HEXParser.Data << 4) | ReadCharacterDec;
 251         HEXParser.ReadMSB = !HEXParser.ReadMSB;
 252
 253         /* Only process further when a full byte (two nibbles) have been read */
 254         if (HEXParser.ReadMSB)
 255           return;
 256
 257         /* Intel HEX checksum is for all fields except starting character and the
 258          * checksum itself
 259          */
 260         if (HEXParser.ParserState != HEX_PARSE_STATE_CHECKSUM)
 261           HEXParser.Checksum += HEXParser.Data;
 262
 263         switch (HEXParser.ParserState)
 264         {
 265                 case HEX_PARSE_STATE_BYTE_COUNT:
 266                         HEXParser.DataRem      = HEXParser.Data;
 267                         HEXParser.ParserState  = HEX_PARSE_STATE_ADDRESS_HIGH;
 268                         break;
 269
 270                 case HEX_PARSE_STATE_ADDRESS_HIGH:
 271                         HEXParser.CurrAddress += ((uint16_t)HEXParser.Data << 8);
 272                         HEXParser.ParserState  = HEX_PARSE_STATE_ADDRESS_LOW;
 273                         break;
 274
 275                 case HEX_PARSE_STATE_ADDRESS_LOW:
 276                         HEXParser.CurrAddress += HEXParser.Data;
 277                         HEXParser.ParserState  = HEX_PARSE_STATE_RECORD_TYPE;
 278                         break;
 279
 280                 case HEX_PARSE_STATE_RECORD_TYPE:
 281                         HEXParser.RecordType   = HEXParser.Data;
 282                         HEXParser.ParserState  = (HEXParser.DataRem ? HEX_PARSE_STATE_READ_DATA : HEX_PARSE_STATE_CHECKSUM);
 283                         break;
 284
 285                 case HEX_PARSE_STATE_READ_DATA:
 286                         /* Track the number of read data bytes in the record */
 287                         HEXParser.DataRem--;
 288
 289                         /* Protect the bootloader against being written to */
 290                         if (HEXParser.CurrAddress >= BOOT_START_ADDR)
 291                         {
 292                                 HEXParser.ParserState = HEX_PARSE_STATE_WAIT_LINE;
 293                                 PageDirty = false;
 294                                 return;
 295                         }
 296
 297                         /* Wait for a machine word (two bytes) of data to be read */
 298                         if (HEXParser.DataRem & 0x01)
 299                         {
 300                                 HEXParser.PrevData = HEXParser.Data;
 301                                 break;
 302                         }
 303
 304                         /* Convert the last two received data bytes into a 16-bit word */
 305                         uint16_t NewDataWord = ((uint16_t)HEXParser.Data << 8) | HEXParser.PrevData;
 306
 307                         switch (HEXParser.RecordType)
 308                         {
 309                                 case HEX_RECORD_TYPE_Data:
 310                                         /* If we are writing to a new page, we need to erase it first */
 311                                         if (!(PageDirty))
 312                                         {
 313                                                 boot_page_erase(HEXParser.PageStartAddress);
 314                                                 boot_spm_busy_wait();
 315
 316                                                 PageDirty = true;
 317                                         }
 318
 319                                         /* Fill the FLASH memory buffer with the new word of data */
 320                                         boot_page_fill(HEXParser.CurrAddress, NewDataWord);
 321                                         HEXParser.CurrAddress += 2;
 322
 323                                         /* Flush the FLASH page to physical memory if we are crossing a page boundary */
 324                                         FlushPageIfRequired();
 325                                         break;
 326
 327                                 case HEX_RECORD_TYPE_ExtendedSegmentAddress:
 328                                         /* Extended address data - store the upper 12-bits of the new address */
 329                                         HEXParser.CurrBaseAddress = ((uint32_t)NewDataWord << 4);
 330                                         break;
 331
 332                                 case HEX_RECORD_TYPE_ExtendedLinearAddress:
 333                                         /* Extended address data - store the upper 16-bits of the new address */
 334                                         HEXParser.CurrBaseAddress = ((uint32_t)NewDataWord << 16);
 335                                         break;
 336                         }
 337
 338                         if (!HEXParser.DataRem)
 339                           HEXParser.ParserState = HEX_PARSE_STATE_CHECKSUM;
 340                         break;
 341
 342                 case HEX_PARSE_STATE_CHECKSUM:
 343                         /* Verify checksum of the completed record */
 344                         if (HEXParser.Data != ((~HEXParser.Checksum + 1) & 0xFF))
 345                           break;
 346
 347                         /* Flush the FLASH page to physical memory if we are crossing a page boundary */
 348                         FlushPageIfRequired();
 349
 350                         /* If end of the HEX file reached, the bootloader should exit at next opportunity */
 351                         if (HEXParser.RecordType == HEX_RECORD_TYPE_EndOfFile)
 352                           RunBootloader = false;
 353
 354                         break;
 355
 356                 default:
 357                         HEXParser.ParserState = HEX_PARSE_STATE_WAIT_LINE;
 358                         break;
 359         }
 360 }
 361
 362 /** Main program entry point. This routine configures the hardware required by the application, then
 363  *  enters a loop to run the application tasks in sequence.
 364  */
 365 int main(void)
 366 {
 367         SetupHardware();
 368
 369         LEDs_SetAllLEDs(LEDMASK_USB_NOTREADY);
 370         GlobalInterruptEnable();
 371
 372         while (RunBootloader)
 373         {
 374                 uint8_t BytesReceived = PRNT_Device_BytesReceived(&TextOnly_Printer_Interface);
 375
 376                 if (BytesReceived)
 377                 {
 378                         LEDs_SetAllLEDs(LEDMASK_USB_BUSY);
 379
 380                         while (BytesReceived--)
 381                         {
 382                                 int16_t ReceivedByte = PRNT_Device_ReceiveByte(&TextOnly_Printer_Interface);
 383
 384                                 /* Feed the next byte of data to the HEX parser */
 385                                 ParseIntelHEXByte(ReceivedByte);
 386                         }
 387
 388                         LEDs_SetAllLEDs(LEDMASK_USB_READY);
 389                 }
 390
 391                 PRNT_Device_USBTask(&TextOnly_Printer_Interface);
 392                 USB_USBTask();
 393         }
 394
 395         /* Disconnect from the host - USB interface will be reset later along with the AVR */
 396         USB_Detach();
 397
 398         /* Unlock the forced application start mode of the bootloader if it is restarted */
 399         MagicBootKey = MAGIC_BOOT_KEY;
 400
 401         /* Enable the watchdog and force a timeout to reset the AVR */
 402         wdt_enable(WDTO_250MS);
 403
 404         for (;;);
 405 }
 406
 407 /** Configures the board hardware and chip peripherals for the demo's functionality. */
 408 static void SetupHardware(void)
 409 {
 410         /* Disable watchdog if enabled by bootloader/fuses */
 411         MCUSR &= ~(1 << WDRF);
 412         wdt_disable();
 413
 414         /* Disable clock division */
 415         clock_prescale_set(clock_div_1);
 416
 417         /* Relocate the interrupt vector table to the bootloader section */
 418         MCUCR = (1 << IVCE);
 419         MCUCR = (1 << IVSEL);
 420
 421         /* Hardware Initialization */
 422         LEDs_Init();
 423         USB_Init();
 424
 425         /* Bootloader active LED toggle timer initialization */
 426         TIMSK1 = (1 << TOIE1);
 427         TCCR1B = ((1 << CS11) | (1 << CS10));
 428 }
 429
 430 /** ISR to periodically toggle the LEDs on the board to indicate that the bootloader is active. */
 431 ISR(TIMER1_OVF_vect, ISR_BLOCK)
 432 {
 433         LEDs_ToggleLEDs(LEDS_LED1 | LEDS_LED2);
 434 }
 435
 436 /** Event handler for the USB_Connect event. This indicates that the device is enumerating via the status LEDs. */
 437 void EVENT_USB_Device_Connect(void)
 438 {
 439         /* Indicate USB enumerating */
 440         LEDs_SetAllLEDs(LEDMASK_USB_ENUMERATING);
 441 }
 442
 443 /** Event handler for the USB_Disconnect event. This indicates that the device is no longer connected to a host via
 444  *  the status LEDs and stops the Printer management task.
 445  */
 446 void EVENT_USB_Device_Disconnect(void)
 447 {
 448         /* Indicate USB not ready */
 449         LEDs_SetAllLEDs(LEDMASK_USB_NOTREADY);
 450 }
 451
 452 /** Event handler for the USB_ConfigurationChanged event. This is fired when the host set the current configuration
 453  *  of the USB device after enumeration - the device endpoints are configured and the Mass Storage management task started.
 454  */
 455 void EVENT_USB_Device_ConfigurationChanged(void)
 456 {
 457         bool ConfigSuccess = true;
 458
 459         /* Setup Printer Data Endpoints */
 460         ConfigSuccess &= PRNT_Device_ConfigureEndpoints(&TextOnly_Printer_Interface);
 461
 462         /* Reset the HEX parser upon successful connection to a host */
 463         HEXParser.ParserState = HEX_PARSE_STATE_WAIT_LINE;
 464
 465         /* Indicate endpoint configuration success or failure */
 466         LEDs_SetAllLEDs(ConfigSuccess ? LEDMASK_USB_READY : LEDMASK_USB_ERROR);
 467 }
 468
 469 /** Event handler for the USB_ControlRequest event. This is used to catch and process control requests sent to
 470  *  the device from the USB host before passing along unhandled control requests to the library for processing
 471  *  internally.
 472  */
 473 void EVENT_USB_Device_ControlRequest(void)
 474 {
 475         PRNT_Device_ProcessControlRequest(&TextOnly_Printer_Interface);
 476 }