Pandora Wiki - User contributions [en]

Assembly Code Optimization

2016-04-30T18:58:37Z

Exophase: /* NEON */

== Assembly code optimization on the Cortex-A8 ==
This guide presents specific optimization techniques for the [[ARM]] Cortex-A8 processor and its dual-issue, in-order pipeline.

== Use the ARMv7 movw/movt instructions ==
Newer ARM processors allow loading 32-bit values as two 16-bit immediates. The movw instruction loads the lower 16 bits, and movt loads the upper 16 bits. The movw instruction clears the upper 16 bits, so that 16-bit values can be loaded using a single instruction. The movt instruction does not affect the lower bits.

On older ARM processors, it was common to load 32-bit values with a PC-relative load. This should be avoided because it may result in a cache miss.

== Branch Prediction ==
There is a one-cycle stall in instruction fetch when a branch is predicted taken. It is therefore preferable to structure code so that the most likely code path is the one where the branch is not taken.

Unconditional branches may be mispredicted, and load instructions which follow branches may be decoded and cause cache accesses. Avoid placing load instructions after branches unless you intend the CPU to prefetch the addresses they reference.

The branch predictor has a call/return stack for jumps which reference r14 or stack operations using r13 which load the program counter. For best performance, make sure any pop, mov pc,lr or bx lr jumps to the same location as was set by the matching bl instruction. For non-return jumps, use a register other than r14.

Although instructions are decoded in pairs, the branch predictor can only predict one branch target per cycle. If you have a conditional branch which is immediately followed by another branch, and the first branch is likely to be taken, place a no-operation instruction between the branches to prevent decoding and prediction of the second branch. Inserting NOPs is detrimental if the first branch is infrequently taken.

== Dual-Issue Restrictions ==
Only one branch instruction can issue per cycle. Only one load or store instruction can issue per cycle. Instructions which write to the same register can not issue together.

There is a one-cycle delay before any written register can be used as the address of a subsequent load or store instruction. There is a one-cycle delay before any written register can be used by an instruction which performs a shift or rotation on that register.

There is one cycle delay before the result of a load can be used. In the aforementioned cases involving subsequent shift or rotate instructions, or the address of a load or store instruction, the total delay is two cycles.

Stores occur at the end of the pipeline and store instructions can issue in the same cycle as another instruction which writes the same register. Similarly, conditional branches can issue in the same cycle as flag-setting instructions because the branch is not resolved until the following cycle. In all other cases, instructions can not issue together if the second instruction depends on the results of the first.

== Instruction pairing restrictions following a branch ==
The Cortex-A8 processor normally fetches two instructions per cycle and the branch predictor tests each against the global history buffer. However, there is only one entry in the branch target buffer for each pair of instructions. Therefore, branch instructions, and certain instructions which resemble branches, may adversely affect branch prediction when present in pairs. To reduce the risk of branch misprediction, avoid pairing branch instructions with the following:

* Branch instructions
* Load instructions, whether or not they write r15
* Arithmetic/logic instructions which do not set flags and do not have an immediate value, whether or not they write r15

Flag-setting instructions can be used to avoid this restriction. Additionally, MOV instructions that do not have immediate values can be replaced with ADD, SUB, ORR, or EOR instructions using zero as an immediate value.

== Code alignment ==
Code alignment should be used with caution. Alignment has the potential to increase performance, but may be detrimental in some circumstances.

Because the instruction decoder always fetches 64-bit aligned words from the level-1 instruction cache, aligning code can improve instruction fetch and decode. However, the global history buffer of the branch predictor is indexed by the low bits of the instruction address. Excessive code alignment can result in a suboptimal distribution of entries in the branch history tables and increase branch misprediction. Additionally, the speculative prefetch may retrieve and decode instructions used as padding, even if those instructions are never executed. The types of instructions used as padding will affect the branch predictor as stated above, and this may affect the prefetch of code into the instruction cache.

== NEON ==
As the manual states, passing data from NEON (and VFP) back to ARM takes at least 20 cycles, but there are some tricks that can be used. The vmov instruction itself that is passing the data will not cause any stalls (provided the needed NEON register is already available), the stall will actually happen on any ARM instruction that follows instead (including branches). This means that:
* Multiple "vmov.32 rX, dY[Z]" can be done back-to-back and only incur one stall after the whole sequence
* Additional NEON instructions can be issued after "vmov" without stalling (with enough instructions the stall can be completely avoided)
* Additional unrelated NEON instructions can be issued before "vmov" (to hide the latency of instruction that produces the source register data)

Even though the VFP is not pipelined, the VFP vldr instructions are. "vldr s0, [r0]" will be faster than "vld1.32 {d0[0]}, [r0]" (2 vs 3 cycles, vldr also gives more flexible addressing mode). The same can't be said about "vmov sX, sY", it waits for all previous instructions to complete before issuing.

You should avoid any NEON loads that come from a location that has recently been written to. NEON does not have store forwarding, so this can cost dozens of cycles. This can happen unknowingly if you use unaligned loads, because they're performed with two aligned accesses. For example, if you have this sequence:

loop:
vld1.u32 { q0 }, [r0]
vadd.u32 q0, q0, q1
vst1.u32 { q0 }, [r0]!
subs r1, #1
bne loop

If r0 is unaligned, the next iteration of vld1.u32 will overlap with the previous iteration of vst1.u32, which will cause a stall. To avoid this situation you can reorder the loop so that the store happens one element behind.

[[Category:Development]]
[[Category:Optimization]]
[[Category:Chipset]]

Assembly Code Optimization

2016-04-30T18:58:25Z

Exophase: /* NEON */

== Assembly code optimization on the Cortex-A8 ==
This guide presents specific optimization techniques for the [[ARM]] Cortex-A8 processor and its dual-issue, in-order pipeline.

== Use the ARMv7 movw/movt instructions ==
Newer ARM processors allow loading 32-bit values as two 16-bit immediates. The movw instruction loads the lower 16 bits, and movt loads the upper 16 bits. The movw instruction clears the upper 16 bits, so that 16-bit values can be loaded using a single instruction. The movt instruction does not affect the lower bits.

On older ARM processors, it was common to load 32-bit values with a PC-relative load. This should be avoided because it may result in a cache miss.

== Branch Prediction ==
There is a one-cycle stall in instruction fetch when a branch is predicted taken. It is therefore preferable to structure code so that the most likely code path is the one where the branch is not taken.

Unconditional branches may be mispredicted, and load instructions which follow branches may be decoded and cause cache accesses. Avoid placing load instructions after branches unless you intend the CPU to prefetch the addresses they reference.

The branch predictor has a call/return stack for jumps which reference r14 or stack operations using r13 which load the program counter. For best performance, make sure any pop, mov pc,lr or bx lr jumps to the same location as was set by the matching bl instruction. For non-return jumps, use a register other than r14.

Although instructions are decoded in pairs, the branch predictor can only predict one branch target per cycle. If you have a conditional branch which is immediately followed by another branch, and the first branch is likely to be taken, place a no-operation instruction between the branches to prevent decoding and prediction of the second branch. Inserting NOPs is detrimental if the first branch is infrequently taken.

== Dual-Issue Restrictions ==
Only one branch instruction can issue per cycle. Only one load or store instruction can issue per cycle. Instructions which write to the same register can not issue together.

There is a one-cycle delay before any written register can be used as the address of a subsequent load or store instruction. There is a one-cycle delay before any written register can be used by an instruction which performs a shift or rotation on that register.

There is one cycle delay before the result of a load can be used. In the aforementioned cases involving subsequent shift or rotate instructions, or the address of a load or store instruction, the total delay is two cycles.

Stores occur at the end of the pipeline and store instructions can issue in the same cycle as another instruction which writes the same register. Similarly, conditional branches can issue in the same cycle as flag-setting instructions because the branch is not resolved until the following cycle. In all other cases, instructions can not issue together if the second instruction depends on the results of the first.

== Instruction pairing restrictions following a branch ==
The Cortex-A8 processor normally fetches two instructions per cycle and the branch predictor tests each against the global history buffer. However, there is only one entry in the branch target buffer for each pair of instructions. Therefore, branch instructions, and certain instructions which resemble branches, may adversely affect branch prediction when present in pairs. To reduce the risk of branch misprediction, avoid pairing branch instructions with the following:

* Branch instructions
* Load instructions, whether or not they write r15
* Arithmetic/logic instructions which do not set flags and do not have an immediate value, whether or not they write r15

Flag-setting instructions can be used to avoid this restriction. Additionally, MOV instructions that do not have immediate values can be replaced with ADD, SUB, ORR, or EOR instructions using zero as an immediate value.

== Code alignment ==
Code alignment should be used with caution. Alignment has the potential to increase performance, but may be detrimental in some circumstances.

Because the instruction decoder always fetches 64-bit aligned words from the level-1 instruction cache, aligning code can improve instruction fetch and decode. However, the global history buffer of the branch predictor is indexed by the low bits of the instruction address. Excessive code alignment can result in a suboptimal distribution of entries in the branch history tables and increase branch misprediction. Additionally, the speculative prefetch may retrieve and decode instructions used as padding, even if those instructions are never executed. The types of instructions used as padding will affect the branch predictor as stated above, and this may affect the prefetch of code into the instruction cache.

== NEON ==
As the manual states, passing data from NEON (and VFP) back to ARM takes at least 20 cycles, but there are some tricks that can be used. The vmov instruction itself that is passing the data will not cause any stalls (provided the needed NEON register is already available), the stall will actually happen on any ARM instruction that follows instead (including branches). This means that:
* Multiple "vmov.32 rX, dY[Z]" can be done back-to-back and only incur one stall after the whole sequence
* Additional NEON instructions can be issued after "vmov" without stalling (with enough instructions the stall can be completely avoided)
* Additional unrelated NEON instructions can be issued before "vmov" (to hide the latency of instruction that produces the source register data)

Even though the VFP is not pipelined, the VFP vldr instructions are. "vldr s0, [r0]" will be faster than "vld1.32 {d0[0]}, [r0]" (2 vs 3 cycles, vldr also gives more flexible addressing mode). The same can't be said about "vmov sX, sY", it waits for all previous instructions to complete before issuing.

You should avoid any NEON loads that come from a location that has recently been written to. NEON does not have store forwarding, so this can cost dozens of cycles. This can happen unknowingly if you use unaligned loads, because they're performed with two aligned accesses. For example, if you have this sequence:

loop:
vld1.u32 { q0 }, [r0]
vadd.u32 q0, q0, q1
vst1.u32 { q0 }, [r0]!
subs r1, #1
bne loop

