YASM bytecode interface. More...

Data Structures
struct	yasm_bytecode_callback
	Bytecode callback structure. More...

struct	yasm_bytecode
	A bytecode. More...

Macros
#define	YASM_LIB_DECL

#define	yasm_bc__next(bc) STAILQ_NEXT(bc, link)
	Get the next bytecode in a linked list of bytecodes. More...

Typedefs
typedef struct yasm_dataval	yasm_dataval
	A data value (opaque type). More...

typedef struct yasm_datavalhead	yasm_datavalhead
	A list of data values. More...

typedef void(*	yasm_bc_add_span_func )(void add_span_data, yasm_bytecode bc, int id, const yasm_value *value, long neg_thres, long pos_thres)
	Add a dependent span for a bytecode. More...

typedef struct yasm_bytecode_callback	yasm_bytecode_callback
	Bytecode callback structure. More...

Functions
	STAILQ_HEAD (yasm_datavalhead, yasm_dataval)
	Linked list of data values. More...

YASM_LIB_DECL yasm_bytecode *	yasm_bc_create_common (const yasm_bytecode_callback callback, void contents, unsigned long line)
	Create a bytecode of any specified type. More...

YASM_LIB_DECL void	yasm_bc_transform (yasm_bytecode bc, const yasm_bytecode_callback callback, void *contents)
	Transform a bytecode of any type into a different type. More...

YASM_LIB_DECL void	yasm_bc_finalize_common (yasm_bytecode bc, yasm_bytecode prev_bc)
	Common bytecode callback finalize function, for where no finalization is ever required for this type of bytecode.

YASM_LIB_DECL int	yasm_bc_calc_len_common (yasm_bytecode bc, yasm_bc_add_span_func add_span, void add_span_data)
	Common bytecode callback calc_len function, for where the bytecode has no calculatable length. More...

YASM_LIB_DECL int	yasm_bc_expand_common (yasm_bytecode bc, int span, long old_val, long new_val, long neg_thres, long *pos_thres)
	Common bytecode callback expand function, for where the bytecode is always short (calc_len never calls add_span). More...

YASM_LIB_DECL int	yasm_bc_tobytes_common (yasm_bytecode bc, unsigned char bufp, unsigned char bufstart, void *d, yasm_output_value_func output_value, yasm_output_reloc_func output_reloc)
	Common bytecode callback tobytes function, for where the bytecode cannot be converted to bytes. More...

YASM_LIB_DECL void	yasm_bc_set_multiple (yasm_bytecode bc, yasm_expr e)
	Set multiple field of a bytecode. More...

YASM_LIB_DECL yasm_bytecode *	yasm_bc_create_data (yasm_datavalhead datahead, unsigned int size, int append_zero, yasm_arch arch, unsigned long line)
	Create a bytecode containing data value(s). More...

YASM_LIB_DECL yasm_bytecode *	yasm_bc_create_leb128 (yasm_datavalhead *datahead, int sign, unsigned long line)
	Create a bytecode containing LEB128-encoded data value(s). More...

YASM_LIB_DECL yasm_bytecode *	yasm_bc_create_reserve (yasm_expr *numitems, unsigned int itemsize, unsigned long line)
	Create a bytecode reserving space. More...

YASM_LIB_DECL const yasm_expr *	yasm_bc_reserve_numitems (yasm_bytecode bc, unsigned int itemsize)
	Get the number of items and itemsize for a reserve bytecode. More...

YASM_LIB_DECL yasm_bytecode *	yasm_bc_create_incbin (char filename, yasm_expr start, yasm_expr maxlen, yasm_linemap linemap, unsigned long line)
	Create a bytecode that includes a binary file verbatim. More...

YASM_LIB_DECL yasm_bytecode *	yasm_bc_create_align (yasm_expr boundary, yasm_expr fill, yasm_expr maxskip, const unsigned char *code_fill, unsigned long line)
	Create a bytecode that aligns the following bytecode to a boundary. More...

