libretro/scummvm
1
0
Fork 0
mirror of https://github.com/libretro/scummvm.git synced 2024-12-12 03:56:20 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Patch

Browse Source 
svn-id: r41647
This commit is contained in:
Max Horn 2009-06-18 22:09:57 +00:00
parent 2e27c7b492
commit 42de7a1573
7 changed files with 543 additions and 422 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
engines/sci/engine/gc.h
View File

@ -45,19 +45,23 @@ struct reg_t_Hash {
}
};
// The reg_t_hash_map is actually really a hashset
/*
* The reg_t_hash_map is actually really a hashset
*/
typedef Common::HashMap<reg_t, bool, reg_t_Hash, reg_t_EqualTo> reg_t_hash_map;
/**
* Finds all used references and normalises them to their memory addresses
* @param s The state to gather all information from
* @return A hash map containing entries for all used references
*/
reg_t_hash_map *find_all_used_references(EngineState *s);
/* Finds all used references and normalises them to their memory addresses
** Parameters: (EngineState *) s: The state to gather all information from
** Returns : (reg_t_hash_map *) A hash map containing entries for all used references
*/
/**
* Runs garbage collection on the current system state
* @param s The state in which we should gc
*/
void run_gc(EngineState *s);
/* Runs garbage collection on the current system state
** Parameters: (EngineState *) s: The state in which we should gc
*/
} // End of namespace Sci

7
engines/sci/engine/intmap.h
View File

@ -83,7 +83,7 @@ public:
/**
* Checks whether a key is in the map, adds it if neccessary.
* @param value The key to check for/add
* @param key The key to check for/add
* @param add Whether to add the key if it's not in there
* @param was_added Set to non-zero if and only if the key is new, ignored if NULL.
* @return The new (or old) index, or -1 if add was zero and
@ -91,6 +91,11 @@ public:
*/
int checkKey(int key, bool add, bool *wasAdded = 0);
/**
* Looks up a key in the map
* @parmam key The key to look for
* @return The value or -1 if not found
*/
int lookupKey(int key) const;

179
engines/sci/engine/kernel.h
View File

