ftp.nice.ch/pub/next/unix/developer/pcn.2.0.s.tar.gz#/src/pcno/pcno.h

This is pcno.h in view mode; [Download] [Up]

/*
 * PCN System -- PCN Object file access routines
 * Author:      Steve Tuecke
 *              Argonne National Laboratory
 *
 * Please see the DISCLAIMER file in the top level directory of the
 * distribution regarding the provisions under which this software
 * is distributed.
 *
 * pcno.h
 *
 * This contains header information for the PCN Object (PCN-O) file
 * format.
 *
 * The internal PCN-O format is described in pcno.pcn.
 *
 * This header can be included in either C or PCN programs.
 *
 * It contains the C structure declarations of parts of the PCN-O file,
 * as well as all PCN-O related #defines used by both C and PCN code.
 *
 * See the pcno.pcn modules for more information on the accessing
 * PCN-O files from PCN.
 *
 * A few general comments regarding the external PCN-O file format:
 *   - All integer values in the various structures are always stored
 *	in big endian format on disk.  If a machine uses little
 *	endian, then it needs to do conversion as it reads the
 * 	PCN-O file in.
 *   - The "u_int_t" type is assumed to be 32 bits.
 *   - Unless otherwised stated, all sizes and offsets are
 *	in bytes, and must be padded out to word (4 byte)
 *	bounderies.
 *   - All sizes in the various block headers described below
 *	include the size of the header.
 *
 * A few general comments regarding the internal PCN-O structure:
 *   - The internal PCN-O structure is just nested tuples, where
 *	the first tuple argument gives enough information to
 *	uniquely identify that tuple level.  For example, if
 *	the first tuple argument is PCNO_LAZY_DATA, this signifies
 *	this tuple level must be retrieved explicitly.  And all
 *	other possible identifiers must be unique with respect
 *	to PCNO_LAZY_DATA and to other identifiers.
 */

#ifndef _PCN_INCLUDE_PCNO_H
#define _PCN_INCLUDE_PCNO_H

#include "pcn_types.h"
#ifndef PCN
#include "pcn_structs.h"
#endif

/*
 * It is assumed that all words in the PCN-O files (u_int_t) are
 * 4 bytes, and that all integers are big endian.  If this is
 * not true, then you need to do conversions when reading words
 * from the PCN-O file into the C structures defined below.
 */
#define PCNO_WORD_SIZE	4

#ifndef TRUE
#define TRUE 1
#define FALSE 0
#endif

/*
 * A PCN-O file contains a header followed by zero or more segments.
 * The header has the following format.
 */
#ifndef PCN
typedef struct pcno_header_struct
{
    u_int_t		magic;		/* PCN-O magic number */
    u_int_t		size;		/* The file's size (with header) */
    u_int_t		n_segments;	/* The number of segments */
    u_int_t		version;	/* PCN-O version number */
} pcno_header_t;
#endif

#define PCNO_HEADER_SIZE		4

#define PCNO_MAGIC	42424242	/* The PCN-O magic number */
#define PCNO_VERSION	3		/* The PCN-O version number */

/*
 * All segments, sections and subsections described below (we'll call
 * them all "blocks") have a standard header format.  All block
 * specific header information comes after this basic header.
 */
#ifndef PCN
typedef struct pcno_block_header_struct
{
    u_int_t		type;		/* This block's type */
    u_int_t		size;		/* This block's size, including
					 * this header */
} pcno_block_header_t;
#endif

#define PCNO_BLOCK_HDR_SIZE		2


/*
 * A block with a list of strings is used in several places in
 * the PCN-O format -- PCN call table and foreign call table, for example.
 * Sometimes these strings are meant to be used in groups.  The
 * 'group_size' fields tells the intended grouping size.
 *
 * These string list blocks have the following format:
 */
#ifndef PCN
typedef struct pcno_string_list_struct
{
    u_int_t		type;		/* The section type */
    u_int_t		size;		/* The section size */
    u_int_t		n_entries;	/* Number of strings */
    u_int_t		group_size;	/* Grouping size of strings */
} pcno_string_list_t;
#endif

#define PCNO_STRING_LIST_HDR_SIZE	4

/*
 * After the header comes a series of 'n_entries' entries, each
 * with the following form.
 *
 * Note: The 'size' fields does NOT include itself.  It is only
 * the size (in bytes) of the entry itself.
 */
#ifndef PCN    
typedef struct pcno_string_struct
{
    u_int_t		size;		/* Size of this entry */
    char_t		*entry;		/* The exported procedure name */
} pcno_string_t;
#endif



/*
 * Each segment must be one of the following types.
 */
#define PCNO_SEG_MODULE	1		/* A module segment */
#define PCNO_SEG_NAMED	2		/* An arbitrary named segment */

/*
 * A named segment (PCNO_SEG_NAMED) has the following header.
 */
#ifndef PCN
typedef struct pcno_named_segment_struct
{
    u_int_t		type;		/* The segment type */
    u_int_t		size;		/* The segment size */
    u_int_t		data_offset;	/* Offset to data */
    u_int_t		data_size;	/* Size of the data */
    char_t		*name;		/* Name of segment */
} pcno_named_segment_t;
#endif

