btldr_pi.h

Embeded bootloader (rrload by ridgerun) for TI linux based platform v5.36

/*
 * File: btldr_pi.h
 *
 * The bootloader's Programmer's Interface. It is imagined that this
 * interface will be used by the UI portion of the bootloader as it picks
 * up user requests and then forms them into appropriate calls to this
 * interface. The implementation behind this interface coordinates most of
 * the activity necessary to carry out that user's request.
 *
 * See Also
 *   btldr_pi.c -- An implementation exposing an btldr_pi.h interface.
 *
 * Copyright (C) 2002 RidgeRun, Inc.
 * Author: RidgeRun, Inc  <[e-mail]>
 *
 *  This program 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 2 of the  License, or (at your
 *  option) any later version.
 *
 *  THIS  SOFTWARE  IS  PROVIDED  ``AS  IS''  AND   ANY  EXPRESS  OR IMPLIED
 *  WARRANTIES,   INCLUDING, BUT NOT  LIMITED  TO, THE IMPLIED WARRANTIES OF
 *  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
 *  NO  EVENT  SHALL   THE AUTHOR  BE    LIABLE FOR ANY   DIRECT,  INDIRECT,
 *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 *  NOT LIMITED   TO, PROCUREMENT OF  SUBSTITUTE GOODS  OR SERVICES; LOSS OF
 *  USE, DATA,  OR PROFITS; OR  BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 *  ANY THEORY OF LIABILITY, WHETHER IN  CONTRACT, STRICT LIABILITY, OR TORT
 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 *  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *  You should have received a copy of the  GNU General Public License along
 *  with this program; if not, write  to the Free Software Foundation, Inc.,
 *  675 Mass Ave, Cambridge, MA 02139, USA.
 *
 * Please report all bugs/problems to the author or <[e-mail]>
 *
 * key: RRGPLCR (do not remove)
 *
 */

#ifndef BTLDR_PI_H
#define BTLDR_PI_H

#include "types.h"

typedef enum {
  c_BOOTLDR=0, // assign value 0
  c_PARAMS,
  c_KERNEL,
  c_FILESYS,
#ifdef REPLACE_VECTOR_TABLE
  c_VECTORS,
#endif
  c_END // place holder only; keep last
} comp_t;

typedef enum {
  sd_SDRAM,
  sd_FLASH,
  sd_TFTP,
  sd_SERPORT,
  sd_PARPORT
} src_dest_t;

typedef enum {
  f_NA,
  f_SREC,
  f_RR_BINARY
} port_format_t;

#define PARAM_STR_LEN 200 /* Bytes we'll set aside for each string. */

typedef struct {
  char     device_MAC  [PARAM_STR_LEN];
  char      server_IP  [PARAM_STR_LEN];
  char     server_MAC  [PARAM_STR_LEN];
  char      device_IP  [PARAM_STR_LEN];
  char    kernel_path  [PARAM_STR_LEN];
  char    filesys_path [PARAM_STR_LEN];
  char kernel_cmdline  [PARAM_STR_LEN];
  char    user_data_1  [PARAM_STR_LEN]; // Note: | user_data fields can be used at the discretion
  char    user_data_2  [PARAM_STR_LEN]; //       | of the client such as for default UI settings,
  char    user_data_3  [PARAM_STR_LEN]; //       | or whatever; ones that need to survive power cycles.
  char    user_data_4  [PARAM_STR_LEN]; //       | 
  char    user_data_5  [PARAM_STR_LEN]; //       | 
#if defined(DSC24_OSD)
  char    OSD_path     [PARAM_STR_LEN];
  char    OSD_enable   [PARAM_STR_LEN];
#endif
  int    MAX_STR_LEN; // This field reflects the bytes available to each string above.
} params_t;

/* returns true if addr is in the flash memory address space */

extern int btldr_AddressIsInFlashSpace(unsigned int addr);

extern int  get_flash_comp_addresses(comp_t c,
				     unsigned int *start_addr,
				     unsigned int *size,
				     unsigned int *max_addr);

extern int  get_sdram_comp_addresses(comp_t c,
				     unsigned int *start_addr,
				     unsigned int *size,
				     unsigned int *entry_addr);

