1 /** @file gb/gb.h 2 Gameboy specific functions. 3 */ 4 #ifndef _GB_H 5 #define _GB_H 6 7 #include <sys/types.h> 8 #include <sys/compiler.h> 9 #include <stdint.h> 10 #include <gb/hardware.h> 11 #include <gb/sgb.h> 12 #include <gb/cgb.h> 13 14 typedef uint8_t UBYTE; 15 typedef uint8_t UINT8; 16 typedef int8_t INT8; 17 typedef uint16_t UWORD; 18 typedef int16_t WORD; 19 #ifndef NULL 20 #define NULL (void *)0 21 #endif 22 23 typedef union _fixed { 24 struct { 25 uint8_t l; 26 uint8_t h; 27 } b; 28 uint16_t w; 29 } fixed; 30 31 /** Joypad bits. 32 A logical OR of these is used in the wait_pad and joypad 33 functions. For example, to see if the B button is pressed 34 try 35 36 uint8_t keys; 37 keys = joypad(); 38 if (keys & J_B) { 39 ... 40 } 41 42 @see joypad 43 */ 44 #define J_START 0x80U 45 #define J_SELECT 0x40U 46 #define J_B 0x20U 47 #define J_A 0x10U 48 #define J_DOWN 0x08U 49 #define J_UP 0x04U 50 #define J_LEFT 0x02U 51 #define J_RIGHT 0x01U 52 53 /** Screen modes. 54 Normally used by internal functions only. 55 */ 56 #define M_DRAWING 0x01U 57 #define M_TEXT_OUT 0x02U 58 #define M_TEXT_INOUT 0x03U 59 /** Set this in addition to the others to disable scrolling 60 If scrolling is disabled, the cursor returns to (0,0) */ 61 #define M_NO_SCROLL 0x04U 62 /** Set this to disable \n interpretation */ 63 #define M_NO_INTERP 0x08U 64 65 /** If this is set, sprite colours come from OBJ1PAL. Else 66 they come from OBJ0PAL. 67 */ 68 #define S_PALETTE 0x10U 69 /** If set the sprite will be flipped horizontally. 70 */ 71 #define S_FLIPX 0x20U 72 /** If set the sprite will be flipped vertically. 73 */ 74 #define S_FLIPY 0x40U 75 /** If this bit is clear, then the sprite will be displayed 76 ontop of the background and window. 77 */ 78 #define S_PRIORITY 0x80U 79 80 /* Interrupt flags */ 81 /** Vertical blank interrupt. 82 Occurs at the start of the vertical blank. During this 83 period the video ram may be freely accessed. 84 */ 85 #define VBL_IFLAG 0x01U 86 /** Interrupt when triggered by the STAT register. 87 See the Pan doc. 88 */ 89 #define LCD_IFLAG 0x02U 90 /** Interrupt when the timer TIMA overflows. 91 */ 92 #define TIM_IFLAG 0x04U 93 /** Occurs when the serial transfer has completed. 94 */ 95 #define SIO_IFLAG 0x08U 96 /** Occurs on a transition of the keypad. 97 */ 98 #define JOY_IFLAG 0x10U 99 100 /* Limits */ 101 /** Width of the visible screen in pixels. 102 */ 103 #define SCREENWIDTH 0xA0U 104 /** Height of the visible screen in pixels. 105 */ 106 #define SCREENHEIGHT 0x90U 107 #define MINWNDPOSX 0x07U 108 #define MINWNDPOSY 0x00U 109 #define MAXWNDPOSX 0xA6U 110 #define MAXWNDPOSY 0x8FU 111 112 /* ************************************************************ */ 113 114 /** Interrupt handlers 115 */ 116 typedef void (*int_handler)(void) NONBANKED; 117 118 /** The remove functions will remove any interrupt 119 handler. A handler of NULL will cause bad things 120 to happen. 121 */ 122 void __LIB__ remove_VBL(int_handler h) NONBANKED; 123 124 void __LIB__ remove_LCD(int_handler h) NONBANKED; 125 126 void __LIB__ remove_TIM(int_handler h) NONBANKED; 127 128 void __LIB__ remove_SIO(int_handler h) NONBANKED; 129 130 void __LIB__ remove_JOY(int_handler h) NONBANKED; 131 132 /** Adds a V-blank interrupt handler. 133 The handler 'h' will be called whenever a V-blank 134 interrupt occurs. Up to 4 handlers may be added, 135 with the last added being called last. If the remove_VBL 136 function is to be called, only three may be added. 137 @see remove_VBL 138 */ 139 void __LIB__ add_VBL(int_handler h) NONBANKED; 140 141 /** Adds a LCD interrupt handler. 142 Called when the LCD interrupt occurs, which is normally 143 when LY_REG == LYC_REG. 144 145 From pan/k0Pa: 146 There are various reasons for this interrupt to occur 147 as described by the STAT register ($FF40). One very 148 popular reason is to indicate to the user when the 149 video hardware is about to redraw a given LCD line. 150 This can be useful for dynamically controlling the SCX/ 151 SCY registers ($FF43/$FF42) to perform special video 152 effects. 153 154 @see add_VBL 155 */ 156 void __LIB__ add_LCD(int_handler h) NONBANKED; 157 158 /** Adds a timer interrupt handler. 159 160 From pan/k0Pa: 161 This interrupt occurs when the TIMA register ($FF05) 162 changes from $FF to $00. 163 164 @see add_VBL 165 */ 166 void __LIB__ add_TIM(int_handler h) NONBANKED; 167 168 /** Adds a serial transmit complete interrupt handler. 169 170 From pan/k0Pa: 171 This interrupt occurs when a serial transfer has 172 completed on the game link port. 173 174 @see send_byte, receive_byte, add_VBL 175 */ 176 void __LIB__ add_SIO(int_handler h) NONBANKED; 177 178 /** Adds a pad tranisition interrupt handler. 179 180 From pan/k0Pa: 181 This interrupt occurs on a transition of any of the 182 keypad input lines from high to low. Due to the fact 183 that keypad "bounce" is virtually always present, 184 software should expect this interrupt to occur one 185 or more times for every button press and one or more 186 times for every button release. 187 188 @see joypad 189 */ 190 void __LIB__ add_JOY(int_handler h) NONBANKED; 191 192 /* ************************************************************ */ 193 194 /** Set the current mode - one of M_* defined above */ 195 void __LIB__ mode(uint8_t m) NONBANKED; 196 197 /** Returns the current mode */ 198 uint8_t __LIB__ get_mode(void) NONBANKED; 199 200 /** GB type (GB, PGB, CGB) */ 201 extern uint8_t _cpu; 202 203 /** Original GB or Super GB */ 204 #define DMG_TYPE 0x01 205 /** Pocket GB or Super GB 2 */ 206 #define MGB_TYPE 0xFF 207 /** Color GB */ 208 #define CGB_TYPE 0x11 209 210 /** Time in VBL periods (60Hz) */ 211 extern uint16_t sys_time; 212 213 /* ************************************************************ */ 214 215 /** Send byte in _io_out to the serial port */ 216 void __LIB__ send_byte(void); 217 218 /** Receive byte from the serial port in _io_in */ 219 void __LIB__ receive_byte(void); 220 221 /** An OR of IO_* */ 222 extern uint8_t _io_status; 223 /** Byte just read. */ 224 extern uint8_t _io_in; 225 /** Write the byte to send here before calling send_byte() 226 @see send_byte 227 */ 228 extern uint8_t _io_out; 229 230 /* Status codes */ 231 /** IO is completed */ 232 #define IO_IDLE 0x00U 233 /** Sending data */ 234 #define IO_SENDING 0x01U 235 /** Receiving data */ 236 #define IO_RECEIVING 0x02U 237 /** Error */ 238 #define IO_ERROR 0x04U 239 240 /* ************************************************************ */ 241 242 /* Multiple banks */ 243 244 /** Switches the upper 16k bank of the 32k rom to bank rombank 245 using the MBC1 controller. 246 By default the upper 16k bank is 1. Make sure the rom you compile 247 has more than just bank 0 and bank 1, a 32k rom. This is done by 248 feeding lcc.exe the following switches: 249 250 -Wl-yt# where # is the type of cartridge. 1 for ROM+MBC1. 251 252 -Wl-yo# where # is the number of rom banks. 2,4,8,16,32. 253 */ 254 #define SWITCH_ROM_MBC1(b) \ 255 *(unsigned char *)0x2000 = (b) 256 257 #define SWITCH_RAM_MBC1(b) \ 258 *(unsigned char *)0x4000 = (b) 259 260 #define ENABLE_RAM_MBC1 \ 261 *(unsigned char *)0x0000 = 0x0A 262 263 #define DISABLE_RAM_MBC1 \ 264 *(unsigned char *)0x0000 = 0x00 265 266 #define SWITCH_16_8_MODE_MBC1 \ 267 *(unsigned char *)0x6000 = 0x00 268 269 #define SWITCH_4_32_MODE_MBC1 \ 270 *(unsigned char *)0x6000 = 0x01 271 272 /* Note the order used here. Writing the other way around 273 * on a MBC1 always selects bank 0 (d'oh) 274 */ 275 /** MBC5 */ 276 #define SWITCH_ROM_MBC5(b) \ 277 *(unsigned char *)0x3000 = (uint16_t)(b)>>8; \ 278 *(unsigned char *)0x2000 = (uint8_t)(b) 279 280 #define SWITCH_RAM_MBC5(b) \ 281 *(unsigned char *)0x4000 = (b) 282 283 #define ENABLE_RAM_MBC5 \ 284 *(unsigned char *)0x0000 = 0x0A 285 286 #define DISABLE_RAM_MBC5 \ 287 *(unsigned char *)0x0000 = 0x00 288 289 /* ************************************************************ */ 290 291 /** Delays the given number of milliseconds. 292 Uses no timers or interrupts, and can be called with 293 interrupts disabled (why nobody knows :) 294 */ 295 void __LIB__ delay(uint16_t d) NONBANKED; 296 297 /* ************************************************************ */ 298 299 /** Reads and returns the current state of the joypad. 300 Follows Nintendo's guidelines for reading the pad. 301 Return value is an OR of J_* 302 @see J_START 303 */ 304 uint8_t __LIB__ joypad(void) NONBANKED; 305 306 /** Waits until all the keys given in mask are pressed. 307 Normally only used for checking one key, but it will 308 support many, even J_LEFT at the same time as J_RIGHT :) 309 @see joypad, J_START 310 */ 311 uint8_t __LIB__ waitpad(uint8_t mask) NONBANKED; 312 313 /** Waits for the pad and all buttons to be released. 314 */ 315 void __LIB__ waitpadup(void) NONBANKED; 316 317 /* ************************************************************ */ 318 319 /** Enables unmasked interrupts 320 @see disable_interrupts 321 */ 322 void __LIB__ enable_interrupts(void) NONBANKED; 323 324 /** Disables interrupts. 325 This function may be called as many times as you like; 326 however the first call to enable_interrupts will re-enable 327 them. 328 @see enable_interrupts 329 */ 330 void __LIB__ disable_interrupts(void) NONBANKED; 331 332 /** Clears any pending interrupts and sets the interrupt mask 333 register IO to flags. 334 @see VBL_IFLAG 335 @param flags A logical OR of *_IFLAGS 336 */ 337 void __LIB__ set_interrupts(uint8_t flags) NONBANKED; 338 339 /** Performs a warm reset by reloading the CPU value 340 then jumping to the start of crt0 (0x0150) 341 */ 342 void __LIB__ reset(void) NONBANKED; 343 344 /** Waits for the vertical blank interrupt (VBL) to finish. 345 This can be used to sync animation with the screen 346 re-draw. If VBL interrupt is disabled, this function will 347 never return. If the screen is off this function returns 348 immediatly. 349 */ 350 void __LIB__ wait_vbl_done(void) NONBANKED; 351 352 /** Turns the display off. 353 Waits until the VBL interrupt before turning the display 354 off. 355 @see DISPLAY_ON 356 */ 357 void __LIB__ display_off(void) NONBANKED; 358 359 /* ************************************************************ */ 360 361 /** Copies data from somewhere in the lower address space 362 to part of hi-ram. 363 @param dst Offset in high ram (0xFF00 and above) 364 to copy to. 365 @param src Area to copy from 366 @param n Number of bytes to copy. 367 */ 368 void __LIB__ hiramcpy(uint16_t dst, const void *src, uint16_t n) __smallc NONBANKED; 369 370 /* ************************************************************ */ 371 372 /** Turns the display back on. 373 @see display_off, DISPLAY_OFF 374 */ 375 #define DISPLAY_ON \ 376 LCDC_REG|=0x80U 377 378 /** Turns the display off immediatly. 379 @see display_off, DISPLAY_ON 380 */ 381 #define DISPLAY_OFF \ 382 display_off(); 383 384 /** Turns on the background layer. 385 Sets bit 0 of the LCDC register to 1. 386 */ 387 #define SHOW_BKG \ 388 LCDC_REG|=0x01U 389 390 /** Turns off the background layer. 391 Sets bit 0 of the LCDC register to 0. 392 */ 393 #define HIDE_BKG \ 394 LCDC_REG&=0xFEU 395 396 /** Turns on the window layer 397 Sets bit 5 of the LCDC register to 1. 398 */ 399 #define SHOW_WIN \ 400 LCDC_REG|=0x20U 401 402 /** Turns off the window layer. 403 Clears bit 5 of the LCDC register to 0. 404 */ 405 #define HIDE_WIN \ 406 LCDC_REG&=0xDFU 407 408 /** Turns on the sprites layer. 409 Sets bit 1 of the LCDC register to 1. 410 */ 411 #define SHOW_SPRITES \ 412 LCDC_REG|=0x02U 413 414 /** Turns off the sprites layer. 415 Clears bit 1 of the LCDC register to 0. 416 */ 417 #define HIDE_SPRITES \ 418 LCDC_REG&=0xFDU 419 420 /** Sets sprite size to 8x16 pixels, two tiles one above the other. 421 Sets bit 2 of the LCDC register to 1. 422 */ 423 #define SPRITES_8x16 \ 424 LCDC_REG|=0x04U 425 426 /** Sets sprite size to 8x8 pixels, one tile. 427 Clears bit 2 of the LCDC register to 0. 428 */ 429 #define SPRITES_8x8 \ 430 LCDC_REG&=0xFBU 431 432 /* ************************************************************ */ 433 434 /** Sets the tile patterns in the Background Tile Pattern table. 435 Starting with the tile pattern x and carrying on for n number of 436 tile patterns.Taking the values starting from the pointer 437 data. Note that patterns 128-255 overlap with patterns 128-255 438 of the sprite Tile Pattern table. 439 440 GBC: Depending on the VBK_REG this determines which bank of 441 Background tile patterns are written to. VBK_REG=0 indicates the 442 first bank, and VBK_REG=1 indicates the second. 443 444 @param first_tile Range 0 - 255 445 @param nb_tiles Range 0 - 255 446 */ 447 void __LIB__ set_bkg_data(uint16_t first_tile, uint16_t nb_tiles, unsigned char *data) __smallc NONBANKED; 448 449 /** Sets the tiles in the background tile table. 450 Starting at position x,y in tiles and writing across for w tiles 451 and down for h tiles. Taking the values starting from the pointer 452 data. 453 454 For the GBC, also see the pan/k00Pa section on VBK_REG. 455 456 @param x Range 0 - 31 457 @param y Range 0 - 31 458 @param w Range 0 - 31 459 @param h Range 0 - 31 460 @param data Pointer to an unsigned char. Usually the 461 first element in an array. 462 */ 463 void __LIB__ set_bkg_tiles(uint16_t x, uint16_t y, uint16_t w, uint16_t h, unsigned char *tiles) __smallc NONBANKED; 464 465 void __LIB__ get_bkg_tiles(uint16_t x, uint16_t y, uint16_t w, uint16_t h, unsigned char *tiles) __smallc NONBANKED; 466 467 /** Moves the background layer to the position specified in x and y in pixels. 468 Where 0,0 is the top left corner of the GB screen. You'll notice the screen 469 wraps around in all 4 directions, and is always under the window layer. 470 */ 471 void __LIB__ move_bkg(uint16_t x, uint16_t y) __smallc NONBANKED; 472 473 /** Moves the background relative to it's current position. 474 475 @see move_bkg 476 */ 477 void __LIB__ scroll_bkg(int16_t x, int16_t y) __smallc NONBANKED; 478 479 /* ************************************************************ */ 480 481 /** Sets the window tile data. 482 This is the same as set_bkg_data, as both the window layer and background 483 layer share the same Tile Patterns. 484 @see set_bkg_data 485 */ 486 void __LIB__ set_win_data(uint16_t first_tile, uint16_t nb_tiles, unsigned char *data) __smallc NONBANKED; 487 488 /** Sets the tiles in the win tile table. 489 Starting at position x,y in 490 tiles and writing across for w tiles and down for h tiles. Taking the 491 values starting from the pointer data. Note that patterns 128-255 overlap 492 with patterns 128-255 of the sprite Tile Pattern table. 493 494 GBC only. 495 Depending on the VBK_REG this determines if you're setting the tile numbers 496 VBK_REG=0; or the attributes for those tiles VBK_REG=1;. The bits in the 497 attributes are defined as: 498 Bit 7 - Priority flag. When this is set, it puts the tile above the sprites 499 with colour 0 being transparent. 0: below sprites, 1: above sprites 500 Note SHOW_BKG needs to be set for these priorities to take place. 501 Bit 6 - Vertical flip. Dictates which way up the tile is drawn vertically. 502 0: normal, 1: upside down. 503 Bit 5 - Horizontal flip. Dictates which way up the tile is drawn 504 horizontally. 0: normal, 1:back to front. 505 Bit 4 - Not used. 506 Bit 3 - Character Bank specification. Dictates from which bank of 507 Background Tile Patterns the tile is taken. 0: Bank 0, 1: Bank 1 508 Bit 2 - See bit 0. 509 Bit 1 - See bit 0. 510 Bit 0 - Bits 0-2 indicate which of the 7 BKG colour palettes the tile is 511 assigned. 512 513 @param x Range 0 - 31 514 @param y Range 0 - 31 515 @param w Range 0 - 31 516 @param h Range 0 - 31 517 */ 518 void __LIB__ set_win_tiles(uint16_t x, uint16_t y, uint16_t w, uint16_t h, unsigned char *tiles) __smallc NONBANKED; 519 520 void __LIB__ get_win_tiles(uint16_t x, uint16_t y, uint16_t w, uint16_t h, unsigned char *tiles) __smallc NONBANKED; 521 522 /** Moves the window layer to the position specified in x and y in pixels. 523 Where 7,0 is the top left corner of the GB screen. The window is locked to 524 the bottom right corner, and is always over the background layer. 525 @see SHOW_WIN, HIDE_WIN 526 */ 527 void __LIB__ move_win(uint16_t x, uint16_t y) __smallc NONBANKED; 528 529 /** Move the window relative to its current position. 530 @see move_win 531 */ 532 void __LIB__ scroll_win(int16_t x, int16_t y) __smallc NONBANKED; 533 534 /* ************************************************************ */ 535 536 /** Sets the tile patterns in the Sprite Tile Pattern table. 537 Starting with the tile pattern x and carrying on for n number of 538 tile patterns.Taking the values starting from the pointer 539 data. Note that patterns 128-255 overlap with patterns 128-255 of 540 the Background Tile Pattern table. 541 542 GBC only. 543 Depending on the VBK_REG this determines which bank of Background tile 544 patterns are written to. VBK_REG=0 indicates the first bank, and VBK_REG=1 545 indicates the second. 546 */ 547 void __LIB__ set_sprite_data(uint16_t first_tile, uint16_t nb_tiles, unsigned char *data) __smallc NONBANKED; 548 549 void __LIB__ get_sprite_data(uint16_t first_tile, uint16_t nb_tiles, unsigned char *data) __smallc NONBANKED; 550 551 /** Sets sprite n to display tile number t, from the sprite tile data. 552 If the GB is in 8x16 sprite mode then it will display the next 553 tile, t+1, below the first tile. 554 @param nb Sprite number, range 0 - 39 555 */ 556 void __LIB__ set_sprite_tile(uint16_t nb, uint16_t tile) __smallc NONBANKED; 557 558 uint8_t __LIB__ get_sprite_tile(uint16_t nb) NONBANKED; 559 560 /** Sets the property of sprite n to those defined in p. 561 Where the bits in p represent: 562 Bit 7 - Priority flag. When this is set the sprites appear behind the 563 background and window layer. 0: infront, 1: behind. 564 Bit 6 - GBC only. Vertical flip. Dictates which way up the sprite is drawn 565 vertically. 0: normal, 1:upside down. 566 Bit 5 - GBC only. Horizontal flip. Dictates which way up the sprite is 567 drawn horizontally. 0: normal, 1:back to front. 568 Bit 4 - DMG only. Assigns either one of the two b/w palettes to the sprite. 569 0: OBJ palette 0, 1: OBJ palette 1. 570 Bit 3 - GBC only. Dictates from which bank of Sprite Tile Patterns the tile 571 is taken. 0: Bank 0, 1: Bank 1 572 Bit 2 - See bit 0. 573 Bit 1 - See bit 0. 574 Bit 0 - GBC only. Bits 0-2 indicate which of the 7 OBJ colour palettes the 575 sprite is assigned. 576 577 @param nb Sprite number, range 0 - 39 578 */ 579 void __LIB__ set_sprite_prop(uint16_t nb, uint16_t prop) __smallc NONBANKED; 580 581 uint8_t __LIB__ get_sprite_prop(uint16_t nb) NONBANKED; 582 583 /** Moves the given sprite to the given position on the 584 screen. 585 Dont forget that the top left visible pixel on the screen 586 is at (8,16). To put sprite 0 at the top left, use 587 move_sprite(0, 8, 16); 588 */ 589 void __LIB__ move_sprite(uint16_t nb, uint16_t x, uint16_t y) __smallc NONBANKED; 590 591 /** Moves the given sprite relative to its current position. 592 */ 593 void __LIB__ scroll_sprite(int16_t nb, int16_t x, int16_t y) __smallc NONBANKED; 594 595 /* ************************************************************ */ 596 597 void __LIB__ set_data(unsigned char *vram_addr, unsigned char *data, uint16_t len) __smallc NONBANKED; 598 599 void __LIB__ get_data(unsigned char *data, unsigned char *vram_addr, uint16_t len) __smallc NONBANKED; 600 601 void __LIB__ set_tiles(uint16_t x, uint16_t y, uint16_t w, uint16_t h, unsigned char *vram_addr, unsigned char *tiles) __smallc NONBANKED; 602 603 void __LIB__ get_tiles(uint16_t x, uint16_t y, uint16_t w, uint16_t h, unsigned char *tiles, unsigned char *vram_addr) __smallc NONBANKED; 604 605 #endif /* _GB_H */ 606