From 343aa50bba30a8c0c795b19480305735d8eabb25 Mon Sep 17 00:00:00 2001 From: Ende! Date: Wed, 11 Mar 2015 20:04:04 +0100 Subject: [PATCH] added documentation to VXInstructionDecoderC.h --- Bindings/C/VXDisassemblerC.h | 2 - Bindings/C/VXDisassemblerTypesC.h | 2 - Bindings/C/VXDisassemblerUtilsC.h | 2 - Bindings/C/VXInstructionDecoderC.h | 129 ++++++++++++++++++++++++++++- Bindings/C/VXOpcodeTableC.h | 2 - 5 files changed, 126 insertions(+), 11 deletions(-) diff --git a/Bindings/C/VXDisassemblerC.h b/Bindings/C/VXDisassemblerC.h index 73f4ec1..173e45f 100644 --- a/Bindings/C/VXDisassemblerC.h +++ b/Bindings/C/VXDisassemblerC.h @@ -30,8 +30,6 @@ **************************************************************************************************/ -/* NOTE: fully ported to C */ - #ifndef _VDE_VXDISASSEMBLERC_H_ #define _VDE_VXDISASSEMBLERC_H_ diff --git a/Bindings/C/VXDisassemblerTypesC.h b/Bindings/C/VXDisassemblerTypesC.h index a70f369..2667dd4 100644 --- a/Bindings/C/VXDisassemblerTypesC.h +++ b/Bindings/C/VXDisassemblerTypesC.h @@ -30,8 +30,6 @@ **************************************************************************************************/ -/* NOTE: fully ported to C */ - #ifndef _VDE_VXDISASSEMBLERTYPESC_H_ #define _VDE_VXDISASSEMBLERTYPESC_H_ diff --git a/Bindings/C/VXDisassemblerUtilsC.h b/Bindings/C/VXDisassemblerUtilsC.h index b4a78ef..060d4c1 100644 --- a/Bindings/C/VXDisassemblerUtilsC.h +++ b/Bindings/C/VXDisassemblerUtilsC.h @@ -30,8 +30,6 @@ **************************************************************************************************/ -/* NOTE: fully ported to C */ - #ifndef _VDE_VXDISASSEMBLERUTILSC_H_ #define _VDE_VXDISASSEMBLERUTILSC_H_ diff --git a/Bindings/C/VXInstructionDecoderC.h b/Bindings/C/VXInstructionDecoderC.h index bda21ae..dd22df5 100644 --- a/Bindings/C/VXInstructionDecoderC.h +++ b/Bindings/C/VXInstructionDecoderC.h @@ -30,8 +30,6 @@ **************************************************************************************************/ -/* NOTE: fully ported to C */ - #ifndef _VDE_VXINSTRUCTIONDECODERC_H_ #define _VDE_VXINSTRUCTIONDECODERC_H_ @@ -49,32 +47,88 @@ extern "C" typedef struct _VXBaseDataSourceContext { int a; } VXBaseDataSourceContext; +/** + * @brief Releases a data source. + * @param ctx The context to release. + * The context may no longer be used after it was released. + */ void VXBaseDataSource_Release( VXBaseDataSourceContext *ctx); +/** + * @brief Reads the next byte from the data source without altering the current input position + * or the @c length field of the @c info parameter. + * @param ctx The data source context. + * @param info The instruction info struct. + * @return The current input byte. If the result is zero, you should always check the @c flags + * field of the @c info parameter for error flags. Possible error values are + * @c IF_ERROR_END_OF_INPUT or @c IF_ERROR_LENGTH. + */ uint8_t VXBaseDataSource_InputPeek( VXBaseDataSourceContext *ctx, VXInstructionInfo *info); +/** + * @brief Reads the next byte from the data source. + * @param ctx The data soruce context. + * @param info The instruction info. + * @return The current input byte. If the result is zero, you should always check the + * @c flags field of the @c info parameter for error flags. + * Possible error values are @c IF_ERROR_END_OF_INPUT or @c IF_ERROR_LENGTH. + * This method increases the current input position and the @c length field of the @c info + * parameter. This function also appends the new byte to to @c data field of the @c info + * parameter. + */ uint8_t VXBaseDataSource_InputNext( VXBaseDataSourceContext *ctx, VXInstructionInfo *info); +/** + * @brief Returns the current input byte. + * @param ctx The data soruce context. + * @return The current input byte. + * The current input byte is set everytime the @c inputPeek or @c inputNext method is called. + */ +// TODO: check long descr uint8_t VXBaseDataSource_InputCurrent( const VXBaseDataSourceContext *ctx); +/** + * @brief Queries if the end of the data source is reached. + * @param ctx The data soruce context. + * @return @c true if end of input, @c false if not. + */ bool VXBaseDataSource_IsEndOfInput( const VXBaseDataSourceContext *ctx); +/** + * @brief Returns the current input position. + * @param ctx The data soruce context. + * @return The current input position. + */ uint64_t VXBaseDataSource_GetPosition( const VXBaseDataSourceContext *ctx); +/** + * @brief Sets a new input position. + * @param ctx The data soruce context. + * @param position The new input position. + * @return @c false if the new position exceeds the maximum input length. + */ bool VXBaseDataSource_SetPosition( VXBaseDataSourceContext *ctx, uint64_t position); /* VXMemoryDataSource ========================================================================== */ +/** + * @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. + * @see VXBaseDataSource_Release + */ +// TODO: verify return value VXBaseDataSourceContext* VXMemoryDataSource_Create( const void* buffer, size_t bufferLen); @@ -105,44 +159,113 @@ typedef enum _VXInstructionSetVendor /* : uint8_t */ typedef struct _VXInstructionDecoderContext { int a; } VXInstructionDecoderContext; +/** + * @brief Creates an instruction decoder. + * @return @c nullptr if it fails, else an instruction decoder context. + * @see VXInstructionDecoder_Release + */ +// TODO: verify return value VXInstructionDecoderContext* VXInstructionDecoder_Create(void); +/** + * @brief Creates an instruction decoder. + * @param input A reference to the input data source. + * @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. + * @see VXInstructionDecoder_Release + */ VXInstructionDecoderContext* VXInstructionDecoder_CreateEx( VXBaseDataSourceContext *input, VXDisassemblerMode disassemblerMode, VXInstructionSetVendor preferredVendor, uint64_t instructionPointer); +/** + * @brief Releases an instruction decoder. + * @param ctx The context of the instruction decoder to release. + */ void VXInstructionDecoder_Release( VXInstructionDecoderContext *ctx); +/** + * @brief Decodes the next instruction from the input data source. + * @param ctx The instruction decoder context. + * @param info The @c VXInstructionInfo struct that receives the information about the decoded + * instruction. + * @return This function returns @c false if the current position exceeds the maximum input + * length. In all other cases (valid and invalid instructions) the return value is + * @c true. + */ bool VXInstructionDecoder_DecodeInstruction( - VXInstructionDecoderContext *ctx, VXInstructionInfo *info); + VXInstructionDecoderContext *ctx, + VXInstructionInfo *info); +/** + * @brief Returns a pointer to the current data source. + * @param ctx The instruction decoder context. + * @return The context of the data source. + */ VXBaseDataSourceContext* VXInstructionDecoder_GetDataSource( const VXInstructionDecoderContext *ctx); +/** + * @brief Sets a new data source. + * @param ctx The instruction decoder context. + * @param input The context of the new input data source. + */ void VXInstructionDecoder_SetDataSource( VXInstructionDecoderContext *ctx, VXBaseDataSourceContext *input); +/** + * @brief Returns the current disassembler mode. + * @param ctx The instruction decoder context. + * @return The current disassembler mode. + */ VXDisassemblerMode VXInstructionDecoder_GetDisassemblerMode( VXInstructionDecoderContext *ctx); +/** + * @brief Sets the current disassembler mode. + * @param ctx The instruction decoder context. + * @param disassemblerMode The new disassembler mode. + */ void VXInstructionDecoder_SetDisassemblerMode( VXInstructionDecoderContext *ctx, VXDisassemblerMode disassemblerMode); +/** + * @brief Returns the preferred instruction-set vendor. + * @param ctx The instruction decoder context. + * @return The preferred instruction-set vendor. + */ VXInstructionSetVendor VXInstructionDecoder_GetPreferredVendor( const VXInstructionDecoderContext *ctx); +/** + * @brief Sets the preferred instruction-set vendor. + * @param ctx The instruction decoder context. + * @param preferredVendor The new preferred instruction-set vendor. + */ void VXInstructionDecoder_SetPreferredVendor( VXInstructionDecoderContext *ctx, VXInstructionSetVendor preferredVendor); +/** + * @brief Returns the current instruction pointer. + * @param ctx The instruction decoder context. + * @return The current instruction pointer. + */ uint64_t VXInstructionDecoder_GetInstructionPointer( VXInstructionDecoderContext *ctx); +/** + * @brief Sets a new instruction pointer. + * @param ctx The instruction decoder context. + * @param instructionPointer The new instruction pointer. + */ void VXInstructionDecoder_SetInstructionPointer( VXInstructionDecoderContext *ctx, uint64_t instructionPointer); diff --git a/Bindings/C/VXOpcodeTableC.h b/Bindings/C/VXOpcodeTableC.h index c6d3bf2..f65b862 100644 --- a/Bindings/C/VXOpcodeTableC.h +++ b/Bindings/C/VXOpcodeTableC.h @@ -30,8 +30,6 @@ **************************************************************************************************/ -/* NOTE: fully ported to C */ - #ifndef _VDE_VXOPCODETABLEC_H_ #define _VDE_VXOPCODETABLEC_H_