/*                                       -*- mode:C++; fill-column: 100 -*-
  SFBProvenance.h - Program code description block
  Copyright (C) 2008 The Regents of the University of New Mexico.  All rights reserved.

  This library is free software; you can redistribute it and/or modify it under the terms of the GNU
  Lesser General Public License as published by the Free Software Foundation; either version 2.1 of
  the License, or (at your option) any later version.

  This library 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
  Lesser General Public License for more details.

  You should have received a copy of the GNU General Public License along with this library; if not,
  write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
  USA

  $Id$
*/

/**
  \ingroup core
  \file SFBProvenance.h Support for tracking sketch origins data.
  \author David H. Ackley.  
  \date (C) 2008 All rights reserved.
  \lgpl
 */
#ifndef SFBPROVENANCE_H
#define SFBPROVENANCE_H

#include "SFBTypes.h"
#include "SFBChecksum.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * An SFBProvenance provides information that describes a sketch as a physical artifact.  It
 * provides spatial information such as the sketch program length and a "checksum" describing the
 * sketch content, temporal information such as when the sketch was built, and a few bits about the
 * origin or "provenance" of the sketch, information such as a "sketch id", who created it, and
 * where we got it.
 *
 * An SBFProvenance block is automatically generated by the sketch build system, and placed just
 * before the sketch itself in program memory, so the effective program starting address immediately
 * follows the provenance block.  (In addition, a "program footer" is placed after the sketch in
 * program memory, to provide an additional consistency check.)
 */
struct SFBProvenance {
  u32 branchInstruction;        ///< A single ARM instruction that jumps over the provenance block,
                                ///  making the block "executable" so it can appear in code flow.
  u32 checksum0;                ///< Filled in by the bootloader.  (Half of the) Checksum of all
                                ///  bytes starting at the magic and running for programLength-12]]
  u32 checksum1;                ///< See #checksum0   
                                ///
  int sourceOwnerId;            ///< Filled in by the bootloader.  The provided owner id of the board
                                ///  or other source that fed this sketch to us.
  int sourceBoardId;            ///< Filled in by the bootloader.  The provided board id of the board
                                ///  or other source that fed this sketch to us.      
  u32 magic;                    ///< A "magic value" (equal to SFB_PROVENANCE_MAGIC) identifying the
                                ///  beginning of the checksummed portion of a valid sketch.
  u16 flags;                    ///< Room for miscellaneous flags, as yet undefined.
                                ///
  u8 rsrvd1;                    ///< Reserved for future use; value should be zero; value should not
                                ///  be read.
  u8 architecture;              ///< The architecture code for the machine this code runs on.
                                ///
  int creatorId;                ///< The sketch creator id, or 0 if none; must not be -1.
                                ///
  int programId;                ///< The sketch program id, or 0 if none; must not be -1.
                                ///
  int buildDate;                ///< Filled in by the sketch build system.  The UTC time zone date
                                ///  this was compiled.  Interpreted as 0xYYYYMMDD.
  int buildTime;                ///< Filled in by the sketch build system.  The UTC time zone time
                                ///  this was compiled.  Interpreted as 0xHHMMSS with 0..24 for HH.
  int programLength;            ///< The size of the sketch, in bytes, including this entire header
                                ///  block.
  u32 copyrightNotice;          ///< A pointer to zstring in program area, or null if unspecified.
                                ///  Represented as a u32 because this is always a 32 bit pointer
                                ///  (either on the actual h/w, or as an offset into a memory
                                ///  image), regardless of the native pointer size.
  u32 cigam;                    ///< A "backwards" magic value (equal to SFB_PROVENANCE_CIGAM)
                                ///  helping to identify a valid SFBProvenance block.
};

enum BootProgrammingFlags {
  PROGRAMMING_FLAG_VERBOSE  = 0x01, ///< Report extra status messages during burns.
  PROGRAMMING_FLAG_QUIET    = 0x02, ///< Report minimal status messages during burns.
  PROGRAMMING_FLAG_CHECKOFF = 0x04, ///< Don't trust existing sector checksums during a burn.
  PROGRAMMING_FLAG_RSRVD4   = 0x08, ///< Reserved for future use; value should be zero and ignored
  PROGRAMMING_FLAG_RSRVD5   = 0x10, ///< Reserved for future use; value should be zero and ignored
  PROGRAMMING_FLAG_RSRVD6   = 0x20, ///< Reserved for future use; value should be zero and ignored
  PROGRAMMING_FLAG_RSRVD7   = 0x40, ///< Reserved for future use; value should be zero and ignored
  PROGRAMMING_FLAG_RSRVD8   = 0x80  ///< Reserved for future use; value should be zero and ignored
};

/**
 * The magic value indicating the start of the checksummed region of a sketch.
 */
#define SFB_PROVENANCE_MAGIC 0xC300A5FB

/**
 * The "backwards" magic value indicating the end of an SFBProvenance block (although not the end of
 * the checksummed region of a sketch).
 */
#define SFB_PROVENANCE_CIGAM 0xBF5A003C

/**
 * The "inverted" magic value indicating the end of the checksummed region of a sketch.  Placed in
 * flash memory after all sketch code by the build system.
 */
#define SFB_PROVENANCE_NZTRX (~SFB_PROVENANCE_MAGIC)  

#ifdef __cplusplus
}
#endif

#endif  /* SFBPROVENANCE_H */
