if2a team

last update 2005/11/06

Table of Contents
1.1. Introduction
1.2. History
1.3. Hardware status
1.3.1. Linkers status
1.3.2. Cartridges status
1.4. OS status
1.4.1. Linux
1.4.2. Windows
1.4.3. MacOSX
1.4.4. FreeBSD
1.5. License
1.6. Compilation and Installation
1.6.1. Compilation
1.6.2. Binaries
1.6.3. Installation
1.6.4. Flash2Advance USB Linker driver
1.7. Credits
2. FAQ
2.1. My cart is not or badly detected !
2.2. Write and delete roms
2.2.1. Without cart map (and without loader)
2.2.2. With cart map (also called "if2a's easyrom" feature)
2.2.3. Header correction
2.2.4. Pogoshell
2.3. Saves and SRAM management
2.3.1. How to backup all cart sram ?
2.3.2. How to backup a rom save when using Flash2Advance Pro loader (gba-loader 3.2 or 3.3) ?
2.3.3. How to backup a rom save when using PogoShell ?
2.3.4. How to backup a rom save when using PowerWriter's loader ?
2.4. *NIX
2.4.1. Using sudo
2.4.2. I get the annoying message 'Device or resource busy' !
3. Links

All you need to know about your Flash2Advance cart and if2a. Almost.


1.1. Introduction

This is if2a, a command-line utility that allows one to control the Flash2Advance flash carts for the GameBoy Advance. It is based on the original f2a utility, and exists only because there is no official *nix drivers and tools. There is an official website too. The latest version of this document can be found in the documentation section of the website.

if2a generally comes with all the files and binaries needed to use your flashcart (exception for the win32 drivers). The binary files included in if2a can be choosen by copying and editing the Makefiles (see Makefile.defaultconf from sources) if you wish to recompile. We made things so that the good files are already inserted and automatically used according to your hardware. You can use your own files without recompiling if you need to, using the if2a options. Thus, if2a comes alone, generally statically linked, so there is no need to use any external files to make things work (except for win32).

1.2. History

if2a is based on Ulrich Hecht's original f2a who first found the basis of the USB communication protocol with the Flash2Advance USB Linker.

1.3. Hardware status

1.3.1. Linkers status Flash2Advance Parallel cable

Not supported yet. Need to import from original f2a software which was updated in the meantime. Flash2Advance USB Writer

Not supported yet. Need USB protocol hacking.

1.3.2. Cartridges status Flash2Advance Turbo

Seen and working as a Pro cart. Flash2Advance Pro

Full autodetection and support. Tested on 256Mbits cart models (Pro and Pro-B). Flash2Advance Ultra

Full Autodetection, but limited support. At least detected and usable as a Pro cart (tested on 256Mbits models). Ability to download compressed SVD...(?to complete?)

1.4. OS status

1.4.1. Linux

Linux-x86 2.4 and 2.6. Maybe Linux-ppc, to be tested.

For linux-x86 < 2.4.19, EZUSB2131 is needed.

1.4.2. Windows

Depends on libusb-win32. Working with windows 98se, 2k and XP. Not tested with Windows 95/98(not se)/me) yet (as of libusb-win32-, libusb-win32-0.1.10 is not working).

1.4.3. MacOSX

Support for Pro carts in version if2a-0.94.1.

1.4.4. FreeBSD

Reported to work.

1.6. Compilation and Installation

1.6.1. Compilation

if2a needs libusb or libusb-win32, gcc and GNU Make. If libusb is installed on your system, nothing more might be needed. If libusb is built by your own and is not installed in usual places, three variables can help to tell Makefile where to find the good files. They are LIBUSBPATH, LIBUSBINCL and LIBUSBLIB.

  • LIBUSBPATH is the directory which contains libusb[-win32] sources in which case the other variables are useless. The value could be ./libusb-0.1.10a or /opt/libusb (or even /usr but this one is luckily automatically used if valid). You can also specify the two directories in which usb.h and libusb.a can be found:

  • LIBUSBINCL is the directory which contains usb.h.

  • LIBUSLIB is the directory which contains libusb.a.

There are several ways to set these variables, here are some examples:

  • export LIBUSBPATH=/usr/local in Bourne shell environments

  • setenv LIBUSBPATH /usr/local in C-Shell environments

  • make if2a LIBUSBINCL=/usr/local/include/libusb/ LIBUSBLIB=/usr/local/lib/libusb/ directly in the make command.

You might also need to read/edit the Makefile. Unfortunately there is no autoconf/automake scripts for if2a. Note that Win32 needs cygwin (msys+mingw not tested yet). Ability to cross compile win32 binaries (edit Makefile to setup your compiler, libusb-win32 is needed).

1.6.2. Binaries

