Partie 1 - Extraction

Je suis actuellement en train de bosser sur la création d'un émulateur pour casio monochrome 35+/75, et je réfléchissais en parallèle à une façon d'extraire automatiquement les instructions de la doc. En effet, il y a des centaines d'instructions, et bien que j'aie implémenté les 27 premières manuellement pour comprendre leur fonctionnement, cela commençait à devenir long et redondant. Je pense avoir désormais compris la base nécessaire pour mettre en place une technique qui le fait à ma place.

Je vais expliquer ici comment je m'y suis pris, sachant que tout le code javascript est disponible dans le repo du projet dans le dossier "script".

La toute première étape consiste à extraire les informations de la doc officielle du CPU SH4 dans un format qui peut être lu par un algorithme. Il existe des bibliothèques qui permettent de lire des PDFs via du code, mais la toute première chose que j'ai tenté de faire est un bête copié/collé (ctrl+a, ctrl+c, ctrl+v) de tout le pdf dans un fichier texte. Les seuls critères étant que les mots devaient apparaître dans l'ordre dans lequel ils apparaissent dans le pdf, c'est-à-dire de gauche à droite puis de haut en bas (ce qui n'est pas garanti avec ce genre de copié/collé bourrin). Heureusement, le document semble bien formaté (enfin presque, on verra pourquoi après), et je peux donc me servir de cette base pour en extraire les informations, il s'agit du fichier raw_instructions.txt.

Ensuite, il faut analyser le pdf et essayer de trouver un pattern qui permettrait d'extraire toutes les instructions. Il y a un gros bloc au début qui contient toutes les instructions à la suite ainsi que leur code, ça avait l'air prometteur, mais leur implémentation ne se situe que bien plus tard dans le document, et pas dans le même ordre, donc il fallait trouver autre chose :



Il y a un deuxième endroit où ces instructions apparaissent, c'est juste avant leur implémentation vers la fin du document, mais elles sont séparées en plusieurs groupes. Pour chaque groupe, il y a d'abord un tableau contenant les informations sur les instructions, toutes à la suite, et un peu plus tard leur implémentation, cette fois-ci dans le même ordre que le tableau ! Ce genre de pattern (tableau + implémentations) est répété plusieurs fois à la suite pour couvrir toutes les instructions. Ce sera le départ de mon algorithme !



Le principe va être de charger le fichier texte en tant que chaîne de caractères, et d'effectuer plein d'opérations dessus (découpage, recherche, trim) pour en isoler certaines parties et en extraire des informations. Le code de cette partie est situé dans le fichier extract_instructions.js.
La première étape est donc d'isoler chacun de ces groupes d'instructions (appelés instruction set dans mon code). Il s'agit de la fonction extractNextInstructionSet() dans mon code. Pour cela, je calcule la position du mot-clé "T Bit" qui représente la fin du header du tableau et donc le début de la toute première instruction (voir image ci-dessus). De façon similaire, je calcule la position de "Format Operation" qui représente le début du prochain tableau, et donc la fin de ce groupe d'instructions

Cela nous donne un tableau de plusieurs chaînes de caractères, contenant chacune un groupe d'instruction avec leur définition et leur implémentation. Pour chacune de ces chaînes, deux algorithmes sont nécessaires :

- extractInstructions() : Tout d'abord, je dois déterminer le nombre d'instructions présentes dans ce groupe. Pour cela, je vais utiliser des expressions régulières (Regexp), un outil très puissant pour chercher des patterns très spécifiques dans des chaînes de caractères. Et ici, on a un pattern qui saute aux yeux, le code de chaque instruction est toujours composé de 16 caractères avec des lettres minuscules ou des 0 ou 1. Le cas de figure parfait pour du regex ! Voici le regex qui permet d'isoler ces instructions :


Ici, le regex est /[01imnd]{16}/, qui signifie "cherche une chaîne de 16 caractères de long contenant uniquement des caractères dans cet ensemble : {0, 1, i, m, n, d}". gm sont deux attributs qui veulent dire (g)lobal - cherche TOUTES les occurrences, (m)ultiline - cherche sur plusieurs lignes.

Cela me permet d'isoler chacune des instructions en découpant la chaîne à l'emplacement de ces codes.
Puis pour extraire la famille de l'instruction, j'utilise le regex suivant :


Je peux aussi isoler la description de l'instruction, elle se trouve simplement entre la famille et le code.
Cette fonction retourne un tableau d’éléments de la sorte:



- extractImplementations() : La fonction précédente retourne un tableau contenant pour chaque instruction sa famille, sa description et son code. Maintenant, il faut relier ces instructions à leur implémentations.
Le nom de fonction de chaque instruction n'est indiqué nulle part autre que lors de l'implémentation, donc il n'est pas possible de faire une simple recherche pour isoler la fonction correspondante à une instruction. Heureusement, les implémentations sont toutes dans le même ordre que celui du tableau, donc il suffit juste de les lire une par une et de les associer à l'instruction correspondante, dans l'ordre. J'ai remarqué que toutes les implémentations se situent dans une section qui commence par "Operations:", donc je peux déjà couper la chaîne jusqu'à cet endroit pour simplifier les choses.
Ensuite, il faut savoir que le regex permet de créer des groupes de recherche, et ainsi retourner plusieurs matchs correspondants à plusieurs groupes. Ma toute première tentative était de créer un regex qui isole ces quatre groupes :


Cela marchait presque bien, mais j'avais des difficultés à détecter la fin du groupe "IMPLEMENTATION", car je me basais sur le caractère "}", mais dans le cas d'un bloc imbriqué (un if { } par exemple) cela coupait la fonction trop tôt. Du coup j'ai modifié un peu les choses pour seulement détecter les 3 premiers groupes. Et ensuite j'utilise un petit algorithme javascript (findLastFunctionBracket()) qui démarre de la fin du dernier groupe (donc juste avant l'implémentation) et calcule la position de l'accolade fermante de la fonction.
Voici le regex, celui-ci est un peu satanique je n'expliquerai pas les détails


Cet algorithme permet donc d'extraire le nom de la fonction, ses arguments, sa description (redondante) et surtout tout le code de son implémentation ! Je peux combiner ces infos avec celles précédentes (la famille et le code de l'instruction) de façon à créer un objet complet et utile informatif sur chacune des instructions :


Après avoir effectué ce processus pour toutes les instructions de tous les instruction sets, je peux sauvegarder ces informations sous un format .json (instructions.json) qui contient les memes informations que le fichier original raw.txt, mais dans un format bien plus pratique pour la suite de l'implémentation !

Il y a juste un détail à prendre en compte:


En fait, ma technique ne marche que pour la moitié du document environ. La seconde moitié des instructions sont liées au DSP (de ce que j'ai compris c'est une unité pour faire des opérations avec des doubles ou fixed-point). Pour une raison quelconque, bien que le format soit exactement le même pour les instructions DSP et non DSP dans le PDF, ma technique de copier/coller tout le document ne fonctionne plus car certains tableaux relatifs aux instructions DSP apparaissent désormais par colonne et non par rangée dans le fichier texte.
Le SDK Casio de base n'utilise jamais ces instructions, cependant gint le fait. Donc je me pencherai sur cette seconde partie plus tard, mon algorithme peut être légèrement réarrangé pour pouvoir gérer ce cas de figure!