Comment documenter une spécification de format de fichier [fermé]

Pour un projet, je dois travailler avec différents types de fichiers provenant d'anciens jeux et logiciels associés - fichiers de configuration, sauvegardes, archives de ressources, etc. La plupart d'entre eux ne sont pas encore documentés, et il n'existe pas d'outils pour les utiliser, donc je dois inverser l'ingénierie des formats et créer mes propres bibliothèques pour les gérer.

Bien que je ne suppose pas qu'il y ait une grande demande pour la plupart, j'ai l'intention de publier les résultats de mes efforts. Existe-t-il des normes acceptées pour documenter les formats de fichiers? En regardant autour de vous, plusieurs styles sont utilisés: certains, comme la spécification du format de fichier .ZIP , sont très verbeux; d'autres, comme ceux sur XentaxWiki, sont beaucoup plus concis - je trouve certains d'entre eux difficiles à lire; celle que j'aime le mieux est cette description du système de fichiers de carte mémoire PlayStation 2 , qui comprend à la fois un texte descriptif détaillé et plusieurs `` cartes mémoire '' avec décalages et autres - elle correspond également le mieux à mon cas d'utilisation. Cela variera un peu pour différents formats, mais il semble qu'il devrait y avoir des principes généraux que je devrais essayer de suivre.

Edit: il me semble que je n'ai pas très bien expliqué ce que je veux faire. Permettez-moi de construire un exemple.

Je peux avoir un vieux logiciel qui stocke sa configuration dans un fichier `` binaire '' - une série de champs de bits, d'entiers, de chaînes et tout le reste collés et compris par le programme, mais pas lisibles par l'homme. Je déchiffre cela. Je souhaite documenter exactement quel est le format de ce fichier, d'une manière lisible par l'homme, comme spécification pour implémenter une bibliothèque pour analyser et modifier ce fichier. De plus, j'aimerais que cela soit facilement compris par d'autres personnes.

Il existe plusieurs façons d'écrire un tel document. L'exemple PKZIP ci-dessus est très verbeux et décrit principalement le format de fichier en texte libre. L'exemple PS2 donne des tableaux de types de valeurs, de décalages et de tailles, avec des commentaires détaillés sur ce qu'ils signifient tous. Beaucoup d'autres, comme ceux sur XentaxWiki, ne listent que les types et tailles de variables, avec peu ou pas de commentaires.

Je demande s'il existe une norme, semblable à un guide de style de codage, qui fournit des conseils sur la façon d'écrire ce type de documentation. Sinon, y a-t-il un excellent exemple bien connu que je devrais imiter? Sinon, quelqu'un peut-il au moins résumer quelques conseils utiles?

documentation reverse-engineering

— Sopoforic
source

i.stack.imgur.com/4illz.jpg -> stackoverflow.com/a/769443/839601

— moucheron

Ha! Je connais ce sentiment. Un format que je regardais, j'avais en fait le code source d'origine qui a écrit le fichier. Le problème était que les variables étaient écrites dans un ordre différent de celui de la définition de la structure, avec quelques éléments supplémentaires saupoudrés entre les deux. Et les commentaires étaient faux sur les compensations. Cela fait partie de ce qui a inspiré cette question - un fort désir de NE PAS FAIRE CELA.

— Sopoforic

Ma seule expérience avec les types de fichiers d'ingénierie inverse documentés est de wiibrew.org. Si je me souviens bien, ils ont documenté le fichier comme struct. Cela a très bien fonctionné.

— MetaFight

Je peux mal comprendre la question, mais il semble que vous recherchiez quelque chose comme EBNF .

@MattFenwick: BNF sert à spécifier la syntaxe d'une langue; pas tout à fait ce que je recherche. Je vais modifier pour être plus clair sur le type de format de fichier que je veux dire.

— Sopoforic

Réponses:

Un fichier binaire n'est qu'une séquence de bits disposés en unités logiques selon certaines règles . Ces règles sont généralement appelées grammaire . La grammaire peut être classée en quatre types (la hiérarchie de Chomsky ), et pour les grammaires hors contexte, vous devez utiliser la forme Backus-Naur étendue comme l'a souligné Matt Fenwick dans son commentaire. L'interprétation (ou la sémantique) de la séquence stockée dans le fichier peut être décrite verbalement ou à l'aide d'exemples de programmes bien annotés sérialisant et désérialisant les informations.

Pour en savoir plus sur la documentation des formats de fichiers binaires, suggérez de lire par exemple la norme ASN.1 .

— Chasseur de cerf
source

