- Main Page
- Modules
- Data Structures
- Files

- Search for |

# Using the decode cache

## Functions

XED_DLL_EXPORT xed_error_enum_t | xed_decode_cache (xed_decoded_inst_t *xedd, const xed_uint8_t *itext, const unsigned int bytes, xed_decode_cache_t *cache)
| This is the main interface to the decoder.
XED_DLL_EXPORT void | xed_decode_cache_initialize (xed_decode_cache_t *cache, xed_decode_cache_entry_t *entries, xed_uint32_t n_entries)
| Have XED initialize the decode cache that you've allocated.

## Detailed Description

To use the decode cache, you must create a xed_decode_cache_t per thread that accesses the decoder. For each xed_decode_cache_t, you must allocate an initialize a cache buffer as shown below.

Each cache entry is 224B, so allocating 16K entries results in a 3.5MB buffer. The interface requires that the user allocate the memory for the cache since XED does not ever allocate memory on its own.

The example shows one thread, but you could use many xed_decode_cache_t's, one per thread. If your JIT or interpreter is single threaded, you would only need one cache as shown.

        /* once per thread */
        xed_decode_cache_t cache;
        xed_uint32_t n_cache_entries = 16*1024;
        xed_decode_cache_entry_t* cache_entries =
          (xed_decode_cache_entry_t*) malloc(n_cache_entries *
                                             sizeof(xed_decode_cache_entry_t));
        xed_decode_cache_initialize(&cache, cache_entries, n_cache_entries);

Then during execution, instead of calling xed_decode(), you call xed_decode_cache() and pass in a pointer to the thread's cache you initialized above.

        xed_error_enum_t xed_error = xed_decode_cache(&xedd,
                                                      itext_buffer,
                                                      nbytes,
                                                      &cache);

During thread shutdown you must free up each cache you allocated.

        free(cache_entries);

## Function Documentation

XED_DLL_EXPORT xed_error_enum_t xed_decode_cache | ( | xed_decoded_inst_t * | xedd,
|  | const xed_uint8_t * | itext,
|  | const unsigned int | bytes,
|  | xed_decode_cache_t * | cache
| ) |

| This is the main interface to the decoder.

Parameters:

  | xedd | the decoded instruction of type xed_decoded_inst_t . Mode/state sent in via xedd; See the xed_state_t
  | itext | the pointer to the array of instruction text bytes
  | bytes | the length of the itext input array. 1 to 15 bytes, anything more is ignored.
  | cache | a per-thread decode cache allocated by the user and initialized once with xed_decode_cache_initialize().

Returns:
  xed_error_enum_t indiciating success (XED_ERROR_NONE) or failure. Note failure can be due to not enough bytes in the input array.

See xed_decode() for further information about the bytes parameter.

XED_DLL_EXPORT void xed_decode_cache_initialize | ( | xed_decode_cache_t * | cache,
|  | xed_decode_cache_entry_t * | entries,
|  | xed_uint32_t | n_entries
| ) |

| Have XED initialize the decode cache that you've allocated. You must allocate one decode cache per thread if you are using the xed_decode_cache. The number of entries must be a power of 2.

Parameters:

  | cache | a pointer to your xed_decode_cache_t
  | entries | an array you have allocated.
  | n_entries | number of xed_decode_cache_entry_t entries, not bytes.