#define PCNO_SEG_NAMED_HDR_SIZE		4

/*
 * A module segment (PCNO_SEG_MODULE) consists of the a header
 * followed by zero or more module sections (each beginning with the
 * usual block header, pcno_block_header_t).
 *
 * A module segment has the following header.
 */
#ifndef PCN
typedef struct pcno_module_segment_struct
{
    u_int_t		type;		/* The segment type */
    u_int_t		size;		/* The segment size */
    u_int_t		n_sections;	/* Number of sections in module */
    u_int_t		section_offset;	/* Offset (from start of header)
					 * to first section. */
    char_t		*name;		/* The module's name */
} pcno_module_segment_t;
#endif

#define PCNO_SEG_MODULE_HDR_SIZE	4


/*    
 * Valid module section types are:
 */
#define PCNO_MODSECT_PROCEDURE	101	/* A procedure section */
#define PCNO_MODSECT_METACALLS	201	/* A metacalls table section */


/*
 * A procedure section (PCNO_MODSECT_PROCEDURE) contains a header
 * followed by 1 or more subsections.  The procedure header has the
 * structure:
 */
#ifndef PCN
typedef struct pcno_procedure_struct
{
    u_int_t		type;		/* The segment type */
    u_int_t		size;		/* The segment size */
    u_int_t		n_subsects;	/* Number of subsections */
    u_int_t		subsect_offset;	/* Offset (from start of header)
					 * to first subsection. */
    u_int_t		exported;	/* Is the procedure exported? */
    u_int_t		n_counters;	/* Number of counter */
    u_int_t		n_timers;	/* Number of timers */
    u_int_t		arity;		/* The procedure's arity */
    char_t		*name;		/* Procedure name */
} pcno_procedure_t;
#endif

#define PCNO_MODSECT_PROCEDURE_HDR_SIZE	8

/*
 * The valid values for 'exported' is 0 (for FALSE) and 1 (for TRUE).
 */


/*
 * The valid procedure subsections types are:
 */
#define PCNO_PROC_CODE			10101	/* Code */
#define PCNO_PROC_PCALL_TABLE		20101	/* PCN call table */
#define PCNO_PROC_METACALL_TABLE	30101	/* Metacall table */
#define PCNO_PROC_FCALL_TABLE		40101	/* Foreign call table */
#define	PCNO_PROC_DOUBLE_TABLE		50101	/* Double constant table */
#define	PCNO_PROC_STRING_TABLE		60101	/* String constant table */
#define	PCNO_PROC_INT_TABLE		70101	/* Integer constant table */
#define	PCNO_PROC_MODEL			80101	/* Gauge model */


/*
 * The procedure's code subsection (PCNO_PROC_CODE)
 * contains a header followed by an array of u_int_t's which
 * represent the PCN Abstract Machine code.
 */
#ifndef PCN
typedef struct pcno_code_struct
{
    u_int_t		type;		/* The section type */
    u_int_t		size;		/* The section size */
    u_int_t    		code_size;	/* The code's size (in chars) */
    code_t		*code_array;	/* The procedure's code */
} pcno_code_t;
#endif

#define PCNO_PROC_CODE_HDR_SIZE		3

/*
 * The procedure's PCN call table subsection (PCNO_PROC_PCALL_TABLE)
 * is a string list block.  It is assumed that the strings
 * will always occur in pairs (group_size = 2), and
 * represent <module_name,procedure_name>
 * pairs.  A module_name of "" (the empty string) means that it
 * is a call within the module.
 */
#ifndef PCN
typedef pcno_string_list_t	pcno_pcall_table_t;
typedef pcno_string_t		pcno_pcall_t;
#endif


/*
 * The procedure's foreign call table subsection (PCNO_PROC_FCALL_TABLE)
 * is a string list block, where the strings are the names of
 * foreign procedures.  (group_size = 1)
 */
#ifndef PCN
typedef pcno_string_list_t	pcno_fcall_table_t;
typedef pcno_string_t		pcno_fcall_t;
#endif


/*
 * The procedure's double constant table subsection (PCNO_PROC_DOUBLE_TABLE)
 * is a string list block, where the strings are the ascii
 * representation of the double constants. (group_size = 1)
 */
#ifndef PCN
typedef pcno_string_list_t	pcno_double_table_t;
typedef pcno_string_t		pcno_double_t;
#endif


/*
 * The procedure's string constant table subsection (PCNO_PROC_STRING_TABLE)
 * is a string list block, where the strings are the ascii
 * representation of the string constants. (group_size = 1)
 */
#ifndef PCN
typedef pcno_string_list_t	pcno_string_table_t;
#endif


/*
 * The procedure's integer constant table subsection (PCNO_PROC_INT_TABLE)
 * is a string list block, where the strings are the ascii
 * representation of the integer constants. (group_size = 1)
 */
#ifndef PCN
typedef pcno_string_list_t	pcno_int_table_t;
typedef pcno_string_t		pcno_int_t;
#endif


