Index

libpal - PROSE Assembly Language library routines

CONTENTS

Synopsis
Description
Interfaces
Type Definitions
Data Structures
Macro Interfaces
Macro Definitions
Custom Error Codes
Files
See Also
Author

cc -Iincludedir/prose [flag ...] file -lpal [library ...]

#include <prism/pal_api.h>

Provides library routines for reading/writing PROSE binary files, assembling and disassembling PROSE Assembly Language (PAL). See the source code for lists of function arguments, return values and general usage guidelines.

In general, to assemble a file use Pal_lexer(input_file, output_file, max_errors), to disassemble use Pal_dsm_file(input_file) or to view file information use Pal_view_file(input_file). These functions then make use of the remaining APIs.

The library is detailed below in terms of INTERFACES, TYPE DEFINITIONS, DATA STRUCTURES, MACRO INTERFACES, MACRO DEFINITIONS and CUSTOM ERROR CODES. Symbols are grouped by functionality, and the groups organised alphabetically.

This library is designed to work in a GNU Autoconf environment, where a configure script has created a config.h file containing macro definitions indicating the availability of features in the compilation environment. To use the library without GNU Autoconf, copy config.h from the library’s source directory after running configure on the target system, and make this header file available in your project’s include directory.

Pal_dsm_file()
	Disassemble a specified PROSE binary file.
Pal_dsm_init()
	Initialises a disassembly buffer in preparation for calling the byte disassembly functions (does not require freeing later).
Pal_dsm_print()
	Disassemble this byte and print PAL symbol to supplied output stream. If the byte cannot be disassembled at this time (more data required), store it in the supplied disassembly buffer.
Pal_dsm_printstr()
	Prints a PAL-style character string enclosed in [ square brackets ] protecting characters with a backslash as necessary, writing the result to the given output stream.
Pal_dsm_printref
	Prints a PAL-style code reference enclosed in &[ ] to the given output stream.
Pal_encode_ulong()
	Encodes an unsigned long into a shortened representation.
Pal_decode_ulong()
	Decodes an unsigned long previously encoded using Pal_encode_ulong().
Pal_file_init()
	Initialise pal_fileio data structure.
Pal_file_open()
	Open file for reading or writing and associate file pointer with an initialised pal_fileio data structure. Mode may also be "m" for memory-mapped IO, which must be used if you intend to use Pal_file_read(), and must not be used if you intend to use Pal_file_write().
Pal_file_close()
	Close a previously opened file associated with a pal_fileio data structure.
Pal_file_write()
	Write id, header, bytecode and tables to a PROSE binary file that has already been opened using Pal_file_open().
Pal_file_writeid()
	Write file id to a PROSE binary file, at the current file position.
Pal_file_writeul()
	Write unsigned long to a PROSE binary file (big endian format) at the current file position, using the compressed algorithm provided by Pal_encode_ulong().
Pal_file_writecompile()
	Write compiler name and compile time to a PROSE binary file, at the current file position.
Pal_file_writevector()
	Write a vector to a PROSE binary file (only vector types VTYPE_UCHAR and VTYPE_ULONG are supported). See libIvor(3).
Pal_file_writetable()
	Write a string table to a PROSE binary file, at the current file position. See Pal_strtab_init().
Pal_file_read()
	Read a PROSE binary file into memory structures associated with an initialised pal_fileio data structure, the file to read has been opened using Pal_file_open() with the "m" mode.
Pal_file_free()
	Free all memory claimed during Pal_file_read() operations, only suitable when the file has been opened for reading using Pal_file_open() with the "m" mode. This is called by Pal_file_close().
Pal_istack_init()
	Initialises an instruction stack for first use, using a stack_root structure.
Pal_istack_free()
	Frees memory previously claimed by Pal_istack_init().
Pal_istack_opcode()
	Transforms an opcode into its bytecode representation, then pulls all instructions off the stack and writes to the end of a vector.
Pal_istack_register()
	Transforms a register into its bytecode representation and pushes this onto the instruction stack.
Pal_istack_index()
	Transforms a code label reference or text reference into its bytecode representation and pushes this onto the instruction stack. The label or text should have already been added to a string table, and the index number gained from that function call is passed in here to be pushed onto the instruction stack.
Pal_mem_open()
	Maps specified PROSE binary file into memory, and returns an initialised pal_memio structure.
Pal_mem_close()
	Unmaps a file previously mapped with Pal_mem_open() and frees memory associated with the pal_memio structure.
Pal_mem_checkid()
	Validates the header ID in a PROSE binary file and moves the pal_memio pointer beyond the ID. This function will only succeed if the pointer is located at the start of the mapped memory.
