Gbfs

[Dr.Vince]

GBFS: Le tutoriel
Auteur: xFlash

I-Introduction

-Qu'est-ce-que GBFS?

GBFS est un système d'accès a des fichiers sur votre Gameboy. En effet la GBA ne possède pas de FileSystem(FS) et on n'accède à la mémoire de nos cartouches que sous la forme d'un énorme bloc mémoire accessible depuis 0x08000000h

-Pourquoi utiliser un système de fichiers?

Utiliser un tel système possède plein d'avantages dans le developemment sur GBA. Cela evites les transformations ou convertions de bon nombre des ressources (gfx/sfx/map/dialogue/...) necessaires au projet, car on les inclut directement, tel quel, sans changement. Adieu les bin2h, bin2obj ,...
Cela implique aussi des gains de temps dans les phases de compilation, car on evite les conversions/transformations de ses ressources lorsqu'on les modifie.

-Qui a écrit GBFS?

L'auteur de GBFS est Damian Yerrick-
Site internet : PinEight[

-Ou peut-on récupérer ces outils?

Ici : http://www.pineight.com/gba/gbfs.zip
ou ici : Mirroir PA



II-Comment ca marche?

Chaque fichier de données que vous désirez inclure à votre ROM est ajouté à la fin de votre ROM compilé. On accède à ces fichiers à l'aide de fonctions C présentes dans l'API de Damian.
Si on regrade en detail le resultat d'une ROM dans lequel est inclus GBFS et 2 fichiers par exemple, l'on obtiendrait ceci :

La "ROM compilé" est le resultat produit le linker d'un compilo, le fichier .bin ou .gba de votre projet.
Le "Header GBFS" est un fichier produit par l'outil (GBFS.exe fournit dans l'archive) qui decrit les entrées, noms et tailles de chaque fichiers inclus
Les Fichiers "TXT01.DLG" et "TXT02.DLG" sont les fichiers de ressources désirés


III-Comment l'inclure dans mon projet?

- Exemple

Imaginons que tel l'exemple précédent, vous ayez besoin d'inclure des fichiers de dialogues à longueur évidemment variable dans le temps et pour lequels, vous voulez y accéder depuis votre code.
Attention ceci est une exemple, vous pourrez tout aussi bien le faire avec des fichiers d'images, sons, map, etc.

- Procédure

Il faut ordonner a Make, plusieurs operations supplementaires :

1. Generer le fichier .GBFS(le Header GBFS precedemment decrit + les fichiers désirés)
2. Aligner la ROM a un pas de 256
3. Inclure les fichiers de ressources

Que vous utilisez HAM ou non, la procedure est la meme. Je partirais d'un makefile issu d'un projet de HAM, car je vous sais nombreux à l'utiliser. Pour les autres, vous connaissez certainement très bien votre makefile et son langage, donc la modif ne devrait pas vous poser de soucis.

- Les modifications du makefile

Dans votre makefile, vous aviez avant une entrée du style:

Code PHP:


all : $(PROGNAME).$(EXT) 


Avec GBFS, Make ne doit pas s'arréter une fois la cible $(PROGNAME).$(EXT) générée.
Aussi on éditera le makefile ainsi:

Code PHP:


OFILES += $(GBFS_HOME)\libgbfs.o
INCDIR += $(GBFS_HOME)
DAT_FILES = dlg\TXT02.DLG dlg\TXT02.DLG

$(PROGNAME).gbfs:
@$(GBFS_HOME)\tools\gbfs.exe $(PROGNAME).gbfs $(DAT_FILES)

$(PROGNAME)_GBFS.$(EXT): $(PROGNAME).$(EXT) $(PROGNAME).gbfs
@$(GBFS_HOME)\tools\padbin 256 $(PROGNAME).$(EXT)
@copy /b $(PROGNAME).$(EXT)+$(PROGNAME).gbfs $(PROGNAME)_GBFS.$(EXT)

all : $(PROGNAME)_GBFS.$(EXT) 