You can find various binaries in the download section on the if2a website. Roni has also made a site dedicated to if2a on OSX.

1.6.3. Installation

There is no installation process. if2a is a unique executable file that you may copy wherever you like. The command line description is documented here (ahem) or when if2a is launched without any arguments.

1.6.4. Flash2Advance USB Linker driver General

The Flash2Advance USB linker is a USB cable fitting in your computer on one side and in yourt GBA in the other side. It contains a an2131 microcontroler (8051 based) (more informations on http://www.linux-usb.org/ezusb. The driver consists in two parts. The first part uploads a program into the cable's an2131 chip. The USB cable then renumerates (ie: changes its USB IDs according to the new program in it). Then a second driver is needed to talk to this new device.

Under windows with the official Flash2Advance installer, these two drivers are automatically used once the cable is plugged. In if2a and under any OS, the easiest way was to let if2a itself do the job. If if2a detects unconfigured things (cable has just been plugged in), it will upload the new program into the cable chip, then a short while later (renumeration) it detects the configured cable and can use the regular USB driver. Portability has been possible thanks to the great libusb.

if2a is then able to upload the GBA-side driver into the GBA, and play with your flash cart's bits.

It is a bit more complex under windows, since it is harder to access to an USB device without having a "proper win32 driver". The libusb-win32 project helps our open world in the way that they added to libusb a fake "proper win32 driver" that allows a userland program to directly talk to a USB device. It is not that simple to install though, Cory explains us how to install these fake drivers in the next section. Windows USB driver installation notes Introduction

Due to changes in the LibUSB, this driver will not work with later versions than libusb-win32 v0.1.8.0. We/I are/am working on getting the later versions compliant for all the best in the bugfixes that they have to offer. Thanks to the LibUSB project for providing such a great (free) win32 lib for USB devices. questions? comments? praise? I can be contacted by mail, or others of the if2a project may even be willing to help/take some praise :) libusb can be found on sourceforge (see credits). Win32 (98se, 2k, XP) installation package can be downloaded there. Warnings

This has only been tested on Windows XP Pro SP2 by myself (cory) and Windows 98se (spooo) at this point, there are possible issues when trying to use under non-winNT based Windows systems (Windows 95, Windows 98 (not se), Windows ME). It's use at your own risk/discretion for these systems. Report any successes with this on older windows to me by mail. Now to the grit, the install (you should not have to restart the PC during this install, as libusb filter does a usb restart): Driver Installation

  • 1) IMPORTANT: you MUST use a different usb plug-in than the one you use with PowerWriter or REMOVE PowerWriter's drivers COMPLETELY from the system. To do so:

    If you use(d) PowerWriter of f2aw31 and have no open usb plug-ins you need to remove the drivers for it:

    • Windows 2k, XP

      • a- START / control panel / system / hardware(tab) / device manager (button) The device manager should now pop up.

      • b- Under view select "Show Hidden Devices". (if its not available you will need to plug in the usb linker to see its drivers)

      • c- In the device list you should see an entry for "Universal Serial Bus controllers" expand this entry to see the devices that are installed to it.

      • d- There will be 2 drivers for Flash 2 Advanced power writer right click on each one and select uninstall.

      Once they are both removed or confirmed to no longer exist in the device manager proceed to 2)

    • Windows 98se. The installation process looks like the 2k/XP one but I (spooo) did not succeed in removing the former drivers before installing those from libusb. So you need to install libusb before, see step 2). Then you have to "upgrade" the existing drivers:

      • a- START / control panel / system / hardware manager tab The device manager should now pop up. Plug your cable now.

      • b- The f2a device driver should appear (check also in the usb host controler). If it does not appear and windows asks for a driver disk (it should happen if you have no f2a drivers already installed), jump to 3)a.

      • c-Select it, then "Properties" then "Driver" tab, and "Driver upgrade". Then jump to 3)b.

  • 2) run the "libusb-win32-filter-bin-" and follow the instructions. - you do not need to install the SDK or source files for this application.

  • 3) plug in the usb linker, and wait for a bit while windows detects it. If you have auto install drivers turned on, it will install whatever it thinks is right, and you will have to go into the device manager and select the driver it installed, right click on it and select update and follow the procedure below with the first "On the next screen".

    • a- ONCE windows autodetects the USB device, it will ask you if you want to autoinstall drivers Select No, not at this time and press next.

    • b- On the next screen select Install from a list or specified location and press next.

    • c- On the next screen select Dont Search. I will choose the driver to install. Press next.

    • d- Click on Have Disk.

    • e- Click on browse.

    • f- Find where you extracted this archive to and enter the if2ausbXP directory, it will select libusb.inf, press open. (for me the path is C:\Documents and Settings\Cory\Desktop\libusbwinxpf2a\if2ausbXP)

    • g- Press OK

    • h- "if2a USB linker, Version 02/15/2004," should be the only entry in the list press next.

    • i- When it asks about driver signing, press continue anyway.

    • j- It will copy some files over and will tell you its complete, press finish.

    • k- Now you need to run if2a.exe with a command to get it to attempt to link, dont worry, the error is expected, there are 2 drivers to install - the linker and the writer drivers. (a good command to use is "if2a.exe -u file.svd" - without the quotes of course)

    • l- After seeing the error,

      • 2k/XP: windows will now realize that there is yet another device to install. The error is this: usb_control_msg: error sending control message: win error: The device is not connected. an2131: could not start chip Unable to connect to F2A linker.

      • 98se: if an old driver is already installed or windows does not complain (but if2a may be unhappy), you need to go back to step 1)b and process to the installation of the second driver. Otherwise, continue with m- below.

    • m- Now that windows has seen the new device, follow the above steps a- through f- again.

    • n- "if2a USB writer, Version 02/15/2004," should be the only entry in the list press next.

    • o- When it asks about driver signing, press continue anyway.

    • p- It will copy some files over and will tell you its complete, press finish.

    Thats it. Now if2a will link to you GBA and be able to read/write the f2a cart.

