/*
 * Copyright (C) 1996-1998 by the Board of Trustees
 *    of Leland Stanford Junior University.
 * 
 * This file is part of the SimOS distribution. 
 * See LICENSE file for terms of the license. 
 *
 */

#ifndef _SESL_LIB_H_
#define _SESL_LIB_H_

/*
 * External interface routines to the SimOS External Symbol Library (SESL)
 *   (which is in itself heavily based on GDB 4.6.1).
 *     - Ben Werther (benw@cs.stanford.edu)
 */

/*--------------------------------------------------
 * Memory management issues when using this library
 * ------------------------------------------------
 * - Calling SESL_LookupSymbol or SESL_CreateSymbol will allocate memory
 * - Calling SESL_FreeSymbol will deallocate that memory
 *
 * Library functions that modify a symbol, such as SESL_Dereference,
 * SESL_FindInBlock, SESL_FindMember, or SESL_Cast, do not create memory.
 * They overwrite the symbol struct that you pass to them with the new
 * symbol info. IMPORTANT: If these functions fail and return NULL, they
 * will also free the memory for the symbol passed in. In this way, you
 * can always replace the passed in pointer with the returned pointer without
 * the risk of memory leaks.
 *--------------------------------------------------
 */

/*
 * The SESL symbol type
 */
struct SESL_Symbol;

/*
 * The type we use for passing addresses.
 * Must be the same size as the CORE_ADDR type inside the library.
 */
typedef uint64 SESL_ADDR;

/*
 * Returns a string describing the version of SESL
 * Format is "SESL X.X[.X[.X]] [(comment here)]"
 *    where X is an integer, and [ ] means optional
 */
char* SESL_Version(void);

/*
 * Initialize SESL - must be called before using the library 
 *  -- IMPORTANT - errorFn is a terminating error - it must
 *                 not return!!!
 */
int SESL_Init(void (*printFn)(char *, ...),
          void (*warningFn)(char *, ...),
          void (*errorFn)(char *, ...));

/* 
 * Loads an executable's symbols into the symbol file tables.
 * - execpath is the full path to the file, and savename is the name to
 *   save this symbol table under
 * - returns 1 for success and 0 for failure
 */
int SESL_LoadFile(char *execpath, char *savename);

/* 
 * Returns the address of executable:srcfile:line
 * - return 0 for failure, or otherwise the address
 */
SESL_ADDR SESL_Line2Addr(char *execfile, char *srcfile, int line);

/*
 * Searches for a symbol at this address. If found, returns a symbolic
 * string representation, otherwise return NULL.
 * The string is allocated from static memory internally, and will remain until
 * the next call to this function.
 */
char * SESL_Addr2Symbolic(char *execfile, SESL_ADDR addr);

/* 
 * Creates a new symbol of the desired type at the desired address.
 * Returns the symbol if successful, or NULL if the executable or
 * the type weren't found.
 *
 * Must call SESL_FreeSymbol to deallocate.
 */
struct SESL_Symbol *
SESL_CreateSymbol(char *execfile, SESL_ADDR addr, char *typename);

/*
 * Looks up symbol 'symname' in execfile and srcfile, and returns a
 * pointer to a symbol structure, or NULL if it wasn't found.
 * If strlen(srcfile) is 0, all srcfiles will be searched.
 *
 * Must call SESL_FreeSymbol to deallocate.
 */
struct SESL_Symbol *
SESL_LookupSymbol(char *execfile, char *srcfile, char *symname);

/*
 * Deallocates a symbol allocated by SESL_LookupSymbol
 */
void SESL_FreeSymbol(struct SESL_Symbol *sesl_sym);

/*
 * Returns true if this symbol is a block (i.e. a function or the like) 
 */
int SESL_IsBlock(struct SESL_Symbol *sesl_sym);

/*
 * Returns true if this symbol is a static variable
 */
int SESL_IsVariable(struct SESL_Symbol *sesl_sym);

/*
 * Returns true if this symbol is a label
 */
int SESL_IsLabel(struct SESL_Symbol *sesl_sym);

/* 
 * Returns the name of this symbol
 * Don't free this string
 */
char* SESL_GetName(struct SESL_Symbol *sesl_sym);

/* 
 * Returns the address of this symbol
 */
