-
Notifications
You must be signed in to change notification settings - Fork 10
/
cinoop.html
891 lines (678 loc) · 32.7 KB
/
cinoop.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, minimum-scale=1.0, maximum-scale=1.0">
<link rel="stylesheet" type="text/css" href="css/core.css" />
<link rel="stylesheet" type="text/css" href="css/prism.css" />
<title>Cinoop</title>
</head>
<body>
<div class="page">
<div class="container">
<div class="header">
<a href="contact.html" class="header-element">
Contact
</a>
<a href="about.html" class="header-element">
About
</a>
<a href="articles.html" class="header-element">
Articles
</a>
<a href="index.html" class="header-element">
Home
</a>
</div>
<h1>Writing a Game Boy emulator, Cinoop</h1>
<span class="date">Initial publication: March 24th, 2015</span>
<hr>
<p>
I've always wanted to write an emulator from scratch, but I've held off for a long time because it's probably the most advanced programming project I've ever wanted to do.
</p>
<p>
Picking a system to emulate isn't an easy choice; the standard first emulator project seems to be a <a href="http://en.wikipedia.org/wiki/CHIP-8">CHIP-8</a> emulator. Reading about CHIP-8 definitely helped me to understand a lot of emulation concepts, but it seemed a bit too basic. I felt that I got enough out of just reading through other people's emulators, and that writing my own would be a pointless exercise.
</p>
<p>
On the other hand, there's the NES and Game Boy; both of which seemed far too advanced for me!
</p>
<p>
Eventually, I decided to write a minimalist Game Boy interpreting emulator, without support for custom mappers or sound, (and probably many inaccuracies). I called the project Cinoop.
</p>
<p>
Cinoop is written in C and is <a href="https://github.com/CTurt/Cinoop">open source</a>. It can be run on Windows, DS, GameCube, 3DS, Linux based OSes, PSP, and PS4.
</p>
<div class="center">
<iframe class="youtube" width="560" height="315" src="https://www.youtube.com/embed/1Sq1B_TefSA" frameborder="0" allowfullscreen></iframe>
</div>
<div class="quote-reference">
- Windows version of Cinoop running Tetris before randomisation support
</div>
<br>
<br>
<p>
While I wouldn't recommend trying to learn about emulation from someone as inexperienced as me, I wanted to outline the process of starting an emulator for the first time, talk about which documents were most helpful to me, and also talk about some of the design choices I went through.
</p>
<br>
<h2>Starting off</h2>
<p>
I used my own library, <a href="https://github.com/CTurt/LDFS">LDFS</a>, to create a window with a valid OpenGL context. A better choice would have been something more standard, and cross-platform, such as <a href="https://www.libsdl.org/">SDL</a>, however, I went with LDFS just because I was familiar with it.
</p>
<p>
I then read through some <a href="http://marc.rawer.de/Gameboy/Docs/GBCPUman.pdf">Game Boy documents</a> to get a better overview of the project. In hindsight, I should have spent much longer doing this so that I wouldn't have to keep looking things up later, but I was excited!
</p>
<p>
Most of the Game Boy specific code that I wrote in the beginning, such as loading a ROM, was based heavily on other emulators. I looked at how two or three different emulators did it, and then wrote it into Cinoop in my own style. It wasn't worth trying to write code on my own just yet, I needed to have a base to work with first, before I could experiment with doing things my own way.
</p>
<br>
<h2>Memory</h2>
<p>
Different sources can refer to memory regions differently. High RAM is sometimes called Zero Page Memory, Cartridge Data is sometimes just called ROM, and if a document just says RAM, it is usually refering to the Working RAM. Being aware of this is essential when reading through documents written by different people.
</p>
<br>
<h2>Registers</h2>
<p>
The Game Boy has eight 8 bit registers: A, B, C, D, E, F, H, and L, as well as two 16 bit registers: SP, and PC. Initially I implemented the registers like so:
</p>
<pre><code class="language-c">struct registers {
unsigned char a;
unsigned char b;
unsigned char c;
unsigned char d;
unsigned char e;
unsigned char h;
unsigned char l;
unsigned char flags;
unsigned short sp;
unsigned short pc;
} extern registers;
</code></pre>
<br>
<p>
While this model is fine for dealing with instructions that access the 8 bit registers individually, what I didn't realise is that often the 8 bit registers are grouped together to form the 16 bit registers: AF, BC, DE, and HL.
</p>
<p>
I revised my register structure to make accessing grouped registers easier:
</p>
<pre><code class="language-c">struct registers {
struct {
union {
struct {
unsigned char f;
unsigned char a;
};
unsigned short af;
};
};
struct {
union {
struct {
unsigned char c;
unsigned char b;
};
unsigned short bc;
};
};
struct {
union {
struct {
unsigned char e;
unsigned char d;
};
unsigned short de;
};
};
struct {
union {
struct {
unsigned char l;
unsigned char h;
};
unsigned short hl;
};
};
unsigned short sp;
unsigned short pc;
} extern registers;
</code></pre>
<br>
<p>
I used C11's anonymous structs and unions so that I could access individual registers, or grouped registers straight from the root structure: <code>registers.a</code> or <code>registers.af</code> for example.
</p>
<p>
This is one of the more unique aspects of my emulator; since most other Game Boy emulators were written in an older C standard, (or an undesirable alternative like C++), they didn't have access to anonymous structs or unions, which meant that they either had to access registers with a messy chain, like <code>gameboy_proc->AF.b.h</code> (this is how <a href="http://www.amidog.com/amiga/gbe/">GBE</a> accesses register a), or rely on bit operations.
</p>
<br>
<h2>Flags</h2>
<p>
The Game Boy has an 8 bit register which controls if the last operation resulted in zero, an underflow, a nibble overflow, or a byte overflow; refered to as the zero flag, the negative flag, the half carry flag, and the full carry flag, respectively.
</p>
<p>
One thing that initially tripped me up, is that I wasn't sure if I should update the flags after every instruction, or after just some, and if so, which ones (and how should I store this information). I eventually came across <a href="http://gameboy.mongenel.com/dmg/opcodes.html">this great piece of documentation</a> which describes in detail which instructions should update the flags, and to what values.
</p>
<br>
<h2>Implementing the CPU</h2>
<p>
Just to get things started, I went with the classic <code>switch(instruction) {</code> approach, in which all instructions are placed in the same function.
</p>
<p>
Whenever an unimplemented instruction was encountered, the register values were written to a debug file, along with the current instruction's hexadecimal value.
</p>
<p>
I chose to use the game <a href="http://en.wikipedia.org/wiki/Tetris_%28Game_Boy%29">Tetris</a> for testing. Upon running it, I got a message telling me "Undefined instruction 0x00!".
</p>
<p>
To confirm that this was right, I ran the game in <a href="http://problemkaputt.de/gmb.htm">NO$GMB</a>, which has an excellent debugger. Sure enough, the first instruction of Tetris is 0x00, which is a <a href="http://en.wikipedia.org/wiki/NOP">NOP</a>.
</p>
<p>
I implemented the NOP instruction, and ran the game again to get the next, unsupported instruction. I continued with this method for a few more instructions, checking each time that the register values displayed by Cinoop matched those in NO$GMB.
</p>
<br>
<h2>Improving instruction handling</h2>
<p>
Looking up each instruction in NO$GMB, or <a href="http://imrannazar.com/Gameboy-Z80-Opcode-Map">an online table</a>, started to get tedious. While I didn't want to write a fully fledged debugger, I wanted something slightly more substantial to work with.
</p>
<p>
I went away from the approach of doing everything directly in an instruction's code, and towards the idea of storing information about each instruction in a structure, so that common tasks could reuse the same code.
</p>
<p>
For example, rather than having each instruction's code responsible for retrieving its operands, I thought it would make more sense to store the operand lengths in the structure, and reuse the same code to retrieve operands for every instruction.
</p>
<p>
I also copied every instruction's disassembly into the structure:
</p>
<pre><code class="language-c">struct instruction {
char *disassembly;
unsigned char operandLength;
void *execute;
//unsigned char ticks;
} extern const instructions[256];
...
const struct instruction instructions[256] = {
{ "NOP", 0, nop }, // 0x00
{ "LD BC, 0x%04X", 2, NULL }, // 0x01
{ "LD (BC), A", 0, NULL }, // 0x02
...
</code></pre>
<br>
<p>
This, in combination with storing the operand lengths, made it incredibly easy to print out the instruction.
</p>
<p>
All I had to do now was run the game, and it would not only tell me the hexadecimal value of the unsupported instruction, but also the full disassembly of it.
</p>
<p>
Running the game now, gave me the message "Unimplemented instruction 0x06 (LD B, 0x00)!". This was all I needed to write the 0x06 instruction, I didn't have to stop and find it in an external program or piece of documentation:
</p>
<pre><code class="language-c">// 0x06
void ld_b_n(unsigned char operand) { registers.b = operand; }
</code></pre>
<br>
<p>
This greatly improved the speed at which I could implement new instructions, and I continued to write most of the CPU this way.
</p>
<p>
I also considered the idea of storing whether an instruction should update certain flags, in the instruction's structure, but decided against the idea because it would just over complicate the system, and would probably cause it to run slower.
</p>
<p>
Implementing the CPU wasn't particularly difficult, it was just time consuming. Most instructions are fairly straight forward, and some are identical other than the target register (<code>INC A</code>, and <code>INC B</code> for example). In addition, there are multiple <code>NOP</code>s (<code>LD A, A</code>, <code>LD B, B</code>, etc...).
</p>
<p>
However, there was one instruction which confused me for a while: <a href="http://www.worldofspectrum.org/faq/reference/z80reference.htm#DAA">DAA</a>, which is used to display the score in Tetris. After looking at several other emulators, I managed to write my own implementation. One thing to note, is that unlike in the original Z80A CPU, the Half Carry flag is always cleared, which makes it a little bit simpler.
</p>
<br>
<h2>Real time debugging</h2>
<p>
Eventually, I realised that running the whole game until I got to an unimplemented instruction was not very flexible.
</p>
<p>
I could tweak the <code>cpuStep</code> function to give me some pseudo breakpoints:
</p>
<pre><code class="language-c">if(registers.pc == 0x300) {
printRegisters();
}</code></pre>
<br>
<p>
But this still wasn't very easy to use. If there was a mistake in one of my instruction implementations, I would want to run the game step by step so that I could find it. To do this, I created a basic, real time debugger, which I could run alongside NO$GMB to check that the instructions were being executed correctly:
</p>
<div class="center">
<img src="images/cinoop/debug.png" />
</div>
<br>
<p>
I was also able to add breakpoints in the <code>readByte</code> and <code>writeByte</code> function, which meant that I could activate a realtime, step by step, debugger on any condition I wanted. In combination with being able to run the game in NO$GMB, this turned out to be sufficient for debugging most problems.
</p>
<br>
<h2>Tilesets</h2>
<p>
Running what seems like an endless list of CPU instructions, to check everything is working, is important, but it becomes dull very quickly. Drawing the tileset would be my first, visual confirmation that Cinoop was actually working well enough to load graphics.
</p>
<p>
I ran Tetris through NO$GMB to see which instructions were copying the tileset into VRAM. The first function to load tiles starts at <code>0x2817</code>, and ends at <code>0x282a</code>.
</p>
<p>
I set a breakpoint in my emulator for the start of the function:
</p>
<pre><code class="language-c">if(registers.pc == 0x2817) {
realtimeDebugEnable = 1;
}</code></pre>
<br>
<p>
Of course, when I ran the emulator, it would exit before reaching this function since I hadn't implemented enough instructions; but I kept working, and eventually the breakpoint triggered! Then there were a few more instructions to implement to get through the function, before I could dump the first tile:
</p>
<pre><code class="language-c">// End of tileset loading function
if(registers.pc == 0x282a) {
FILE *f = fopen("tile0.bin", "wb");
fwrite(vram, 16, 1, f);
fclose(f);
realtimeDebugEnable = 1;
}</code></pre>
<br>
<p>
I compared this with NO$GMB's memory, and the data matched!
</p>
<pre><code>00 00 3c 3c 66 66 66 66 66 66 66 66 3c 3c 00 00</pre></code>
<br>
<p>
The next thing to do was to dump the processed tile as well:
</p>
<pre><code class="language-c">FILE *f = fopen("tile0.txt", "wb");
int x, y;
for(y = 0; y < 8; y++) {
for(x = 0; x < 8; x++) fprintf(f, "%02x ", tiles[0][x][y]);
fprintf(f, "\n");
}
fclose(f);</code></pre>
<br>
<p>
This was the result:
</p>
<pre><code>00 00 00 00 00 00 00 00
00 00 03 03 03 03 00 00
00 03 03 00 00 03 03 00
00 03 03 00 00 03 03 00
00 03 03 00 00 03 03 00
00 03 03 00 00 03 03 00
00 00 03 03 03 03 00 00
00 00 00 00 00 00 00 00</code></pre>
<br>
<p>
To clarify the above image, let's replace "00" with " ", and "03" with "xx":
</p>
<pre><code>
xx xx xx xx
xx xx xx xx
xx xx xx xx
xx xx xx xx
xx xx xx xx
xx xx xx xx
</code></pre>
<br>
<p>
With the confidence that everything was working as it should, I copied the first 8 tiles onto the screen:
</p>
<pre><code class="language-c">int i, x, y;
for(i = 0; i < 8; i++) {
for(x = 0; x < 8; x++) {
for(y = 0; y < 8; y++) {
framebuffer[i * 8 + x + y * 160].r = palette[tiles[i][x][y]].r;
framebuffer[i * 8 + x + y * 160].g = palette[tiles[i][x][y]].g;
framebuffer[i * 8 + x + y * 160].b = palette[tiles[i][x][y]].b;
}
}
}</code></pre>
<br>
<div class="center">
<img src="images/cinoop/tiles.png" />
</div>
<br>
<p>
I let the game run a little bit further, and then copied as many tiles as would fit onto the screen:
</p>
<pre><code class="language-c">// draw tileset to framebuffer as a test
int i;
for(i = 0; i < (144 / 8) * (160 / 8); i++) {
int x;
for(x = 0; x < 8; x++) {
int y;
for(y = 0; y < 8; y++) {
framebuffer[(i * 8 % 160) + x + (y + i * 8 / 160 * 8) * 160].r = palette[tiles[i][x][y]].r;
framebuffer[(i * 8 % 160) + x + (y + i * 8 / 160 * 8) * 160].g = palette[tiles[i][x][y]].g;
framebuffer[(i * 8 % 160) + x + (y + i * 8 / 160 * 8) * 160].b = palette[tiles[i][x][y]].b;
}
}
}</code></pre>
<br>
<div class="center">
<img src="images/cinoop/fullTileset.png" />
</div>
<br>
<h2>Maps</h2>
<p>
My initial attempt at reading maps resulted in this:
</p>
<div class="center">
<img src="images/cinoop/map1.png" />
</div>
<br>
<p>
I'm not sure if this was caused by a problem with the GPU tutorial that I followed, or my implementation, but changing the following line:
</p>
<pre><code class="language-c">mapOffset += ((gpu.scanline + gpu.scrollY) & 255) >> 3;</code></pre>
<br>
<p>
to:
</p>
<pre><code class="language-c">mapOffset += (((gpu.scanline + gpu.scrollY) & 255) >> 3) << 5;</code></pre>
<br>
<p>
fixed the problem. My emulator could now reach the copyright screen of Tetris!
</p>
<div class="center">
<img src="images/cinoop/map2.png" />
</div>
<br>
<h2>Getting past the copyright screen</h2>
<p>
Cinoop was getting stuck in a loop, and not progressing past the copyright screen. After some brief debugging, I found that blocking any writes to the first byte of HRAM (0xff80) would allow the loop to be completed:
</p>
<pre><code class="language-c">void writeByte(unsigned short address, unsigned char value) {
// Block writes to ff80
if(tetrisPatch && address == 0xff80) return;</code></pre>
<br>
<p>
It wasn't my intention to use game specific patches rather than sorting out bugs properly, but I assumed that if I temporarily enabled this patch, the problem would eventually sort its self out as I improved Cinoop (which it did).
</p>
<p>
After temporarily fixing the previous looping problem, I was presented with another; the game was repeating the following three instructions infinitely:
</p>
<pre><code class="language-c">ld a, 0xff80
and a
jr z</code></pre>
<br>
<p>
I realised that it was probably waiting for the value to be written to by an interrupt, so I dumped the interrupt enable register: <code>0x09</code>, meaning that both VBlank and Serial interrupts were enabled (<code>(1 << 0) | (1 << 3)</code>), since it probably wasn't dependent on there being a Serial interrupt, I assumed that my VBlank code was wrong.
</p>
<p>
Sure enough, it was! After correcting the VBlank interrupt handler, I was presented with a few more unimplemented instructions, and eventually, Cinoop made it to the Tetris menu!
</p>
<div class="center">
<img src="images/cinoop/menu.png" />
</div>
<br>
<h2>Sprites</h2>
<p>
The final major addition to the core would be sprite support, which wasn't too difficult to implement after having already implemented background maps. The Game Boy can display up to 40 sprites, with the properties of each stored in a basic OAM table, containing the position, tile number, palette number, flip, and priority.
</p>
<br>
<h2>Randomisation</h2>
<p>
Tetris relies on reading the divider register, at address <code>0xff04</code>, as the source of entropy to determine which random block will be next. Usually this register is a timer which increments linearly until either overflown or reset to 0 (by writing any value to it).
</p>
<p>
I decided to return <code>rand</code> when attempting to read from this value instead. Since this register is only used as a random number generator for Tetris, this change will provide a better source of entropy, without any adverse effects for this game.
</p>
<p>
When using <code>rand</code>, you should change the seed with <code>srand</code> (usually with the current time), otherwise, if you <code>srand</code> with the same seed, you will play the game with the exact same order of blocks.
</p>
<br>
<h2>Porting</h2>
<p>
To make Cinoop more useful, I decided to port it to several other systems.
</p>
<br>
<h3>DS</h3>
<p>
The first system I ported Cinoop to was the DS, which really didn't take long since I am so familiar with it.
</p>
<p>
I started by rendering to the DS in framebuffer mode, which can be done as follows.
</p>
<pre><code class="language-c">videoSetMode(MODE_FB0);
vramSetBankA(VRAM_A_LCD);
VRAM_A[x + y * 256] = RGB15(red, green, blue);</code></pre>
<br>
<p>
This was good at first because it meant that I could just reuse the Windows rendering code, so I managed to get Cinoop up and running fairly quickly:
</p>
<p>
However, the DS already has support for tiles and sprites; rendering to a framebuffer is slow.
</p>
<p>
I revised the code to use the DS' native tile rendering. It ran faster than the framebuffer renderer, but it had some minor graphical glitches on some tiles (happened on real hardware as well as on emulators):
</p>
<div class="center">
<img src="images/cinoop/dsTiles.png" />
</div>
<br>
<p>
I'm not exactly sure what caused this, but I think it was because I was writing to VRAM too frequently. I fixed the issue by writing to an array in RAM instead, and setting a <code>dirtyTileset</code> variable. During the DS' VBlank, I checked to see if the tileset had changed, and if so, copied the tiles from RAM into VRAM:
</p>
<pre><code class="language-c">void dsVblank(void) {
if(dirtyTileset) {
memcpy(bgGetGfxPtr(layer), tiles, 160 / 8 * 144 / 8 * 32);
dirtyTileset = 0;
}
}
int main(void) {
irqSet(IRQ_VBLANK, dsVblank);
...
void updateTile(unsigned short address, unsigned char value) {
...
#ifdef DS
dirtyTileset = 1;
#endif
}</code></pre>
<br>
<p>
The way that the DS video modes are designed, it is not possible for sprites and backgrounds to share a tileset, like the Game Boy does. As a result of this, I had to copy the tileset into both the background, and sprite memory in the <code>dsVblank</code> routine.
</p>
<p>
Finally, I wrote a plain black tile into VRAM, and used it for the border. With the finalised tile rendering system in place, the emulator had no graphical artifacts, and ran noticeably faster (but still not full speed).
</p>
<div class="center">
<img src="images/cinoop/ds.png" />
</div>
<br>
<h3>GameCube</h3>
<p>
The GameCube isn't a system that I have ever programmed for, so I decided that this would be a good project to start with. While there isn't nearly as much documentation as there is for the DS, it was still easy to get started with thanks to libogc and devkitPPC.
</p>
<p>
Unlike x86 and the DS, the GameCube's PowerPC processor is big endian. This was a minor annoyance, but was trivial to account for:
</p>
<pre><code class="language-c">#ifdef WIN
#define LITTLE_E
#endif
#ifdef DS
#define LITTLE_E
#endif
#ifdef GC
#define BIG_E
#endif
struct registers {
struct {
union {
struct {
#ifdef LITTLE_E
unsigned char f;
unsigned char a;
#else
unsigned char a;
unsigned char f;
#endif
};
unsigned short af;
};
};
struct {
union {
struct {
#ifdef LITTLE_E
unsigned char c;
unsigned char b;
#else
unsigned char b;
unsigned char c;
#endif
};
unsigned short bc;
};
};
...</code></pre>
<br>
<p>
The GameCube emulator I used for testing, gcube, doesn't support reading files from the memory card, so I had to hardcode the Tetris ROM into the binary, which was another minor annoyance. With all that done, I had Cinoop running on the GameCube!
</p>
<div class="center">
<img src="images/cinoop/gamecube.png" />
</div>
<br>
<h3>3DS</h3>
<p>
3DS development is a lot harder than DS development since it has had far less time to mature. There is far less documentation, and it feels clunky to develop for as a result of this.
</p>
<p>
For example, the DS' libfat supports file reading using the standard C procedures (<code>fopen</code> et al.), however the 3DS' ctrulib has its own special way to read files (<code>FSUSER_OpenFileDirectly</code> et al.).
</p>
<p>
The 3DS scene is very chaotic at the moment; there are multiple launchers which you should support when releasing something:
</p>
<ul>
<li>3ds - Flashcards</li>
<li>3dsx and smdh - Homebrew Launcher</li>
<li>cia - Custom firmwares</li>
<li>elf - Emulators</li>
</ul>
<p>
Also note that some applications are released as a ".dat" ROP chain, since they require execution under a specific exploit's environment (usually for access to certain system calls).
</p>
<p>
3DS emulation also isn't very good at the moment, so I had to test on real hardware, which was quite time consuming.
</p>
<p>
Apart from these few annoyances, the 3DS port didn't take too long. In the future, I hope to add support for rendering sprites above the background using 3D.
</p>
<br>
<h3>Ubuntu</h3>
<p>
I tried a range a Linux distros, and found Ubuntu to be a pleasant platform to port Cinoop to.
</p>
<div class="center">
<img src="images/cinoop/ubuntu.png" />
</div>
<br>
<h3>PSP</h3>
<p>
PSP was by far the easiest platform to develop for that I was new to.
</p>
<p>
I set up the <a href="http://sourceforge.net/projects/minpspw/">Minimalist PSP SDK</a>, and the <a href="http://www.ppsspp.org/">PPSSPP</a> emulator, and was able to port Cinoop within a single day!
</p>
<div class="center">
<img src="images/cinoop/psp.png" />
</div>
<br>
<h3>PS2</h3>
<p>
I had plans for a PS2 port of Cinoop, but I gave up due to the many difficulties of PS2 development.
</p>
<p>
The first reason for this is because of the decentralised nature of the scene; whatever information about PS2 development that is still available is scattered across the internet like Lego in a child's room.
</p>
<p>
I tried to install the <a href="https://github.com/ps2dev">ps2dev</a> toolchain from GitHub; I tried it on Windows 7, Ubuntu 14.04, and Mac OS X Lion. But, whatever I did, I ended up with numerous compile errors, so I just gave up.
</p>
<p>
For anyone who can actually manage to setup a PS2 development kit, there is no easy way to plot pixels directly to a framebuffer, like there was for every other system I ported Cinoop to.
</p>
<div class="quote">
<p>
There's no way to write directly to the frame buffer because the VRAM is not within EE RAM and isn't mapped to EE memory space. The only way is to have a local framebuffer within EE RAM, which you can transfer to the real framebuffer within VRAM via DMA at every frame. The VRAM is actually 4MB of eRAM within the GS.
</p>
<p>
To understand how this is to be done, it's important to first understand how to upload textures during a program's runtime. The frame buffer is basically a very large texture. Some graphics libraries (e.g. gsKit) have nice functions for facilitating processes like this.
</p>
<p>
I think that it may be possible to transfer bitmap data directly to the frame buffer on the GS because I think that FMCB (and probably some earlier homebrew demos) does that for drawing its boot logo. But so far I've only transferred bitmap data to the GS as texture data (to a buffer within VRAM which is outside of the frame buffer), which is later drawn onto the frame buffer as a full-screen 2D-texture.
</p>
<p>
You may be now wondering why it's so difficult to do something as simple as updating the frame buffer. Well, it's because the PlayStation 2 was primarily made to support 3D rather than 2D. As mentioned above, the VRAM is within the GS, which is a separate processor from the EE.
</p>
</div>
<div class="quote-reference">
- <a href="https://github.com/sp193">Liu Woon Yung</a>
</div>
<br>
<p>
So, I just gave up with a PS2 port.
</p>
<br>
<h3>Mac OS X</h3>
<p>
I also had plans to port to Mac OS X, but like with PS2, this proved too difficult since I was unable to install a working C compiler and development environment on Mac OS X.
</p>
<p>
Whilst nothing seemed to work on OS X for me, in the sprit of open source, <a href="https://github.com/nsenica">nsenica</a> managed to port to Cinoop to OS X with XQuartz, and submitted a pull request!
</p>
<div class="center">
<img src="images/cinoop/osx.png" />
</div>
<br>
<h3>PS4</h3>
<p>
The PlayStation 4 port is probably the most interesting one since homebrew is not yet commonplace on it; only a few people have code execution on the PS4, and with the access that we have as of writing, homebrew on this console suffers from some severe limitations.
</p>
<p>
The first problem is the controller. I'm not sure what's wrong, but <a href="https://github.com/CTurt/PS4-SDK/blob/master/examples/pad/source/main.c">using the official <code>libScePad.sprx</code> module</a> doesn't work. Maybe it is because the controller is already in use and that connecting a second controller would work, but I only have 1 controller to test with.
</p>
<p>
There are two workarounds for this: use the USB library to receive input from a third party controller, or just use any WiFi compatible device with buttons to send input over a UDP socket. I opted for using a Nintendo DS wirelessly.
</p>
<p>
The second problem is the <code>libSceVideoOut.sprx</code> module not working for us. I'll explain in more detail everything I tried doing to get video output in my next article on the PS4, but the solution I found is to create an HTML5 canvas, and render to that instead.
</p>
<p>
With these two workarounds I was able to make a mini Pong game on the PS4:
</p>
<div class="center">
<iframe class="youtube" width="560" height="315" src="https://www.youtube.com/embed/aNqKyuTDbjE" frameborder="0" allowfullscreen></iframe>
</div>
<br>
<p>
The final limitation is that we don't have permission to mount USB flash drives and read them as normal.
</p>
<p>
We do however have access to the <code>libUsbd.sprx</code> module (basically just <a href="http://libusb.info/">libusb</a>) which allows us to communicate directly with USB devices.
</p>
<p>
Whilst it may be possible in the future to port a full FAT implementation based on raw USB commands, for now I just wrote my Tetris ROM as the raw image of the USB flash drive using <a href="http://sourceforge.net/projects/win32diskimager/">Win32 Disk Imager</a>.
</p>
<p>
With these three workarounds in place, I was able to port Cinoop to PS4 using the <a href="https://github.com/CTurt/PS4-SDK">PS4-SDK</a>!
</p>
<div class="center">
<iframe class="youtube" width="560" height="315" src="https://www.youtube.com/embed/94Q91xDJatE" frameborder="0" allowfullscreen></iframe>
</div>
<br>
<h2>Final thoughts</h2>
<p>
Feel free to browse through the <a href="https://github.com/CTurt/Cinoop">source code of Cinoop</a>; it's gotten quite cluttered with all of the ports being together, but the core interpreter is still rather clean and it shouldn't be too difficult to fix bugs in it.
</p>
<p>
Although Tetris is probably the only game that is playable, I have still learnt a lot from this project, and I hope to improve on it in time.
</p>
<p>
During most of the development, I used NO$GMB to confirm that my emulator was working, however, <a href="http://bgb.bircd.org/">bgb</a> is more accurate, is still being actively maintained, and has a debugger which is just as good as NO$GMB's; I would recommend using it over NO$GMB.
</p>
<br>
<h2>Thanks</h2>
<p>
<a href="http://imrannazar.com/GameBoy-Emulation-in-JavaScript">Imran Nazar</a>, <a href="http://www.amidog.com/amiga/gbe/">Chuck Mason and Steven Fuller</a>, <a href="http://problemkaputt.de/gmb.htm">Martin Korth</a>, <a href="http://bgb.bircd.org/">beware</a>, and <a href="http://blog.gg8.se/">nitro2k01</a>.
</p>
</div>
</div>
<script src="js/prism.js" type="text/javascript"></script>
</body>
</html>