From a51c9085e66df72898d500eee093769b68ee38f7 Mon Sep 17 00:00:00 2001 From: Ende! Date: Thu, 12 Mar 2015 22:11:00 +0100 Subject: [PATCH] added documentation to VXInstructionFormatterC.h --- Bindings/C/VXInstructionDecoderC.h | 6 +- Bindings/C/VXInstructionFormatterC.cpp | 5 -- Bindings/C/VXInstructionFormatterC.h | 91 ++++++++++++++++++++++++-- 3 files changed, 90 insertions(+), 12 deletions(-) diff --git a/Bindings/C/VXInstructionDecoderC.h b/Bindings/C/VXInstructionDecoderC.h index dd22df5..e6a2333 100644 --- a/Bindings/C/VXInstructionDecoderC.h +++ b/Bindings/C/VXInstructionDecoderC.h @@ -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( diff --git a/Bindings/C/VXInstructionFormatterC.cpp b/Bindings/C/VXInstructionFormatterC.cpp index edae59f..3a0dbb7 100644 --- a/Bindings/C/VXInstructionFormatterC.cpp +++ b/Bindings/C/VXInstructionFormatterC.cpp @@ -152,11 +152,6 @@ inline const VXBaseInstructionFormatterContext* VXIntelInstructionFormatter_CPtr /* VXBaseSymbolResolver ======================================================================== */ -VXBaseSymbolResolverContext* VXBaseSymbolResolver_Create() -{ - return VXBaseSymbolResolver_CPtr(new Verteron::VXBaseSymbolResolver); -} - void VXBaseSymbolResolver_Release( VXBaseSymbolResolverContext *ctx) { diff --git a/Bindings/C/VXInstructionFormatterC.h b/Bindings/C/VXInstructionFormatterC.h index fa81b19..b0ae0ec 100644 --- a/Bindings/C/VXInstructionFormatterC.h +++ b/Bindings/C/VXInstructionFormatterC.h @@ -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);