libyasm/bytecode.h File Reference

YASM bytecode interface. More...

Go to the source code of this file.

Data Structures
struct	yasm_bytecode_callback
	Bytecode callback structure. More...
struct	yasm_bytecode
	A bytecode. More...
Defines
#define	yasm_bc__next(bc)   STAILQ_NEXT(bc, link)
	Get the next bytecode in a linked list of bytecodes.
Typedefs
typedef yasm_dataval	yasm_dataval
	A data value (opaque type).
typedef yasm_datavalhead	yasm_datavalhead
	A list of data values.
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.
Functions
	STAILQ_HEAD (yasm_datavalhead, yasm_dataval)
	Linked list of data values.
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.
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.
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.
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).
YASM_LIB_DECL int	yasm_bc_tobytes_common (yasm_bytecode *bc, unsigned char **bufp, 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.
YASM_LIB_DECL void	yasm_bc_set_multiple (yasm_bytecode *bc, yasm_expr *e)
	Set multiple field of a bytecode.
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).
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).
YASM_LIB_DECL yasm_bytecode *	yasm_bc_create_reserve (yasm_expr *numitems, unsigned int itemsize, unsigned long line)
	Create a bytecode reserving space.
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.
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.
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.
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.
YASM_LIB_DECL yasm_section *	yasm_bc_get_section (yasm_bytecode *bc)
	Get the section that contains a particular bytecode.
YASM_LIB_DECL void	yasm_bc__add_symrec (yasm_bytecode *bc, yasm_symrec *sym)
	Add to the list of symrecs that reference a bytecode.
YASM_LIB_DECL void	yasm_bc_destroy (yasm_bytecode *bc)
	Delete (free allocated memory for) a bytecode.
YASM_LIB_DECL void	yasm_bc_print (const yasm_bytecode *bc, FILE *f, int indent_level)
	Print a bytecode.
YASM_LIB_DECL void	yasm_bc_finalize (yasm_bytecode *bc, yasm_bytecode *prev_bc)
	Finalize a bytecode after parsing.
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.
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).
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.
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.
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.
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.
YASM_LIB_DECL const yasm_expr *	yasm_bc_get_multiple_expr (const yasm_bytecode *bc)
	Get the bytecode multiple value as an expression.
YASM_LIB_DECL yasm_insn *	yasm_bc_get_insn (yasm_bytecode *bc)
	Get a yasm_insn structure from an instruction bytecode (if possible).
YASM_LIB_DECL yasm_dataval *	yasm_dv_create_expr (yasm_expr *expn)
	Create a new data value from an expression.
yasm_dataval *	yasm_dv_create_string (char *contents, size_t len)
	Create a new data value from a string.
YASM_LIB_DECL yasm_dataval *	yasm_dv_create_raw (unsigned char *contents, unsigned long len)
	Create a new data value from raw bytes data.
void	yasm_dvs_initialize (yasm_datavalhead *headp)
	Initialize a list of data values.
YASM_LIB_DECL void	yasm_dvs_delete (yasm_datavalhead *headp)
	Delete (free allocated memory for) a list of data values.
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.
YASM_LIB_DECL void	yasm_dvs_print (const yasm_datavalhead *headp, FILE *f, int indent_level)
	Print a data value list.

---

Detailed Description

YASM bytecode interface.

Definition in file bytecode.h.

---

Define 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 280 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 60 of file bytecode.h.

typedef struct yasm_dataval yasm_dataval

A data value (opaque type).

Definition at line 42 of file bytecode.h.

typedef struct yasm_datavalhead yasm_datavalhead

A list of data values.

Definition at line 44 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_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,
		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_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 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

---