Pal_mem_getheader()
	Reads header data (compiler information) from a PROSE binary file, and moves the pal_memio pointer beyond the header data. This function will only succeed if the pointer is located at the start of the header data, i.e. following successful calls to Pal_mem_open() and Pal_mem_checkid().
Pal_mem_readul()
	Reads unsigned long integer from current position in mapped memory identified in the pal_memio structure, and decodes using Pal_decode_ulong(). This function is implemented as a macro if the library was compiled following a configure --enable-extradebug.
Pal_mem_readvector()
	Reads vector from current position in mapped memory identified in the pal_memio structure. This vector will have previously been written to a binary file using Pal_file_writevector(). Only vector types VTYPE_UCHAR and VTYPE_ULONG are supported. See libIvor(3).
Pal_mem_readtable()
	Reads table from current position in mapped memory identified in the pal_memio structure. This table will have previously been written to a binary file using Pal_file_writetable(). N.B. Pal_file_read() uses this function, while string tables in the compiler consist of hashes and indexes to maintain uniqueness, this function only reads strings into a vector. Therefore the pal_strtab_root structure will have a NULL htab, i.e. only vroot is used when reading a file back in.
Pal_init_errcodes()
	Initialise the error codes used by PAL associated functions. This uses Error_add(). See libIvor(3).
Pal_get_opcode()
	Translates PAL instruction into a pal_opcode_t number and returns the result.
Pal_get_opsym()
	Translates pal_opcode_t number into printable PAL instruction symbol, copying this into the supplied character array for no more than PAL_OPSYM_MAX bytes. The string will be null terminated if space allows.
Pal_get_regsym()
	Translates pal_reg_t number into printable PAL register symbol, copying this into the supplied character array for no more than PAL_REGSYM_MAX bytes. This string will be null terminated if space allows.
Pal_list_opcodes()
	Lists all known opcodes to the supplied output stream, these opcodes will have their appropriate flags set, so the codes will match exactly the bytes written to a PROSE binary file.
Pal_lexer()
	Initialises data structures and parses PAL input from named input file, generating bytecode to the specified output file. If the input file is called "stdin", standard input will be parsed instead of a file.
Pal_strtab_init()
	Claims memory and initialises a string table.
Pal_strtab_free()
	Frees memory previously claimed by a string table.
Pal_strtab_add()
	Adds new entry to string table generating an index number for this string. Use Pal_strtab_lookup() macro to lookup the string again using the index number.
Pal_view_file()
	Displays layout and information about a specified PROSE binary file.
Pal_view_vector()
	Displays information about a vector in a PROSE binary file, where the file is mapped into memory and the start of the vector (type byte) is pointed to by the pal_memio data structure.
Pal_view_table()
	Displays information about a string table in a PROSE binary file, where the file is mapped into memory and the start of the table is pointed to by the pal_memio data structure.

pal_opcode_t
	PAL instruction.
pal_reg_t
	Pointer register.
pal_strindex_t
	String table index.

pal_dsm_buffer
	A buffer used by the disassembly routines.
pal_fileio
	Structure containing file and table pointers used by assembly and disassembly routines.
pal_memio_header
	Header structure containing version, compiler and compile date information written to the header of a PROSE binary file.
pal_memio
	Root structure containing details of a file mapped into memory using Pal_mem_open() or Pal_file_open() using the "m" option.
pal_opcode
	Structure used for carrying both an opcode symbol and its value. The exported symbol pal_opcodes is a table containing all pal_opcode symbols and values known to the library.
pal_strtab_root
	Root structure of string table containing a hash and a vector.
pal_strtab_data
	Structure encapsulating the data items added by a string table onto a hash.

Pal_dsm_testbuf()
	Test to see if any data remains in the disassembly buffer.
Pal_file_size()
	Return size of currently open PROSE binary file. For a file that has been opened for reading, this will always return a fixed size. For a file that has been opened for writing, the returned value will grow as more data is written as long as libpal APIs are used to write to the file.
Pal_mem_filename()
	Return pointer to name of file referenced by pal_memio data structure.
Pal_mem_filesize()
	Return size of file referenced by pal_memio data structure.
Pal_mem_version()
	Return indexed compiler version byte (1 of 3 bytes) for file referenced by pal_memio data structure.
Pal_mem_compiler()
	Return pointer to name of compiler for file referenced by pal_memio data structure.
Pal_mem_compiled()
	Return compilation time of file referenced by pal_memio data structure.
Pal_mem_ptr()
	Return pointer to first byte of file referenced by pal_memio data structure.
Pal_mem_pos()
	Return position of current pointer within file referenced by pal_memio data structure.
