1.\" Copyright (c) 2015 Anthony J. Bentley <anthony@anjbe.name>
  2.\"
  3.\" This Source Code Form is subject to the terms of the Mozilla Public
  4.\" License, v. 2.0. If a copy of the MPL was not distributed with this
  5.\" file, you can obtain one at https://mozilla.org/MPL/2.0/.
  6.Dd July 29, 2015
  7.Dt MGBA 6
  8.Os
  9.Sh NAME
 10.Nm mgba
 11.Nd Game Boy Advance emulator
 12.Sh SYNOPSIS
 13.Nm mgba
 14.Op Fl 123456dfg
 15.Op Fl b Ar biosfile
 16.Op Fl c Ar cheatfile
 17.Op Fl l Ar loglevel
 18.Op Fl p Ar patchfile
 19.Op Fl s Ar n
 20.Op Fl v Ar moviefile
 21.Ar file
 22.Sh DESCRIPTION
 23.Nm
 24is a Game Boy Advance emulator.
 25The options are as follows:
 26.Bl -tag -width Ds
 27.It Fl 1
 28Scale the window 1\(mu.
 29.It Fl 2
 30Scale the window 2\(mu.
 31.It Fl 3
 32Scale the window 3\(mu.
 33.It Fl 4
 34Scale the window 4\(mu.
 35.It Fl 5
 36Scale the window 5\(mu.
 37.It Fl 6
 38Scale the window 6\(mu.
 39.It Fl b Ar biosfile , Fl -bios Ar biosfile
 40Specify a BIOS file to use during boot.
 41If this flag is omitted,
 42.Nm
 43will use the BIOS specified in the configuration file,
 44or a high\(hylevel emulated BIOS if none is specified.
 45.It Fl c Ar cheatfile , Fl -cheats Ar cheatfile
 46Apply cheat codes from
 47.Ar cheatfile .
 48.It Fl d
 49Start emulating via the command\(hyline debugger.
 50.It Fl f
 51Start the emulator full\(hyscreen.
 52.It Fl g
 53Start a
 54.Xr gdb 1
 55session.
 56By default the session starts on port 2345.
 57.It Fl l Ar loglevel
 58Log messages during emulation to
 59.Dv stdout .
 60.Ar loglevel
 61is a bitmask defining which types of messages to log:
 62.Bl -bullet -compact
 63.It
 641 \(en fatal errors
 65.It
 662 \(en errors
 67.It
 684 \(en warnings
 69.It
 708 \(en informative messages
 71.It
 7216 \(en debugging messages
 73.It
 7432 \(en stub messages for unimplemented features
 75.It
 76256 \(en in\(hygame errors
 77.It
 78512 \(en software interrupts
 79.It
 801024 \(en emulator status messages
 81.It
 822048 \(en serial I/O messages
 83.El
 84The default is to log warnings, errors, fatal errors, and status messages.
 85.It Fl p Ar patchfile , Fl -patch Ar patchfile
 86Specify a patch file in BPS, IPS, or UPS format.
 87.It Fl s Ar n , Fl -frameskip Ar n
 88Skip every
 89.Ar n
 90frames.
 91.It Fl v Ar moviefile , Fl -movie Ar moviefile
 92Play back a movie of recording input from
 93.Ar moviefile .
 94.El
 95.Sh CONTROLS
 96The default controls are as follows:
 97.Bl -hang -width "Frame advance" -compact
 98.It A
 99.Cm x
100.It B
101.Cm z
102.It L
103.Cm a
104.It R
105.Cm s
106.It Start
107.Aq Cm Enter
108.It Select
109.Aq Cm Backspace
110.It Load state
111.Cm F1 Ns \(en Ns Cm F9
112.It Save state
113.Ao Cm Shift Ac Ns \(hy Ns Cm F1 Ns \(en Ns Cm F9
114.It Frame advance
115.Ao Cm Ctrl Ac Ns \(hy Ns Cm n
116.El
117.Sh DEBUGGER
118When
119.Nm
120is run with the
121.Fl d
122option, the command\(hyline debugger is enabled.
123It supports the following commands:
124.Pp
125.Bl -tag -compact -width 1
126.It Cm b Ns Oo Cm reak Oc Ar address
127.It Cm b Ns Oo Cm reak Oc Ns Cm /a Ar address
128.It Cm b Ns Oo Cm reak Oc Ns Cm /t Ar address
129Set a breakpoint \(en ARM
130.Pq Ql /a ,
131Thumb
132.Pq Ql /t ,
133or the current CPU mode \(en at
134.Ar address .
135.It Cm c Ns Op Cm ontinue
136Continue execution.
137.It Cm d Ns Oo Cm elete Oc Ar address
138Delete a breakpoint at
139.Ar address .
140.It Cm dis Ns Oo Cm asm Oc Op Ar address Op Ar count
141.It Cm dis Ns Oo Cm asm Oc Ns Cm /a Op Ar address Op Ar count
142.It Cm dis Ns Oo Cm asm Oc Ns Cm /t Op Ar address Op Ar count
143.It Cm dis Ns Oo Cm assemble Oc Op Ar address Op Ar count
144.It Cm dis Ns Oo Cm assemble Oc Ns Cm /a Op Ar address Op Ar count
145.It Cm dis Ns Oo Cm assemble Oc Ns Cm /t Op Ar address Op Ar count
146Disassemble
147.Ar count
148instructions starting at
149.Ar address ,
150as ARM
151.Pq Ql /a ,
152Thumb
153.Pq Ql /t ,
154or the current CPU mode.
155If
156.Ar count
157is not specified, only disassemble the instruction at
158.Ar address .
159If
160.Ar address
161is not specified, only disassemble the current address.
162.It Cm h Ns Op Cm elp
163Print help.
164.It Cm i Ns Op Cm nfo
165.It Cm status
166Print the current contents of general\(hypurpose registers and the current
167program state register, and disassemble the current instruction.
168.It Cm n Ns Op Cm ext
169Execute the next instruction.
170.It Cm p Ns Oo Cm rint Oc Ar value ...
171.It Cm p Ns Oo Cm rint Oc Ns Cm /t Ar value ...
172.It Cm p Ns Oo Cm rint Oc Ns Cm /x Ar value ...
173Print one or more
174.Ar value Ns s
175as binary
176.Pq Ql /t ,
177hexadecimal
178.Pq Ql /x ,
179or decimal.
180.It Cm q Ns Op Cm uit
181Quit the emulator.
182.It Cm reset
183Reset the emulation.
184.It Cm r/1 Ar address
185.It Cm r/2 Ar address
186.It Cm r/4 Ar address
187Read a byte
188.Pq Ql /1 ,
189halfword
190.Pq Ql /2 ,
191or word
192.Pq Ql /4
193from
194.Ar address .
195.It Cm w Ns Oo Cm atch Oc Ar address
196Set a watchpoint at
197.Ar address .
198.It Cm w/1 Ar address data
199.It Cm w/2 Ar address data
200.It Cm w/4 Ar address data
201Write
202.Ar data
203as a byte
204.Pq Ql /1 ,
205halfword
206.Pq Ql /2 ,
207or word
208.Pq Ql /4
209to
210.Ar address .
211.It Cm w/r Ar register
212Write a word to
213.Ar register .
214.It Cm x/1 Ar address Op Ar count
215.It Cm x/2 Ar address Op Ar count
216.It Cm x/4 Ar address Op Ar count
217Examine
218.Ar count
219bytes
220.Pq Ql /1 ,
221halfwords
222.Pq Ql /2 ,
223or words
224.Pq Ql /4
225from
226.Ar address .
227If
228.Ar count
229is not specified, examine 16 bytes, 8 halfwords, or 4 words.
230.It Cm \&!\ \&
231Break into the attached debugger.
232.El
233.Sh FILES
234.Bl -tag -width ~/.config/mgba/config.ini -compact
235.It Pa ~/.config/mgba/config.ini
236Default
237.Nm
238configuration file.
239.It Pa portable.ini
240If this file exists in the current directory,
241.Nm
242will read
243.Pa config.ini
244from the current directory instead of
245.Pa ~/.config/mgba .
246.El
247.Sh AUTHORS
248.An Jeffrey Pfau Aq Mt jeffrey@endrift.com
249.Sh HOMEPAGE
250.Bl -bullet
251.It
252.Lk https://mgba.io/ "mGBA homepage"
253.It
254.Lk https://github.com/mgba-emu/mgba "Development repository"
255.It
256.Lk https://github.com/mgba-emu/mgba/issues "Bug tracker"
257.It
258.Lk https://forums.mgba.io/ "Message board"
259.El