/* Chrysalide - Outil d'analyse de fichiers binaires
 * instruction.h - prototypes pour la gestion générique des instructions
 *
 * Copyright (C) 2008-2025 Cyrille Bagard
 *
 *  This file is part of Chrysalide.
 *
 *  Chrysalide is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  Chrysalide is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with Chrysalide.  If not, see <http://www.gnu.org/licenses/>.
 */


#ifndef _ARCH_INSTRUCTION_H
#define _ARCH_INSTRUCTION_H


#include <stdbool.h>
#include <stdint.h>


#include "operand.h"
#include "vmpa.h"
#include "../glibext/helpers.h"
#include "../glibext/portion.h"



/* ----------------------- DEFINITION GENERIQUE D'INSTRUCTION ----------------------- */


#define G_TYPE_ARCH_INSTRUCTION (g_arch_instruction_get_type())

DECLARE_GTYPE(GArchInstruction, g_arch_instruction, G, ARCH_INSTRUCTION);


/* Type pour les types d'instructions */
typedef uint16_t itid_t;

/* Fournit l'identifiant correspondant à un type d'instructions. */
itid_t g_arch_instruction_get_type_id(const GArchInstruction *);

/* Indique l'encodage d'une instruction de façon détaillée. */
char *g_arch_instruction_get_encoding(const GArchInstruction *);

/* Fournit le nom humain de l'instruction manipulée. */
char *g_arch_instruction_get_keyword(const GArchInstruction *);


 /* Type de masques pour les encodages d'instructions */
typedef enum _InstructionBytesMask
{
    /**
     * Correspond aux bits fixes : pas de valeurs de registre ni de valeur entière.
     */
    IBM_LOOSE,

    /**
     * Dissimulation des références à des éléments externes pouvant varier avec
     * entre compilations : adresses de saut ou d'appel, références vers des tables,
     * etc.
     */
    IBM_LOCAL,

    /**
     * Dissimulation des déplacements à partir d'une base.
     */
    IBM_STRICT,

    /**
     * Conservation de toutes les valeurs immédiates et dissimulation des registres.
     */
    IBM_LARGE,

    IBM_COUNT

} InstructionBytesMask;


/* Calcule la localisation d'une instruction. */
void g_arch_instruction_compute_range(GArchInstruction *, GBinaryPortion *, const vmpa2t *, phys_t);

/* Fournit la place mémoire d'une instruction. */
bool g_arch_instruction_get_range(const GArchInstruction *, mrange_t *);


#define AIF_USER_BIT 4

typedef enum _ArchInstructionFlag
{
    AIF_NONE              = (0 << 0),       /* Aucune information          */
    AIF_ROUTINE_START     = (1 << 0),       /* Début de routine            */
    AIF_RETURN_POINT      = (1 << 1),       /* Retour de fonction appelée  */
    AIF_COND_RETURN_POINT = (1 << 2),       /* Retour éventuel de fonction */
    AIF_CALL              = (1 << 3),       /* Instruction d'appel         */

    AIF_LOW_USER          = (1 << AIF_USER_BIT), /* Premier bit disponible */
    AIF_HIGH_USER         = (1 << 7),      /* Dernier bit disponible      */

} ArchInstructionFlag;

#define AIF_USER_FLAG(n) (1 << (AIF_USER_BIT + n))


/* Ajoute une information complémentaire à une instruction. */
bool g_arch_instruction_set_flag(GArchInstruction *, ArchInstructionFlag);

/* Retire une information complémentaire à une instruction. */
bool g_arch_instruction_unset_flag(GArchInstruction *, ArchInstructionFlag);

/* Détermine si une instruction possède un fanion particulier. */
bool g_arch_instruction_has_flag(const GArchInstruction *, ArchInstructionFlag);

/* Fournit les particularités de l'instruction. */
ArchInstructionFlag g_arch_instruction_get_flags(const GArchInstruction *);


/* Types de crochet de traitement */
typedef enum _InstrProcessHook
{
    IPH_FETCH,                              /* Itinéraire de désassemblage */
    IPH_LINK,                               /* Edition des liens           */
    IPH_POST,                               /* Résolution des symboles     */

    IPH_COUNT

} InstrProcessHook;





/* ------------------- DEFINITION DES LIAISONS ENTRE INSTRUCTIONS ------------------- */


