Intel® X86 Encoder Decoder: High Level API for Encoding Instructions

Intel® X86 Encoder Decoder

Loading...
Searching...
No Matches
High Level API for Encoding Instructions

## Memory Displacement
static XED_INLINE xed_enc_displacement_t | xed_disp (xed_int64_t displacement, xed_uint32_t displacement_bits)
| a memory displacement (not for branches)

## Branch Displacement
static XED_INLINE xed_encoder_operand_t | xed_relbr (xed_int32_t brdisp, xed_uint_t width_bits)
| a relative branch displacement operand
static XED_INLINE xed_encoder_operand_t | xed_absbr (xed_int32_t brdisp, xed_uint_t width_bits)
| an absolute branch displacement operand

## Pointer Displacement
static XED_INLINE xed_encoder_operand_t | xed_ptr (xed_int32_t brdisp, xed_uint_t width_bits)
| a relative displacement for a PTR operand – the subsequent imm0 holds the 16b selector

## Register and Immediate Operands
static XED_INLINE xed_encoder_operand_t | xed_reg (xed_reg_enum_t reg)
| a register operand
static XED_INLINE xed_encoder_operand_t | xed_imm0 (xed_uint64_t v, xed_uint_t width_bits)
| a first immediate operand (known as IMM0)
static XED_INLINE xed_encoder_operand_t | xed_simm0 (xed_int32_t v, xed_uint_t width_bits)
| an 32b signed immediate operand
static XED_INLINE xed_encoder_operand_t | xed_imm1 (xed_uint8_t v)
| The 2nd immediate operand (known as IMM1) for rare instructions that require it.
static XED_INLINE xed_encoder_operand_t | xed_other (xed_operand_enum_t operand_name, xed_int32_t value)
| an operand storage field name and value

## Memory and Segment-releated Operands
static XED_INLINE xed_encoder_operand_t | xed_seg0 (xed_reg_enum_t seg0)
| seg reg override for implicit suppressed memory ops
static XED_INLINE xed_encoder_operand_t | xed_seg1 (xed_reg_enum_t seg1)
| seg reg override for implicit suppressed memory ops
static XED_INLINE xed_encoder_operand_t | xed_mem_b (xed_reg_enum_t base, xed_uint_t width_bits)
| memory operand - base only
static XED_INLINE xed_encoder_operand_t | xed_mem_bd (xed_reg_enum_t base, xed_enc_displacement_t disp, xed_uint_t width_bits)
| memory operand - base and displacement only
static XED_INLINE xed_encoder_operand_t | xed_mem_bisd (xed_reg_enum_t base, xed_reg_enum_t index, xed_uint_t scale, xed_enc_displacement_t disp, xed_uint_t width_bits)
| memory operand - base, index, scale, displacement
static XED_INLINE xed_encoder_operand_t | xed_mem_gb (xed_reg_enum_t seg, xed_reg_enum_t base, xed_uint_t width_bits)
| memory operand - segment and base only
static XED_INLINE xed_encoder_operand_t | xed_mem_gbd (xed_reg_enum_t seg, xed_reg_enum_t base, xed_enc_displacement_t disp, xed_uint_t width_bits)
| memory operand - segment, base and displacement only
static XED_INLINE xed_encoder_operand_t | xed_mem_gd (xed_reg_enum_t seg, xed_enc_displacement_t disp, xed_uint_t width_bits)
| memory operand - segment and displacement only
static XED_INLINE xed_encoder_operand_t | xed_mem_gbisd (xed_reg_enum_t seg, xed_reg_enum_t base, xed_reg_enum_t index, xed_uint_t scale, xed_enc_displacement_t disp, xed_uint_t width_bits)
| memory operand - segment, base, index, scale, and displacement

## Instruction Properties and prefixes
static XED_INLINE void | xed_addr (xed_encoder_instruction_t *x, xed_uint_t width_bits)
| This is to specify effective address size different than the default.
static XED_INLINE void | xed_rep (xed_encoder_instruction_t *x)
| To add a REP (0xF3) prefix.
static XED_INLINE void | xed_repne (xed_encoder_instruction_t *x)
| To add a REPNE (0xF2) prefix.
XED_DLL_EXPORT xed_bool_t | xed_convert_to_encoder_request (xed_encoder_request_t *out, xed_encoder_instruction_t *in)
| convert a xed_encoder_instruction_t to a xed_encoder_request_t for encoding

