View source for Atari Lynx

== Atari Lynx ==
The Atari Lynx consists of the 65C02 with custom hardware for graphics and sound.<br>
If you come from Atari 8bit or Apple, there are no illegal opcodes anymore like <b>lax</b>, but a lot new nice opcodes like <b>stz</b>. :-)

=== Setting up ===
Setting up your development platform for the Atari Lynx:

* Assembler:
Below size coding examples use [https://github.com/42Bastian/lyxass Lyxass] as assembler and are using the in-official DevKit [https://github.com/42Bastian/new_bll new_bll].<br>
But any other 6502 assembler is suitable. Best if it can assemble the extra opcodes of the 65C02 (like <b>BBRx</b> or <b>RMBx</b>).

* Encryption
The Lynx boot ROM will decrypt the "boot sector" of a Lynx card image. It is done in chunks of 50bytes. Maximum are 5 chunks, hence the limit of a "boot sector" is 250 bytes, but the last byte <b>must</b> be zero.

* Emulator(s): 
Currently Felix is the most accurate Emulator, though only running yet on Windows platform.<br>
It is currently available via [https://github.com/laoo/Felix GitHub].

* Hardware:
If you want to run the code on a real Lynx, you should have a SD card for the Lynx (AgaCard, LynxGD) and also a USB<->Serial adapter.

=== Initial values ===
After the boot-rom has decrypted the boot-sector, some things are pre-defined:
* CPU Registers:
  A = 0
  X = 0
  Y = 2
  P = undefined
  S = undefined

* Zero page

 $00 - 0
 $01 - 0
 $02 - 0

* Main

Main memory is cleared to zero despite a $5000..%$50aa where decryption code is placed.

* Bank switching

ROM, Mikey and Suzy are mapped, Vector table is ROM.

* Suzy
The sprite engine is <b>not</b> setup.



=== Video display ===
The Lynx display is 160x102 pixels which are linear organized as 4 bit per pixel. Hence the screen is little less than 8K.
The pixel value is a pointer to the color look up table.
The Lynx can display black and 4095 colors. The color table is split up into a green and an blue-red part (so not RGB but GBR).

==== Getting something on screen ====
After the ROM has deciphered the boot sector the display memory is at $2000, background color (that is pen 0) is black, all other entries are $f despite entry 14 which is also 0.

So to fill the screen simply do:
<pre>
lda #$ff
ldx #0
ldy #$20   ; round(160*102/2/256)
loop:
    sta $2000,x
    inx
  bne loop
  inc loop+2 ; Self modify
  dey
bne loop
</pre>

=== Tips 'n' tricks ===
A nice trick with the new opcodes to limit a counter:
* 6502
  lda counter  ; 2
  inc          ; 1
  and #3       ; 2
  sta counter  ; 2 = 7 bytes

* 65C02
  inc counter ; 2
  rmb2 counter ; 2 => 4 bytes

Set a counter (previously 0) to a power-of-two (here 32)

* 6502
  lda #32     ; 2
  sta counter ; 2 => 4

* 65C02
  smb5 counter ; 2


=== Sound ===
To be added soon.

==== Make some noise ====
To be added soon.

=== Additional Resources ===
*[https://www.monlynx.de/lynx/lynxdoc.html Hardware documentation]
*[https://github.com/42Bastian/lynx_hacking/tree/master/248b Size coding examples.]
*[https://github.com/42Bastian/lynx-encryption-tools Lynx encryption-tools]