The command line tool called xed or xed.exe is built when you build the examples (Examples of using XED) that come with XED. The xed-ex3 is just encode portion of the xed command line tool.
This tool is useful for encoding and decoding or even decoding-then-re-encoding a single instruction or all the instructions in the text segment of an ELF binary (32 or 64b). For decoding, just jump to the examples.
This section also explains a little language for writing the instructions for encode requests (-e option). I am constantly using this tool and updating it. The xed-ex3 (xed-ex3.exe) example is just the encoder portion of the xed command line tool.
The SUPPRESSED operands emitted by the decoder are not used when encoding. They are ignored. They are not required to select an encoding.
The syntax for encodable strings is as follows:
Opcode[/width] [operand [operand]]
The width is a 8, 16, 32 or 64, indicating the effective operand width if it differs from the default. 8b operations generally require this. Or since most operations that default to 32b widths in 64b mode, it is required for 64b operation widths in 64b mode.
The operand specifier is one of the following.
- A register name such as EAX or R8B, etc. Case does not matter.
- An immediate specifier such as IMM:12ff
- A branch displacement specifier such as BRDISP:0000001f
- A memory specifier that indicates the base register, index register, scale value, and displacement value. If one of the fields is not required, a - is necessary. The displacement is omittable. For example: MEM4:ESI,EAX,8,ff or MEM4:EBX. The first one specifies that the memory address 4 bytes and should be ESI + EAX * 8 + 0xff. The second one specifies that EBX should be used to access 4 bytes of memory; note the displacement is omitted. A segment override can be specified as follows: MEM4:GS:EAX by using a segment-name followed by a ":" before the base register. If there is no base register, you can use a "-", for example: MEM4:GS:-,-,11223344. One also needs to specify a memory operation width. This can be accomplished by indicating a number of bytes just after the MEM specifier. For example: MEM2:EAX indicates a 2 byte memory operation.
- If the Haswell gather instructions are included in the build, then you can also specify a VSIB memop as follows: VSIB4:RAX,YMM2,2,ff. This would be a memory operand for a gather with RAX as the base, YMM2 as the gather index register. The scale is 2 and the displacement is 0xff. The element size is 4 (dwords, 4 bytes). Use 8 for qwords (8 bytes).
- An address generation specifer that has the same syntax as the above MEM: specifier, but is only used for LEA instructions. Example: AGEN:EAX,EBX,2,-
Here is the help message:
% obj/xed -h
Usage: obj/xed [options]
One of the following is required:
-i input_file (decode file)
-ide input_file (decode/encode file)
-d hex-string (decode one instruction)
-e instruction (encode, must be last)
-de hex-string (decode-then-encode)
Optional arguments:
-v verbosity (0=quiet, 1=errors, 2=useful-info, 3=trace, 5=very verbose)
-n number-of-instructions-to-decode (default 10,000, accepts K/M/G qualifiers)
-I (Intel SYSV syntax for disassembly)
-A (ATT SYSV syntax for disassembly)
-16 (for LEGACY_16 mode)
-32 (for LEGACY_32 mode, default)
-64 (for LONG_64 mode w/64b addressing)
-s32 (32b stack addressing, default, not in LONG_64 mode)
-s16 (16b stack addressing, not in LONG_64 mode)
Here are a couple of examples:
% xed -d 0000
ADD INT_ALU BASE Opcode: 00 MODRM: 00 Bytes: 2
Eb/EXPLICIT/RW Gb/EXPLICIT/R
ADD EffWidth: 8b
MachineMode: LEGACY_32 AddrWidth: 32b StackAddrWidth: 32b
MEM/EXPLICIT/RW REG/AL(REG8)/EXPLICIT/R
Read Write BASE= EAX(REG32) MemopLength = 1
rFLAGS: of-mod sf-mod zf-mod af-mod pf-mod cf-mod \
Read: Written: of sf zf af pf cf writes
% xed -e ADD EAX EBX
Encodable! 01d8
xed -e ADD EAX MEM4:ESP,EBX,4
Encodable! 03049c
% xed -d 6a00
PUSH INT_ALU BASE Opcode: 6a Immed: 00 Bytes: 2
Ib/EXPLICIT/R STACKPUSH/SUPPRESSED/R
PUSH EffWidth: 32b
MachineMode: LEGACY_32 AddrWidth: 32b StackAddrWidth: 32b
MEM/SUPPRESSED/W REG/ESP(REG32)/SUPPRESSED/RW IMM/EXPLICIT/R
Write SEG= SS BASE= ESP(REG32) MemopLength = 4
IMMED: 00
Does not use rFLAGS
% xed -e MOV EAX MEM4:SS:ESP
Encodable! 8b0424
Or using the xed-ex3 example tool:
% obj/xed-ex3
Usage: obj/xed-ex3 [-16|-32|-64] [-s16|-s32] encode-string
The -16, -32 or -64 are for specifying the major mode of the machine. The major mode of the machine determines the default data operand size and default addressing width. In 64b mode, the default data size is 32b and the default addressing mode is 64b addressing. In 32b mode, the default addressing width is 32b. In 16b mode, the default addressing width is 16b. In 32b mode or 16b mode, the stack addressing width must also be specified. Usually it matches the major mode. The -s16 option is for specifying 16b stack addressing in 32b mode. The -s32 is for specifying 32b stack addressing in 16 bit mode.
% obj/xed-ex3 -64 PUSH/64 RAX
Encode request:
PUSH Prefixes: EffOpWidth: 64b EffAddrWidth: 64b
MachineMode: LONG_64 AddrWidth: 64b StackAddrWidth: 32b
REG/RAX(REG64)/EXPLICIT/RW
MemopLength = 0
Encodable! 50
% obj/xed-ex3 MOV MEM4:EAX IMM:11223344
Encode request:
MOV Prefixes: EffOpWidth: 32b EffAddrWidth: 32b
MachineMode: LEGACY_32 AddrWidth: 32b StackAddrWidth: 32b
MEM0/EXPLICIT/RW IMM/EXPLICIT/RW
TmpltIdx=0 BASE= EAX(REG32) MemopLength = 0
IMMED: 0x11223344 signed: 1144201745 starts@byte: 1
Encodable! c70011223344
An example of using the encoder
The encoder language file which is part of the xed command line tool shows how to build up instructions from scratch. The example uses a string to drive the creation of the instruction, but that is just an example. Look at the parse_encode_request function for the required pieces.
#include <iostream>
#include <iomanip>
#include <vector>
#include <sstream>
#include <cassert>
#include <cstring>
#include <cstdlib>
extern "C" {
#include "xed-examples-util.h"
}
#include "xed-enc-lang.H"
using namespace std;
static char xed_enc_lang_toupper(char c) {
if (c >= 'a' && c <= 'z')
return c-'a'+'A';
return c;
}
static string upcase(string s) {
string t = "";
for(i=0 ; i < len ; i++ )
t = t + xed_enc_lang_toupper(s[i]);
return t;
}
unsigned int
xed_split_args(const string& sep,
const string& input,
vector<string>& output_array)
{
string::size_type last_pos = input.find_first_not_of(sep, 0);
string::size_type pos = input.find_first_of(sep, last_pos);
if (CLIENT_VERBOSE3)
int i=0;
while( pos != string::npos && last_pos != string::npos )
{
string a = input.substr(last_pos, pos-last_pos);
output_array.push_back(a);
if (CLIENT_VERBOSE3)
printf("\t\tlast_pos " XED_FMT_U " pos " XED_FMT_U " i %d\n",
i);
last_pos = input.find_first_not_of(sep, pos);
pos = input.find_first_of(sep, last_pos);
i++;
}
if (last_pos != string::npos && pos == string::npos)
{
if (CLIENT_VERBOSE3)
string a = input.substr(last_pos);
output_array.push_back(a);
i++;
}
if (CLIENT_VERBOSE3)
printf("\t returning %d\n",i);
return i;
}
vector<string>
tokenize(const string& s,
const string& delimiter) {
vector<string> v;
(void) xed_split_args(delimiter, s, v);
return v;
}
void slash_split(const string& src,
string& first,
string& second)
{
string::size_type p = src.find("/");
if (p == string::npos) {
first = src;
second = "";
}
else {
first = src.substr(0,p);
second = src.substr(p+1);
}
}
class immed_parser_t {
public:
string immed;
unsigned int width_bits;
xed_uint64_t immed_val;
string tok0;
immed_parser_t(const string& s,
const string& arg_tok0)
: valid(false),
tok0(arg_tok0)
{
vector<string> vs = tokenize(s,":");
if (vs.size() == 2) {
if (vs[0] == tok0) {
string immed_str = vs[1];
immed_val = convert_ascii_hex_to_int(immed_str.c_str());
width_bits = static_cast<unsigned int>(immed_str.size()*4);
valid = true;
}
}
}
void
print(ostream& o) const {
o << tok0
<< "(" ;
if (valid) {
o << std::hex;
o << setfill('0');
o << std::setw(8);
o << std::setw(8);
o << setfill(' ');
o << std::dec;
}
else
o << "???";
o << ")";
}
};
ostream& operator<<(ostream& o, const immed_parser_t& x)
{
x.print(o);
return o;
}
class seg_parser_t
{
public:
string segment;
seg_parser_t(const string& s)
: valid(false),
segno(0)
{
vector<string> vs = tokenize(s,":");
if (ntokens == 2) {
if (vs[0] == "SEG" || vs[0] == "SEG0") {
segment = vs[1];
segno = 0;
valid=true;
}
}
if (vs[0] == "SEG1") {
segment = vs[1];
segno = 1;
valid=true;
}
}
}
}
};
class mem_bis_parser_t
{
public:
string segment;
string base;
string index;
string scale;
string disp;
xed_uint8_t scale_val;
xed_int64_t disp_val;
unsigned int disp_width_bits;
unsigned int mem_len;
void
print(ostream& o) const {
if (agen)
o << "AGEN";
if (mem)
o << "MEM";
if (mem_len)
o << setw(1) << mem_len;
o << "(";
o << segment_reg << ":";
o << base_reg;
o << "," << index_reg
<< ","
<< (unsigned int) scale_val;
if (disp_valid)
o << "," << disp;
o << ")";
}
mem_bis_parser_t(const string& s)
: valid(false),
mem(false),
agen(false),
disp_valid(false),
base("INVALID"),
index("INVALID"),
scale("1"),
disp_val(0),
disp_width_bits(0),
mem_len(0)
{
string t = upcase(s);
vector<string> vs = tokenize(t,":");
vector<string> astr;
string main_token, addr_token;
if (ntokens == 3) {
main_token = vs[0];
segment = vs[1];
addr_token = vs[2];
}
else if (ntokens == 2) {
main_token = vs[0];
segment = "INVALID";
addr_token = vs[1];
}
else
return;
size_t n=0;
if (main_token == "AGEN")
agen=true;
else if (main_token.substr(0,3) == "MEM") {
mem = true;
n = 3;
}
else
return;
if (mem && main_token.size() > n) {
string len = main_token.substr(n);
mem_len = strtol(len.c_str(),0,0);
}
if (agen && segment != "INVALID")
xedex_derror("AGENs cannot have segment overrides");
astr = tokenize(addr_token,",");
n_addr_tokens =
static_cast<xed_uint_t>(astr.size());
if (n_addr_tokens == 0 || n_addr_tokens > 4)
xedex_derror("Bad addressing mode syntax for memop");
base = astr[0];
if (base == "-" || base == "NA")
base = "INVALID";
if (n_addr_tokens > 2)
index = astr[1];
if (index == "-" || index == "NA")
index = "INVALID";
if (n_addr_tokens > 2)
scale = astr[2];
if (scale == "-" || scale == "NA")
scale = "1";
if (scale == "1" || scale == "2" || scale == "4" || scale == "8") {
valid=true;
if (n_addr_tokens == 4 && astr[3] != "-") {
disp = astr[3];
disp_valid = true;
if (nibbles & 1) {
string zero("0");
disp = zero + disp;
nibbles++;
}
xed_uint64_t unsigned64_disp;
unsigned64_disp = convert_ascii_hex_to_int(disp.c_str());
disp_width_bits = nibbles*4;
switch (disp_width_bits){
case 64: disp_val = unsigned64_disp; break;
}
}
}
}
};
ostream& operator<<(ostream& o, const mem_bis_parser_t& x) {
x.print(o);
return o;
}
unsigned int i;
vector<string> tokens = tokenize(areq.command," ");
string first, second;
unsigned int token_index = 0;
while(token_index < tokens.size()) {
slash_split(tokens[token_index], first, second);
first = upcase(first);
if (CLIENT_VERBOSE3)
printf( "[%s][%s][%s]\n",
tokens[0].c_str(), first.c_str(), second.c_str());
if (token_index == 0 && first == "REP") {
token_index++;
continue;
}
else if (token_index == 0 && first == "REPNE") {
token_index++;
continue;
}
token_index++;
break;
}
if (second == "8")
else if (second == "16")
else if (second == "32")
else if (second == "64")
ostringstream os;
os << "Bad instruction name: " << first;
xedex_derror(os.str().c_str());
}
for( i=token_index; i < tokens.size(); i++, operand_index++ ) {
string str_res_reg, second_x;
slash_split(tokens[i], str_res_reg, second_x);
str_res_reg = upcase(str_res_reg);
mem_bis_parser_t mem_bis(str_res_reg);
if (mem_bis.valid) {
if (mem_bis.mem) {
if (memop == 0) {
}
else {
}
memop++;
}
else if (mem_bis.agen) {
}
else
assert(mem_bis.agen || mem_bis.mem);
if (mem_bis.mem_len)
&req,
mem_bis.mem_len );
if (mem_bis.disp_valid)
&req,
mem_bis.disp_val,
mem_bis.disp_width_bits/8);
continue;
}
seg_parser_t seg_parser(str_res_reg);
if (seg_parser.valid) {
if (CLIENT_VERBOSE3)
printf("Setting segment to %s\n",
if (seg_parser.segno == 0)
else
continue;
}
immed_parser_t imm(str_res_reg, "IMM");
if (imm.valid) {
if (CLIENT_VERBOSE3)
printf(
"Setting immediate value to " XED_FMT_LX "\n",
imm.immed_val);
imm.immed_val,
imm.width_bits);
operand_index,
continue;
}
immed_parser_t simm(str_res_reg, "SIMM");
if (simm.valid) {
if (CLIENT_VERBOSE3)
printf(
"Setting immediate value to " XED_FMT_LX "\n",
simm.immed_val);
&req,
simm.width_bits/8);
operand_index,
continue;
}
immed_parser_t imm2(str_res_reg, "IMM2");
if (imm2.valid) {
if (imm2.width_bits != 8)
xedex_derror("2nd immediate must be just 1 byte long");
operand_index,
continue;
}
immed_parser_t disp(str_res_reg, "BRDISP");
if (disp.valid) {
if (CLIENT_VERBOSE3)
printf(
"Setting displacement value to " XED_FMT_LX "\n",
disp.immed_val);
&req,
disp.width_bits/8);
operand_index,
continue;
}
immed_parser_t ptr_disp(str_res_reg, "PTR");
if (ptr_disp.valid) {
if (CLIENT_VERBOSE3)
printf(
"Setting pointer displacement value to " XED_FMT_LX "\n",
ptr_disp.immed_val);
&req,
ptr_disp.width_bits/8);
operand_index,
continue;
}
ostringstream os;
os << "Bad register name: " << str_res_reg << " on operand " << i;
xedex_derror(os.str().c_str());
}
regnum++;
}
return req;
}