## Creating instructions from operands
static XED_INLINE void | xed_inst0 (xed_encoder_instruction_t *inst, xed_state_t mode, xed_iclass_enum_t iclass, xed_uint_t effective_operand_width)
| instruction with no operands
static XED_INLINE void | xed_inst1 (xed_encoder_instruction_t *inst, xed_state_t mode, xed_iclass_enum_t iclass, xed_uint_t effective_operand_width, xed_encoder_operand_t op0)
| instruction with one operand
static XED_INLINE void | xed_inst2 (xed_encoder_instruction_t *inst, xed_state_t mode, xed_iclass_enum_t iclass, xed_uint_t effective_operand_width, xed_encoder_operand_t op0, xed_encoder_operand_t op1)
| instruction with two operands
static XED_INLINE void | xed_inst3 (xed_encoder_instruction_t *inst, xed_state_t mode, xed_iclass_enum_t iclass, xed_uint_t effective_operand_width, xed_encoder_operand_t op0, xed_encoder_operand_t op1, xed_encoder_operand_t op2)
| instruction with three operands
static XED_INLINE void | xed_inst4 (xed_encoder_instruction_t *inst, xed_state_t mode, xed_iclass_enum_t iclass, xed_uint_t effective_operand_width, xed_encoder_operand_t op0, xed_encoder_operand_t op1, xed_encoder_operand_t op2, xed_encoder_operand_t op3)
| instruction with four operands
static XED_INLINE void | xed_inst5 (xed_encoder_instruction_t *inst, xed_state_t mode, xed_iclass_enum_t iclass, xed_uint_t effective_operand_width, xed_encoder_operand_t op0, xed_encoder_operand_t op1, xed_encoder_operand_t op2, xed_encoder_operand_t op3, xed_encoder_operand_t op4)
| instruction with five operands
static XED_INLINE void | xed_inst (xed_encoder_instruction_t *inst, xed_state_t mode, xed_iclass_enum_t iclass, xed_uint_t effective_operand_width, xed_uint_t number_of_operands, const xed_encoder_operand_t *operand_array)
| instruction with an array of operands.

## Detailed Description

This is a higher level API for encoding instructions.

A full example is present in examples/xed-enc-direct.c

In the following example we create one instruction template that can be passed to the encoder.

    @code

xed_encoder_instruction_t x; xed_encoder_request_t enc_req; xed_state_t dstate;

dstate.mmode=XED_MACHINE_MODE_LEGACY_32; dstate.stack_addr_width=XED_ADDRESS_WIDTH_32b;

xed_inst2(&x, dstate, XED_ICLASS_ADD, 0, xreg(XED_REG_EAX), xmem_bd(XED_REG_EDX, xdisp(0x11223344, 32), 32));

xed_encoder_request_zero_set_mode(&enc_req, &dstate); convert_ok = xed_convert_to_encoder_request(&enc_req, &x); if (!convert_ok) { fprintf(stderr,"conversion to encode request failed\n"); continue; } xed_error = xed_encode(&enc_req, itext, ilen, &olen);

The high-level encoder interface allows passing the effective operand width for the xed_inst*() function as 0 (zero) when the effective operand width is the default.

The default width in 16b mode is 16b. The default width in 32b or 64b modes is 32b. So if you do a 16b operation in 32b/64b mode, you must set the effective operand width. If you do a 64b operation in 64b mode, you must set it (the default is 32). Or if you do a more rare 32b operation in 16b mode you must also set it.

When all the operands are "suppressed" operands, then the effective operand width must be supplied for nondefault operation widths.

## Function Documentation

## ◆ xed_absbr()

XED_INLINE xed_encoder_operand_t xed_absbr | ( | xed_int32_t | brdisp,
|  | xed_uint_t | width_bits )
| static