If 0 is unaligned, the next iteration of vld1.u32 will overlap with the previous iteration of vst1.u32, which will cause a stall. To avoid this situation you can reorder the loop so that the store happens one element behind.

[[Category:Development]]
[[Category:Optimization]]
[[Category:Chipset]]

Assembly Code Optimization

2016-04-30T18:57:49Z

Exophase: Added NEON load-hit-store penalties and misaligned access caveat

== Assembly code optimization on the Cortex-A8 ==
This guide presents specific optimization techniques for the [[ARM]] Cortex-A8 processor and its dual-issue, in-order pipeline.

== Use the ARMv7 movw/movt instructions ==
Newer ARM processors allow loading 32-bit values as two 16-bit immediates. The movw instruction loads the lower 16 bits, and movt loads the upper 16 bits. The movw instruction clears the upper 16 bits, so that 16-bit values can be loaded using a single instruction. The movt instruction does not affect the lower bits.

On older ARM processors, it was common to load 32-bit values with a PC-relative load. This should be avoided because it may result in a cache miss.

== Branch Prediction ==
There is a one-cycle stall in instruction fetch when a branch is predicted taken. It is therefore preferable to structure code so that the most likely code path is the one where the branch is not taken.

Unconditional branches may be mispredicted, and load instructions which follow branches may be decoded and cause cache accesses. Avoid placing load instructions after branches unless you intend the CPU to prefetch the addresses they reference.

The branch predictor has a call/return stack for jumps which reference r14 or stack operations using r13 which load the program counter. For best performance, make sure any pop, mov pc,lr or bx lr jumps to the same location as was set by the matching bl instruction. For non-return jumps, use a register other than r14.

Although instructions are decoded in pairs, the branch predictor can only predict one branch target per cycle. If you have a conditional branch which is immediately followed by another branch, and the first branch is likely to be taken, place a no-operation instruction between the branches to prevent decoding and prediction of the second branch. Inserting NOPs is detrimental if the first branch is infrequently taken.

== Dual-Issue Restrictions ==
Only one branch instruction can issue per cycle. Only one load or store instruction can issue per cycle. Instructions which write to the same register can not issue together.

There is a one-cycle delay before any written register can be used as the address of a subsequent load or store instruction. There is a one-cycle delay before any written register can be used by an instruction which performs a shift or rotation on that register.

There is one cycle delay before the result of a load can be used. In the aforementioned cases involving subsequent shift or rotate instructions, or the address of a load or store instruction, the total delay is two cycles.

Stores occur at the end of the pipeline and store instructions can issue in the same cycle as another instruction which writes the same register. Similarly, conditional branches can issue in the same cycle as flag-setting instructions because the branch is not resolved until the following cycle. In all other cases, instructions can not issue together if the second instruction depends on the results of the first.

== Instruction pairing restrictions following a branch ==
The Cortex-A8 processor normally fetches two instructions per cycle and the branch predictor tests each against the global history buffer. However, there is only one entry in the branch target buffer for each pair of instructions. Therefore, branch instructions, and certain instructions which resemble branches, may adversely affect branch prediction when present in pairs. To reduce the risk of branch misprediction, avoid pairing branch instructions with the following:

* Branch instructions
* Load instructions, whether or not they write r15
* Arithmetic/logic instructions which do not set flags and do not have an immediate value, whether or not they write r15

Flag-setting instructions can be used to avoid this restriction. Additionally, MOV instructions that do not have immediate values can be replaced with ADD, SUB, ORR, or EOR instructions using zero as an immediate value.

== Code alignment ==
Code alignment should be used with caution. Alignment has the potential to increase performance, but may be detrimental in some circumstances.

Because the instruction decoder always fetches 64-bit aligned words from the level-1 instruction cache, aligning code can improve instruction fetch and decode. However, the global history buffer of the branch predictor is indexed by the low bits of the instruction address. Excessive code alignment can result in a suboptimal distribution of entries in the branch history tables and increase branch misprediction. Additionally, the speculative prefetch may retrieve and decode instructions used as padding, even if those instructions are never executed. The types of instructions used as padding will affect the branch predictor as stated above, and this may affect the prefetch of code into the instruction cache.

== NEON ==
As the manual states, passing data from NEON (and VFP) back to ARM takes at least 20 cycles, but there are some tricks that can be used. The vmov instruction itself that is passing the data will not cause any stalls (provided the needed NEON register is already available), the stall will actually happen on any ARM instruction that follows instead (including branches). This means that:
* Multiple "vmov.32 rX, dY[Z]" can be done back-to-back and only incur one stall after the whole sequence
* Additional NEON instructions can be issued after "vmov" without stalling (with enough instructions the stall can be completely avoided)
* Additional unrelated NEON instructions can be issued before "vmov" (to hide the latency of instruction that produces the source register data)

Even though the VFP is not pipelined, the VFP vldr instructions are. "vldr s0, [r0]" will be faster than "vld1.32 {d0[0]}, [r0]" (2 vs 3 cycles, vldr also gives more flexible addressing mode). The same can't be said about "vmov sX, sY", it waits for all previous instructions to complete before issuing.

You should avoid any NEON loads that come from a location that has recently been written to. NEON does not have store forwarding, so this can cost dozens of cycles. This can happen unknowingly if you use unaligned loads, because they're performed with two aligned accesses. For example, if you have this sequence:

loop:
vld1.u32 { q0 }, [r0]
vadd.u32 q0, q0, q1
vst1.u32 { q0 }, [r0]!

subs r1, #1
bne loop

If 0 is unaligned, the next iteration of vld1.u32 will overlap with the previous iteration of vst1.u32, which will cause a stall. To avoid this situation you can reorder the loop so that the store happens one element behind.

[[Category:Development]]
[[Category:Optimization]]
[[Category:Chipset]]

DraStic Compatibility List

2014-04-05T04:13:51Z

Exophase:

DraStic is a Nintendo DS Emulator created by Exophase for ARM devices such as the OpenPandora.