@ -69,16 +69,17 @@ public:
uint getKernelNamesSize() const { return _kernelNames.size(); }
const Common::String &getKernelName(uint number) const { return _kernelNames[number]; }
/* Determines the selector ID of a selector by its name
** (const char *) selectorName: Name of the selector to look up
** Returns : (int) The appropriate selector ID, or -1 on error
*/
/**
* Determines the selector ID of a selector by its name
* @param selectorName Name of the selector to look up
* @return The appropriate selector ID, or -1 on error
*/
int findSelector(const char *selectorName) const;
/* Detects whether a particular kernel function is required in the game
** (const char *) functionName: The name of the desired kernel function
** Returns : (bool) true if the kernel function is listed in the kernel table,
** false otherwise
/**
* Detects whether a particular kernel function is required in the game
* @param functionName The name of the desired kernel function
* @return True if the kernel function is listed in the kernel table, false otherwise
*/
bool hasKernelFunction(const char *functionName) const;
@ -104,18 +105,18 @@ private:
/**
* Loads the kernel selector names.
* Returns true upon success, false otherwise.
* @return True upon success, false otherwise.
*/
bool loadSelectorNames(bool isOldSci0);
/* Maps special selectors
** Returns : (void)
*/
/**
* Maps special selectors
*/
void mapSelectors();
/* Maps kernel functions
** Returns : (void)
*/
/**
* Maps kernel functions
*/
void mapFunctions();
/**
@ -127,8 +128,10 @@ private:
ResourceManager *_resmgr;
// Kernel-related lists
// List of opcodes, loaded from vocab.998. This list is only used for debugging
// purposes, as we hardcode the list of opcodes in the sci_opcodes enum (script.h)
/**
* List of opcodes, loaded from vocab.998. This list is only used for debugging
* purposes, as we hardcode the list of opcodes in the sci_opcodes enum (script.h)
*/
Common::Array<opcode> _opcodes;
Common::StringList _selectorNames;
Common::StringList _kernelNames;
@ -178,61 +181,62 @@ int invoke_selector(EngineState *s, reg_t object, int selector_id, SelectorInvoc
/******************** Text functionality ********************/
/**
* Looks up text referenced by scripts
* SCI uses two values to reference to text: An address, and an index. The address
* determines whether the text should be read from a resource file, or from the heap,
* while the index either refers to the number of the string in the specified source,
* or to a relative position inside the text.
*
* @param s The current state
* @param address The address to look up
* @param index The relative index
* @return The referenced text, or NULL on error.
*/
char *kernel_lookup_text(EngineState *s, reg_t address, int index);
/* Looks up text referenced by scripts
** Parameters: (EngineState *s): The current state
** (reg_t) address: The address to look up
** (int) index: The relative index
** Returns : (char *): The referenced text, or NULL on error.
** SCI uses two values to reference to text: An address, and an index. The address
** determines whether the text should be read from a resource file, or from the heap,
** while the index either refers to the number of the string in the specified source,
** or to a relative position inside the text.
*/
/******************** Debug functionality ********************/
/**
* Checks whether a heap address contains an object
* @param s The current state
* @parm obj The address to check
* @return True if it is an object, false otherwise
*/
bool is_object(EngineState *s, reg_t obj);
/* Checks whether a heap address contains an object
** Parameters: (EngineState *) s: The current state
** (reg_t) obj: The address to check
** Returns : (bool) true if it is an object, false otherwise
*/
/******************** Kernel function parameter macros ********************/
/* Returns the parameter value or (alt) if not enough parameters were supplied */
/**
* Dereferences a heap pointer
* @param s The state to operate on
* @param pointer The pointer to dereference
* @parm entries The number of values expected (for checking; use 0 for strings)
* @return A physical reference to the address pointed to, or NULL on error or
* if not enugh entries were available.
* reg_t dereferenciation also assures alignedness of data.
*/
reg_t *kernel_dereference_reg_pointer(EngineState *s, reg_t pointer, int entries);
byte *kernel_dereference_bulk_pointer(EngineState *s, reg_t pointer, int entries);
#define kernel_dereference_char_pointer(state, pointer, entries) (char*)kernel_dereference_bulk_pointer(state, pointer, entries)
/* Dereferences a heap pointer
** Parameters: (EngineState *) s: The state to operate on
** (reg_t ) pointer: The pointer to dereference
** (int) entries: The number of values expected (for checking)
** (use 0 for strings)
** Returns : (reg_t/char *): A physical reference to the address pointed
** to, or NULL on error or if not enugh entries
** were available
** reg_t dereferenciation also assures alignedness of data.
*/
/******************** Priority macros/functions ********************/
/**
* Finds the position of the priority band specified
* Parameters: (EngineState *) s: State to search in
* (int) band: Band to look for
* Returns : (int) Offset at which the band starts
*/
int _find_priority_band(EngineState *s, int band);
/* Finds the position of the priority band specified
** Parameters: (EngineState *) s: State to search in
** (int) band: Band to look for
** Returns : (int) Offset at which the band starts
*/
/**
* Does the opposite of _find_priority_band
* @param s Engine state
* @param y Coordinate to check
* @return The priority band y belongs to
*/
int _find_view_priority(EngineState *s, int y);
/* Does the opposite of _find_priority_band
** Parameters: (EngineState *) s: State
** (int) y: Coordinate to check
** Returns : (int) The priority band y belongs to
*/
#define SCI0_VIEW_PRIORITY_14_ZONES(y) (((y) < s->priority_first)? 0 : (((y) >= s->priority_last)? 14 : 1\
+ ((((y) - s->priority_first) * 14) / (s->priority_last - s->priority_first))))
@ -249,50 +253,59 @@ int _find_view_priority(EngineState *s, int y);
/******************** Dynamic view list functions ********************/
/**
* Determines the base rectangle of the specified view object
* @param s The state to use
* @param object The object to set
* @return The absolute base rectangle
*/
Common::Rect set_base(EngineState *s, reg_t object);
/* Determines the base rectangle of the specified view object
** Parameters: (EngineState *) s: The state to use
** (reg_t) object: The object to set
** Returns : (abs_rect) The absolute base rectangle
*/
/**
* Determines the now-seen rectangle of a view object
* @param s The state to use
* @param object The object to check
* @param clip Flag to determine wheter priority band clipping
* should be performed
* @return The absolute rectangle describing the now-seen area.
*/
extern Common::Rect get_nsrect(EngineState *s, reg_t object, byte clip);
/* Determines the now-seen rectangle of a view object
** Parameters: (EngineState *) s: The state to use
** (reg_t) object: The object to check
** (byte) clip: Flag to determine wheter priority band
** clipping should be performed
** Returns : (abs_rect) The absolute rectangle describing the
** now-seen area.
*/
/**
* Removes all views in anticipation of a new window or text
*/
void _k_dyn_view_list_prepare_change(EngineState *s);
/* Removes all views in anticipation of a new window or text */
/**
* Redraws all views after a new window or text was added
*/
void _k_dyn_view_list_accept_change(EngineState *s);
/* Redraws all views after a new window or text was added */
/******************** Misc functions ********************/
void process_sound_events(EngineState *s); /* Get all sound events, apply their changes to the heap */
/**
* Get all sound events, apply their changes to the heap
*/
void process_sound_events(EngineState *s);
/**
* Resolves an address into a list node
* @param s The state to operate on
* @param addr The address to resolve
* @return The list node referenced, or NULL on error
*/
Node *lookup_node(EngineState *s, reg_t addr);
/* Resolves an address into a list node
** Parameters: (EngineState *) s: The state to operate on
** (reg_t) addr: The address to resolve
** Returns : (Node *) The list node referenced, or NULL on error
*/
/**
* Resolves a list pointer to a list
* @param s The state to operate on
* @param addr The address to resolve
* @return The list referenced, or NULL on error
*/
List *lookup_list(EngineState *s, reg_t addr);
/* Resolves a list pointer to a list
** Parameters: (EngineState *) s: The state to operate on
** (reg_t) addr: The address to resolve
** Returns : (List *) The list referenced, or NULL on error
*/
/******************** Constants ********************/

2
engines/sci/engine/seg_manager.cpp
View File