/*
 * The procedure's Gauge model subsection (PCNO_PROC_MODEL)
 * is a string list block, where the strings are the ascii
 * representation of parts of the model. (group_size = 1)
 */
#ifndef PCN
typedef pcno_string_list_t	pcno_model_t;
typedef pcno_string_t		pcno_model_entry_t;
#endif


/*
 * The procedure's metacall list (PCNO_PROC_METACALLS), or
 * a modules metacall list (PCNO_MODSECT_METACALLS),
 * is a string list block.  The meta call list is a list
 * of all procedures that might be the target of metacalls
 * from this procedure, and therefore must be linked into
 * the final executable if this procedure is linked in.
 * It is assumed that the strings
 * will always occur in pairs (group_size = 2), and
 * represent <module_name,procedure_name>
 * pairs.  A module_name of "" (the empty string) means that
 * the meta call target is in the module.
 */
#ifndef PCN
typedef pcno_string_list_t	pcno_metacall_list_t;
typedef pcno_string_t		pcno_metacall_t;
#endif



/*
 * PCNO_COMPUTE
 *
 * When writing a block that contains a size or number
 * of entries field, PCNO_COMPUTE can be put into this
 * field to tell the system to compute the correct value
 * for this field and to fill it in automatically.
 */
#define PCNO_COMPUTE		-1


/*
 * PCNO_STRUCTURE
 *
 * This is the identifier for the entire internal
 * PCN-O structure.  The sub-tuples contain the
 * PCN-O file information.
 */
#define PCNO_STRUCTURE			11


/*
 * PCNO_BLOCK_HEADER
 *
 * Each tuple of the internal PCN-O structure contains
 * a block type (identifier) and a block header.  The
 * block header is a tuple that has an identifier
 * of PCNO_BLOCK_HEADER.
 */
#define PCNO_BLOCK_HEADER		12


/*
 * PCNO_LAZY_DATA
 *
 * The pcno access module retrieves data from the PCN-O file
 * in a lazy manner.  Only enough data is read in to differentiate
 * the block types.  The rest of the blocks are just "pointed to",
 * and must be explicitly retrieved.  PCNO_LAZY_DATA is used
 * to differentiate these "pointers" from the real data.  So it
 * must be unique with respect to all of the PCN-O block types.
 */
#define PCNO_LAZY_DATA			21

/*
 * Other defines used to identify lazy blocks
 */
#define PCNO_LAZY_SEGMENTS		121
#define PCNO_LAZY_MODULE_SECTIONS	221
#define PCNO_LAZY_PROC_SUBSECTS		321
#define PCNO_LAZY_CODE_ARRAY		421
#define PCNO_LAZY_LIST_ENTRIES		521
#define PCNO_LAZY_NAMED_DATA		621

#define PCNO_DATA			22

/*
 * PCNO_RETRIEVE_DATA
 * PCNO_DISCARD_DATA
 *
 * These definitions are used to communicate the type
 * of operation from retrieve_lazy_data() or discard_lazy_data()
 * to the lazy_data_handler.
 */
#define PCNO_RETRIEVE_DATA		31
#define PCNO_DISCARD_DATA		32

/*
 * PCNO_OK
 *
 * This is used when a status needs to be returned by a procedure
 * that does not return a pcno data structure.  For example,
 * discard_lazy_data() returns this if everything goes ok.
 */
#define PCNO_OK				0


/*
 * PCNO_ERROR
 *
 * When a read or retrieve error occurs in the pcno access routines,
 * this is used to differentiate the error from the real data.  So it
 * must be unique with respect to all of the PCN-O block types.
 */
#define PCNO_ERROR			99


/*
 * PCNO_ERROR_*
 *
 * Error codes and strings used by the pcno access routines.
 */
#define PCNO_ERROR_READ_OPEN		1
#define PCNO_ERROR_READ_OPEN_STRING	"Cannot open file for reading"
#define PCNO_ERROR_READ			2
#define PCNO_ERROR_READ_STRING		"Error while reading PCN-O file"
#define PCNO_ERROR_READ_STRUCTURE	3
#define PCNO_ERROR_READ_STRUCTURE_STRING	"Error in external PCN-O file format encountered during reading"

#define PCNO_ERROR_LAZY_TYPE		51
#define PCNO_ERROR_LAZY_TYPE_STRING	"Illegal lazy data block type passed to pcno:do_lazy_retrieve()"

#define PCNO_ERROR_WRITE_OPEN		101
#define PCNO_ERROR_WRITE_OPEN_STRING	"Cannot open file for writing"
#define PCNO_ERROR_WRITE_STRUCTURE	102
#define PCNO_ERROR_WRITE_STRUCTURE_STRING	"Error in internal PCN-O structure encountered during writing"
#define PCNO_ERROR_WRITE		103
#define PCNO_ERROR_WRITE_STRING		"Error while writing PCN-O file"


/*
 * Some debugging stuff
 */
#ifndef PCNO_DEBUG
#define PCNO_DEBUG 1
#endif 


#endif /* _PCN_INCLUDE_PCNO_H */

These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Marcel Waldvogel and Netfuture.ch.