Techniquement , la plupart des fichiers de configuration ont un langage sans contexte, car ils ont un langage fini. Pratiquement, l'écriture de «l'ensemble de toutes les chaînes de 2 octets» (par exemple pour un fichier de configuration qui n'est qu'un champ de bits de 16 éléments) dans EBNF n'enseigne rien à personne. Le pointeur vers la norme ASN.1 est la chose la plus proche d'une réponse que j'ai obtenue, bien qu'il semble qu'une spécification dans ASN.1 soit destinée à être lue par des ordinateurs, et je voulais des informations pour écrire de la documentation pour les humains. Cependant, si rien ne correspond plus à mes besoins, sous peu, j'accepterai cette réponse. Merci pour votre aide.

— Sopoforic

C'est étrange car une recherche rapide des formats de fichiers a fait apparaître un article Wikipedia (Liste des formats de fichiers) . Il comprend également plusieurs formats de données de jeux vidéo .

Liste des formats de fichiers courants de données pour les jeux vidéo sur les systèmes qui prennent en charge les systèmes de fichiers, le plus souvent les jeux PC.

Il comprend également une large sélection de formats de supports de stockage de jeux vidéo .

Liste des extensions de nom de fichier les plus courantes utilisées lorsque l'image ROM ou le support de stockage d'un jeu est copié d'un périphérique ROM d'origine vers une mémoire externe telle qu'un disque dur à des fins de sauvegarde ou pour rendre le jeu jouable avec un émulateur. Dans le cas d'un logiciel à cartouche, si l'extension spécifique à la plate-forme n'est pas utilisée, les extensions de nom de fichier ".rom" ou ".bin" sont généralement utilisées pour préciser que le fichier contient une copie du contenu d'une ROM. Les images ROM, disque ou bande ne se composent généralement pas d'un seul fichier ou d'une ROM, mais plutôt d'un fichier entier ou d'une structure ROM contenue dans un seul fichier sur le support de sauvegarde.

Existe-t-il des normes acceptées pour documenter les formats de fichiers?

Il n'y a de norme "officielle" nulle part. Étant donné que les formats de fichiers sont créés par une entreprise, l'entreprise décide du format de la documentation.

— Adam Zuckerman
source

Je pense que vous avez mal compris ma question. Bien sûr, il existe de nombreux formats de fichiers qui ont été documentés - j'ai mentionné XentaxWiki, qui en contient plus de 1500. Mais les fichiers qui m'intéressent ne sont souvent pas documentés - des choses spécifiques au jeu comme les fichiers de sauvegarde ou la configuration, plutôt que les formats de conteneurs généraux, généralement. Ma situation est qu’il n’existe aucune documentation et j’ai l’intention d’en écrire - alors comment procéder?

— Sopoforic

De la même manière, tous ces autres formats de fichiers ont été documentés.

— Robert Harvey

@RobertHarvey: déroutant, conflictuel, inexact et incomplet? Sérieusement, cependant, comme je l'ai mentionné, j'ai noté plusieurs styles généraux différents. Je ne connais pas suffisamment le travail dans ce domaine pour savoir si un style particulier doit être préféré. Ceux sur XentaxWiki, la plus grande ressource unique que j'ai vue, sont presque exclusivement destinés aux formats de conteneurs, donc ils ne correspondent pas tout à fait au cas plus général. Si je pensais que choisir un exemple aléatoire à émuler serait suffisant, je ne demanderais pas conseil.

— Sopoforic

@Sopoforic: Ensuite, vous devez être plus clair dans votre question sur ce que vous voulez. Vous nous demandez sérieusement "Comment puis-je écrire de la documentation pour un format de fichier?" Il existe des programmes d'enseignement complets sur la rédaction technique qui sont consacrés à ce sujet. Trouvez un format qui contient une documentation claire et bien écrite (selon vos normes personnelles) et émulez-le. Ils ne peuvent pas tous être de la merde. Astuce: les exemples d'utilisation sont roi. La clarté de l'explication vient juste après.

— Robert Harvey

@RobertHarvey: Oui, tout comme les questions sur la façon de commenter votre code ou de documenter une fonction, je recherche un «guide de style» pour écrire une spécification de format compréhensible. Si je veux savoir comment écrire un RFC, je peux regarder le RFC 2223. Si je veux savoir quel style utiliser dans le code Python, je peux lire PEP 8. Si je veux savoir comment poser des questions de manière intelligente, ESR m'a couvert. Existe-t-il des conseils similaires pour les spécifications de format de fichier? Ou un excellent exemple bien connu d'un? Je peux sûrement utiliser mon propre jugement, mais si une norme existe, il serait judicieux de la suivre.

— Sopoforic