@ -430,7 +430,7 @@ void SegManager::heapRelocate(reg_t block) {
#define INST_LOOKUP_CLASS(id) ((id == 0xffff) ? NULL_REG : get_class_address(s, id, SCRIPT_GET_LOCK, NULL_REG))
reg_t get_class_address(EngineState *s, int classnr, int lock, reg_t caller);
reg_t get_class_address(EngineState *s, int classnr, SCRIPT_GET lock, reg_t caller);
Object *SegManager::scriptObjInit0(EngineState *s, reg_t obj_pos) {
Object *obj;

267
engines/sci/engine/seg_manager.h
View File

@ -45,29 +45,38 @@ namespace Sci {
class SegManager : public Common::Serializable {
public:
// Initialize the segment manager
/**
* Initialize the segment manager
*/
SegManager(bool sci1_1);
// Deallocate all memory associated with the segment manager
/**
* Deallocate all memory associated with the segment manager
*/
~SegManager();
virtual void saveLoadWithSerializer(Common::Serializer &ser);
// 1. Scripts
// Allocate a script into the segment manager
// Parameters: (int) script_nr: number of the script to load
// (state_t *) s: The state containing resource manager handlers to load the
// script data
// Returns : (int) 0 on failure, 1 on success
// (int) *seg_id: The segment ID of the newly allocated segment, on success
/**
* Allocate a script into the segment manager
* @param s The state containing resource manager
* handlers to load the script data
* @param script_nr The number of the script to load
* @param seg_id The segment ID of the newly allocated segment,
* on success
* @return 0 on failure, 1 on success
*/
Script *allocateScript(EngineState *s, int script_nr, SegmentId *seg_id);
// The script must then be initialised; see section (1b.), below.
// Forcefully deallocate a previously allocated script
// Parameters: (int) script_nr: number of the script to deallocate
// Returns : (int) 1 on success, 0 on failure
/**
* Forcefully deallocate a previously allocated script
* @param script_nr number of the script to deallocate
* @return 1 on success, 0 on failure
*/
int deallocateScript(int script_nr);
/**
@ -76,30 +85,40 @@ public:
*/
bool scriptIsLoaded(SegmentId seg);
// Validate whether the specified public function is exported by the script in the specified segment
// Parameters: (int) pubfunct: Index of the function to validate
// (int) seg: Segment ID of the script the check is to be performed for
// Returns : (uint16) 0 if the public function is invalid, its offset into the script's segment
// otherwise
/**
* Validate whether the specified public function is exported by
* the script in the specified segment
* @param pubfunct Index of the function to validate
* @param seg Segment ID of the script the check is to
* be performed for
* @return NULL if the public function is invalid, its
* offset into the script's segment otherwise
*/
uint16 validateExportFunc(int pubfunct, SegmentId seg);
// Get the segment ID associated with a script number
// Parameters: (int) script_nr: Number of the script to look up
// Returns : (int) The associated segment ID, or -1 if no matching segment exists
/**
* Get the segment ID associated with a script number
* @param script_nr Number of the script to look up
* @return The associated segment ID, or -1 if no
* matching segment exists
*/
SegmentId segGet(int script_nr) const;
/**
* Return a pointer to the specified script. If the id is invalid, does not refer
* to a script or the script is not loaded, this will invoke error().
* Return a pointer to the specified script.
* If the id is invalid, does not refer to a script or the script is
* not loaded, this will invoke error().
* @param seg ID of the script segment to check for
* @return pointer to the Script object
* @return A pointer to the Script object
*/
Script *getScript(SegmentId seg);
/**
* Return a pointer to the specified script. If the id is invalid, does not refer
* Return a pointer to the specified script.
* If the id is invalid, does not refer to a script, or
* the script is not loaded, this will return NULL
* @param seg ID of the script segment to check for
* @return pointer to the Script object, or NULL
* @return A pointer to the Script object, or NULL
*/
Script *getScriptIfLoaded(SegmentId seg);
@ -112,51 +131,70 @@ public:
// to be used during script instantiation,
// i.e. loading and linking.
// Initializes a script's local variable block
// Parameters: (SegmentId) seg: Segment containing the script to initialize
// (int) nr: Number of local variables to allocate
// All variables are initialized to zero.
/**
* Initializes a script's local variable block
* All variables are initialized to zero.
* @param seg Segment containing the script to initialize
* @param nr Number of local variables to allocate
*/
void scriptInitialiseLocalsZero(SegmentId seg, int nr);
// Initializes a script's local variable block according to a prototype
// Parameters: (reg_t) location: Location to initialize from
/**
* Initializes a script's local variable block according to a prototype
* @param location Location to initialize from
*/
void scriptInitialiseLocals(reg_t location);
// Initializes an object within the segment manager
// Parameters: (reg_t) obj_pos: Location (segment, offset) of the object
// Returns : (Object *) A newly created Object describing the object
// obj_pos must point to the beginning of the script/class block (as opposed
// to what the VM considers to be the object location)
// The corresponding Object is stored within the relevant script.
/**
* Initializes an object within the segment manager
* @param obj_pos Location (segment, offset) of the object. It must
* point to the beginning of the script/class block
* (as opposed to what the VM considers to be the
* object location)
* @returns A newly created Object describing the object,
* stored within the relevant script
*/
Object *scriptObjInit(EngineState *s, reg_t obj_pos);
// Informs the segment manager that a code block must be relocated
// Parameters: (reg_t) location: Start of block to relocate
/**
* Informs the segment manager that a code block must be relocated
* @param location Start of block to relocate
*/
void scriptAddCodeBlock(reg_t location);
// Tells the segment manager whether exports are wide (32-bit) or not.
// Parameters: (int) flag: 1 if exports are wide, 0 otherwise
/**
* Tells the segment manager whether exports are wide (32-bit) or not.
* @param flag 1 if exports are wide, 0 otherwise
*/
void setExportWidth(int flag);
// Processes a relocation block witin a script
// Parameters: (reg_t) obj_pos: Location (segment, offset) of the block
// Returns : (Object *) Location of the relocation block
// This function is idempotent, but it must only be called after all
// objects have been instantiated, or a run-time error will occur.
/**
* Processes a relocation block witin a script
* This function is idempotent, but it must only be called after all
* objects have been instantiated, or a run-time error will occur.
* @param obj_pos Location (segment, offset) of the block
* @return Location of the relocation block
*/
void scriptRelocate(reg_t block);
// Determines whether the script referenced by the indicated segment is marked as being deleted.
// Parameters: (SegmentId) Segment ID of the script to investigate
// Returns : (int) 1 iff seg points to a script and the segment is deleted, 0 otherwise
// Will return 0 when applied to an invalid or non-script seg.
/**
* Determines whether the script referenced by the indicated segment
* is marked as being deleted.
* Will return 0 when applied to an invalid or non-script seg.
* @param seg Segment ID of the script to investigate
* @return 1 iff seg points to a script and the segment is
* deleted, 0 otherwise
*/
bool scriptIsMarkedAsDeleted(SegmentId seg);
// 2. Clones
// Allocate a fresh clone
// Returns : (Clone*): Reference to the memory allocated for the clone
// (reg_t) *addr: The offset of the freshly allocated clone
/**
* Allocate a fresh clone
* @param addr The offset of the freshly allocated clone
* @return Reference to the memory allocated for the clone
*/
Clone *alloc_Clone(reg_t *addr);
@ -166,76 +204,96 @@ public:
// 4. Stack
// Allocates a data stack
// Parameters: (int) size: Number of stack entries to reserve
// Returns : (DataStack *): The physical stack
// (SegmentId) segid: Segment ID of the stack
/**
* Allocates a data stack
* @param size Number of stack entries to reserve
* @param segid Segment ID of the stack
* @return The physical stack
*/
DataStack *allocateStack(int size, SegmentId *segid);
// 5. System Strings
// Allocates a system string table
// Returns : (DataStack *): The physical stack
// (SegmentId) segid: Segment ID of the stack
// See also sys_string_acquire();
/**
* Allocates a system string table
* See also sys_string_acquire();
* @param[in] segid Segment ID of the stack
* @returns The physical stack
*/
SystemStrings *allocateSysStrings(SegmentId *segid);
// 5. System Strings
// Allocates a string fragments segment
// Returns : (SegmentId): Segment ID to use for string fragments
// See also stringfrag.h
/**
* Allocates a string fragments segment
* See also stringfrag.h
* @return Segment ID to use for string fragments
*/
SegmentId allocateStringFrags();
// 6, 7. Lists and Nodes
// Allocate a fresh list
// Returns : (listY_t*): Reference to the memory allocated for the list
// (reg_t) *addr: The offset of the freshly allocated list
/**
* Allocate a fresh list
* @param[in] addr The offset of the freshly allocated list
* @return Reference to the memory allocated for the list
*/
List *alloc_List(reg_t *addr);
// Allocate a fresh node
// Returns : (node_t*): Reference to the memory allocated for the node
// (reg_t) *addr: The offset of the freshly allocated node
/**
* Allocate a fresh node
* @param[in] addr The offset of the freshly allocated node
* @return Reference to the memory allocated for the node
*/
Node *alloc_Node(reg_t *addr);
// 8. Hunk Memory
// Allocate a fresh chunk of the hunk
// Parameters: (int) size: Number of bytes to allocate for the hunk entry
// (const char *) hunk_type: A descriptive string for the hunk entry,
// for debugging purposes
// Returns : (Hunk *): Reference to the memory allocated for the hunk piece
// (reg_t) *addr: The offset of the freshly allocated hunk entry
/**
* Allocate a fresh chunk of the hunk
* @param[in] size Number of bytes to allocate for the hunk entry
* @param[in] hunk_type A descriptive string for the hunk entry, for
* debugging purposes
* @param[out] addr The offset of the freshly allocated hunk entry
* @return Reference to the memory allocated for the hunk
* piece
*/
Hunk *alloc_hunk_entry(const char *hunk_type, int size, reg_t *addr);
// Deallocates a hunk entry
// Parameters: (reg_t) addr: Offset of the hunk entry to delete
/**
* Deallocates a hunk entry
* @param[in] addr Offset of the hunk entry to delete
*/
void free_hunk_entry(reg_t addr);
// 9. Dynamic Memory
// Allocate some dynamic memory
// Parameters: (int) size: Number of bytes to allocate
// (const char_ *) description: A descriptive string,
// for debugging purposes
// Returns : (unsigned char*): Raw pointer into the allocated dynamic memory
// (reg_t) *addr: The offset of the freshly allocated X
/**
* Allocate some dynamic memory
* @param[in] size Number of bytes to allocate
* @param[in] description A descriptive string for debugging purposes
* @param[out] addr The offset of the freshly allocated X
* @return Raw pointer into the allocated dynamic
* memory
*/
unsigned char *allocDynmem(int size, const char *description, reg_t *addr);
// Deallocates a piece of dynamic memory
// Parameters: (reg_t) addr: Offset of the dynmem chunk to free
/**
* Deallocates a piece of dynamic memory
* @param[in] addr Offset of the dynmem chunk to free
*/
int freeDynmem(reg_t addr);
// Gets the description of a dynmem segment
// Parameters: (reg_t) addr: Segment to describe
// Returns : (const char *): Pointer to the descriptive string set in
// allocDynmem
/**
* Gets the description of a dynmem segment
* @param[in] addr Segment to describe
* @return Pointer to the descriptive string set in allocDynmem
*/
const char *getDescription(reg_t addr);
@ -251,10 +309,12 @@ public:
// Generic Operations on Segments and Addresses
// Dereferences a raw memory pointer
// Parameters: (reg_t) reg: The reference to dereference
// Returns : (byte *) The data block referenced
// (int) size: (optionally) the theoretical maximum size of it
/**
* Dereferences a raw memory pointer
* @param[in] reg The reference to dereference
* @param[out] size (optional) The theoretical maximum size
* @return The data block referenced
*/
byte *dereference(reg_t reg, int *size);
@ -266,17 +326,17 @@ public:
int initialiseScript(Script &scr, EngineState *s, int script_nr);
private:
IntMapper *id_seg_map; // id - script id; seg - index of heap
IntMapper *id_seg_map; ///< id - script id; seg - index of heap
public: // TODO: make private
Common::Array<MemObject *> _heap;
int reserved_id;
int exports_wide;
bool isSci1_1;
SegmentId Clones_seg_id; // ID of the (a) clones segment
SegmentId Lists_seg_id; // ID of the (a) list segment
SegmentId Nodes_seg_id; // ID of the (a) node segment
SegmentId Hunks_seg_id; // ID of the (a) hunk segment
SegmentId Clones_seg_id; ///< ID of the (a) clones segment
SegmentId Lists_seg_id; ///< ID of the (a) list segment
SegmentId Nodes_seg_id; ///< ID of the (a) node segment
SegmentId Hunks_seg_id; ///< ID of the (a) hunk segment
private:
MemObject *allocNonscriptSegment(MemObjectType type, SegmentId *segid);
@ -295,11 +355,12 @@ private:
Object *scriptObjInit0(EngineState *s, reg_t obj_pos);
Object *scriptObjInit11(EngineState *s, reg_t obj_pos);
/* Check segment validity
** Parameters: (int) seg: The segment to validate
** Returns : (bool) false if 'seg' is an invalid segment
** true if 'seg' is a valid segment
*/
/**
* Check segment validity
* @param[in] seg The segment to validate
* @return false if 'seg' is an invalid segment, true if
* 'seg' is a valid segment
*/
bool check(SegmentId seg);
void dbgPrint(const char* msg, void *i); // for debug only

4
engines/sci/engine/vm.cpp
View File

@ -193,7 +193,7 @@ int script_error(EngineState *s, const char *file, int line, const char *reason)
}
#define CORE_ERROR(area, msg) script_error(s, "[" area "] " __FILE__, __LINE__, msg)
reg_t get_class_address(EngineState *s, int classnr, int lock, reg_t caller) {
reg_t get_class_address(EngineState *s, int classnr, SCRIPT_GET lock, reg_t caller) {
if (NULL == s) {
warning("vm.c: get_class_address(): NULL passed for \"s\"");
@ -1550,7 +1550,7 @@ SelectorType lookup_selector(EngineState *s, reg_t obj_location, Selector select
return _lookup_selector_function(s, obj_location.segment, obj, selector_id, fptr);
}
SegmentId script_get_segment(EngineState *s, int script_nr, int load) {
SegmentId script_get_segment(EngineState *s, int script_nr, SCRIPT_GET load) {
SegmentId segment;
if ((load & SCRIPT_GET_LOAD) == SCRIPT_GET_LOAD)

486
engines/sci/engine/vm.h
View File

@ -287,8 +287,8 @@ struct Breakpoint {
};
/**
* Set this to 1 to abort script execution immediately. Aborting will leave the
* debug exec stack intact.
* Set this to 1 to abort script execution immediately. Aborting will
* leave the debug exec stack intact.
* Set it to 2 to force a replay afterwards.
*/
extern int script_abort_flag;
@ -307,31 +307,36 @@ extern int script_step_counter;
/**
* Executes function pubfunct of the specified script.
* Parameters: (EngineState *) s: The state which is to be executed with
* (uint16) script: The script which is called
* (uint16) pubfunct: The exported script function which is to be called
* (StackPtr) sp: Stack pointer position
* (reg_t) calling_obj: The heap address of the object which executed the call
* (uint16) argc: Number of arguments supplied
* (StackPtr) argp: Pointer to the first supplied argument
* Returns : (ExecStack *): A pointer to the new exec stack TOS entry
* @param[in] s The state which is to be executed with
* @param[in] script The script which is called
* @param[in] pubfunct The exported script function which is to
* be called
* @param[in] sp Stack pointer position
* @param[in] calling_obj The heap address of the object that
* executed the call
* @param[in] argc Number of arguments supplied
* @param[in] argp Pointer to the first supplied argument
* @return A pointer to the new exec stack TOS entry
*/
ExecStack *execute_method(EngineState *s, uint16 script, uint16 pubfunct, StackPtr sp, reg_t calling_obj,
uint16 argc, StackPtr argp);
ExecStack *execute_method(EngineState *s, uint16 script, uint16 pubfunct,
StackPtr sp, reg_t calling_obj, uint16 argc, StackPtr argp);
/**
* Executes a "send" or related operation to a selector.
* Parameters: (EngineState *) s: The EngineState to operate on
* (reg_t) send_obj: Heap address of the object to send to
* (reg_t) work_obj: Heap address of the object initiating the send
* (StackPtr) sp: Stack pointer position
* (int) framesize: Size of the send as determined by the "send" operation
* (StackPtr) argp: Pointer to the beginning of the heap block containing the
* data to be sent. This area is a succession of one or more
* sequences of [selector_number][argument_counter] and then
* "argument_counter" word entries with the parameter values.
* Returns : (ExecStack *): A pointer to the new execution stack TOS entry
* @param[in] s The EngineState to operate on
* @param[in] send_obj Heap address of the object to send to
* @param[in] work_obj Heap address of the object initiating the send
* @param[in] sp Stack pointer position
* @param[in] framesize Size of the send as determined by the "send"
* operation
* @param[in] argp Pointer to the beginning of the heap block
* containing the data to be sent. This area is a
* succession of one or more sequences of
* [selector_number][argument_counter] and then
* "argument_counter" word entries with the
* parameter values.
* @return A pointer to the new execution stack TOS entry
*/
ExecStack *send_selector(EngineState *s, reg_t send_obj, reg_t work_obj,
StackPtr sp, int framesize, StackPtr argp);
@ -342,267 +347,300 @@ ExecStack *send_selector(EngineState *s, reg_t send_obj, reg_t work_obj,
/**
* Adds an entry to the top of the execution stack.
*
* @param s The state with which to execute
* @param pc The initial program counter
* @param sp The initial stack pointer
* @param objp Pointer to the beginning of the current object
* @param argc Number of parameters to call with
* @param argp Heap pointer to the first parameter
* @param selector The selector by which it was called or
* NULL_SELECTOR if n.a. For debugging.
* @param sendp Pointer to the object which the message was sent to.
* Equal to objp for anything but super.
* @param origin Number of the execution stack element this entry was created by
* (usually the current TOS number, except for multiple sends).
* @param local_segment The segment to use for local variables,
* or SCI_XS_CALLEE_LOCALS to use obj's segment.
* @return a pointer to the new exec stack TOS entry
* @param[in] s The state with which to execute
* @param[in] pc The initial program counter
* @param[in] sp The initial stack pointer
* @param[in] objp Pointer to the beginning of the current object
* @param[in] argc Number of parameters to call with
* @param[in] argp Heap pointer to the first parameter
* @param[in] selector The selector by which it was called or
* NULL_SELECTOR if n.a. For debugging.
* @param[in] sendp Pointer to the object which the message was
* sent to. Equal to objp for anything but super.
* @param[in] origin Number of the execution stack element this
* entry was created by (usually the current TOS
* number, except for multiple sends).
* @param[in] local_segment The segment to use for local variables,
* or SCI_XS_CALLEE_LOCALS to use obj's segment.
* @return A pointer to the new exec stack TOS entry
*/
ExecStack *add_exec_stack_entry(EngineState *s, reg_t pc, StackPtr sp, reg_t objp, int argc,
StackPtr argp, Selector selector, reg_t sendp, int origin, SegmentId local_segment);
ExecStack *add_exec_stack_entry(EngineState *s, reg_t pc, StackPtr sp,
reg_t objp, int argc, StackPtr argp, Selector selector,
reg_t sendp, int origin, SegmentId local_segment);
/**
* Adds one varselector access to the execution stack.
* Parameters: (EngineState *) s: The EngineState to use
* (reg_t) objp: Pointer to the object owning the selector
* (int) argc: 1 for writing, 0 for reading
* (StackPtr) argp: Pointer to the address of the data to write -2
* (int) selector: Selector name
* (ObjVarRef& ) address: Heap address of the selector
* (int) origin: Stack frame which the access originated from
* Returns : (ExecStack *): Pointer to the new exec-TOS element
* This function is called from send_selector only.
* @param[in] s The EngineState to use
* @param[in] objp Pointer to the object owning the selector
* @param[in] argc 1 for writing, 0 for reading
* @param[in] argp Pointer to the address of the data to write -2
* @param[in] selector Selector name
* @param[in] address Heap address of the selector
* @param[in] origin Stack frame which the access originated from
* @return Pointer to the new exec-TOS element
*/
ExecStack *add_exec_stack_varselector(EngineState *s, reg_t objp, int argc, StackPtr argp,
Selector selector, const ObjVarRef& address, int origin);
ExecStack *add_exec_stack_varselector(EngineState *s, reg_t objp, int argc,
StackPtr argp, Selector selector, const ObjVarRef& address,
int origin);
/**
* This function executes SCI bytecode
* It executes the code on s->heap[pc] until it hits a 'ret' operation
* while (stack_base == stack_pos). Requires s to be set up correctly.
* @param[in] s The state to use
* @param[in] restoring 1 if s has just been restored, 0 otherwise
*/
void run_vm(EngineState *s, int restoring);
/* Executes the code on s->heap[pc] until it hits a 'ret' operation while (stack_base == stack_pos)
** Parameters: (EngineState *) s: The state to use
** (int) restoring: 1 if s has just been restored, 0 otherwise
** Returns : (void)
** This function will execute SCI bytecode. It requires s to be set up
** correctly.
*/
/**
* Handles a fatal error condition
* @param[in] s The state to recover from
* @param[in] line Source code line number the error occured in
* @param[in] file File the error occured in
*/
void vm_handle_fatal_error(EngineState *s, int line, const char *file);
/* Handles a fatal error condition
** Parameters: (EngineState *) s: The state to recover from
** (int) line: Source code line number the error occured in
** (const char *) file: File the error occured in
*/
void script_debug(EngineState *s, reg_t *pc, StackPtr *sp, StackPtr *pp, reg_t *objp,
int *restadjust, SegmentId *segids, reg_t **variables, reg_t **variables_base,
int *variables_nr, int bp);
/* Debugger functionality
** Parameters: (EngineState *) s: The state at which debugging should take place
** (reg_t *) pc: Pointer to the program counter
** (StackPtr *) sp: Pointer to the stack pointer
** (StackPtr *) pp: Pointer to the frame pointer
** (reg_t *) objp: Pointer to the object base pointer
** (int *) restadjust: Pointer to the &rest adjustment value
** (SegmentId *) segids: four-element array containing segment IDs for locals etc.
** (reg_t **) variables: four-element array referencing registers for globals etc.
** (reg_t **) variables_base: four-element array referencing
** register bases for temps etc.
** (int *) variables_nr: four-element array giving sizes for params etc. (may be NULL)
** (int) bp: Flag, set to 1 when a breakpoint is triggered
** Returns : (void)
*/
/**
* Debugger functionality
* @param[in] s The state at which debugging should take
* place
* @param[in] pc Pointer to the program counter
* @param[in] sp Pointer to the stack pointer
* @param[in] pp Pointer to the frame pointer
* @param[in] objp Pointer to the object base pointer
* @param[in] restadjust Pointer to the &rest adjustment value
* @param[in] segids four-element array containing segment IDs
* for locals etc.
* @param[in] variables four-element array referencing registers
* for globals etc.
* @param[in] variables_base four-element array referencing register
* bases for temps etc.
* @param[in] variables_nr four-element array giving sizes for params
* etc. (may be NULL)
* @param[in] bp Flag, set to 1 when a breakpoint is
* triggered
*/
void script_debug(EngineState *s, reg_t *pc, StackPtr *sp, StackPtr *pp,
reg_t *objp, int *restadjust, SegmentId *segids, reg_t **variables,
reg_t **variables_base, int *variables_nr, int bp);
/**
* Initializes a EngineState block
* @param[in] s The state to initialize
* @return 0 on success, 1 if vocab.996 (the class table) is missing
* or corrupted
*/
int script_init_engine(EngineState *s);
/* Initializes a EngineState block
** Parameters: (EngineState *) s: The state to initialize
** Returns : 0 on success, 1 if vocab.996 (the class table) is missing or corrupted
*/
/**
* Sets the gamestate's save_dir to the parameter path
* @param[in] s The state to set
* @param[in] path Path where save_dir will point to
*/
void script_set_gamestate_save_dir(EngineState *s, const char *path);
/* Sets the gamestate's save_dir to the parameter path
** Parameters: (EngineState *) s: The state to set
** (const char *) path: Path where save_dir will point to
** Returns : (void)
*/
/**
* Frees all additional memory associated with a EngineState block
* @param[in] s The EngineState whose elements should be cleared
*/
void script_free_engine(EngineState *s);
/* Frees all additional memory associated with a EngineState block
** Parameters: (EngineState *) s: The EngineState whose elements should be cleared
** Returns : (void)
*/
/**
* Frees all script memory (heap, hunk, and class tables).
* This operation is implicit in script_free_engine(), but is required for
* restoring the game state.
* @param[in] s The EngineState to free
*/
void script_free_vm_memory(EngineState *s);
/* Frees all script memory (heap, hunk, and class tables).
** Parameters: (EngineState *) s: The EngineState to free
** Returns : (void)
** This operation is implicit in script_free_engine(), but is required for restoring
** the game state.
*/
/**
* Looks up a selector and returns its type and value
* varindex is written to iff it is non-NULL and the selector indicates a property of the object.
* @param[in] s The EngineState to use
* @param[in] obj Address of the object to look the selector up in
* @param[in] selectorid The selector to look up
* @param[out] varp A reference to the selector, if it is a
* variable.
* @param[out] fptr A reference to the function described by that
* selector, if it is a valid function selector.
* fptr is written to iff it is non-NULL and the
* selector indicates a member function of that
* object.
* @return kSelectorNone if the selector was not found in
* the object or its superclasses.
* kSelectorVariable if the selector represents an
* object-relative variable.
* kSelectorMethod if the selector represents a
* method
*/
SelectorType lookup_selector(EngineState *s, reg_t obj, Selector selectorid,
ObjVarRef *varp, reg_t *fptr);
SelectorType lookup_selector(EngineState *s, reg_t obj, Selector selectorid, ObjVarRef *varp, reg_t *fptr);
/* Looks up a selector and returns its type and value
** Parameters: (EngineState *) s: The EngineState to use
** (reg_t) obj: Address of the object to look the selector up in
** (Selector) selectorid: The selector to look up
** Returns : (SelectorType) kSelectorNone if the selector was not found in the object or its superclasses.
** kSelectorVariable if the selector represents an object-relative variable
** kSelectorMethod if the selector represents a method
** (ObjVarRef *) *varp: A reference to the selector, if
** it is a variable
** (reg_t) *fptr: A reference to the function described by that selector, if it is
** a valid function selector.
** *varindex is written to iff it is non-NULL and the selector indicates a property of the object.
** *fptr is written to iff it is non-NULL and the selector indicates a member function of that object.
*/
enum {
/**
* Parameters for script_get_segment()
*/
typedef enum {
SCRIPT_GET_DONT_LOAD = 0, /**< Fail if not loaded */
SCRIPT_GET_LOAD = 1, /**< Load, if neccessary */
SCRIPT_GET_LOCK = 3 /**< Load, if neccessary, and lock */
};
} SCRIPT_GET;
SegmentId script_get_segment(EngineState *s, int script_id, int load);
/* Determines the segment occupied by a certain script
** Parameters: (EngineState *) s: The state to operate on
** (int) script_id: The script in question
** (int) load: One of SCRIPT_GET_*
** Returns : The script's segment, or 0 on failure
*/
/**
* Determines the segment occupied by a certain script
* @param[in] s The state to operate on
* @param[in] script_id The script in question
* @param[in] load One of SCRIPT_GET_*
* @return The script's segment, or 0 on failure
*/
SegmentId script_get_segment(EngineState *s, int script_id, SCRIPT_GET load);
/**
* Looks up an entry of the exports table of a script
* @param[in] s The state to operate on
* @param[in] script_nr The script to look up in
* @param[out] export_index The index of the export entry to look up
* @return The handle
*/
reg_t script_lookup_export(EngineState *s, int script_nr, int export_index);
/* Looks up an entry of the exports table of a script
** Parameters: (EngineState *) s: The state to operate on
** (int) script_nr: The script to look up in
** Returns : (int) export_index: index of the export entry to look up
*/
/**
* Makes sure that a script and its superclasses get loaded to the heap.
* If the script already has been loaded, only the number of lockers is
* increased. All scripts containing superclasses of this script are loaded
* recursively as well, unless 'recursive' is set to zero. The
* complementary function is "script_uninstantiate()" below.
* @param[in] s The state to operate on
* @param[in] script_nr The script number to load
* @return The script's segment ID or 0 if out of heap
*/
int script_instantiate(EngineState *s, int script_nr);
/* Makes sure that a script and its superclasses get loaded to the heap
** Parameters: (EngineState *) s: The state to operate on
** (int) script_nr: The script number to load
** Returns : (int) The script's segment ID or 0 if out of heap
** If the script already has been loaded, only the number of lockers is increased.
** All scripts containing superclasses of this script aret loaded recursively as well,
** unless 'recursive' is set to zero.
** The complementary function is "script_uninstantiate()" below.
*/
/**
* Decreases the numer of lockers of a script and unloads it if that number
* reaches zero.
* This function will recursively unload scripts containing its
* superclasses, if those aren't locked by other scripts as well.
* @param[in] s The state to operate on
* @param[in] script_nr The script number that is requestet to be unloaded
*/
void script_uninstantiate(EngineState *s, int script_nr);
/* Decreases the numer of lockers of a script and unloads it if that number reaches zero
** Parameters: (EngineState *) s: The state to operate on
** (int) script_nr: The script number that is requestet to be unloaded
** Returns : (void)
** This function will recursively unload scripts containing its superclasses, if those
** aren't locked by other scripts as well.
*/
/**
* Initializes an SCI game
* This function must be run before script_run() is executed. Graphics data
* is initialized iff s->gfx_state != NULL.
* @param[in] s The state to operate on
* @return 0 on success, 1 if an error occured.
*/
int game_init(EngineState *s);
/* Initializes an SCI game
** Parameters: (EngineState *) s: The state to operate on
** Returns : (int): 0 on success, 1 if an error occured.
** This function must be run before script_run() is executed.
** Graphics data is initialized iff s->gfx_state != NULL.
*/
/**
* Initializes the graphics part of an SCI game
* This function may only be called if game_init() did not initialize
* the graphics data.
* @param[in] s The state to initialize the graphics in
* @return 0 on success, 1 if an error occured
*/
int game_init_graphics(EngineState *s);
/* Initializes the graphics part of an SCI game
** Parameters: (EngineState *) s: The state to initialize the graphics in
** Returns : (int) 0 on success, 1 if an error occured
** This function may only be called if game_init() did not initialize
** the graphics data.
*/
/**
* Initializes the sound part of an SCI game
* This function may only be called if game_init() did not initialize
* the sound data.
* @param[in] s The state to initialize the sound in
* @param[in] sound_flags Flags to pass to the sound subsystem
* @return 0 on success, 1 if an error occured
*/
int game_init_sound(EngineState *s, int sound_flags);
/* Initializes the sound part of an SCI game
** Parameters: (EngineState *) s: The state to initialize the sound in
** (int) sound_flags: Flags to pass to the sound subsystem
** Returns : (int) 0 on success, 1 if an error occured
** This function may only be called if game_init() did not initialize
** the graphics data.
*/
/**
* Runs an SCI game
* This is the main function for SCI games. It takes a valid state, loads
* script 0 to it, finds the game object, allocates a stack, and runs the
* init method of the game object. In layman's terms, this runs an SCI game.
* Note that, EngineState *s may be changed during the game, e.g. if a game
* state is restored.
* @param[in] s Pointer to the pointer of the state to operate on
* @return 0 on success, 1 if an error occured.
*/
int game_run(EngineState **s);
/* Runs an SCI game
** Parameters: (EngineState **) s: Pointer to the pointer of the state to operate on
** Returns : (int): 0 on success, 1 if an error occured.
** This is the main function for SCI games. It takes a valid state, loads script 0 to it,
** finds the game object, allocates a stack, and runs the init method of the game object.
** In layman's terms, this runs an SCI game.
** By the way, *s may be changed during the game, e.g. if a game state is restored.
*/
/**
* Restores an SCI game state and runs the game
* This restores a savegame; otherwise, it behaves just like game_run().
* @param[in] s Pointer to the pointer of the state to
* operate on
* @param[in] savegame_name Name of the savegame to restore
* @return 0 on success, 1 if an error occured.
*/
int game_restore(EngineState **s, char *savegame_name);
/* Restores an SCI game state and runs the game
** Parameters: (EngineState **) s: Pointer to the pointer of the state to operate on
** (char *) savegame_name: Name of the savegame to restore
** Returns : (int): 0 on success, 1 if an error occured.
** This restores a savegame; otherwise, it behaves just like game_run().
*/
/**
* Uninitializes an initialized SCI game
* This function should be run after each script_run() call.
* @param[in] s The state to operate on
* @return 0 on success, 1 if an error occured.
*/
int game_exit(EngineState *s);
/* Uninitializes an initialized SCI game
** Parameters: (EngineState *) s: The state to operate on
** Returns : (int): 0 on success, 1 if an error occured.
** This function should be run after each script_run() call.
*/
/**
* Instructs the virtual machine to abort
*/
void quit_vm();
/* Instructs the virtual machine to abort
** Paramteres: (void)
** Returns : (void)
*/
/**
* Allocates "kernel" memory and returns a handle suitable to be passed on
* to SCI scripts
* @param[in] s Pointer to the EngineState to operate on
* @param[in] type A free-form type description string (static)
* @param[in] space The space to allocate
* @return The handle
*/
reg_t kalloc(EngineState *s, const char *type, int space);
/* Allocates "kernel" memory and returns a handle suitable to be passed on to SCI scripts
** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
** (const char *) type: A free-form type description string (static)
** (int) space: The space to allocate
** Returns : (reg_t) The handle
*/
/**
* Returns a pointer to "kernel" memory based on the handle
* @param[in] s Pointer to the EngineState to operate on
* @param[in] handle The handle to use
* @return A pointer to the allocated memory
*/
byte *kmem(EngineState *s, reg_t handle);
/* Returns a pointer to "kernel" memory based on the handle
** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
** (reg_t) handle: The handle to use
** Returns : (byte *) A pointer to the allocated memory
*/
/**
* Frees all "kernel" memory associated with a handle
* @param[in] s Pointer to the EngineState to operate on
* @param[in] handle The handle to free
* @return 0 on success, 1 otherwise
*/
int kfree(EngineState *s, reg_t handle);
/* Frees all "kernel" memory associated with a handle
** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
** (reg_t) handle: The handle to free
** Returns : (int) 0 on success, 1 otherwise
*/
/**
* Determines the name of an object
* @param[in] s Pointer to the EngineState to operate on
* @param[in] pos Location of the object whose name we want to inspect
* @return A name for that object, or a string describing an error
* that occured while looking it up. The string is stored
* in a static buffer and need not be freed (neither may
* it be modified).
*/
const char *obj_get_name(EngineState *s, reg_t pos);
/* Determines the name of an object
** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
** (reg_t) pos: Location of the object whose name we want to
** inspect
** Returns : (const char *) A name for that object, or a string describing
** an error that occured while looking it up
** The string is stored in a static buffer and need not be freed (neither
** may it be modified).
*/
/**
* Retrieves an object from the specified location
* @param[in] s Pointer to the EngineState to operate on
* @param[in] offset The object's offset
* @return The object in question, or NULL if there is none
*/
Object *obj_get(EngineState *s, reg_t offset);
/* Retrieves an object from the specified location
** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
** (reg_t) offset: The object's offset
** Returns : (Object *) The object in question, or NULL if there is none
*/
/**
* Shrink execution stack to size.
* Contains an assert it is not already smaller.
*/
void shrink_execution_stack(EngineState *s, uint size);
/* Shrink execution stack to size.
** Contains an assert it is not already smaller.
*/
} // End of namespace Sci