SESL_ADDR SESL_GetAddress(struct SESL_Symbol *sesl_sym);

/*
 * Returns the size of this symbol(variable) or function(block)
 */
unsigned long SESL_GetSize(struct SESL_Symbol *sesl_sym);

/* 
 * Returns an integer code that represents the type of the symbol 
 */
int SESL_GetType(struct SESL_Symbol *sesl_sym);

/*
 * Returns an integer code that represents the type of the 
 * target of the pointer or array - returns 0 (SESL_TYPE_UNKNOWN)
 * on failure.
 */
int SESL_GetTargetType(struct SESL_Symbol *sesl_sym);

/*
 * Returns the name of the type of this symbol
 * Memory is statically allocated internally, so the pointer will
 * be valid until the next call of this function.
 */
char* SESL_GetTypeName(struct SESL_Symbol *sesl_sym);

/*
 * Finds symname inside the block of the symbol passed in.
 * Return NULL if unsuccessful (not a block, or not found).
 * Otherwise, returns the resulting symbol.
 * NOTE: Resulting symbol overwrites the memory of the symbol passed in.
 *  - i.e. no new memory is allocated - this replaces the symbol given as
 *    a parameter.  
 */
struct SESL_Symbol*
SESL_FindInBlock(struct SESL_Symbol *sesl_sym, char *symname);

/*
 * Return true if the symbol can be dereferenced, and false if it can't 
 */
int
SESL_CanDereference(struct SESL_Symbol* sesl_sym);

/*
 * Dereference a pointer or array type symbol.
 * You should first call SESL_GetAddress, find the value stored at that 
 * address, and pass that as newaddr in this call.
 * Returns NULL on failure, or the dereferenced symbol if successful.
 * NOTE: Resulting symbol overwrites the memory of the symbol passed in.
 *  - i.e. no new memory is allocated - this replaces the symbol given as
 *    a parameter.  
 */
struct SESL_Symbol*
SESL_Dereference(struct SESL_Symbol* sesl_sym, SESL_ADDR newaddr);

/*
 * Moves forward or back through through an array. Pass the symbol of 
 * an array element, and an index (positive is forward, negative is
 * back), and it will return the resulting element. No bounds checking is
 * performed.
 */
struct SESL_Symbol* SESL_Index(struct SESL_Symbol *sesl_sym, int index);

/*
 * Cast a symbol to a new type 
 * Returns NULL on failure, or the cast symbol if successful.
 * NOTE: Resulting symbol overwrites the memory of the symbol passed in.
 *  - i.e. no new memory is allocated - this replaces the symbol given as
 *    a parameter.  
 */
struct SESL_Symbol*
SESL_Cast(char *execfile, struct SESL_Symbol *sesl_sym, char *typename);

/*
 * Searches for a symbol name inside a structure.
 * Returns the internal symbol if successful, or NULL if unsuccessful.
 * NOTE: Resulting symbol overwrites the memory of the symbol passed in.
 *  - i.e. no new memory is allocated - this replaces the symbol given as
 *    a parameter.  
 */
struct SESL_Symbol*
SESL_FindMember(struct SESL_Symbol *sesl_sym, char *symname);

/*
 * Symbol types
 */
#define SESL_TYPE_UNKNOWN       0
#define SESL_TYPE_VOID          1
#define SESL_TYPE_CHAR          2
#define SESL_TYPE_UCHAR         3
#define SESL_TYPE_SHORT         4
#define SESL_TYPE_USHORT        5
#define SESL_TYPE_INT           6
#define SESL_TYPE_UINT          7
#define SESL_TYPE_LONG          8
#define SESL_TYPE_ULONG         9
#define SESL_TYPE_LONGLONG      10
#define SESL_TYPE_ULONGLONG     11
#define SESL_TYPE_FLOAT         12
#define SESL_TYPE_DOUBLE        13
#define SESL_TYPE_LONGDOUBLE    14
#define SESL_TYPE_STRUCT        15
#define SESL_TYPE_UNION         16
#define SESL_TYPE_ENUM          17
#define SESL_TYPE_ARRAY         18
#define SESL_TYPE_PTR           19
#define SESL_TYPE_FUNC          20
#define SESL_TYPE_LABEL         21

#endif