1.\" Copyright (c) 2015-2016 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 data
212Write
213.Ar data
214as a word to
215.Ar register .
216.It Cm x/1 Ar address Op Ar count
217.It Cm x/2 Ar address Op Ar count
218.It Cm x/4 Ar address Op Ar count
219Examine
220.Ar count
221bytes
222.Pq Ql /1 ,
223halfwords
224.Pq Ql /2 ,
225or words
226.Pq Ql /4
227from
228.Ar address .
229If
230.Ar count
231is not specified, examine 16 bytes, 8 halfwords, or 4 words.
232.El
233.Sh ENVIRONMENT
234.Bl -tag -width Ds -compact
235.It Ev XDG_CONFIG_HOME
236The location where
237.Nm
238will look for the configuration directory.
239If not set,
240.Pa ~/.config
241is used.
242.El
243.Sh FILES
244.Bl -tag -width Ds -compact
245.It Pa $XDG_CONFIG_HOME/mgba/config.ini
246Default
247.Nm mgba
248configuration file.
249.It Pa portable.ini
250If this file exists in the current directory,
251.Nm
252will read
253.Pa config.ini
254from the current directory instead of
255.Pa $XDG_CONFIG_HOME/mgba .
256.El
257.Sh AUTHORS
258.An Jeffrey Pfau Aq Mt jeffrey@endrift.com
259.Sh HOMEPAGE
260.Bl -bullet
261.It
262.Lk https://mgba.io/ "mGBA homepage"
263.It
264.Lk https://github.com/mgba-emu/mgba "Development repository"
265.It
266.Lk https://github.com/mgba-emu/mgba/issues "Bug tracker"
267.It
268.Lk https://forums.mgba.io/ "Message board"
269.El