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