1.7. Credits

Ulrich Hecht - original f2a creator.

Eli Curtz - Initial OSX port and f2a linker multiboot protocol.

Julien Janier - Linux-x86 2.6 USB initial port.

Vince - if2a development, f2au hacking, f2a firmware and loaders extraction and related scripts, if2a website creator & maintainer.

Cory - win32 tests, if2a's libusb-win32 driver installer and installation howto, f2a loader extraction.

Chris - if2a MacOSX port.

spooo - if2a development.

r0ni - OSX builds.

Stephan Meyer (from the libusb-win32 team) for his ultra portable an2131 usb loader.

libusb and libusb-win32 projects teams.

devkitpro project team for their gbafix program.

Special thanks to Nintendo and the Flash2Advance team.

2. FAQ

In all the following examples, the option -d will be used. It tells to if2a not to write anything. If you want to write, don't use this option.

2.1. My cart is not or badly detected !

It seems that recent ultra carts need a recent multiboot program (the one loaded onto the GBA for I/O operations on carts). If nothing works (for instance Unknown cart displayed on GBA), an alternate multiboot program maybe tried. Inside the binaries version of if2a, two of them are available:

$ ./if2a -B list
if2a - http://if2a.free.fr
Available internal files for F2A-usb-linker-multiboot:
	0 = binware/multiboot-f2a-usb-v2.4b.mb (22528 bytes)
	1 = binware/multiboot-f2a-usb-v2.6bU.mb (23552 bytes)
	or  name = any external file name

The first one (0=) is the latest version which works properly with pro carts. These are not correctly detected with the latest multiboot program (1=) (got from PowerWriter 2.61). Recent ultra carts (any size, from 256Mbits to 2Gbits) need this last version:

if2a -B 1 other options...

Old pro cart users may try the latest multiboot program with if2a since if2a tries and corrects the cart detection. Use this feature at your own risk (but it works at least for my two 256Mbits pro carts :-).

If you need to change the default behaviour of if2a (to use -B 1 by default), you need to get the sources, copy Makefile.defaultconf to Makefile.conf, edit it and recompile.

2.2. Write and delete roms

You might need a loader. Several loaders are internally available in if2a. You can see them with the following command. You need either to plug your GBA in so to automatically detect the flashcart type or to specify your flashcart type with the -t option.

if2a -L list
From if2a-0.94, a minimal version of PogoShell is included in the loaders, with almost nothing in the filesystem, so to have a small and very powerfull loader which perfectly works with f2apro carts. This loader can also be used with f2a ultra carts (option -L 1). If you want to use your own Pogoshell build, just specify it with the -L option (see the Pogoshell paragraph).

2.2.1. Without cart map (and without loader)

Let's suppose you have rom1.gba, rom2.gba and rom3.gba. The following command will put them into your cart (the loader will be automatically included).

if2a -d -W rom1.gba rom2.gba rom3.gba
If you need to add rom4.gba later, you need the three other files:
if2a -d -W rom1.gba rom2.gba rom3.gba rom4.gba
if2a will not rewrite rom1.gba through rom3.gba. Update: the if2a-0.94.2 built the cartmap with this -W option. This is no longer the case since if2a-0.94.3. Read about the cartmap in the next paragraph.

For the loader not to be automatically inserted in the beginning of the cart, (ex: a single flashme.gba or a nds roms to be burned), use the option -n:

if2a -d -W -n rom1.gba rom2.gba rom3.gba rom4.gba

