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.
167.It Cm n Ns Op Cm ext
168Execute the next instruction.
169.It Cm p Ns Oo Cm rint Oc Ar value ...
170.It Cm p Ns Oo Cm rint Oc Ns Cm /t Ar value ...
171.It Cm p Ns Oo Cm rint Oc Ns Cm /x Ar value ...
172Print one or more
173.Ar value Ns s
174as binary
175.Pq Ql /t ,
176hexadecimal
177.Pq Ql /x ,
178or decimal.
179.It Cm q Ns Op Cm uit
180Quit the emulator.
181.It Cm reset
182Reset the emulation.
183.It Cm r/1 Ar address
184.It Cm r/2 Ar address
185.It Cm r/4 Ar address
186Read a byte
187.Pq Ql /1 ,
188halfword
189.Pq Ql /2 ,
190or word
191.Pq Ql /4
192from
193.Ar address .
194.It Cm w Ns Oo Cm atch Oc Ar address
195Set a watchpoint at
196.Ar address .
197.It Cm w/1 Ar address
198.It Cm w/2 Ar address
199.It Cm w/4 Ar address
200Write a byte
201.Pq Ql /1 ,
202halfword
203.Pq Ql /2 ,
204or word
205.Pq Ql /4
206to
207.Ar address .
208.It Cm w/r Ar register
209Write a word to
210.Ar register .
211.It Cm x/1 Ar address
212.It Cm x/2 Ar address
213.It Cm x/4 Ar address
214Examine bytes
215.Pq Ql /1 ,
216halfwords
217.Pq Ql /2 ,
218or words
219.Pq Ql /4
220from
221.Ar address .
222.It Cm \&!\ \&
223Break into the attached debugger.
224.El
225.Sh FILES
226.Bl -tag -width ~/.config/mgba/config.ini -compact
227.It Pa ~/.config/mgba/config.ini
228Default
229.Nm
230configuration file.
231.It Pa portable.ini
232If this file exists in the current directory,
233.Nm
234will read
235.Pa config.ini
236from the current directory instead of
237.Pa ~/.config/mgba .
238.El
239.Sh AUTHORS
240.An Jeffrey Pfau Aq Mt jeffrey@endrift.com
241.Sh HOMEPAGE
242.Bl -bullet
243.It
244.Lk https://mgba.io/ "mGBA homepage"
245.It
246.Lk https://github.com/mgba-emu/mgba "Development repository"
247.It
248.Lk https://github.com/mgba-emu/mgba/issues "Bug tracker"
249.It
250.Lk https://forums.mgba.io/ "Message board"
251.El