bia_microddr_fw/common_src/memory.h

/*************************************************************************
 * Copyright (C) 2019 by Justin Byers
 * 
 * This file is part of clubdance_v2.
 *
 * clubdance_v2 is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * clubdance_v2 is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with clubdance_v2.  If not, see <https://www.gnu.org/licenses/>.
 *************************************************************************/

/**
 * @file memory.h
 * @author Justin Byers
 * @date August 11, 2019
 * @brief Program flash memory addresses of data relocated to work with the bootloader.
 *
 */
#ifndef MEMORY_
#define	MEMORY_

/**
 * ##########################################################################################
 * ### Regarding the modified memory layout of program flash to accomodate the bootloader ###
 * ##########################################################################################
 * 
 * This firmware implements a bootloader to allow the user to flash firmware over USB without requiring an external
 * programmer/debugger such as the ICD or Pickit 3. The bootloader and the application are separate binaries that
 * are compiled and linked independently of each other.
 * 
 * The bootloader occupies memory in program flash starting at address 0x0000. The MCU will always start program
 * execution at this address. The application occupies program flash memory starting from a predetermined address after
 * the end of the memory space occupied by the bootloader through the remainder of the program flash memory. As an
 * example let's assume the application starts at address 0x1400. The memory map of the corresponding program flash is
 * shown below.
 * 
 * ###############################
 * # Memory Map of Program Flash #
 * ###############################
 * 
 * Address      Description
 * ------------------------
 * 0x0000       Bootloader reset vector
 * 0x0008       Bootloader interrupt vector (high)
 * 0x0018       Bootloader interrupt vector (low)
 * ...
 * 0x0030       Bootloader absolute entrypoint (application can enter bootloader by jumping to this address)
 * ==[Remainder of bootloader code]==
 * 0x1400       Application reset vector
 * 0x1406       Application signature word**
 * 0x1408       Application interrupt vector (high)****
 * 0x1416       Application version word***
 * 0x1418       Application interrupt vector (low)****
 * ==[Remainder of application code]==
 * 0x7FFF       (Last byte of program flash)
 * 
 * Notes:   **      The signature word is written with a known value by the bootloader after it writes the application
 *                  code to flash memory and verifies the data written. If the bootloader does not read this exact value
 *                  at this address at startup it will assume the application code is corrupted and immediately enter
 *                  firmware update mode so valid application code can be flashed.
 *          ***     The version word is stored at this address by the application code at link time. Currently unused
 *                  but I'm leaving the functionality in so the bootloader can report the version of the current
 *                  application.
 *          ****    The bootloader's interrupt vectors will forward interrupts to the application's interrupt vectors
 *                  because they were moved when we offset the application code to 0x1400.
 * 
 * ##############################################
 * # Changing the application's memory location #
 * ##############################################
 * 
 * 2 source files must be modified, as well as the project configurations for both the bootloader and application
 * projects.
 * 
 * #
 * # File changes
 * #
 * File             Location                Changes
 * ------------------------------------------------
 * VectorRemap.asm  bootloader              * Change address in HiVector goto instruction to address of application
 *                                              high priority interrupt vector (ex. 0x1408).
 *                                          * Change address in LoVector goto instruction (NOT the goto 0x30) to address
 *                                              of application low priority interrupt vector (ex. 0x1418).
 * THIS FILE        shared                  * Change APP_FW_MEMORY_OFFSET to the starting address of the application
 *                                              (ex. 0x1400)
 * 
 * #
 * # BOOTLOADER project configuration changes
 * #
 * Configuration > Linker > Memory Model > ROM space 
 *      * Add memory range of application as a protected region. Ranges are separated by a single comma. Ranges that
 *        start with a '-' will be considered protected. Memory addresses specified in hexadecimal. No spaces allowed.
 *        (ex. 'default,-1400-7FFF')
 * 
 * #
 * # APPLICATION project configuration changes
 * #
 * Configuration > Linker > Memory Model > Additional Options > Code offset
 *      * Set to APP_FW_MEMORY_OFFSET
 * Configuration > Linker > Memory Model > ROM space 
 *      * Add memory ranges for bootloader, application signature word, and application version word as protected
 *        regions. Ranges are separated by a single comma. Ranges that start with a '-' will be considered protected.
 *        Memory addresses specified in hexadecimal. No spaces allowed.
 *        (ex. 'default,-0-13FF,-1406-1407,-1416-1417')
 */

/**
 * The base address of the application memory space. The application's reset vector will be
 * at this address. 
 */
#define APP_FW_MEMORY_OFFSET 0x1400

/**
 * The address in application memory space that stores the application's version number.
 */
#define APP_FW_VERSION_ADDRESS (APP_FW_MEMORY_OFFSET + 0x16)

/**
 * The address in application memory space that stores the signature word written by
 * the bootloader after a sucessful flash of application firmware.
 */
#define APP_SIGNATURE_ADDRESS (APP_FW_MEMORY_OFFSET + 0x06)

/**
 * The absolute address of the bootloader entrypoint. The application can jump to the
 * bootloader by executing a "goto" instruction with this address.
 */
#define BOOTLOADER_ENTRYPOINT 0x0030

#endif	/* MEMORY_ */