extern int cmd_copy_comp(comp_t c,
                          src_dest_t s,
                          src_dest_t d,
                          port_format_t f,
                          progress_meter_CBack_t CBack, // NULL okay.
                          int strobe_interval);
  // --cmd_copy_comp--
  //   Moves a component image from the specified source
  //   to the specified destination using any specified
  //   format that might be indicated. Along the way the
  //   process will strobe the user supplied call back
  //   function so that the client can update a progress
  //   meter giving the user feedback during the xfer.
  //   The supplied strobe interval controls how many bytes 
  //   are processed between strobes.
  //   Returns non-zero if an error was encountered (flash write error)
  //
  //   Example#1: (downloading to SDRAM)
  //   ----------
  //   cmd_copy_comp(c_KERNEL, sd_SERPORT, sd_SDRAM, f_SREC, NULL, 0);
  //
  //   Result:
  //      Reads in a kernel image from the serial port which
  //      is expressed in SREC format; parses the SREC format
  //      and lays down the binary image into SDRAM at locations
  //      indicated in the incoming SREC data stream. No strobing
  //      along the way since the caller didn't supply a progress
  //      meter callback.
  //
  //   Example#2: (writing to flash)
  //   ----------
  //   cmd_copy_comp(c_KERNEL, sd_SDRAM, sd_FLASH, f_NA, NULL, 0);
  //
  //   Result:
  //     Takes a component stored in SDRAM and copies it to
  //     Flash.  Overwrites only that area of flash dedicated 
  //     to the specified component leaving other components 
  //     unaltered.  When copying the source SDRAM locations
  //     involved in the operation are those that pertained to
  //     the last load of that component into SDRAM. That
  //     information was retained internally so that it could
  //     be used if a subsequent copy from SDRAM to flash was
  //     requested. No progress meter function strobed in this
  //     example; a NULL callback was supplied.

extern params_t *cmd_get_params(void);

  // --cmd_get_params--
  //   Used to read params *or* modify params.
  //
  //   READING:
  //   Retrieves the current SDRAM based user param
  //   settings. For example, this might be used so
  //   that the UI portion of this program can dump
  //   those settings in response to a user request
  //   to view them and/or modify them.
  //
  //   MODIFYING:
  //   Note! This call actually hands back the bootloader's
  //   *real* params_t internal SDRAM structure so that if
  //   the caller wishes to change one of the params
  //   contained within it they simple need to write a new
  //   string over the existing one and it takes effect.
  //
  //   Example#1: (reading/modifying params)
  //   {
  //     params_t *t;
  //     t = cmd_get_params();
  //     strncpy(t->server_IP,"12.34.56.78",t->MAXLEN); // overwrites the prev-
  //                                                    // ious system setting.
  //   }

extern void cmd_boot_kernel(int auto_xfer, // TRUE or FALSE
                            progress_meter_CBack_t CBack, // NULL okay.
                            int strobe_interval);

  // --cmd_boot_kernel--
  //   Transfers to the entry address of the kernel.
  //   Note: If auto_xfer is TRUE then if we currently
  //   do not have a kernel and filesystem already in RAM
  //   this call will try and locate one in on-board flash
  //   to use -- and if those components in flash indicate
  //   that they need to be moved to RAM before use, then this
  //   call will perform the copy to RAM before doing
  //   the kernel boot. The CBack, if supplied, is used
  //   to give user feedback during the copy if it is
  //   performed.

extern void erase_comp(comp_t c);

  // --erase_comp--
  // Each component has a dedicated area of the on-board flash
  // memory map which is reserved to hold it. The areas are 
  // determined by the internal implementation and client's may
  // use this call to erase the specified component.

extern void lock_flash(void);
extern void unlock_flash(void);

  // --lock_flash--
  // --unlock_flash--
  // You will not be able to perform any flash erase or write
  // operations if the flash has been locked. Once locked it
  // remains that way until specifically unlocked.

extern void btldr_init(void);

  // --btldr_init--
  //   Call once to initialize the module and make ready for client use.

#endif