an absolute branch displacement operand

Parameters

  brdisp | The branch displacement
  width_bits | The width of the displacement in bits.

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_addr()

XED_INLINE void xed_addr | ( | xed_encoder_instruction_t * | x,
|  | xed_uint_t | width_bits )
| static

This is to specify effective address size different than the default.

For things with base or index regs, XED picks it up from the registers. But for things that have implicit memops, or no base or index reg, we must allow the user to set the address width directly.

Parameters

  x | The xed_encoder_instruction_t being filled in.
  width_bits | The intended effective address size in bits. Values: 16, 32 or 64.

## ◆ xed_convert_to_encoder_request()

XED_DLL_EXPORT xed_bool_t xed_convert_to_encoder_request | ( | xed_encoder_request_t * | out,
|  | xed_encoder_instruction_t * | in )

convert a xed_encoder_instruction_t to a xed_encoder_request_t for encoding

## ◆ xed_disp()

XED_INLINE xed_enc_displacement_t xed_disp | ( | xed_int64_t | displacement,
|  | xed_uint32_t | displacement_bits )
| static

a memory displacement (not for branches)

Parameters

  displacement | The value of the displacement
  displacement_bits | The width of the displacement in bits. Typically 8 or 32.

Returns
  xed_enc_displacement_t

## ◆ xed_imm0()

XED_INLINE xed_encoder_operand_t xed_imm0 | ( | xed_uint64_t | v,
|  | xed_uint_t | width_bits )
| static

a first immediate operand (known as IMM0)

Parameters

  v | An immdediate operand.
  width_bits | The immediate width in bits.

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_imm1()

XED_INLINE xed_encoder_operand_t xed_imm1 | ( | xed_uint8_t | v | ) |
| static

The 2nd immediate operand (known as IMM1) for rare instructions that require it.

Parameters

  v | The 2nd immdediate (byte-width) operand

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_inst()

XED_INLINE void xed_inst | ( | xed_encoder_instruction_t * | inst,
|  | xed_state_t | mode,
|  | xed_iclass_enum_t | iclass,
|  | xed_uint_t | effective_operand_width,
|  | xed_uint_t | number_of_operands,
|  | const xed_encoder_operand_t * | operand_array )
| static

instruction with an array of operands.

The maximum number is XED_ENCODER_OPERANDS_MAX. The array's contents are copied.

Parameters

  inst | The xed_encoder_instruction_t to be filled in
  mode | The xed_state_t including the machine mode and stack address width.
  iclass | The xed_iclass_enum_t
  effective_operand_width | in bits
  number_of_operands | length of the subsequent array
  operand_array | An array of xed_encoder_operand_t objects

## ◆ xed_inst0()

XED_INLINE void xed_inst0 | ( | xed_encoder_instruction_t * | inst,
|  | xed_state_t | mode,
|  | xed_iclass_enum_t | iclass,
|  | xed_uint_t | effective_operand_width )
| static

instruction with no operands

Parameters

  inst | The xed_encoder_instruction_t to be filled in
  mode | The xed_state_t including the machine mode and stack address width.
  iclass | The xed_iclass_enum_t
  effective_operand_width | in bits

## ◆ xed_inst1()

XED_INLINE void xed_inst1 | ( | xed_encoder_instruction_t * | inst,
|  | xed_state_t | mode,
|  | xed_iclass_enum_t | iclass,
|  | xed_uint_t | effective_operand_width,
|  | xed_encoder_operand_t | op0 )
| static

instruction with one operand

Parameters

  inst | The xed_encoder_instruction_t to be filled in
  mode | The xed_state_t including the machine mode and stack address width.
  iclass | The xed_iclass_enum_t
  effective_operand_width | in bits
  op0 | the operand

## ◆ xed_inst2()

XED_INLINE void xed_inst2 | ( | xed_encoder_instruction_t * | inst,
|  | xed_state_t | mode,
|  | xed_iclass_enum_t | iclass,
|  | xed_uint_t | effective_operand_width,
|  | xed_encoder_operand_t | op0,
|  | xed_encoder_operand_t | op1 )
| static