/* Typage des instructions rencontrées */
typedef enum _InstructionLinkType
{
    ILT_EXEC_FLOW,                          /* Raccord attendu entre blocs */
    ILT_JUMP,                               /* Saut inconditionnel         */
    ILT_CASE_JUMP,                          /* Saut suite à aiguillage     */
    ILT_JUMP_IF_TRUE,                       /* Saut conditionnel (si vrai) */
    ILT_JUMP_IF_FALSE,                      /* Saut conditionnel (si faux) */
    ILT_LOOP,                               /* Retour en arrière (boucle)  */
    ILT_CALL,                               /* Appel d'une fonction        */
    ILT_CATCH_EXCEPTION,                    /* Gestion d'une exception     */
    ILT_REF,                                /* Simple référence croisée    */

    ILT_COUNT

} InstructionLinkType;


/* Détermine si un type de lien amène à une instruction. */
bool g_arch_instruction_has_src_link(const GArchInstruction *, InstructionLinkType);

/* Détermine si un type de lien émerge d'une instruction. */
bool g_arch_instruction_has_dest_link(const GArchInstruction *, InstructionLinkType);

/* Détermine si une instruction est source d'une autre. */
bool g_arch_instruction_has_src_link_with(const GArchInstruction *, const GArchInstruction *);

/* Détermine si une instruction est destination d'une autre. */
bool g_arch_instruction_has_dest_link_with(const GArchInstruction *, const GArchInstruction *);

/* Etablit un lien entre deux instructions. */
void g_arch_instruction_link(GArchInstruction *, GArchInstruction *, InstructionLinkType);

/* Supprime un lien entre deux instructions. */
void g_arch_instruction_unlink(GArchInstruction *, GArchInstruction *, InstructionLinkType);

/* Change la nature d'un lien entre deux instructions. */
bool g_arch_instruction_change_link(GArchInstruction *, GArchInstruction *, InstructionLinkType, InstructionLinkType);

/* Supprime tous les liens établis avec d'autres instructions. */
void g_arch_instruction_delete_all_links(GArchInstruction *);

/* Fournit la quantité d'instructions placées en source. */
size_t g_arch_instruction_count_src_links(const GArchInstruction *);

/* Fournit la quantité d'instructions placées en destination. */
size_t g_arch_instruction_count_dest_links(const GArchInstruction *);

/* Fournit les détails d'une source donnée d'une instruction. */
GArchInstruction *g_arch_instruction_get_linked_source(const GArchInstruction *, size_t, InstructionLinkType *);

/* Fournit les détails d'une destination donnée d'une instruction. */
GArchInstruction *g_arch_instruction_get_linked_destination(const GArchInstruction *, size_t, InstructionLinkType *);



/* --------------------------- MANIPULATION DES OPERANDES --------------------------- */


/* Indique la quantité d'opérandes présents dans l'instruction. */
size_t g_arch_instruction_count_operands(const GArchInstruction *);

/* Attache un opérande supplémentaire à une instruction. */
void g_arch_instruction_attach_operand(GArchInstruction *, GArchOperand *);

/* Remplace un opérande d'une instruction par un autre. */
bool g_arch_instruction_replace_operand(GArchInstruction *, GArchOperand *, GArchOperand *);

/* Détache un opérande liée d'une instruction. */
bool g_arch_instruction_detach_operand(GArchInstruction *, GArchOperand *);

/* Fournit un opérande donné d'une instruction. */
GArchOperand *g_arch_instruction_get_operand(const GArchInstruction *, size_t);

/* Détermine le chemin conduisant à un opérande. */
char *g_arch_instruction_find_operand_path(GArchInstruction *, const GArchOperand *);

/* Obtient l'opérande correspondant à un chemin donné. */
GArchOperand *g_arch_instruction_get_operand_from_path(GArchInstruction *, const char *);




#if 0



/**
 * La définition de "GArchProcessor", utile aux traitements complémentaires, ne peut
 * se faire en incluant le fichier d'en-tête "processor.h", pour cause de références
 * circulaires.
 *
 * On procède donc à une seconde déclaration, en attendant éventuellement mieux.
 */

/* Depuis "processeur.h" : définition générique d'un processeur d'architecture (instance) */
typedef struct _GArchProcessor GArchProcessor;


/* Complète un désassemblage accompli pour une instruction. */
typedef void (* instr_hook_fc) (GArchInstruction *, GArchProcessor *, GProcContext *, GExeFormat *);

/* Complète un désassemblage accompli pour une instruction. */
void g_arch_instruction_call_hook(GArchInstruction *, InstrProcessHook, GArchProcessor *, GProcContext *, GExeFormat *);



#endif



#endif  /* _ARCH_INSTRUCTION_H */