Pal_mem_lookup()
	Return byte at current pointer position within file referenced by pal_memio data structure.
PAL_MEM_CHECK()
	Check that an amount of memory can be successfully read from the specified pal_memio data structure (i.e. would not require a read beyond the end of the mapped memory space) - if this validation fails the macro returns from the calling function with errno set as specified.
Pal_mem_readul()
	Performs same functionality as the function of the same name. Defined as a macro for speed if the library was compiled following a configure --enable-extradebug.
Pal_strtab_lookup()
	Lookup string with given table pointer and index number.
Pal_strtab_size()
	Return number of strings in table.
Pal_strtab_test()
	Test if given table pointer and index number exists.
Pal_strtab_settype()
	Set table type to one of STRTAB_TYPE_UNIQUE or STRTAB_TYPE_FORCEUNIQUE.

PAL_FILE_ID
	PROSE binary file identifier.
PAL_FILE_MARK_END
	Marks the end of a PROSE binary file.
PAL_FILE_MARK_ICODE
	Marks the beginning of instruction code in a PROSE binary file.
PAL_FILE_MARK_LABROOT
	Marks the beginning of the table of code labels in a PROSE binary file.
PAL_FILE_MARK_PTRROOT
	Marks the beginning of the address table in a PROSE binary file.
PAL_FILE_MARK_TEXROOT
	Marks the beginning of the user string table in a PROSE binary file.
PAL_FILE_MINSIZE
	A file containing less than this number of bytes is not a valid PROSE binary file.
ISTACK_TYPE
	Instruction stack type used in a call to Stack_init(). An instruction stack is type STYPE_UCHAR.See libIvor(3).
ISTACK_SIZE
	Initial size of instruction stack.
ISTACK_GROW
	Grow factor for instruction stack.
PAL_IDESC_FLAG
	Flags an index descriptor byte (logical OR).
PAL_IDESCTYPE_MASK
	Masks out all but the string table identifier, removing PAL_IDESC_FLAG and the number of bytes in the index (logical AND).
PAL_IDESCSIZE_MASK
	Masks out all but the size of the string table index, removing PAL_IDESC_FLAG and the string table identifier (logical AND).
PAL_IDESCTYPE_NONE
	Return value used to indicate an invalid index number.
PAL_IDESCTYPE_LABEL
	String table identifier number indicating a table for code labels.
PAL_IDESCTYPE_TEXT
	String table identifier number indicating a table for arbitrary text.
PAL_OPCODE_FLAG
	Flags a byte containing an opcode (logical OR).
PAL_OPCODE_MASK
	Masks out all but the opcode value, removing PAL_OPCODE_FLAG from the byte (logical AND).
PAL_OPCODE_ERROR
	Return value used to indicate an opcode not found.
PAL_OPSYM_MAX
	Maximum length of an instruction symbol.
PAL_REG_FLAG
	Flags a byte containing a register (logical OR).
PAL_REG_MASK
	Masks out all but the register value, removing PAL_REG_FLAG from the byte (logical AND).
PAL_REGSYM_MAX
	Maximum length of a register symbol.
PAL_REG_MAX
	Total number of permitted registers.
PAL_REG_CODE_NULL
	NULL special register code.
PAL_REG_CODE_PUSH
	PUSH special register code.
PAL_REG_CODE_PULL
	PULL special register code.
PAL_REG_CODE_PEEK
	PEEK special register code.
PAL_MAX_STRTAB
	A string table cannot support more strings than this.
STRTAB_TYPE_UNIQUE
	String table based on type HTYPE_UNIQUE. See libIvor(3).
STRTAB_TYPE_FORCEUNIQUE
	String table based on type HTYPE_FORCEUNIQUE. See libIvor(3).

E_PAL_INSTRUCTION_UNKNOWN
	Unknown instruction.
E_PAL_OPCODE_UNKNOWN
	Unknown opcode.
E_PAL_REGCODE_UNKNOWN
	Unknown register code.
E_PAL_SI_OVERFLOW
	String index overflow.
E_PAL_STRTAB_NOSPACE
	No space left in string table.
E_PAL_INCOMPLETE_BYTECODE
	Incomplete bytecode.
E_PAL_INVALID_FILE
	Invalid bytecode.
E_PAL_ARCH_TOO_BIG
	Address too big for this architecture.
E_PAL_TOO_BIG
	Value too big.

libpal.so.

prism(1),
libIvor(3),
PROSE Programming Language at prose.sourceforge.net,
GNU Automake & Autoconf at www.gnu.org.

Copyright (c) 2002, 2003, 2004 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.