instruction with two operands

Parameters

  inst | The xed_encoder_instruction_t to be filled in
  mode | The xed_state_t including the machine mode and stack address width.
  iclass | The xed_iclass_enum_t
  effective_operand_width | in bits
  op0 | the 1st operand
  op1 | the 2nd operand

## ◆ xed_inst3()

XED_INLINE void xed_inst3 | ( | xed_encoder_instruction_t * | inst,
|  | xed_state_t | mode,
|  | xed_iclass_enum_t | iclass,
|  | xed_uint_t | effective_operand_width,
|  | xed_encoder_operand_t | op0,
|  | xed_encoder_operand_t | op1,
|  | xed_encoder_operand_t | op2 )
| static

instruction with three operands

Parameters

  inst | The xed_encoder_instruction_t to be filled in
  mode | The xed_state_t including the machine mode and stack address width.
  iclass | The xed_iclass_enum_t
  effective_operand_width | in bits
  op0 | the 1st operand
  op1 | the 2nd operand
  op2 | the 3rd operand

## ◆ xed_inst4()

XED_INLINE void xed_inst4 | ( | xed_encoder_instruction_t * | inst,
|  | xed_state_t | mode,
|  | xed_iclass_enum_t | iclass,
|  | xed_uint_t | effective_operand_width,
|  | xed_encoder_operand_t | op0,
|  | xed_encoder_operand_t | op1,
|  | xed_encoder_operand_t | op2,
|  | xed_encoder_operand_t | op3 )
| static

instruction with four operands

Parameters

  inst | The xed_encoder_instruction_t to be filled in
  mode | The xed_state_t including the machine mode and stack address width.
  iclass | The xed_iclass_enum_t
  effective_operand_width | in bits
  op0 | the 1st operand
  op1 | the 2nd operand
  op2 | the 3rd operand
  op3 | the 4th operand

## ◆ xed_inst5()

XED_INLINE void xed_inst5 | ( | xed_encoder_instruction_t * | inst,
|  | xed_state_t | mode,
|  | xed_iclass_enum_t | iclass,
|  | xed_uint_t | effective_operand_width,
|  | xed_encoder_operand_t | op0,
|  | xed_encoder_operand_t | op1,
|  | xed_encoder_operand_t | op2,
|  | xed_encoder_operand_t | op3,
|  | xed_encoder_operand_t | op4 )
| static

instruction with five operands

Parameters

  inst | The xed_encoder_instruction_t to be filled in
  mode | The xed_state_t including the machine mode and stack address width.
  iclass | The xed_iclass_enum_t
  effective_operand_width | in bits
  op0 | the 1st operand
  op1 | the 2nd operand
  op2 | the 3rd operand
  op3 | the 4th operand
  op4 | the 5th operand

## ◆ xed_mem_b()

XED_INLINE xed_encoder_operand_t xed_mem_b | ( | xed_reg_enum_t | base,
|  | xed_uint_t | width_bits )
| static

memory operand - base only

Parameters

  base | The base register
  width_bits | The length of the memory reference in bits.

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_mem_bd()

XED_INLINE xed_encoder_operand_t xed_mem_bd | ( | xed_reg_enum_t | base,
|  | xed_enc_displacement_t | disp,
|  | xed_uint_t | width_bits )
| static

memory operand - base and displacement only

Parameters

  base | The base register
  disp | The displacement
  width_bits | The length of the memory reference in bits.

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_mem_bisd()

XED_INLINE xed_encoder_operand_t xed_mem_bisd | ( | xed_reg_enum_t | base,
|  | xed_reg_enum_t | index,
|  | xed_uint_t | scale,
|  | xed_enc_displacement_t | disp,
|  | xed_uint_t | width_bits )
| static

memory operand - base, index, scale, displacement

Parameters

  base | The base register
  index | The index register
  scale | The scale for the index register value
  disp | The displacement
  width_bits | The length of the memory reference in bits.

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_mem_gb()

