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).
if2a is based on Ulrich Hecht's original f2a who first found the basis of the USB communication protocol with the Flash2Advance USB Linker.
Supported.
Not supported yet. Need to import from original f2a software which was updated in the meantime.
Seen and working as a Pro cart.
Full autodetection and support. Tested on 256Mbits cart models (Pro and Pro-B).
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?)
Linux-x86 2.4 and 2.6. Maybe Linux-ppc, to be tested.
For linux-x86 < 2.4.19, EZUSB2131 is needed.
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-0.1.8.0, libusb-win32-0.1.10 is not working).
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.
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 can find various binaries in the download section on the if2a website. Roni has also made a site dedicated to if2a on OSX.
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.
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.
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.
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):
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.
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-0.1.8.0.exe" 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, 0.1.8.0" 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, 0.1.8.0" 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.
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.
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.
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.
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 listFrom 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).
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.gbaIf you need to add rom4.gba later, you need the three other files:
if2a -d -W rom1.gba rom2.gba rom3.gba rom4.gbaif2a 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
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.
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...
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.gbaThen 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
The command is:
if2a -d -b all -r all-sram.binAccording 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.
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.binYou can restore it back to GBA with:
if2a -d -b 2b3 -w myromsave.bin
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.binTo 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.binThen 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.
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]
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 busyTo 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 #1This 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.