Vous remarquerez plusieurs choses:

- GBFS_HOME est une variable d'environnement contenant le chemin d'acces à votre distribution de GBFS décompressé.
- On rajoutes aux aobjet a compiler et a linker la librairie de gbfs
- GBFS.exe est l'outil qui vous générera un fichier .gbfs dans le repertoir de votre projet contenant une entete GBFS et les 2 fichiers de datas désirés. C'est ce qui est encadré en gris dans mon exemple plus haut.
- PADBIN.exe est un outil permettant d'aligner votre ROM a une valeur multiple de 2. Ils remplit le trou restant avec des 00. Ceci etant necessaire car le code de GBFS scanne la ROM de manière optimale avec une plage a 256. Explication de l'auteur :

Envoyé par Damian

Note that this does a slow linear search at 256-byte strides, so make sure that your files are aligned to 256-byte boundaries and that you pass a start location close to (but not past) the beginning of the GBFS file.

De plus cette operation peut etre faite avec d'autres outils. Personnellement j'utilise GBAFIX de DarkFader permettant en plus de fixer le nom de la ROM dans la meme operation.
- La copie binaire concatène simplement la ROM et le fichier GBFS ensemble dans un nouveau fichier
- Ne pas oublier d'inclure

- Utilisation de GBFS dans le code

Une fois dans votre code, l'utilisation de GBFS est assez simple. La complexité réside plus dans ce que vous allez faire de la ressource incluse, ex: Décompression, lecture de BMP/JPG, ...
Aussi voici un exemple de ce que vous pouvez faire avec l'exe^mple precedent.

Code PHP:


#include <gbfs.h>

#define GBFS_ENTRY_NAME_LGMAX 24

/**
Variables globales
**/
//pointeurs sur données de texte
static const char*   pTxt1 = NULL;
static const char*   pTxt2 = NULL;
//pointeur sur la premiere structure GBFS trouvée
static GBFS_FILE*  pGBFSFile=NULL;

int main()
{
/**
Variables locales
**/
u32  uFileSize, uNbFiles;
char pFileName[GBFS_ENTRY_NAME_LGMAX];

//init
uFileSize = 0;

//on recupere un pointeur sur la structure GBFS cherchée
pGBFSFile = find_first_gbfs_file(find_first_gbfs_file);

//Attention:
// la subtilité ici est d'indiquer a GBFS de commencer sa recherche de la structure
// GBFS ajoutée à la ROM au plus proche de la ou elle pourrait etre.
// on pourrait tout a fait remplacer la ligne par :
// pGBFSFile = find_first_gbfs_file(0);
// auquel cas, GBFS commencerait a chercher depuis le debut de la Memoire
// ce qui pourrait etre très très lent...
// aussi on lui donne l'adresse de la fonction find_first_gbfs_file qui en memoire
// est l'une des derniere ajoutées a la ROM compilé donc une bonne estimation du
// plus proche endroit de la structure recherchée...
 
//on peut recuperer le nombre de fichiers presents
uNbFiles = gbfs_count_objs(pGBFSFile);

//recuperation pointeur sur le premier fichier par son nom
pTxt1 = gbfs_get_obj(pGBFSFile, "TXT01.DLG", &uFileSize);

// on peut recuperer le 2eme fichier par son ordre dans la structure
pTxt2 = gbfs_get_nth_obj(pGBFSFile, 1, pFileName, &uFileSize);

//On peut a partir de la manipuler les données de notre fichier comme on le désire
//...

return 0;
} 


IV-Autres choses?

Ne pas oubliez avec GBFS:

• Le padding de la ROM a 256
• Inclure libgfs.o en tout dernier lieu dans la chaine du linker
• Les sources de GBFS sont fournies!! N'hesitez pas a y jeter un oeil. C'est assez instructif
• Remercier l'auteur Damian Yerrick
• Poser des questions ici, si vous avez des doutes.

[greg15]

Merci pour ces explications