* [http://repo.openpandora.org/?page=detail&app=DraStic Download]
* [http://exophase.devzero.co.uk/drastic_readme.txt Readme and Changelog]
* [http://boards.openpandora.org/index.php/topic/12038-emulator-drastic-nintendo-ds/page-1 Forum Thread]

The current version on the Repo is 2.2.1.0, released on March 28th, 2014. It identifies itself as "Version r2.2.1.0p" on the menu screen.

* [http://pandorawiki.org/DraStic_Compatibility_List_1.x Outdated Previous 1.x Version Compatibility List]

==Compatibility==
'By default, games are uncompressed to RAM. 128MB+ compressed games have issues with this CC Pandoras because of limited RAM. 256MB compressed games may work on 512MB systems such as the Rebirth or 1GHz Pandora. 512MB compressed games won't decompress on any system. Compressed games of any size are not dependent on RAM, so should work the same on all systems. You can enable an option to compress to file instead of RAM to get around this problem, but it will make games take longer to start.'

==Adding to the list==
Note: you can use the [http://repo.openpandora.org/?page=detail&app=drasticwikihelper-PowerGod Drastic Wiki Helper] application from the repo to automatically generate appropriate text to paste in the compatibility list below.

Choose a playability color that reflects a game's best playability state. Also include the clockspeed at which you ran it, for whichever Pandora version you tested. Please also indicate in the name of the Game whether the version is US/EU/JP, since compatibility may differ depending on regions. Include the unzipped ROM size in base-2 mebibytes (16MB, 64MB, 128MB, etc.). If available please indicate the game ID figure, too. The Game ID figure should be 8 characters long and can usually be found by pressing Y on the rom selection menu.

'''Don't''' post a redundant entry unless you are using a different Pandora model and the playability differs from an existing entry. If a game's playability gets worse (new bugs, new crashes) in a new DraStic version, update the entry and add that to notes. Please don't copy entries from the old list into this one unless you first re-test the game using a recent version of DraStic and update the color and notes as required.

Default frameskip is automatic and 4. Please record a comment if you use a different setting.

{|class="wikitable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: left;"
|- style="background: #ececec; text-align: center;"
!Playability
!Description
|- style="background: #90FF90"
|Fullspeed
|Games with a '''green''' background run at fullspeed and are fully playable from start to finish. If frameskip is required, add to notes.
|- style="background: #F3F781"
|Playable
|Games with a '''yellow''' background run slower than fullspeed, but are otherwise fully playable. Add problems/slowdowns to notes.
|- style="background: #F7BE81"
|Incomplete
|Games with an '''orange''' background have playability issues and cannot be played from start to finish. This may include missing functionality (wifi) or game crashes. Add problems to notes.
|- style="background: #F78181"
|Unplayable
|Games with a '''red''' background are unplayable. They either don't run at all, or don't get past the intro. Add any other oddities to notes.
|-
|N/A
|Games with a '''white''' background have not been fully tested. If you see one on this list, try it out and report back!
|}
If you are inclined, post your forum username at the end of your notes so you can be contacted by Exophase about further debugging your problems.

==The Compatibility List==


You can sort the colums by clicking the table header (javascript required).

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Game ID
! Game Name
! DraStic Version
! ROM Size
! Pandora Model[1]

! Frequency
! Notes
! Status

|- style="background: #90FF90"
|454d5341
|Super Mario 64 DS
|r2.1.0p
|16MiB
|1GHz
|900MHz
|Minimal graphical tears; almost none; other than that seems to plays perfectly. :(knightron)
|Green

|- style="background: #90FF90"
|454c4759
|Geometry Wars - Galaxies
|r2.1.3p
|64MiB
|1Ghz
|1000Mhz
|Works very well. (ekianjo)
| Green

|- style="background: #F3F781"
|55595241
|Rayman DS
|r2.1.0p
|32MiB
|1GHz
|900MHz
|Very choppy sound often, and frameskip choppyness too. :(knightron)
|Yellow

|- style="background: #90FF90"
|50445441
|42 All Time Classics/Clubhouse Games (E)
|r2.1.0p
|16MiB
|1GHz
|900MHz
|Plays fine with frameskip 2
|Green

|- style="background: #90FF90"
|45575941
|Yoshis Island DS
|r2.1.0p
|32MiB
|1GHz
|900MHz
|Seems to play perfectly. :(Knightron)
|Green

|- style="background: #90FF90"
|45474443
|Disgaea DS (U)
|r2.1.3p
|64MiB
|1Ghz
|1000Mhz
|runs very well overall. No issue detected. (ekianjo)
| Green

|- style="background: #F3F781"
|50425341
|Snowboard Kids
|r2.1.0p
|64MiB
|1GHz
|900MHz
|Runs at full speed but has constant choppy sound during races. :(Knightron)
|Yellow

|- style="background: #90FF90"
|45455341
|Children of Mana
|r2.1.0p
|64MiB
|1GHz
|900MHz
|Seems to play perfectly. :(Knightron)
|Green

|- style="background: #90FF90"
|45555159
|Chrono Trigger
|r2.1.0p
|128MiB
|1GHz
|900MHz
|Seems to run perfect. I did not play long enough to test cut scenes. :(Knightron)
|Green

|- style="background: #90FF90"
|45445741
|Diddy Kong Racing DS
|r2.1.0p
|32MiB
|1GHz
|900MHz
|A couple of graphical bugs in a few places, but seems close to perfect. :(Knightron)
|Green

|- style="background: #90FF90"
|4a554a41
|Jump Ultimate Stars (English patched)
|r2.1.0p
|62.9MiB
|1GHz
|900MHz
|Seems to play perfectly. :(Knightron)
|Green

|- style="background: #F3F781"
|45475049
|Pokemon SoulSilver
|r2.1.0p
|128MiB
|1GHz
|900MHz
|Slight graphical tearing. Lags a little when entering buildings ect. Other than that, it seems very playable. :(Knightron)
|Yellow

|- style="background: #90FF90"
|45484d41
|Metroid Prime Hunters
|r2.1.0p
|64MiB
|1GHz
|900MHz
|Seems close to perfect. Full speed most of the time, but when lots of enemies are fireing at you, it slows down a little. May encounter bigger issues further into the game. :(Knightron)
|Green

|- style="background: #90FF90"
|45524341
|Sprung The Dating Game
|r2.1.0p
|32MiB
|1GHz
|900MHz
|Seems to play perfectly. :(Knightron)
|Green

|- style="background: #F7BE81"
|454a4c43
|Mario and Luigi Bowsers Inside Story
|r2.1.0p
|128MiB
|1GHz
|900MHz
|Plays pretty close to perfect, but freezes during the first fight, while playing as Bowser. :(knightron)
|Orange

|- style="background: #90FF90"
|45355659
|Dragon Quest V Hand of the Heavenly Bride
|r2.1.0p
|128MiB
|1GHz
|900MHz
|Seems to play close to perfectly, very slight choppy inconsistancy between two screens, but not as bad as DQIV. :(Knightron)
|Green

|- style="background: #90FF90"
|45425742
|Plants vs Zombies
|r2.1.0p
|64MiB
|1GHz
|900MHz
|Seems to play perfectly. :(Knightron)
|Green

|- style="background: #90FF90"
|454b5441
|Kirby Canvas Curse
|r2.1.0p
|64MiB
|1GHz
|900MHz
|Seems to play perfectly. :(Knightron)
|Green

|- style="background: #90FF90"
|4a534259
|Soma Bringer (English patched)
|r2.1.0p
|122MiB
|1GHz
|900MHz
|Seems to play perfectly. :(Knightron)
|Green

|- style="background: #90FF90"
|45564959
|Dragon Quest IV Chapters of the Chosen
|r2.1.0p
|128MiB
|1GHz
|900MHz
|It can apear a little choppy when playing with vertical screens, but still plays very well: I switch it to one screen mode. :(Knightron)
|Green

|- style="background: #90FF90"
|45464641
|Final Fantasy III
|r2.1.0p
|128MiB
|1GHz
|900MHz
|Plays pretty damn close to perfect. :(Knightron)
|Green

|- style="background: #F3F781"
|45344659
|Final Fantasy IV
|r2.1.0p
|128MiB
|1GHz
|900MHz
|Plays at full speed, but has choppy sound quite often. :(Knightron)
|Yellow

|- style="background: #F7BE81"
|4a545941
|Tales Of Innocence (English Patched)
|r2.1.0p
|128MiB
|1GHz
|900MHz
|Plays at full speed, but there are major graphical issues that make the game very hard to follow. :(Knightron)
|Orange

|- style="background: #90FF90"
|454b5341
|Lost in Blue
|r2.1.0p
|64MiB
|1GHz
|900MHz
|Plays almost perfectly, just a few very minor graphical and sound bugs in a few spots. Microphone fails sometimes but works again once Drastic is restarted. Game crashes occasionally when atempting to light the fire or build something. At the moment, I recommend regular saving through savestates just in case. :(Knightron)
|Green

|- style="background: #F78181"
|45514459
|Dragon Quest IX Sentinels of the Starry Skies
|r2.1.0p
|22.3MiB
|1GHz
|900MHz
|Game crashes on boot. :(Knightron)
|Red

|- style="background: #90FF90"
|454d5241
|Mario and Luigi Partners in Time
|r2.1.0p
|64MiB
|1GHz
|900MHz
|Seems to play perfectly. :(Knightron)
|Green

|- style="background: #90FF90"
|45495941
|Yoshi Touch & Go
|r2.1.0p
|16MiB
|1GHz
|900MHz
|This Game Apears to play perfectly, but it has major problems when the Pandora is put to sleep. :(Knightron)
|Green

|- style="background: #90FF90"
|454b5342
|9 Hours, 9 Persons, 9 Doors
|r2.0.1p
|128MiB
|Rebirth
|850
|Plays at full speed.
|Green

|- style="background: #90FF90"
|45574b59
|Kirby - Super Star Ultra
|r2.0.1p
|128MiB
|CC
|800
|Plays at full speed.
|Green

|- style="background: #90FF90"
|45365359
|Civilization Revolution DS
|r2.0.1p
|64MiB
|Rebirth
|825MHz
|Fully playable. (Long firststart ~62sec.)
|Green

|- style="background: #90FF90"
|45365359
|Barnyard Blast: Swine of the Night
|r2.0.1p
|8MiB
|1GHz
|1.1GHz
|Works Completely fine. No Lag or Graphical Issues even on cut scenes
|Green

|- style="background: #90FF90"
|45454650
|Fire Emblem: Shadow Dragon (E)
|r2.1.3p
|64MiB
|1GHz
|900MHz
|Runs fine since r2.1.3p
|Green

|- style="background: #90FF90"
|4a564942
|Ivy the Kiwi (J)
|r2.1.3p
|8MiB
|1GHz
|900MHz
|Runs fine since r2.1.0p. Doesn't even need frameskip at 900Mhz.
|Green

|- style="background: #90FF90"
|50505841
|Picross DS (E)
|r2.1.3p
|32MiB
|1GHz
|600MHz
|Very minor graphical glitch where at end of level the top screen image transitions from monochrome to (animated) colour - one pixel line of monochrome image is left above the animated image.
|Green

|- style="background: #90FF90"
|50503643
|Picross 3D (E)
|r2.1.3p
|32MiB
|1GHz
|600MHz
|Absolutely perfect since version r2.1.0p
|Green

|- style="background: #F3F781"
|50344759
|Suikoden Tierkreis
|r2.0.1p
|256MiB
|Rebirth
|900MHz
|Sound sometimes a bit laggy during battle. (tested for 40min only)
|Yellow

|- style="background: #90FF90"
|45375341
|Summon Night, Twin Age
|r2.0.1p
|128MiB
|Rebirth
|900MHz
|nice. (tested for 10h)
|Green

|- style="background: #F3F781"
|404c5741
|The World Ends With You (E)
|r2.0.1p
|128MiB
|Rebirth
|900MHz
|Ran fine as far as the end of the first day. (not further tested.)
|Yellow

|- style="background: #90FF90"
|45434d41
|MarioKart DS (US)
|r2.1.3p
|32MiB
|1GHz
|1050MHz
|Runs fine with frameskip
|Green

|- style="background: #90FF90"
|45444e41
|Brain Age - Train Your Brain in Minutes a Day! (v01)
|r2.1.0p
|16MiB
|1Ghz
|800 Mhz
|Works great. (PowerGod)
|Green

|- style="background: #90FF90"
|50444e41
|Dr Kawashima's Brain Training - How Old Is Your Brain
|r2.1.0p
|16MiB
|1Ghz
|800 Mhz
|Works great. (PowerGod)
|Green

|- style="background: #F3F781"
|455a4443
|Dragon Ball - Origins
|r2.1.6.1p
|64MiB
|1Ghz
|800 Mhz
|Playable with some lag. (PowerGod)
|Yellow

|- style="background: #90FF90"
|45503743
|Peggle Dual Shot
|r2.1.3p
|64MiB
|1Ghz
|750MHz
|Perfect play, fluid motion, just like the real thing. :(kumaki+levi)
|Green

|- style="background: #F3F781"
|45533241
|Dragon Ball Z - Supersonic Warriors 2
|r2.0.1p
|64MiB
|1Ghz
|800 Mhz
|Playable with some lag. (PowerGod)
|Yellow

|- style="background: #F3F781"
|45414441
|Pokemon Diamond Version (v13)
|r2.0.1p
|64MiB
|1Ghz
|800 Mhz
|No text in the introduction tutorial. Only played it a bit. (PowerGod)
(Edit by knightron: text is now played in DraStic 2.1.0p)
|Yellow

|- style="background: #90FF90"
|45433643
|Infinite Space
|r2.1.3p
|256MiB
|1Ghz
|1050Mhz
|Plays well. Graphical glitches in the attract mode. Played only as far as the first spaceport. (levi)
|Green
|- style="background: #90FF90"
|50385243
|Crash - Mind Over Mutant (U)
|r2.1.3p
|64MiB
|CC
|800Mhz
|works perfect at default (dsleaf67)
| Green

|- style="background: #90FF90"
|50595943
|Giana Sisters DS (U)
|r2.1.3p
|8MiB
|CC
|800Mhz
|works perfect (dsleaf67)
| Green

|- style="background: #F3F781"
|50595943
|Giana Sisters DS (E)
|r2.1.6.1p
|8MiB
|1Ghz
|800Mhz
|Playable, but there are issues with the microphone in later levels and it should be disabled (to use the jump button instead) in order to use the bubble. UPDATE: actually seems something related more to the DraStic session than to the game itself, because when the issue happened I made a savestate, and even reloading it had the same issue, but after restarting DraStic that savestate is working right (PowerGod)
| Yellow

|- style="background: #90FF90"
|45563241
|M&M's - Break'em (U)
|r2.1.3p
|8MiB
|CC
|800Mhz
|works great only has minor sound issue at start (dsleaf67)
| Green

|- style="background: #90FF90"
|45575041
|Pac-Man World 3 (U)
|r2.1.3p
|32MiB
|CC
|800Mhz
|works good some slowdowns but very playable (dsleaf67)
| Green
|- style="background: #F3F781"
|454a5141
|Crash of the Titans (U)
|r2.1.3p
|128MiB
|CC
|800Mhz
|playable with choppy sound and some slow downs (dsleaf67)
| Yellow

|- style="background: #F3F781"
|50394643
|FIFA 09 (U)
|r2.1.3p
|32MiB
|CC
|800Mhz
|playable with sound issues (dsleaf67)
| Yellow

|- style="background: #90FF90"
|45413541
|Golden Compass, The (U)
|r2.1.3p
|64MiB
|CC
|800Mhz
|works good minor sound issues (dsleaf67)
| Green

|- style="background: #90FF90"
|45424a59
|LEGO Batman - The Videogame (U)
|r2.1.3p
|64MiB
|CC
|800Mhz
|works great (dsleaf67)
| Green

|- style="background: #F7BE81"
|50494b42
|Legend of Zelda - Spirit Tracks, The (E)
|r2.1.6.1p
|128MiB
|1Ghz
|1100Mhz
|when you're supposed to use the microphone to blow in the flute it doesn't work. (frostfall)
| Orange

|- style="background: #F3F781"
|45343243
|Phantasy Star 0
|r2.1.6.1p
|128MiB
|Rebirth
|600Mhz
|Nice gameplay, but the sound with some problem, 80~90% in battle. The game crash if you are using saves state and try to feed the MAG, if you use normal save and reset the game work fine. (MarTinazzI)
| Yellow

|- style="background: #90FF90"
|454d3341
|Dynasty Warriors DS - Fighter's Battle (E)
|r2.1.6.1p
|128MiB
|Rebirth
|600Mhz
| (MarTinazzI)
| Green

|- style="background: #90FF90"
|454d4241
|Bomberman (E)
|r2.1.6.1p
|8MiB
|Rebirth
|600Mhz
| (MarTinazzI)
| Green

|- style="background: #90FF90"
|504e4241
|Bomberman Story DS (U)
|r2.1.6.1p
|128MiB
|Rebirth
|600Mhz
| (MarTinazzI)
| Green

|- style="background: #90FF90"
|45584241
|Bomberman Land Touch!
|r2.1.6.1p
|32MiB
|Rebirth
|600Mhz
| (MarTinazzI)
| Green

|- style="background: #90FF90"
|45324259
|Bomberman Land Touch! 2
|r2.1.6.1p
|32MiB
|Rebirth
|600Mhz
| (MarTinazzI)
| Green

|- style="background: #F3F781"
|45435741
|Drone Tactics (U)
|r2.1.6.1p
|64MiB
|Rebirth
|600Mhz
|Only in battle scene run about 70~90% (MarTinazzI)
| Yellow

|- style="background: #90FF90"
|454a5841
|Dungeon Explorer - Warriors of Ancient Arts (U)
|r2.1.6.1p
|64MiB
|Rebirth
|600Mhz
| (MarTinazzI)
| Green

|- style="background: #F3F781"
|45474b59
|Kingdom Hearts - 358-2 Days
|r2.1.6.1p
|256MiB
|Rebirth
|600Mhz
|Run 75~90% and bad sound, but playable (MarTinazzI)
| Yellow

|- style="background: #90FF90"
|45574b59
|Kirby - Super Star Ultra (U)
|r2.1.6.1p
|128MiB
|Rebirth
|600Mhz
| (MarTinazzI)
| Green

|- style="background: #F3F781"
|454e4c41
|Lunar - Dragon Song (U)
|r2.1.6.1p
|32MiB
|Rebirth
|600Mhz
|Some lag on action select in battle, 70~90% but in far of the game seem all 100%, need test early game again. (MarTinazzI)
| Yellow

|- style="background: #F78181"
|45555043
|Pokemon - Platinum Version (v10) (U)
|r2.1.6.1p
|128MiB
|Rebirth
|600Mhz
|bug on introduction. blinking screen and game stop (MarTinazzI)
| Red

|- style="background: #90FF90"
|45555043
|Pokemon - Platinum Version (DE)
|r2.2.0.0p
|128MiB
|CC
|900Mhz
|some slowdowns, especially with Pokéfetch. However seem to run quite smooth at 900 Mhz.
| Green

|- style="background: #F78181"
|4f415249
|Pokemon - White Version (DSi Enhanced)(USA) (U)
|r2.1.6.1p
|256MiB
|Rebirth
|600Mhz
|just close the game on introduction (MarTinazzI)
| Red

|- style="background: #F78181"
|454c4859
|Time Hollow (U)
|r2.1.6.1p
|128MiB
|1Ghz
|975Mhz
|Game crashes at the beginning of Chapter 2, also ingame saves doesn't work at all (PowerGod)
| Red

|}


===Notes===

1. Pandora model:
* CC - OMAP3530 SoC@600Mhz stock, 256MiB RAM@166MHz
* Rebirth - OMAP3530 SoC@600MHz stock, '''512MiB RAM'''@166MHz
* 1GHz - '''DM3730 SoC@1GHz stock''', 512MiB RAM@'''200Mhz'''

[[Category:Emulators]]
[[Category: Compatibility]]
[[Category:List]]

Kernel interface

2010-06-21T00:50:46Z

Exophase: /* Input */

'''Warning''': if your goal is just to write a game/program use higher level libraries/interfaces like SDL, Qt, X or similar for your own good (portability). It may be impossible to retain this layout on some major hardware revision, let's say Pandora 3000, and your program will break. Also this requires some level of Linux programming knowledge.

In case you need to write low level code (you can't/don't want to use high level libs like SDL), you can use kernel interface. This is the recommended way to access hardware (as opposed to GP2X style of accessing chip registers by mmap'ing /dev/mem), because in case hardware changes are needed in future, they could be handled by kernel and all programs would still work. It also should allow several programs to work at the same time and should be more stable.

==Input==
Buttons, keypad, touchscreen and nubs are all exposed through Linux event interface (EVDEV). All devices are represented by /dev/input/eventX files, which can be opened, read and queried (using ioctl calls). The reads can be synchronous (the read will only return when user does something, like presses the button), or asynchronous (the system will report what changed since the last time you asked).

'''Warning''': don't hardcode device filenames in your program! For example, currently /dev/input/event2 represents game buttons, but in future it may become touchscreen. Scan input device names instead, example:
<source lang="c">
for (i = 0; 1; i++)
{
sprintf(name, "/dev/input/event%i", i);
fd = open(name, O_RDONLY);
if (fd < 0) break; /* no more devices */
ioctl(fd, EVIOCGNAME(sizeof(name)), name);
if (strcmp(name, "gpio-keys") == 0)
return fd; /* found the buttons! */
close(fd); /* we don't need this device */
}
</source>

List of device names and events they send:
{|border=1 cellpadding=2 cellspacing=0
|-
!name
!description
!event.type
!event.code
!event.value
|-
|keypad
|keypad
|EV_KEY
|KEY_0...KEY_Z, KEY_BACKSPACE, KEY_LEFTSHIFT, KEY_SPACE, KEY_ENTER, KEY_COMMA, KEY_DOT, KEY_FN
|0 - released, 1 - pressed, 2 - autorepeat event
|-
|gpio-keys
|game buttons
|EV_KEY
|KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_MENU (Pandora button), KEY_LEFTALT (Start), KEY_LEFTCTRL (Select), KEY_END (Y/North), KEY_HOME (A/East), KEY_PAGEDOWN (X/South), KEY_END (B/West), KEY_RIGHTSHIFT (Shoulder L), KEY_RIGHTCTRL (Shoulder R), KEY_KPPLUS (Shoulder L2), KEY_KPMINUS (Shoulder R2), KEY_COFFEE (Hold)
|0 - released, 1 - pressed
|-
|gpio-keys
|lid state
|EV_SW
|SW_LID
|0 - closing, 1 - opening
|-
|touchscreen
|touchscreen
|EV_ABS
|ABS_X, ABS_Y, ABS_PRESSURE
|varies, use calibration data
|-
|nub0
|left nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|-
|nub1
|right nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|}

Sample code: 
[http://beagleboard.googlecode.com/files/evtest.c evtest.c]
[http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-misc.git;a=blob;f=op_test_inputs.c;hb=HEAD op_test_inputs.c]

===Touchscreen===
Event interface returns uncalibrated values directly from driver, so you need to use tslib or manage calibration yourself (using data from /etc/pointercal).

==Sound==
Pandora uses ALSA, but it has OSS emulation enabled too, so GP2X code should work.

==Video==
===Architecture===
Framebuffer device (/dev/fbX) is supported. There are 3 framebuffers available (/dev/fb0, /dev/fb1 and /dev/fb2), which represent 3 graphics/video layers on OMAP3 by default (but can be reconfigured). Only /dev/fb0 is enabled by default.

OMAP3 display subsystem is controlled by a driver known as DSS2, which has various controls available on /sys/devices/platform/omapdss/ (but they are not meant to be changed by programs, so they are root writable only). The driver exposes 3 layers (called overlays) and 2 displays. Overlays 1 and 2 can perform hardware scaling on the fly using 5-tap poly-phase filter, overlay0 can not. Displays 0 and 1 represent LCD and TV respectively. By default the 3 framebuffers (/dev/fbX) are redirected to 3 overlays, which all output to the LCD. This configuration is not meant to be changed by programs, only firmware should manage these.

===Basic usage===
====framebuffer interface====
Framebuffers can be accessed Linux fbdev interface:
<source lang="c">
fbdev = open("/dev/fb0", O_RDONLY);
buffer = mmap(0, 800*480*2, PROT_WRITE, MAP_SHARED, fbdev, 0);
</source>
(this is basic example, no error checks)

the returned pointer can be used to draw on the screen.

Be sure to #include <linux/fb.h> to get access to the FB device ioctl interface, and <sys/ioctl.h> for access to ioctl itself.

====double buffering====
This can be achieved using FBIOPAN_DISPLAY ioctl system call. For this you need to mmap framebuffer of double size
<source lang="c">
buffer1 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 0);
buffer2 = (char *)mem + 800*480*2;
</source>

Then to display buffer2 you would call:
<source lang="c">
struct fb_var_screeninfo fbvar;
ioctl(fbdev, FBIOGET_VSCREENINFO, &fbvar);
fbvar.yoffset = 480;
ioctl(fbdev, FBIOPAN_DISPLAY, &fbvar);
</source>
going back to buffer1 would be repeating above with fbvar.yoffset = 0. Tripple or quad buffering can be implemented using the same technique.

====vertical sync====
Linux has standard FBIO_WAITFORVSYNC for this:
<source lang="c">
int arg = 0;
ioctl(fbdev, FBIO_WAITFORVSYNC, &arg);
</source>
be sure to pass argument value 0 or it will not work.

Currently FBIO_WAITFORVSYNC is not defined in <linux/fb.h>, although this is in the process of modification. For now, define in the following manner:

<source lang="c">
#ifndef FBIO_WAITFORVSYNC
#define FBIO_WAITFORVSYNC _IOW('F', 0x20, __u32)
#endif
</source>

====hardware scaling====
Overlay1 (/dev/fb1) can be used to achieve hardware scaling. Technically overlay2 (fb2) can be used for this too, but it is planned to be used by the system for TV-out functionality, so don't use it. The overlay is configured using series of standard and OMAP specific ioctl calls, but the system ships with some tools to achieve this from scripts too. This way the framebuffer can be set up for some arbitrary size (say 320x240) and can output to LCD as 800x480 with hardware scaling.
Here is an example script:
<source lang="bash">
ofbset -fb /dev/fb1 -pos 0 0 -size 800 480 -mem 307200 -en 1
fbset -fb /dev/fb1 -g 320 240 320 480 16

./your_app_here

ofbset -fb /dev/fb1 -pos 0 0 -size 0 0 -mem 0 -en 0
</source>

What it does:
* allocates OMAP DSS layer, asks video output to be 800x480 at position 0,0 (could set it to 640x480 at 80,0 instead to get centered 2x scaling of 320x240). 307200 bytes of video memory are allocated for 2 320x240 16bpp screens (for doublebuffering).
* sets video mode to 320x240@16bpp, virtual resolution 320x480 for doublebuffering.
* runs your app
* cleans the video layer on exit

Now the program can act as if works with 16bpp screen.

==LEDs and backlight==
The LEDs can be controlled via /sys/class/leds/, and then a file [http://www.gp32x.com/board/index.php?s=&showtopic=45309&view=findpost&p=673593]:
* pandora::sd1
* pandora::sd2
* pandora::charger
* pandora::power
* pandora::bluetooth
* pandora::wifi
* pandora::keypad_bl
Backlight can be controlled via /sys/class/backlight/.

==Misc==
Some things can be controlled through files in /proc/pandora/:
* /proc/pandora/cpu_mhz_max - if [http://www.kernel.org/pub/linux/utils/kernel/cpufreq/cpufreq.html cpufreq] is enabled, sets maximum allowed cpu clock, if not, just sets CPU clock to value supplied (echo 600 > /proc/pandora/cpu_mhz_max). Might also just use cpufreq parameters themselves.
more to come..
[[Category:Development]]

Kernel interface

2010-06-20T00:05:41Z

Exophase: /* Input */

'''Warning''': if your goal is just to write a game/program use higher level libraries/interfaces like SDL, Qt, X or similar for your own good (portability). It may be impossible to retain this layout on some major hardware revision, let's say Pandora 3000, and your program will break. Also this requires some level of Linux programming knowledge.

In case you need to write low level code (you can't/don't want to use high level libs like SDL), you can use kernel interface. This is the recommended way to access hardware (as opposed to GP2X style of accessing chip registers by mmap'ing /dev/mem), because in case hardware changes are needed in future, they could be handled by kernel and all programs would still work. It also should allow several programs to work at the same time and should be more stable.

==Input==
Buttons, keypad, touchscreen and nubs are all exposed through Linux event interface (EVDEV). All devices are represented by /dev/input/eventX files, which can be opened, read and queried (using ioctl calls). The reads can be synchronous (the read will only return when user does something, like presses the button), or asynchronous (the system will report what changed since the last time you asked).

'''Warning''': don't hardcode device filenames in your program! For example, currently /dev/input/event2 represents game buttons, but in future it may become touchscreen. Scan input device names instead, example:
<source lang="c">
for (i = 0; 1; i++)
{
sprintf(name, "/dev/input/event%i", i);
fd = open(name, O_RDONLY);
if (fd < 0) break; /* no more devices */
ioctl(fd, EVIOCGNAME(sizeof(name)), name);
if (strcmp(name, "gpio-keys") == 0)
return fd; /* found the buttons! */
close(fd); /* we don't need this device */
}
</source>

List of device names and events they send:
{|border=1 cellpadding=2 cellspacing=0
|-
!name
!description
!event.type
!event.code
!event.value
|-
|keypad
|keypad
|EV_KEY
|KEY_0...KEY_Z, KEY_BACKSPACE, KEY_LEFTSHIFT, KEY_SPACE, KEY_ENTER, KEY_COMMA, KEY_DOT, KEY_FN
|0 - released, 1 - pressed, 2 - autorepeat event
|-
|gpio-keys
|game buttons
|EV_KEY
|KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_MENU (Pandora button), KEY_LEFTALT (Start), KEY_LEFTCTRL (Select), KEY_END (Y/North), KEY_HOME (A/East), KEY_PAGEDOWN (X/South), KEY_END (B/West), KEY_RIGHTSHIFT (Shoulder L), KEY_RIGHTCTRL (Shoulder R), KEY_KP7 (Shoulder L2), KEY_KP8 (Shoulder R2), KEY_COFFEE (Hold)
|0 - released, 1 - pressed
|-
|gpio-keys
|lid state
|EV_SW
|SW_LID
|0 - closing, 1 - opening
|-
|touchscreen
|touchscreen
|EV_ABS
|ABS_X, ABS_Y, ABS_PRESSURE
|varies, use calibration data
|-
|nub0
|left nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|-
|nub1
|right nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|}

Sample code: 
[http://beagleboard.googlecode.com/files/evtest.c evtest.c]
[http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-misc.git;a=blob;f=op_test_inputs.c;hb=HEAD op_test_inputs.c]

===Touchscreen===
Event interface returns uncalibrated values directly from driver, so you need to use tslib or manage calibration yourself (using data from /etc/pointercal).

==Sound==
Pandora uses ALSA, but it has OSS emulation enabled too, so GP2X code should work.

==Video==
===Architecture===
Framebuffer device (/dev/fbX) is supported. There are 3 framebuffers available (/dev/fb0, /dev/fb1 and /dev/fb2), which represent 3 graphics/video layers on OMAP3 by default (but can be reconfigured). Only /dev/fb0 is enabled by default.

OMAP3 display subsystem is controlled by a driver known as DSS2, which has various controls available on /sys/devices/platform/omapdss/ (but they are not meant to be changed by programs, so they are root writable only). The driver exposes 3 layers (called overlays) and 2 displays. Overlays 1 and 2 can perform hardware scaling on the fly using 5-tap poly-phase filter, overlay0 can not. Displays 0 and 1 represent LCD and TV respectively. By default the 3 framebuffers (/dev/fbX) are redirected to 3 overlays, which all output to the LCD. This configuration is not meant to be changed by programs, only firmware should manage these.

===Basic usage===
====framebuffer interface====
Framebuffers can be accessed Linux fbdev interface:
<source lang="c">
fbdev = open("/dev/fb0", O_RDONLY);
buffer = mmap(0, 800*480*2, PROT_WRITE, MAP_SHARED, fbdev, 0);
</source>
(this is basic example, no error checks)

the returned pointer can be used to draw on the screen.

Be sure to #include <linux/fb.h> to get access to the FB device ioctl interface, and <sys/ioctl.h> for access to ioctl itself.

====double buffering====
This can be achieved using FBIOPAN_DISPLAY ioctl system call. For this you need to mmap framebuffer of double size
<source lang="c">
buffer1 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 0);
buffer2 = (char *)mem + 800*480*2;
</source>

Then to display buffer2 you would call:
<source lang="c">
struct fb_var_screeninfo fbvar;
ioctl(fbdev, FBIOGET_VSCREENINFO, &fbvar);
fbvar.yoffset = 480;
ioctl(fbdev, FBIOPAN_DISPLAY, &fbvar);
</source>
going back to buffer1 would be repeating above with fbvar.yoffset = 0. Tripple or quad buffering can be implemented using the same technique.

====vertical sync====
Linux has standard FBIO_WAITFORVSYNC for this:
<source lang="c">
int arg = 0;
ioctl(fbdev, FBIO_WAITFORVSYNC, &arg);
</source>
be sure to pass argument value 0 or it will not work.

Currently FBIO_WAITFORVSYNC is not defined in <linux/fb.h>, although this is in the process of modification. For now, define in the following manner:

<source lang="c">
#ifndef FBIO_WAITFORVSYNC
#define FBIO_WAITFORVSYNC _IOW('F', 0x20, __u32)
#endif
</source>

====hardware scaling====
Overlay1 (/dev/fb1) can be used to achieve hardware scaling. Technically overlay2 (fb2) can be used for this too, but it is planned to be used by the system for TV-out functionality, so don't use it. The overlay is configured using series of standard and OMAP specific ioctl calls, but the system ships with some tools to achieve this from scripts too. This way the framebuffer can be set up for some arbitrary size (say 320x240) and can output to LCD as 800x480 with hardware scaling.
Here is an example script:
<source lang="bash">
ofbset -fb /dev/fb1 -pos 0 0 -size 800 480 -mem 307200 -en 1
fbset -fb /dev/fb1 -g 320 240 320 480 16

./your_app_here

ofbset -fb /dev/fb1 -pos 0 0 -size 0 0 -mem 0 -en 0
</source>

What it does:
* allocates OMAP DSS layer, asks video output to be 800x480 at position 0,0 (could set it to 640x480 at 80,0 instead to get centered 2x scaling of 320x240). 307200 bytes of video memory are allocated for 2 320x240 16bpp screens (for doublebuffering).
* sets video mode to 320x240@16bpp, virtual resolution 320x480 for doublebuffering.
* runs your app
* cleans the video layer on exit

Now the program can act as if works with 16bpp screen.

==LEDs and backlight==
The LEDs can be controlled via /sys/class/leds/, and then a file [http://www.gp32x.com/board/index.php?s=&showtopic=45309&view=findpost&p=673593]:
* pandora::sd1
* pandora::sd2
* pandora::charger
* pandora::power
* pandora::bluetooth
* pandora::wifi
* pandora::keypad_bl
Backlight can be controlled via /sys/class/backlight/.

==Misc==
Some things can be controlled through files in /proc/pandora/:
* /proc/pandora/cpu_mhz_max - if [http://www.kernel.org/pub/linux/utils/kernel/cpufreq/cpufreq.html cpufreq] is enabled, sets maximum allowed cpu clock, if not, just sets CPU clock to value supplied (echo 600 > /proc/pandora/cpu_mhz_max). Might also just use cpufreq parameters themselves.
more to come..
[[Category:Development]]

Kernel interface

2010-06-19T11:01:10Z

Exophase: /* double buffering */

'''Warning''': if your goal is just to write a game/program use higher level libraries/interfaces like SDL, Qt, X or similar for your own good (portability). It may be impossible to retain this layout on some major hardware revision, let's say Pandora 3000, and your program will break. Also this requires some level of Linux programming knowledge.

In case you need to write low level code (you can't/don't want to use high level libs like SDL), you can use kernel interface. This is the recommended way to access hardware (as opposed to GP2X style of accessing chip registers by mmap'ing /dev/mem), because in case hardware changes are needed in future, they could be handled by kernel and all programs would still work. It also should allow several programs to work at the same time and should be more stable.

==Input==
Buttons, keypad, touchscreen and nubs are all exposed through Linux event interface (EVDEV). All devices are represented by /dev/input/eventX files, which can be opened, read and queried (using ioctl calls). The reads can be synchronous (the read will only return when user does something, like presses the button), or asynchronous (the system will report what changed since the last time you asked).

'''Warning''': don't hardcode device filenames in your program! For example, currently /dev/input/event2 represents game buttons, but in future it may become touchscreen. Scan input device names instead, example:
<source lang="c">
for (i = 0; 1; i++)
{
sprintf(name, "/dev/input/event%i", i);
fd = open(name, O_RDONLY);
if (fd < 0) break; /* no more devices */
ioctl(fd, EVIOCGNAME(sizeof(name)), name);
if (strcmp(name, "gpio-keys") == 0)
return fd; /* found the buttons! */
close(fd); /* we don't need this device */
}
</source>

List of device names and events they send:
{|border=1 cellpadding=2 cellspacing=0
|-
!name
!description
!event.type
!event.code
!event.value
|-
|keypad
|keypad
|EV_KEY
|KEY_0...KEY_Z, KEY_BACKSPACE, KEY_LEFTSHIFT, KEY_SPACE, KEY_ENTER, KEY_COMMA, KEY_DOT, KEY_FN
|0 - released, 1 - pressed, 2 - autorepeat event
|-
|gpio-keys
|game buttons
|EV_KEY
|KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_MENU (Pandora button), KEY_LEFTALT (Start), KEY_LEFTCTRL (Select), KEY_KP1 (Y/North), KEY_KP2 (A/East), KEY_KP3 (X/South), KEY_KP4 (B/West), KEY_KP5 (Shoulder L), KEY_KP6 (Shoulder R), KEY_KP7 (Shoulder L2), KEY_KP8 (Shoulder R2), KEY_COFFEE (Hold)
|0 - released, 1 - pressed
|-
|gpio-keys
|lid state
|EV_SW
|SW_LID
|0 - closing, 1 - opening
|-
|touchscreen
|touchscreen
|EV_ABS
|ABS_X, ABS_Y, ABS_PRESSURE
|varies, use calibration data
|-
|nub0
|left nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|-
|nub1
|right nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|}

Sample code: 
[http://beagleboard.googlecode.com/files/evtest.c evtest.c]
[http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-misc.git;a=blob;f=op_test_inputs.c;hb=HEAD op_test_inputs.c]

===Touchscreen===
Event interface returns uncalibrated values directly from driver, so you need to use tslib or manage calibration yourself (using data from /etc/pointercal).

==Sound==
Pandora uses ALSA, but it has OSS emulation enabled too, so GP2X code should work.

==Video==
===Architecture===
Framebuffer device (/dev/fbX) is supported. There are 3 framebuffers available (/dev/fb0, /dev/fb1 and /dev/fb2), which represent 3 graphics/video layers on OMAP3 by default (but can be reconfigured). Only /dev/fb0 is enabled by default.

OMAP3 display subsystem is controlled by a driver known as DSS2, which has various controls available on /sys/devices/platform/omapdss/ (but they are not meant to be changed by programs, so they are root writable only). The driver exposes 3 layers (called overlays) and 2 displays. Overlays 1 and 2 can perform hardware scaling on the fly using 5-tap poly-phase filter, overlay0 can not. Displays 0 and 1 represent LCD and TV respectively. By default the 3 framebuffers (/dev/fbX) are redirected to 3 overlays, which all output to the LCD. This configuration is not meant to be changed by programs, only firmware should manage these.

===Basic usage===
====framebuffer interface====
Framebuffers can be accessed Linux fbdev interface:
<source lang="c">
fbdev = open("/dev/fb0", O_RDONLY);
buffer = mmap(0, 800*480*2, PROT_WRITE, MAP_SHARED, fbdev, 0);
</source>
(this is basic example, no error checks)

the returned pointer can be used to draw on the screen.

Be sure to #include <linux/fb.h> to get access to the FB device ioctl interface, and <sys/ioctl.h> for access to ioctl itself.

====double buffering====
This can be achieved using FBIOPAN_DISPLAY ioctl system call. For this you need to mmap framebuffer of double size
<source lang="c">
buffer1 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 0);
buffer2 = (char *)mem + 800*480*2;
</source>

Then to display buffer2 you would call:
<source lang="c">
struct fb_var_screeninfo fbvar;
ioctl(fbdev, FBIOGET_VSCREENINFO, &fbvar);
fbvar.yoffset = 480;
ioctl(fbdev, FBIOPAN_DISPLAY, &fbvar);
</source>
going back to buffer1 would be repeating above with fbvar.yoffset = 0. Tripple or quad buffering can be implemented using the same technique.

====vertical sync====
Linux has standard FBIO_WAITFORVSYNC for this:
<source lang="c">
int arg = 0;
ioctl(fbdev, FBIO_WAITFORVSYNC, &arg);
</source>
be sure to pass argument value 0 or it will not work.

Currently FBIO_WAITFORVSYNC is not defined in <linux/fb.h>, although this is in the process of modification. For now, define in the following manner:

<source lang="c">
#ifndef FBIO_WAITFORVSYNC
#define FBIO_WAITFORVSYNC _IOW('F', 0x20, __u32)
#endif
</source>

====hardware scaling====
Overlay1 (/dev/fb1) can be used to achieve hardware scaling. Technically overlay2 (fb2) can be used for this too, but it is planned to be used by the system for TV-out functionality, so don't use it. The overlay is configured using series of standard and OMAP specific ioctl calls, but the system ships with some tools to achieve this from scripts too. This way the framebuffer can be set up for some arbitrary size (say 320x240) and can output to LCD as 800x480 with hardware scaling.
Here is an example script:
<source lang="bash">
ofbset -fb /dev/fb1 -pos 0 0 -size 800 480 -mem 307200 -en 1
fbset -fb /dev/fb1 -g 320 240 320 480 16

./your_app_here

ofbset -fb /dev/fb1 -pos 0 0 -size 0 0 -mem 0 -en 0
</source>

What it does:
* allocates OMAP DSS layer, asks video output to be 800x480 at position 0,0 (could set it to 640x480 at 80,0 instead to get centered 2x scaling of 320x240). 307200 bytes of video memory are allocated for 2 320x240 16bpp screens (for doublebuffering).
* sets video mode to 320x240@16bpp, virtual resolution 320x480 for doublebuffering.
* runs your app
* cleans the video layer on exit

Now the program can act as if works with 16bpp screen.

==LEDs and backlight==
The LEDs can be controlled via /sys/class/leds/, and then a file [http://www.gp32x.com/board/index.php?s=&showtopic=45309&view=findpost&p=673593]:
* pandora::sd1
* pandora::sd2
* pandora::charger
* pandora::power
* pandora::bluetooth
* pandora::wifi
* pandora::keypad_bl
Backlight can be controlled via /sys/class/backlight/.

==Misc==
Some things can be controlled through files in /proc/pandora/:
* /proc/pandora/cpu_mhz_max - if [http://www.kernel.org/pub/linux/utils/kernel/cpufreq/cpufreq.html cpufreq] is enabled, sets maximum allowed cpu clock, if not, just sets CPU clock to value supplied (echo 600 > /proc/pandora/cpu_mhz_max). Might also just use cpufreq parameters themselves.
more to come..
[[Category:Development]]

Kernel interface

2010-06-19T10:59:29Z

Exophase: /* vertical sync */

'''Warning''': if your goal is just to write a game/program use higher level libraries/interfaces like SDL, Qt, X or similar for your own good (portability). It may be impossible to retain this layout on some major hardware revision, let's say Pandora 3000, and your program will break. Also this requires some level of Linux programming knowledge.

In case you need to write low level code (you can't/don't want to use high level libs like SDL), you can use kernel interface. This is the recommended way to access hardware (as opposed to GP2X style of accessing chip registers by mmap'ing /dev/mem), because in case hardware changes are needed in future, they could be handled by kernel and all programs would still work. It also should allow several programs to work at the same time and should be more stable.

==Input==
Buttons, keypad, touchscreen and nubs are all exposed through Linux event interface (EVDEV). All devices are represented by /dev/input/eventX files, which can be opened, read and queried (using ioctl calls). The reads can be synchronous (the read will only return when user does something, like presses the button), or asynchronous (the system will report what changed since the last time you asked).

'''Warning''': don't hardcode device filenames in your program! For example, currently /dev/input/event2 represents game buttons, but in future it may become touchscreen. Scan input device names instead, example:
<source lang="c">
for (i = 0; 1; i++)
{
sprintf(name, "/dev/input/event%i", i);
fd = open(name, O_RDONLY);
if (fd < 0) break; /* no more devices */
ioctl(fd, EVIOCGNAME(sizeof(name)), name);
if (strcmp(name, "gpio-keys") == 0)
return fd; /* found the buttons! */
close(fd); /* we don't need this device */
}
</source>

List of device names and events they send:
{|border=1 cellpadding=2 cellspacing=0
|-
!name
!description
!event.type
!event.code
!event.value
|-
|keypad
|keypad
|EV_KEY
|KEY_0...KEY_Z, KEY_BACKSPACE, KEY_LEFTSHIFT, KEY_SPACE, KEY_ENTER, KEY_COMMA, KEY_DOT, KEY_FN
|0 - released, 1 - pressed, 2 - autorepeat event
|-
|gpio-keys
|game buttons
|EV_KEY
|KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_MENU (Pandora button), KEY_LEFTALT (Start), KEY_LEFTCTRL (Select), KEY_KP1 (Y/North), KEY_KP2 (A/East), KEY_KP3 (X/South), KEY_KP4 (B/West), KEY_KP5 (Shoulder L), KEY_KP6 (Shoulder R), KEY_KP7 (Shoulder L2), KEY_KP8 (Shoulder R2), KEY_COFFEE (Hold)
|0 - released, 1 - pressed
|-
|gpio-keys
|lid state
|EV_SW
|SW_LID
|0 - closing, 1 - opening
|-
|touchscreen
|touchscreen
|EV_ABS
|ABS_X, ABS_Y, ABS_PRESSURE
|varies, use calibration data
|-
|nub0
|left nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|-
|nub1
|right nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|}

Sample code: 
[http://beagleboard.googlecode.com/files/evtest.c evtest.c]
[http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-misc.git;a=blob;f=op_test_inputs.c;hb=HEAD op_test_inputs.c]

===Touchscreen===
Event interface returns uncalibrated values directly from driver, so you need to use tslib or manage calibration yourself (using data from /etc/pointercal).

==Sound==
Pandora uses ALSA, but it has OSS emulation enabled too, so GP2X code should work.

==Video==
===Architecture===
Framebuffer device (/dev/fbX) is supported. There are 3 framebuffers available (/dev/fb0, /dev/fb1 and /dev/fb2), which represent 3 graphics/video layers on OMAP3 by default (but can be reconfigured). Only /dev/fb0 is enabled by default.

OMAP3 display subsystem is controlled by a driver known as DSS2, which has various controls available on /sys/devices/platform/omapdss/ (but they are not meant to be changed by programs, so they are root writable only). The driver exposes 3 layers (called overlays) and 2 displays. Overlays 1 and 2 can perform hardware scaling on the fly using 5-tap poly-phase filter, overlay0 can not. Displays 0 and 1 represent LCD and TV respectively. By default the 3 framebuffers (/dev/fbX) are redirected to 3 overlays, which all output to the LCD. This configuration is not meant to be changed by programs, only firmware should manage these.

===Basic usage===
====framebuffer interface====
Framebuffers can be accessed Linux fbdev interface:
<source lang="c">
fbdev = open("/dev/fb0", O_RDONLY);
buffer = mmap(0, 800*480*2, PROT_WRITE, MAP_SHARED, fbdev, 0);
</source>
(this is basic example, no error checks)

the returned pointer can be used to draw on the screen.

Be sure to #include <linux/fb.h> to get access to the FB device ioctl interface, and <sys/ioctl.h> for access to ioctl itself.

====double buffering====
This can be achieved using FBIOPAN_DISPLAY ioctl system call. For this you need to mmap framebuffer of double size
<source lang="c">
buffer1 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 0);
buffer2 = (char *)mem + 800*480*2;
</source>
or map 2 buffers
<source lang="c">
buffer1 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 0);
buffer2 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 800*480*2);
</source>
Then to display buffer2 you would call:
<source lang="c">
struct fb_var_screeninfo fbvar;
ioctl(fbdev, FBIOGET_VSCREENINFO, &fbvar);
fbvar.yoffset = 480;
ioctl(fbdev, FBIOPAN_DISPLAY, &fbvar);
</source>
going back to buffer1 would be repeating above with fbvar.yoffset = 0. Tripple or quad buffering can be implemented using the same technique.

====vertical sync====
Linux has standard FBIO_WAITFORVSYNC for this:
<source lang="c">
int arg = 0;
ioctl(fbdev, FBIO_WAITFORVSYNC, &arg);
</source>
be sure to pass argument value 0 or it will not work.

Currently FBIO_WAITFORVSYNC is not defined in <linux/fb.h>, although this is in the process of modification. For now, define in the following manner:

<source lang="c">
#ifndef FBIO_WAITFORVSYNC
#define FBIO_WAITFORVSYNC _IOW('F', 0x20, __u32)
#endif
</source>

====hardware scaling====
Overlay1 (/dev/fb1) can be used to achieve hardware scaling. Technically overlay2 (fb2) can be used for this too, but it is planned to be used by the system for TV-out functionality, so don't use it. The overlay is configured using series of standard and OMAP specific ioctl calls, but the system ships with some tools to achieve this from scripts too. This way the framebuffer can be set up for some arbitrary size (say 320x240) and can output to LCD as 800x480 with hardware scaling.
Here is an example script:
<source lang="bash">
ofbset -fb /dev/fb1 -pos 0 0 -size 800 480 -mem 307200 -en 1
fbset -fb /dev/fb1 -g 320 240 320 480 16

./your_app_here

ofbset -fb /dev/fb1 -pos 0 0 -size 0 0 -mem 0 -en 0
</source>

What it does:
* allocates OMAP DSS layer, asks video output to be 800x480 at position 0,0 (could set it to 640x480 at 80,0 instead to get centered 2x scaling of 320x240). 307200 bytes of video memory are allocated for 2 320x240 16bpp screens (for doublebuffering).
* sets video mode to 320x240@16bpp, virtual resolution 320x480 for doublebuffering.
* runs your app
* cleans the video layer on exit

Now the program can act as if works with 16bpp screen.

==LEDs and backlight==
The LEDs can be controlled via /sys/class/leds/, and then a file [http://www.gp32x.com/board/index.php?s=&showtopic=45309&view=findpost&p=673593]:
* pandora::sd1
* pandora::sd2
* pandora::charger
* pandora::power
* pandora::bluetooth
* pandora::wifi
* pandora::keypad_bl
Backlight can be controlled via /sys/class/backlight/.

==Misc==
Some things can be controlled through files in /proc/pandora/:
* /proc/pandora/cpu_mhz_max - if [http://www.kernel.org/pub/linux/utils/kernel/cpufreq/cpufreq.html cpufreq] is enabled, sets maximum allowed cpu clock, if not, just sets CPU clock to value supplied (echo 600 > /proc/pandora/cpu_mhz_max). Might also just use cpufreq parameters themselves.
more to come..
[[Category:Development]]

Kernel interface

2010-06-19T10:57:29Z

Exophase: /* vertical sync */

'''Warning''': if your goal is just to write a game/program use higher level libraries/interfaces like SDL, Qt, X or similar for your own good (portability). It may be impossible to retain this layout on some major hardware revision, let's say Pandora 3000, and your program will break. Also this requires some level of Linux programming knowledge.

In case you need to write low level code (you can't/don't want to use high level libs like SDL), you can use kernel interface. This is the recommended way to access hardware (as opposed to GP2X style of accessing chip registers by mmap'ing /dev/mem), because in case hardware changes are needed in future, they could be handled by kernel and all programs would still work. It also should allow several programs to work at the same time and should be more stable.

==Input==
Buttons, keypad, touchscreen and nubs are all exposed through Linux event interface (EVDEV). All devices are represented by /dev/input/eventX files, which can be opened, read and queried (using ioctl calls). The reads can be synchronous (the read will only return when user does something, like presses the button), or asynchronous (the system will report what changed since the last time you asked).

'''Warning''': don't hardcode device filenames in your program! For example, currently /dev/input/event2 represents game buttons, but in future it may become touchscreen. Scan input device names instead, example:
<source lang="c">
for (i = 0; 1; i++)
{
sprintf(name, "/dev/input/event%i", i);
fd = open(name, O_RDONLY);
if (fd < 0) break; /* no more devices */
ioctl(fd, EVIOCGNAME(sizeof(name)), name);
if (strcmp(name, "gpio-keys") == 0)
return fd; /* found the buttons! */
close(fd); /* we don't need this device */
}
</source>

List of device names and events they send:
{|border=1 cellpadding=2 cellspacing=0
|-
!name
!description
!event.type
!event.code
!event.value
|-
|keypad
|keypad
|EV_KEY
|KEY_0...KEY_Z, KEY_BACKSPACE, KEY_LEFTSHIFT, KEY_SPACE, KEY_ENTER, KEY_COMMA, KEY_DOT, KEY_FN
|0 - released, 1 - pressed, 2 - autorepeat event
|-
|gpio-keys
|game buttons
|EV_KEY
|KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_MENU (Pandora button), KEY_LEFTALT (Start), KEY_LEFTCTRL (Select), KEY_KP1 (Y/North), KEY_KP2 (A/East), KEY_KP3 (X/South), KEY_KP4 (B/West), KEY_KP5 (Shoulder L), KEY_KP6 (Shoulder R), KEY_KP7 (Shoulder L2), KEY_KP8 (Shoulder R2), KEY_COFFEE (Hold)
|0 - released, 1 - pressed
|-
|gpio-keys
|lid state
|EV_SW
|SW_LID
|0 - closing, 1 - opening
|-
|touchscreen
|touchscreen
|EV_ABS
|ABS_X, ABS_Y, ABS_PRESSURE
|varies, use calibration data
|-
|nub0
|left nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|-
|nub1
|right nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|}

Sample code: 
[http://beagleboard.googlecode.com/files/evtest.c evtest.c]
[http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-misc.git;a=blob;f=op_test_inputs.c;hb=HEAD op_test_inputs.c]

===Touchscreen===
Event interface returns uncalibrated values directly from driver, so you need to use tslib or manage calibration yourself (using data from /etc/pointercal).

==Sound==
Pandora uses ALSA, but it has OSS emulation enabled too, so GP2X code should work.

==Video==
===Architecture===
Framebuffer device (/dev/fbX) is supported. There are 3 framebuffers available (/dev/fb0, /dev/fb1 and /dev/fb2), which represent 3 graphics/video layers on OMAP3 by default (but can be reconfigured). Only /dev/fb0 is enabled by default.

OMAP3 display subsystem is controlled by a driver known as DSS2, which has various controls available on /sys/devices/platform/omapdss/ (but they are not meant to be changed by programs, so they are root writable only). The driver exposes 3 layers (called overlays) and 2 displays. Overlays 1 and 2 can perform hardware scaling on the fly using 5-tap poly-phase filter, overlay0 can not. Displays 0 and 1 represent LCD and TV respectively. By default the 3 framebuffers (/dev/fbX) are redirected to 3 overlays, which all output to the LCD. This configuration is not meant to be changed by programs, only firmware should manage these.

===Basic usage===
====framebuffer interface====
Framebuffers can be accessed Linux fbdev interface:
<source lang="c">
fbdev = open("/dev/fb0", O_RDONLY);
buffer = mmap(0, 800*480*2, PROT_WRITE, MAP_SHARED, fbdev, 0);
</source>
(this is basic example, no error checks)

the returned pointer can be used to draw on the screen.

Be sure to #include <linux/fb.h> to get access to the FB device ioctl interface, and <sys/ioctl.h> for access to ioctl itself.

====double buffering====
This can be achieved using FBIOPAN_DISPLAY ioctl system call. For this you need to mmap framebuffer of double size
<source lang="c">
buffer1 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 0);
buffer2 = (char *)mem + 800*480*2;
</source>
or map 2 buffers
<source lang="c">
buffer1 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 0);
buffer2 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 800*480*2);
</source>
Then to display buffer2 you would call:
<source lang="c">
struct fb_var_screeninfo fbvar;
ioctl(fbdev, FBIOGET_VSCREENINFO, &fbvar);
fbvar.yoffset = 480;
ioctl(fbdev, FBIOPAN_DISPLAY, &fbvar);
</source>
going back to buffer1 would be repeating above with fbvar.yoffset = 0. Tripple or quad buffering can be implemented using the same technique.

====vertical sync====
Linux has standard FBIO_WAITFORVSYNC for this:
<source lang="c">
int arg = 0;
ioctl(fbdev, FBIO_WAITFORVSYNC, &arg);
</source>
be sure to pass argument value 0 or it will not work.

Currently FBIO_WAITFORVSYNC is not defined in <linux/fb.h>, although this is in the process of modification. For now, define in the following manner:

#ifndef FBIO_WAITFORVSYNC
#define FBIO_WAITFORVSYNC _IOW('F', 0x20, __u32)
#endif

====hardware scaling====
Overlay1 (/dev/fb1) can be used to achieve hardware scaling. Technically overlay2 (fb2) can be used for this too, but it is planned to be used by the system for TV-out functionality, so don't use it. The overlay is configured using series of standard and OMAP specific ioctl calls, but the system ships with some tools to achieve this from scripts too. This way the framebuffer can be set up for some arbitrary size (say 320x240) and can output to LCD as 800x480 with hardware scaling.
Here is an example script:
<source lang="bash">
ofbset -fb /dev/fb1 -pos 0 0 -size 800 480 -mem 307200 -en 1
fbset -fb /dev/fb1 -g 320 240 320 480 16

./your_app_here

ofbset -fb /dev/fb1 -pos 0 0 -size 0 0 -mem 0 -en 0
</source>

What it does:
* allocates OMAP DSS layer, asks video output to be 800x480 at position 0,0 (could set it to 640x480 at 80,0 instead to get centered 2x scaling of 320x240). 307200 bytes of video memory are allocated for 2 320x240 16bpp screens (for doublebuffering).
* sets video mode to 320x240@16bpp, virtual resolution 320x480 for doublebuffering.
* runs your app
* cleans the video layer on exit

Now the program can act as if works with 16bpp screen.

==LEDs and backlight==
The LEDs can be controlled via /sys/class/leds/, and then a file [http://www.gp32x.com/board/index.php?s=&showtopic=45309&view=findpost&p=673593]:
* pandora::sd1
* pandora::sd2
* pandora::charger
* pandora::power
* pandora::bluetooth
* pandora::wifi
* pandora::keypad_bl
Backlight can be controlled via /sys/class/backlight/.

==Misc==
Some things can be controlled through files in /proc/pandora/:
* /proc/pandora/cpu_mhz_max - if [http://www.kernel.org/pub/linux/utils/kernel/cpufreq/cpufreq.html cpufreq] is enabled, sets maximum allowed cpu clock, if not, just sets CPU clock to value supplied (echo 600 > /proc/pandora/cpu_mhz_max). Might also just use cpufreq parameters themselves.
more to come..
[[Category:Development]]

Kernel interface

2010-06-19T10:56:07Z

Exophase: /* framebuffer interface */

'''Warning''': if your goal is just to write a game/program use higher level libraries/interfaces like SDL, Qt, X or similar for your own good (portability). It may be impossible to retain this layout on some major hardware revision, let's say Pandora 3000, and your program will break. Also this requires some level of Linux programming knowledge.

In case you need to write low level code (you can't/don't want to use high level libs like SDL), you can use kernel interface. This is the recommended way to access hardware (as opposed to GP2X style of accessing chip registers by mmap'ing /dev/mem), because in case hardware changes are needed in future, they could be handled by kernel and all programs would still work. It also should allow several programs to work at the same time and should be more stable.

==Input==
Buttons, keypad, touchscreen and nubs are all exposed through Linux event interface (EVDEV). All devices are represented by /dev/input/eventX files, which can be opened, read and queried (using ioctl calls). The reads can be synchronous (the read will only return when user does something, like presses the button), or asynchronous (the system will report what changed since the last time you asked).

'''Warning''': don't hardcode device filenames in your program! For example, currently /dev/input/event2 represents game buttons, but in future it may become touchscreen. Scan input device names instead, example:
<source lang="c">
for (i = 0; 1; i++)
{
sprintf(name, "/dev/input/event%i", i);
fd = open(name, O_RDONLY);
if (fd < 0) break; /* no more devices */
ioctl(fd, EVIOCGNAME(sizeof(name)), name);
if (strcmp(name, "gpio-keys") == 0)
return fd; /* found the buttons! */
close(fd); /* we don't need this device */
}
</source>

List of device names and events they send:
{|border=1 cellpadding=2 cellspacing=0
|-
!name
!description
!event.type
!event.code
!event.value
|-
|keypad
|keypad
|EV_KEY
|KEY_0...KEY_Z, KEY_BACKSPACE, KEY_LEFTSHIFT, KEY_SPACE, KEY_ENTER, KEY_COMMA, KEY_DOT, KEY_FN
|0 - released, 1 - pressed, 2 - autorepeat event
|-
|gpio-keys
|game buttons
|EV_KEY
|KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_MENU (Pandora button), KEY_LEFTALT (Start), KEY_LEFTCTRL (Select), KEY_KP1 (Y/North), KEY_KP2 (A/East), KEY_KP3 (X/South), KEY_KP4 (B/West), KEY_KP5 (Shoulder L), KEY_KP6 (Shoulder R), KEY_KP7 (Shoulder L2), KEY_KP8 (Shoulder R2), KEY_COFFEE (Hold)
|0 - released, 1 - pressed
|-
|gpio-keys
|lid state
|EV_SW
|SW_LID
|0 - closing, 1 - opening
|-
|touchscreen
|touchscreen
|EV_ABS
|ABS_X, ABS_Y, ABS_PRESSURE
|varies, use calibration data
|-
|nub0
|left nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|-
|nub1
|right nub
|EV_ABS
|ABS_X, ABS_Y
| -256 (Left/Up) ...0... +256 (Right/Down)
|}

Sample code: 
[http://beagleboard.googlecode.com/files/evtest.c evtest.c]
[http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-misc.git;a=blob;f=op_test_inputs.c;hb=HEAD op_test_inputs.c]

===Touchscreen===
Event interface returns uncalibrated values directly from driver, so you need to use tslib or manage calibration yourself (using data from /etc/pointercal).

==Sound==
Pandora uses ALSA, but it has OSS emulation enabled too, so GP2X code should work.

==Video==
===Architecture===
Framebuffer device (/dev/fbX) is supported. There are 3 framebuffers available (/dev/fb0, /dev/fb1 and /dev/fb2), which represent 3 graphics/video layers on OMAP3 by default (but can be reconfigured). Only /dev/fb0 is enabled by default.

OMAP3 display subsystem is controlled by a driver known as DSS2, which has various controls available on /sys/devices/platform/omapdss/ (but they are not meant to be changed by programs, so they are root writable only). The driver exposes 3 layers (called overlays) and 2 displays. Overlays 1 and 2 can perform hardware scaling on the fly using 5-tap poly-phase filter, overlay0 can not. Displays 0 and 1 represent LCD and TV respectively. By default the 3 framebuffers (/dev/fbX) are redirected to 3 overlays, which all output to the LCD. This configuration is not meant to be changed by programs, only firmware should manage these.

===Basic usage===
====framebuffer interface====
Framebuffers can be accessed Linux fbdev interface:
<source lang="c">
fbdev = open("/dev/fb0", O_RDONLY);
buffer = mmap(0, 800*480*2, PROT_WRITE, MAP_SHARED, fbdev, 0);
</source>
(this is basic example, no error checks)

the returned pointer can be used to draw on the screen.

Be sure to #include <linux/fb.h> to get access to the FB device ioctl interface, and <sys/ioctl.h> for access to ioctl itself.

====double buffering====
This can be achieved using FBIOPAN_DISPLAY ioctl system call. For this you need to mmap framebuffer of double size
<source lang="c">
buffer1 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 0);
buffer2 = (char *)mem + 800*480*2;
</source>
or map 2 buffers
<source lang="c">
buffer1 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 0);
buffer2 = mmap(0, 800*480*2 * 2, PROT_WRITE, MAP_SHARED, fbdev, 800*480*2);
</source>
Then to display buffer2 you would call:
<source lang="c">
struct fb_var_screeninfo fbvar;
ioctl(fbdev, FBIOGET_VSCREENINFO, &fbvar);
fbvar.yoffset = 480;
ioctl(fbdev, FBIOPAN_DISPLAY, &fbvar);
</source>
going back to buffer1 would be repeating above with fbvar.yoffset = 0. Tripple or quad buffering can be implemented using the same technique.

====vertical sync====
Linux has standard FBIO_WAITFORVSYNC for this:
<source lang="c">
int arg = 0;
ioctl(fbdev, FBIO_WAITFORVSYNC, &arg);
</source>
be sure to pass argument value 0 or it will not work.

====hardware scaling====
Overlay1 (/dev/fb1) can be used to achieve hardware scaling. Technically overlay2 (fb2) can be used for this too, but it is planned to be used by the system for TV-out functionality, so don't use it. The overlay is configured using series of standard and OMAP specific ioctl calls, but the system ships with some tools to achieve this from scripts too. This way the framebuffer can be set up for some arbitrary size (say 320x240) and can output to LCD as 800x480 with hardware scaling.
Here is an example script:
<source lang="bash">
ofbset -fb /dev/fb1 -pos 0 0 -size 800 480 -mem 307200 -en 1
fbset -fb /dev/fb1 -g 320 240 320 480 16

./your_app_here

ofbset -fb /dev/fb1 -pos 0 0 -size 0 0 -mem 0 -en 0
</source>

What it does:
* allocates OMAP DSS layer, asks video output to be 800x480 at position 0,0 (could set it to 640x480 at 80,0 instead to get centered 2x scaling of 320x240). 307200 bytes of video memory are allocated for 2 320x240 16bpp screens (for doublebuffering).
* sets video mode to 320x240@16bpp, virtual resolution 320x480 for doublebuffering.
* runs your app
* cleans the video layer on exit

Now the program can act as if works with 16bpp screen.

==LEDs and backlight==
The LEDs can be controlled via /sys/class/leds/, and then a file [http://www.gp32x.com/board/index.php?s=&showtopic=45309&view=findpost&p=673593]:
* pandora::sd1
* pandora::sd2
* pandora::charger
* pandora::power
* pandora::bluetooth
* pandora::wifi
* pandora::keypad_bl
Backlight can be controlled via /sys/class/backlight/.

==Misc==
Some things can be controlled through files in /proc/pandora/:
* /proc/pandora/cpu_mhz_max - if [http://www.kernel.org/pub/linux/utils/kernel/cpufreq/cpufreq.html cpufreq] is enabled, sets maximum allowed cpu clock, if not, just sets CPU clock to value supplied (echo 600 > /proc/pandora/cpu_mhz_max). Might also just use cpufreq parameters themselves.
more to come..
[[Category:Development]]