XED_INLINE xed_encoder_operand_t xed_mem_gb | ( | xed_reg_enum_t | seg,
|  | xed_reg_enum_t | base,
|  | xed_uint_t | width_bits )
| static

memory operand - segment and base only

Parameters

  seg | The segment override register
  base | The base register
  width_bits | The length of the memory reference in bits.

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_mem_gbd()

XED_INLINE xed_encoder_operand_t xed_mem_gbd | ( | xed_reg_enum_t | seg,
|  | xed_reg_enum_t | base,
|  | xed_enc_displacement_t | disp,
|  | xed_uint_t | width_bits )
| static

memory operand - segment, base and displacement only

Parameters

  seg | The segment override register
  base | The base register
  disp | The displacement
  width_bits | The length of the memory reference in bits.

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_mem_gbisd()

XED_INLINE xed_encoder_operand_t xed_mem_gbisd | ( | xed_reg_enum_t | seg,
|  | xed_reg_enum_t | base,
|  | xed_reg_enum_t | index,
|  | xed_uint_t | scale,
|  | xed_enc_displacement_t | disp,
|  | xed_uint_t | width_bits )
| static

memory operand - segment, base, index, scale, and displacement

Parameters

  seg | The segment override register
  base | The base register
  index | The index register
  scale | The scale for the index register value
  disp | The displacement
  width_bits | The length of the memory reference in bits.

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_mem_gd()

XED_INLINE xed_encoder_operand_t xed_mem_gd | ( | xed_reg_enum_t | seg,
|  | xed_enc_displacement_t | disp,
|  | xed_uint_t | width_bits )
| static

memory operand - segment and displacement only

Parameters

  seg | The segment override register
  disp | The displacement
  width_bits | The length of the memory reference in bits.

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_other()

XED_INLINE xed_encoder_operand_t xed_other | ( | xed_operand_enum_t | operand_name,
|  | xed_int32_t | value )
| static

an operand storage field name and value

## ◆ xed_ptr()

XED_INLINE xed_encoder_operand_t xed_ptr | ( | xed_int32_t | brdisp,
|  | xed_uint_t | width_bits )
| static

a relative displacement for a PTR operand – the subsequent imm0 holds the 16b selector

Parameters

  brdisp | The displacement for a far pointer operand
  width_bits | The width of the far pointr displacement in bits.

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_reg()

XED_INLINE xed_encoder_operand_t xed_reg | ( | xed_reg_enum_t | reg | ) |
| static

a register operand

Parameters

  reg | A xed_reg_enum_t register operand

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_relbr()

XED_INLINE xed_encoder_operand_t xed_relbr | ( | xed_int32_t | brdisp,
|  | xed_uint_t | width_bits )
| static

a relative branch displacement operand

Parameters

  brdisp | The branch displacement
  width_bits | The width of the displacement in bits. Typically 8 or 32.

Returns
  xed_encoder_operand_t An operand.

## ◆ xed_rep()

XED_INLINE void xed_rep | ( | xed_encoder_instruction_t * | x | ) |
| static

To add a REP (0xF3) prefix.

Parameters

  x | The xed_encoder_instruction_t being filled in.

## ◆ xed_repne()

XED_INLINE void xed_repne | ( | xed_encoder_instruction_t * | x | ) |
| static

To add a REPNE (0xF2) prefix.

Parameters

  x | The xed_encoder_instruction_t being filled in.

## ◆ xed_seg0()

XED_INLINE xed_encoder_operand_t xed_seg0 | ( | xed_reg_enum_t | seg0 | ) |
| static

seg reg override for implicit suppressed memory ops

## ◆ xed_seg1()

XED_INLINE xed_encoder_operand_t xed_seg1 | ( | xed_reg_enum_t | seg1 | ) |
| static

seg reg override for implicit suppressed memory ops

## ◆ xed_simm0()

XED_INLINE xed_encoder_operand_t xed_simm0 | ( | xed_int32_t | v,
|  | xed_uint_t | width_bits )
| static

an 32b signed immediate operand

Parameters

  v | An signed immdediate operand.
  width_bits | The immediate width in bits.

Returns
  xed_encoder_operand_t An operand.