added documentation to VXInstructionFormatterC.h

This commit is contained in:
Ende! 2015-03-12 22:11:00 +01:00
parent 76bd456544
commit a51c9085e6
3 changed files with 90 additions and 12 deletions

View File

@ -125,7 +125,7 @@ bool VXBaseDataSource_SetPosition(
* @brief Creates a memory data source.
* @param buffer The input buffer.
* @param bufferLen THe length of the input buffer.
* @return @c nullptr if it fails, else a data source context.
* @return @c NULL if it fails, else a data source context.
* @see VXBaseDataSource_Release
*/
// TODO: verify return value
@ -161,7 +161,7 @@ typedef struct _VXInstructionDecoderContext { int a; } VXInstructionDecoderConte
/**
* @brief Creates an instruction decoder.
* @return @c nullptr if it fails, else an instruction decoder context.
* @return @c NULL if it fails, else an instruction decoder context.
* @see VXInstructionDecoder_Release
*/
// TODO: verify return value
@ -173,7 +173,7 @@ VXInstructionDecoderContext* VXInstructionDecoder_Create(void);
* @param disassemblerMode The disassembler mode.
* @param preferredVendor The preferred instruction-set vendor.
* @param instructionPointer The initial instruction pointer.
* @return @c nullptr if it fails, else an instruction decoder context.
* @return @c NULL if it fails, else an instruction decoder context.
* @see VXInstructionDecoder_Release
*/
VXInstructionDecoderContext* VXInstructionDecoder_CreateEx(

View File

@ -152,11 +152,6 @@ inline const VXBaseInstructionFormatterContext* VXIntelInstructionFormatter_CPtr
/* VXBaseSymbolResolver ======================================================================== */
VXBaseSymbolResolverContext* VXBaseSymbolResolver_Create()
{
return VXBaseSymbolResolver_CPtr(new Verteron::VXBaseSymbolResolver);
}
void VXBaseSymbolResolver_Release(
VXBaseSymbolResolverContext *ctx)
{

View File

@ -42,13 +42,25 @@ extern "C"
/* VXBaseSymbolResolver ======================================================================== */
typedef struct _VXBaseSymbolResolverContext { int a; } VXBaseSymbolResolverContext;
VXBaseSymbolResolverContext* VXBaseSymbolResolver_Create(void);
typedef struct _VXBaseSymbolResolverContext { int a; } VXBaseSymbolResolverContext;
/**
* @brief Releases a symbol resolver.
* @param ctx The context of the symbol resolver to free.
* The context may no longer used after it was released.
*/
void VXBaseSymbolResolver_Release(
VXBaseSymbolResolverContext *ctx);
/**
* @brief Resolves a symbol.
* @param ctx The symbol resolver context.
* @param info The instruction info.
* @param address The address.
* @param offset Pointer to an unsigned 64 bit integer that receives an offset relative to
* the base address of the symbol.
* @return The name of the symbol if the symbol was found, else @c NULL.
*/
const char* VXBaseSymbolResolver_ResolveSymbol(
VXBaseSymbolResolverContext *ctx,
const VXInstructionInfo *info,
@ -57,21 +69,50 @@ const char* VXBaseSymbolResolver_ResolveSymbol(
/* VXExactSymbolResolver ======================================================================= */
/**
* @brief Creates an exact symbol resolver.
* @return @c NULL if it fails, else a symbol resolver context.
* @see VXBaseSymbolResolver_Release
* An exact resolver is a simple symbol resolver that only matches exact addresses.
*/
// TODO: verify return value
VXBaseSymbolResolverContext* VXExactSymbolResolver_Create(void);
/**
* @brief Query if the given address is a known symbol.
* @param ctx The exact symbol resolver context.
* @param address The address.
* @return @c true if the address is known, @c false if not.
*/
bool VXExactSymbolResolver_ContainsSymbol(
VXBaseSymbolResolverContext *ctx,
uint64_t address);
/**
* @brief Adds or changes a symbol.
* @param ctx The exact symbol resolver context.
* @param address The address.
* @param name The symbol name.
*/
void VXExactSymbolResolverContext_SetSymbol(
VXBaseSymbolResolverContext *ctx,
uint64_t address,
const char* name);
/**
* @brief Removes the symbol described by address.
* @param ctx The exact symbol resolver context.
* @param address The address.
* This will invalidate all char-pointers to the affected symbol name.
*/
void VXExactSymbolResolverContext_RemoveSymbol(
VXBaseSymbolResolverContext *ctx,
uint64_t address);
/**
* @brief Clears the symbol tree.
* @param ctx The exact symbol resolver context.
*/
void VXExactSymbolResolverContext_Clear(
VXBaseSymbolResolverContext *ctx);
@ -83,6 +124,13 @@ typedef const char* (*VXResolveSymbol_t)(
uint64_t *offset,
void *userData);
/**
* @brief Creates a custom symbol resolver.
* @param resolverCb The resolver callback consulted when symbols need to be resolved.
* @param userData A pointer to arbitrary data passed to the resolver callback.
* May also be @c NULL.
* @return @c NULL if it fails, else a symbol resolver context.
*/
VXBaseSymbolResolverContext* VXCustomSymbolResolver_Create(
VXResolveSymbol_t resolverCb,
void *userData);
@ -91,23 +139,58 @@ VXBaseSymbolResolverContext* VXCustomSymbolResolver_Create(
typedef struct _VXBaseInstructionFormatterContext {int a;} VXBaseInstructionFormatterContext;
/**
* @brief Formats a decoded instruction.
* @param ctx The instruction formatter context.
* @param info The instruction info.
* @return Pointer to the formatted instruction string. This pointer remains valid until
* this function is called again or the context is released.
*/
const char* VXBaseInstructionFormatter_FormatInstruction(
VXBaseInstructionFormatterContext *ctx,
const VXInstructionInfo *info);
/**
* @brief Returns a pointer to the current symbol resolver.
* @param ctx The instruction formatter context.
* @return Pointer to the current symbol resolver or @c NULL if no symbol resolver is used.
*/
VXBaseSymbolResolverContext* VXBaseInstructionFormatter_GetSymbolResolver(
const VXBaseInstructionFormatterContext *ctx);
/**
* @brief Sets a new symbol resolver.
* @param ctx The instruction formatter context.
* @param symbolResolver Pointer to a symbol resolver instance or @c NULL, if no smybol
* resolver should be used.
*/
void VXBaseInstructionFormatter_SetSymbolResolver(
VXBaseInstructionFormatterContext *ctx,
VXBaseSymbolResolverContext *resolver);
void VXBaseInstructionFormatter_Release(VXBaseInstructionFormatterContext *ctx);
/**
* @brief Releases an instruction formatter.
* @param ctx The context of the instruction formatter to release.
* The context may no longer used after it has been released.
*/
void VXBaseInstructionFormatter_Release(
VXBaseInstructionFormatterContext *ctx);
/* VXIntelInstructionFormatter ================================================================ */
/**
* @brief Creates an Intel-syntax instruction formatter.
* @return @c NULL if it fails, else an Intel instruction formatter context.
* @see VXBaseInstructionFormatter_Release
*/
VXBaseInstructionFormatterContext* VXIntelInstructionFormatter_Create(void);
/**
* @brief Creates an Intel-syntax instruction formatter.
* @param resolver The symbol resolver consulted to resolve symbols on formatting.
* @return @c NULL if it fails, else an Intel instruction formatter context.
* @see VXBaseInstructionFormatter_Release
*/
VXBaseInstructionFormatterContext* VXIntelInstructionFormatter_CreateEx(
VXBaseSymbolResolverContext *resolver);