2.2.2. With cart map (also called "if2a's easyrom" feature)

A flexible way to manage roms has appeared in if2a-0.94. Roms can be added with option -A and removed with option -X. For each operation, a rom map is maintained in the cart just after the loader. To be able to use them if no cartmap is present on your cart, you need to tell if2a to build one. The option -Y will do this:

if2a -d -Y -A mynewrom.gba -A "my other new rom.gba" -X myoldbuggyhomebrewprogram -A "my new corrected program.gba,showed name in loader"
The -Y option will forget any older cartmap from the cart. It will rebuild a new one according to the command line. Then you can add / remove roms:
if2a -d -A anotherrom.gba -X "showed name in loader"
As you can see, this is flexible. if2a will tell you whether what you want to do is possible. If names contain spaces, you need to double quote. You can change the rom name specifying it after the comma like in the example.

Note: one cannot build a map from scratch according to what's already existing in cart. If you already have roms in cart, they cannot be taken into account in the "easyrom" cartmap unless they are reburned using the -Y / -A options.

2.2.3. Header correction

By default, headers are gba-ly automatically corrected. If this is unwanted, use the option -H:

if2a -d -H -W -n rom1.nds.gba rom2...

2.2.4. Pogoshell

Pogoshell is usable in conjunction with the easyrom feature. By default (for Pro carts), a minimal version of pogoshell is used as the default loader. This can be changed by the -L option. The first time you can do (with optional -A / -X options, see above):

if2a -d -Y -L flashme.gba
Then you can add or remove roms using if2a and without the need to rebuild a new pogoshell everytime (see above). Your pogoshell will see them in the cartrom/ directory. Note: you cannot remove a rom which is inside pogoshell using if2a.

In case you prefer not using the if2a easyrom feature, you still can do:

if2a -d -W -n flashme.gba

2.3. Saves and SRAM management

2.3.1. How to backup all cart sram ?

The command is:

if2a -d -b all -r all-sram.bin
According to your cart type, it will create 256KB (f2apro) or 128KB (f2au) file. The option -r tells if2a that the SRAM is to be read.

2.3.2. How to backup a rom save when using Flash2Advance Pro loader (gba-loader 3.2 or 3.3) ?

First check which sram bank is used by your rom. By default, the first four banks use 64KB each which are designed as bank 1, 2, 3 or 4 and they refer respectively to the rom number 1, 2, 3 or 4. If you play with Select, B, R or L in the loader, you can change the sram bank used for the rom. The bank used takes names like '1a' or '2b3'. You must use these names with the -b option in if2a:

if2a -d -b 2b3 -r myromsave.bin
You can restore it back to GBA with:
if2a -d -b 2b3 -w myromsave.bin

2.3.3. How to backup a rom save when using PogoShell ?

There is no automatic way to backup a particular save rom when using PogoShell yet. What can be done is to save everything, or if you need to backup a particular rom's sram, you can start this rom with PogoShell (using its save) then power-off the GBA. PogoShell will have make an expanded copy of the rom save in the first 64Ko bank of the sram cart. You can then back it up with the command:

if2a -d -b 1 -r mysamerom.bin
To restore it back to the cart, you should start again the rom from PogoShell, then power-off the GBA, then write the sram data with:
if2a -d -b 1 -w mysaverom.bin
Then power-on PogoShell back, it will ask if the save rom has to be saved, answer yes.

IMPORTANT NOTE: before doing this, you should make a whole backup of your sram.

2.4. *NIX

2.4.1. Using sudo

if2a needs to be run as "root" so that it can access the usb devices. You might be interested in staying who you really are when using if2a. In order to do that, you can use the sudo program that temporarily gives the root power to a normal user for a specific command. You need to have this program (often included in a packaged called sudo) installed on your machine and if2a copied in /usr/local/bin (where it should usually be). Then you need to edit the file /etc/sudoers, and to add the following line:

myself	ALL=NOPASSWD:/usr/local/bin/if2a
(where "myself" is your account login). Then you will be able to do, beeing yourself:
sudo if2a [command and options]

2.4.2. I get the annoying message 'Device or resource busy' !

This happens under Linux with some distributions that include the usbtest module in the kernel configuration. This module is automatically loaded by hotplug when the linker renumerates, and prevents if2a from using the cable.

The error message looks like this:

usb_set_configuration: could not set config 1: Device or resource busy
To check if it is really usbtest that messes things up, try the command dmesg|tail, here it says:
usb 1-2.4: usbfs: interface 0 claimed by usbtest while 'if2a' sets config #1
This module can be unloaded (as root) with the command rmmod usbest then if2a can be restarted. For future use, you can add the word usbtest at the end of the file /etc/hotplug/blacklist, this will prevent hotplug from loading this module.

3. Links