YASM_LIB_DECL yasm_bytecode *	yasm_bc_create_org (unsigned long start, unsigned long fill, unsigned long line)
	Create a bytecode that puts the following bytecode at a fixed section offset. More...

YASM_LIB_DECL yasm_section *	yasm_bc_get_section (yasm_bytecode *bc)
	Get the section that contains a particular bytecode. More...

YASM_LIB_DECL void	yasm_bc__add_symrec (yasm_bytecode bc, yasm_symrec sym)
	Add to the list of symrecs that reference a bytecode. More...

YASM_LIB_DECL void	yasm_bc_destroy (yasm_bytecode *bc)
	Delete (free allocated memory for) a bytecode. More...

YASM_LIB_DECL void	yasm_bc_print (const yasm_bytecode bc, FILE f, int indent_level)
	Print a bytecode. More...

YASM_LIB_DECL void	yasm_bc_finalize (yasm_bytecode bc, yasm_bytecode prev_bc)
	Finalize a bytecode after parsing. More...

YASM_LIB_DECL yasm_intnum *	yasm_calc_bc_dist (yasm_bytecode precbc1, yasm_bytecode precbc2)
	Determine the distance between the starting offsets of two bytecodes. More...

YASM_LIB_DECL unsigned long	yasm_bc_next_offset (yasm_bytecode *precbc)
	Get the offset of the next bytecode (the next bytecode doesn't have to actually exist). More...

YASM_LIB_DECL int	yasm_bc_elem_size (yasm_bytecode *bc)
	Return elemens size of a data bytecode. More...

YASM_LIB_DECL int	yasm_bc_calc_len (yasm_bytecode bc, yasm_bc_add_span_func add_span, void add_span_data)
	Resolve EQUs in a bytecode and calculate its minimum size. More...

YASM_LIB_DECL int	yasm_bc_expand (yasm_bytecode bc, int span, long old_val, long new_val, long neg_thres, long *pos_thres)
	Recalculate a bytecode's length based on an expanded span length. More...

YASM_LIB_DECL unsigned char *	yasm_bc_tobytes (yasm_bytecode bc, unsigned char buf, unsigned long bufsize, int gap, void *d, yasm_output_value_func output_value, yasm_output_reloc_func output_reloc)
	Convert a bytecode into its byte representation. More...

YASM_LIB_DECL int	yasm_bc_get_multiple (yasm_bytecode bc, long multiple, int calc_bc_dist)
	Get the bytecode multiple value as an integer. More...

YASM_LIB_DECL const yasm_expr *	yasm_bc_get_multiple_expr (const yasm_bytecode *bc)
	Get the bytecode multiple value as an expression. More...

YASM_LIB_DECL yasm_insn *	yasm_bc_get_insn (yasm_bytecode *bc)
	Get a yasm_insn structure from an instruction bytecode (if possible). More...

YASM_LIB_DECL yasm_dataval *	yasm_dv_create_expr (yasm_expr *expn)
	Create a new data value from an expression. More...

YASM_LIB_DECL yasm_dataval *	yasm_dv_create_string (char *contents, size_t len)
	Create a new data value from a string. More...

YASM_LIB_DECL yasm_dataval *	yasm_dv_create_raw (unsigned char *contents, unsigned long len)
	Create a new data value from raw bytes data. More...

YASM_LIB_DECL yasm_dataval *	yasm_dv_create_reserve (void)
	Create a new uninitialized data value. More...

YASM_LIB_DECL yasm_value *	yasm_dv_get_value (yasm_dataval *dv)
	Get the underlying value of a data value. More...

YASM_LIB_DECL void	yasm_dv_set_multiple (yasm_dataval dv, yasm_expr e)
	Set multiple field of a data value. More...

YASM_LIB_DECL int	yasm_dv_get_multiple (yasm_dataval dv, unsigned long multiple)
	Get the data value multiple value as an unsigned long integer. More...

void	yasm_dvs_initialize (yasm_datavalhead *headp)
	Initialize a list of data values. More...

YASM_LIB_DECL void	yasm_dvs_delete (yasm_datavalhead *headp)
	Delete (free allocated memory for) a list of data values. More...

YASM_LIB_DECL yasm_dataval *	yasm_dvs_append (yasm_datavalhead headp, yasm_dataval dv)
	Add data value to the end of a list of data values. More...

YASM_LIB_DECL void	yasm_dvs_print (const yasm_datavalhead headp, FILE f, int indent_level)
	Print a data value list. More...

Detailed Description

YASM bytecode interface.

Definition in file bytecode.h.

Macro Definition Documentation

#define yasm_bc__next ( bc ) STAILQ_NEXT(bc, link)

Get the next bytecode in a linked list of bytecodes.

Parameters

bc bytecode

Returns: Next bytecode.

Definition at line 287 of file bytecode.h.

Typedef Documentation

typedef void(* yasm_bc_add_span_func)(void *add_span_data, yasm_bytecode *bc, int id, const yasm_value *value, long neg_thres, long pos_thres)

Add a dependent span for a bytecode.

Parameters

add_span_data	add_span_data passed into bc_calc_len()
bc	bytecode containing span
id	non-zero identifier for span; may be any non-zero value if <0, expand is called for any change; if >0, expand is only called when exceeds threshold
value	dependent value for bytecode expansion
neg_thres	negative threshold for long/short decision
pos_thres	positive threshold for long/short decision

Definition at line 56 of file bytecode.h.

typedef struct yasm_bytecode_callback yasm_bytecode_callback

Bytecode callback structure.

Any implementation of a specific bytecode must implement these functions and this callback structure. The bytecode implementation-specific data is stored in yasm_bytecode.contents.

typedef struct yasm_dataval yasm_dataval

A data value (opaque type).

Definition at line 38 of file bytecode.h.

typedef struct yasm_datavalhead yasm_datavalhead

A list of data values.

Definition at line 40 of file bytecode.h.

Function Documentation

STAILQ_HEAD	(	yasm_datavalhead	,
		yasm_dataval
	)

Linked list of data values.

YASM_LIB_DECL void yasm_bc__add_symrec	(	yasm_bytecode *	bc,
		yasm_symrec *	sym
	)

Add to the list of symrecs that reference a bytecode.

For symrec use only.

Parameters

bc	bytecode
sym	symbol

YASM_LIB_DECL int yasm_bc_calc_len	(	yasm_bytecode *	bc,
		yasm_bc_add_span_func	add_span,
		void *	add_span_data
	)

Resolve EQUs in a bytecode and calculate its minimum size.

Generates dependent bytecode spans for cases where, if the length spanned increases, it could cause the bytecode size to increase. Any bytecode multiple is NOT included in the length or spans generation; this must be handled at a higher level.

Parameters

bc	bytecode
add_span	function to call to add a span
add_span_data	extra data to be passed to add_span function

Returns: 0 if no error occurred, nonzero if there was an error recognized (and output) during execution.

Note: May store to bytecode updated expressions and the short length.

YASM_LIB_DECL int yasm_bc_calc_len_common	(	yasm_bytecode *	bc,
		yasm_bc_add_span_func	add_span,
		void *	add_span_data
	)

Common bytecode callback calc_len function, for where the bytecode has no calculatable length.

Causes an internal error if called.

YASM_LIB_DECL yasm_bytecode* yasm_bc_create_align	(	yasm_expr *	boundary,
		yasm_expr *	fill,
		yasm_expr *	maxskip,
		const unsigned char **	code_fill,
		unsigned long	line
	)

Create a bytecode that aligns the following bytecode to a boundary.

Parameters

boundary	byte alignment (must be a power of two)
fill	fill data (if NULL, code_fill or 0 is used)
maxskip	maximum number of bytes to skip
code_fill	code fill data (if NULL, 0 is used)
line	virtual line (from yasm_linemap)

Returns: Newly allocated bytecode.

Note

The precedence on generated fill is as follows:

from fill parameter (if not NULL)
from code_fill parameter (if not NULL)
0

YASM_LIB_DECL yasm_bytecode* yasm_bc_create_common	(	const yasm_bytecode_callback *	callback,
		void *	contents,
		unsigned long	line
	)

Create a bytecode of any specified type.

Parameters

callback	bytecode callback functions, if NULL, creates empty bytecode (may not be resolved or output)
contents	type-specific data
line	virtual line (from yasm_linemap)

Returns: Newly allocated bytecode of the specified type.

YASM_LIB_DECL yasm_bytecode* yasm_bc_create_data	(	yasm_datavalhead *	datahead,
		unsigned int	size,
		int	append_zero,
		yasm_arch *	arch,
		unsigned long	line
	)

Create a bytecode containing data value(s).

Parameters

datahead	list of data values (kept, do not free)
size	storage size (in bytes) for each data value
append_zero	append a single zero byte after each data value (if non-zero)
arch	architecture (optional); if provided, data items are directly simplified to bytes if possible
line	virtual line (from yasm_linemap)

Returns: Newly allocated bytecode.

YASM_LIB_DECL yasm_bytecode* yasm_bc_create_incbin	(	char *	filename,
		yasm_expr *	start,
		yasm_expr *	maxlen,
		yasm_linemap *	linemap,
		unsigned long	line
	)

Create a bytecode that includes a binary file verbatim.

Parameters

filename	path to binary file (kept, do not free)
start	starting location in file (in bytes) to read data from (kept, do not free); may be NULL to indicate 0
maxlen	maximum number of bytes to read from the file (kept, do do not free); may be NULL to indicate no maximum
linemap	line mapping repository
line	virtual line (from yasm_linemap) for the bytecode

Returns: Newly allocated bytecode.

YASM_LIB_DECL yasm_bytecode* yasm_bc_create_leb128	(	yasm_datavalhead *	datahead,
		int	sign,
		unsigned long	line
	)

Create a bytecode containing LEB128-encoded data value(s).

Parameters

datahead	list of data values (kept, do not free)
sign	signedness (1=signed, 0=unsigned) of each data value
line	virtual line (from yasm_linemap)

Returns: Newly allocated bytecode.

YASM_LIB_DECL yasm_bytecode* yasm_bc_create_org	(	unsigned long	start,
		unsigned long	fill,
		unsigned long	line
	)

Create a bytecode that puts the following bytecode at a fixed section offset.

Parameters

start	section offset of following bytecode
fill	fill value
line	virtual line (from yasm_linemap)

Returns: Newly allocated bytecode.

YASM_LIB_DECL yasm_bytecode* yasm_bc_create_reserve	(	yasm_expr *	numitems,
		unsigned int	itemsize,
		unsigned long	line
	)

Create a bytecode reserving space.

Parameters

numitems	number of reserve "items" (kept, do not free)
itemsize	reserved size (in bytes) for each item
line	virtual line (from yasm_linemap)

Returns: Newly allocated bytecode.

YASM_LIB_DECL void yasm_bc_destroy ( yasm_bytecode * bc )

Delete (free allocated memory for) a bytecode.

Parameters

bc	bytecode (only pointer to it); may be NULL

YASM_LIB_DECL int yasm_bc_elem_size ( yasm_bytecode * bc )

Return elemens size of a data bytecode.

Returns the size of each elements of a data bytecode, for proper dereference of symbols attached to it.

Parameters

bc bytecode

Returns: 0 if element size is unknown

YASM_LIB_DECL int yasm_bc_expand	(	yasm_bytecode *	bc,
		int	span,
		long	old_val,
		long	new_val,
		long *	neg_thres,
		long *	pos_thres
	)

Recalculate a bytecode's length based on an expanded span length.

Parameters

bc	bytecode
span	span ID (as given to yasm_bc_add_span_func in yasm_bc_calc_len)
old_val	previous span value
new_val	new span value
neg_thres	negative threshold for long/short decision (returned)
pos_thres	positive threshold for long/short decision (returned)

Returns: 0 if bc no longer dependent on this span's length, negative if there was an error recognized (and output) during execution, and positive if bc size may increase for this span further based on the new negative and positive thresholds returned.

Note: May store to bytecode updated expressions and the updated length.

YASM_LIB_DECL int yasm_bc_expand_common	(	yasm_bytecode *	bc,
		int	span,
		long	old_val,
		long	new_val,
		long *	neg_thres,
		long *	pos_thres
	)

Common bytecode callback expand function, for where the bytecode is always short (calc_len never calls add_span).

Causes an internal error if called.

YASM_LIB_DECL void yasm_bc_finalize	(	yasm_bytecode *	bc,
		yasm_bytecode *	prev_bc
	)

Finalize a bytecode after parsing.

Parameters

bc	bytecode
prev_bc	bytecode directly preceding bc in a list of bytecodes

YASM_LIB_DECL yasm_insn* yasm_bc_get_insn ( yasm_bytecode * bc )

Get a yasm_insn structure from an instruction bytecode (if possible).

Parameters

bc bytecode

Returns: Instruction details if bytecode is an instruction bytecode, otherwise NULL.

YASM_LIB_DECL int yasm_bc_get_multiple	(	yasm_bytecode *	bc,
		long *	multiple,
		int	calc_bc_dist
	)

Get the bytecode multiple value as an integer.

Parameters

bc	bytecode
multiple	multiple value (output)
calc_bc_dist	nonzero if distances between bytecodes should be calculated, 0 if error should be returned in this case

Returns: 1 on error (set with yasm_error_set), 0 on success.

YASM_LIB_DECL const yasm_expr* yasm_bc_get_multiple_expr ( const yasm_bytecode * bc )

Get the bytecode multiple value as an expression.

Parameters

bc bytecode

Returns: Bytecode multiple, NULL if =1.

YASM_LIB_DECL yasm_section* yasm_bc_get_section ( yasm_bytecode * bc )

Get the section that contains a particular bytecode.

Parameters

bc bytecode

Returns: Section containing bc (can be NULL if bytecode is not part of a section).

YASM_LIB_DECL unsigned long yasm_bc_next_offset ( yasm_bytecode * precbc )

Get the offset of the next bytecode (the next bytecode doesn't have to actually exist).

Parameters

precbc preceding bytecode

Returns: Offset of the next bytecode in bytes.

Warning: Only valid /after/ optimization.

YASM_LIB_DECL void yasm_bc_print	(	const yasm_bytecode *	bc,
		FILE *	f,
		int	indent_level
	)

Print a bytecode.

For debugging purposes.

Parameters

f	file
indent_level	indentation level
bc	bytecode

YASM_LIB_DECL const yasm_expr* yasm_bc_reserve_numitems	(	yasm_bytecode *	bc,
		unsigned int *	itemsize
	)

Get the number of items and itemsize for a reserve bytecode.

If bc is not a reserve bytecode, returns NULL.

Parameters

bc	bytecode
itemsize	reserved size (in bytes) for each item (returned)

Returns: NULL if bc is not a reserve bytecode, otherwise an expression for the number of items to reserve.

YASM_LIB_DECL void yasm_bc_set_multiple	(	yasm_bytecode *	bc,
		yasm_expr *	e
	)

Set multiple field of a bytecode.

A bytecode can be repeated a number of times when output. This function sets that multiple.

Parameters

bc	bytecode
e	multiple (kept, do not free)

YASM_LIB_DECL unsigned char* yasm_bc_tobytes	(	yasm_bytecode *	bc,
		unsigned char *	buf,
		unsigned long *	bufsize,
		int *	gap,
		void *	d,
		yasm_output_value_func	output_value,
		yasm_output_reloc_func	output_reloc
	)

Convert a bytecode into its byte representation.

Parameters

bc	bytecode
buf	byte representation destination buffer
bufsize	size of buf (in bytes) prior to call; size of the generated data after call
gap	if nonzero, indicates the data does not really need to exist in the object file; if nonzero, contents of buf are undefined [output]
d	data to pass to each call to output_value/output_reloc
output_value	function to call to convert values into their byte representation
output_reloc	function to call to output relocation entries for a single sym

Returns: Newly allocated buffer that should be used instead of buf for reading the byte representation, or NULL if buf was big enough to hold the entire byte representation.

Note: Calling twice on the same bytecode may not produce the same results on the second call, as calling this function may result in non-reversible changes to the bytecode.

YASM_LIB_DECL int yasm_bc_tobytes_common	(	yasm_bytecode *	bc,
		unsigned char **	bufp,
		unsigned char *	bufstart,
		void *	d,
		yasm_output_value_func	output_value,
		yasm_output_reloc_func	output_reloc
	)

Common bytecode callback tobytes function, for where the bytecode cannot be converted to bytes.

Causes an internal error if called.

YASM_LIB_DECL void yasm_bc_transform	(	yasm_bytecode *	bc,
		const yasm_bytecode_callback *	callback,
		void *	contents
	)

Transform a bytecode of any type into a different type.

Parameters

bc	bytecode to transform
callback	new bytecode callback function
contents	new type-specific data

YASM_LIB_DECL yasm_intnum* yasm_calc_bc_dist	(	yasm_bytecode *	precbc1,
		yasm_bytecode *	precbc2
	)

Determine the distance between the starting offsets of two bytecodes.

Parameters

precbc1	preceding bytecode to the first bytecode
precbc2	preceding bytecode to the second bytecode

Returns: Distance in bytes between the two bytecodes (bc2-bc1), or NULL if the distance was indeterminate.

Warning: Only valid /after/ optimization.

YASM_LIB_DECL yasm_dataval* yasm_dv_create_expr ( yasm_expr * expn )

Create a new data value from an expression.

Parameters

expn	expression

Returns: Newly allocated data value.

YASM_LIB_DECL yasm_dataval* yasm_dv_create_raw	(	unsigned char *	contents,
		unsigned long	len
	)

Create a new data value from raw bytes data.

Parameters

contents	raw data (may contain NULs)
len	length

Returns: Newly allocated data value.

YASM_LIB_DECL yasm_dataval* yasm_dv_create_reserve ( void )

Create a new uninitialized data value.

Returns: Newly allocated data value.

YASM_LIB_DECL yasm_dataval* yasm_dv_create_string	(	char *	contents,
		size_t	len
	)

Create a new data value from a string.

Parameters

contents	string (may contain NULs)
len	length of string

Returns: Newly allocated data value.

YASM_LIB_DECL int yasm_dv_get_multiple	(	yasm_dataval *	dv,
		unsigned long *	multiple
	)

Get the data value multiple value as an unsigned long integer.

Parameters

dv	data value
multiple	multiple value (output)

Returns: 1 on error (set with yasm_error_set), 0 on success.

YASM_LIB_DECL yasm_value* yasm_dv_get_value ( yasm_dataval * dv )

Get the underlying value of a data value.

Parameters

dv	data value

Returns: Value, or null if non-value (e.g. string or raw).

YASM_LIB_DECL void yasm_dv_set_multiple	(	yasm_dataval *	dv,
		yasm_expr *	e
	)

Set multiple field of a data value.

A data value can be repeated a number of times when output. This function sets that multiple.

Parameters

dv	data value
e	multiple (kept, do not free)

YASM_LIB_DECL yasm_dataval* yasm_dvs_append	(	yasm_datavalhead *	headp,
		yasm_dataval *	dv
	)

Add data value to the end of a list of data values.

Note: Does not make a copy of the data value; so don't pass this function static or local variables, and discard the dv pointer after calling this function.

Parameters

headp	data value list
dv	data value (may be NULL)

Returns: If data value was actually appended (it wasn't NULL), the data value; otherwise NULL.

YASM_LIB_DECL void yasm_dvs_delete ( yasm_datavalhead * headp )

Delete (free allocated memory for) a list of data values.

Parameters

headp list of data values

void yasm_dvs_initialize ( yasm_datavalhead * headp )

Initialize a list of data values.

Parameters

headp list of data values

YASM_LIB_DECL void yasm_dvs_print	(	const yasm_datavalhead *	headp,
		FILE *	f,
		int	indent_level
	)

Print a data value list.

For debugging purposes.

Parameters

f	file
indent_level	indentation level
headp	data value list

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation