8bitworkshop/doc/notes.txt

TODO:

- NaN in cycle count for macros
- debugging of scan line overflow
- confuse code/data in listing
- show memory locations hovering over lines
- don't check against ROM signatures
- DASM
  - macro forward refs
  - labels start with . omit timing info (isCode)
  - spaces in filename don't parse code listing (DASM, maybe more)
- asm: support macro expansion
- multiple breakpoints, expression breakpoints
- watchpoints
- step over (line, instruction)
- slowdown beam for all platforms?
- intro/help text for each platform
- show self-modifying code insns left of editor
- update Javatari version? (and others?)
- sound mute?
- $error updates source editor
- online tools for music etc
- text log debugging script
- vscode/atom extension?
- click to break on raster position
- debug bankswitching for funky formats
- 'undefined' for bitmap replacer
- requestInterrupt needs to be disabled after breakpoint?
- C/asm source formatter
- allow download of JSASM output
- update bootstrap to 4.0
- batariBasic: proper line numbers, debugging
- builds:
  - compiler flags for final ROM build
  - workermain: split build functions, better msg types
  - what if >1 file with same name? (local/nonlocal/directory)
  - what if .c and .s names collide?
  - maybe put stuff in examples/ dir?
  - error msg when #link doesn't work
  - warning when ROM too big
  - detect "libcv.h" and include library automagically?
- sdcc:
  - can't link asm files before c files (e.g. acheader.s must be last)
  - figure out area names ordering
  - debug inline asm
- live coding URL
- resize memory browser, other windows when vertical div resize
- markdown, verilog: can't share
- https://www.crowdsupply.com/tinyfpga/tinyfpga-bx
- stego shareable images (http://pico-8.wikia.com/wiki/P8PNGFileFormat)
- https://makecode.com/language?
- open ROM from URL?
- game starts even if switched away before first load
- put globals into view/controller objects
- autostart audio
  - chrome: https://github.com/processing/p5.js-sound/issues/249
  - firefox: https://support.mozilla.org/en-US/kb/block-autoplay
- touch support
- better undo/diff for mistakes?
- ide bug/feature visualizer for sponsors
- global undo/redo at checkpoints (when rom changes)
- landscape mode for arcade ports
- symmetric load/save state types (like in Machine)
- pixel editor
  - persist palette/tilemap selections
  - more tools for editing
  - map editor
  - arbitrary nametable editing
  - metasprites
  - throw errors when bad/no refs
  - per-View keyboard shortcuts
  - parse labels
  - parse .incbin directives?
  - can't replace in hex directives
  - should maybe use same single-canvas editor for map + char editor
  - undo doesn't refresh editor
  - editing sometimes messes up cursor movement (CURBS)
- crt0.s compiled each time?
- debug highlight doesn't go away when debugging -> running
  - show breakpoint of PC or highest address on stack
  - can we highlight line instead of select?
- profiler
  - profiler restarts emulator when paused
  - running profiler while replaying? grand unified replay?
  - click on profiler to step to position
    - breakpoints stop profiler from running
  - single-screen profiler
  - hide labels that aren't available, like BIOS addrs
  - show interrupts, other events
  - sometimes interleaves two different PCs? like two profilers running simultaneously?
    - ah, symbols persist across builds
- Verilog
  - larger scope range, better scrolling
  - make scope data wrap around range
  - remove FPS and play controls when Verilog scope paused
  - when paused scope doesn't work
  - Safari: scope doesn't show while CRT in use (sometimes Firefox too)
  - verilog debugging/reloading makes it slow
  - why loadState() on verilog kill perf?
  - quantify verilog "graph iterations"
  - CPU debugging
  - use $readmem for inline asm programs?
  - can't add control instructions b/c of split
  - bad error msg if >2 moduels and top module doesn't match filename
  - separate Scope View
  - Audio doesn't work if clock != default
- Verilog WASM not yet supported:
  - wide numbers > 64 bits (and in scope view)
  - multiple modules instances 
  - structs
  - other $funcs
  - multidim arrays
  - optimize trace log w/ wasm buffer
  - yosys compatibility 
  - randomize on reset? (https://www.xilinx.com/support/documentation/white_papers/wp272.pdf)
    - XML should tell us which values are supposed to reset
- single-stepping vector games makes screen fade
- break on stack overflow, illegal op, bad access, BRK, etc
  - show in scope instead?
- nes
  - replay doesn't work for nes (force background tile redraw, sprites
    messed up)
  - nes debug view toolbar
  - support NES_HEADER_16K?
  - NES crt should mark raster pos when debugging
  - OAMDMA in profiler? (haltCycles)
  - typed arrays don't serialize?
- JSNES
  - doesn't support hiding >8 sprites
  - doesn't do sprite zero test right
  - doesn't do clip right
  - doesn't do b/w tint
- vcs
  - sometimes still plays when paused on FF
  - vcs: INPTx needs to be added to control state
  - vcs: break on # of lines changed (maybe using getRasterPosition?)
  - chrome looks blurry on vcs
  - VCS asm game library
  - VCS skips step on lsr/lsr after run to line
  - better VCS single stepping, maybe also listings
  - upgrade to 4.1 for Supercharger format
- upload multiple files/zip file to subdirectory
  - allow "include graphics.asm" instead of "include project/graphics.asm"
- convert more stuff to Promises
- don't have to include firebase always?
  - squelch error msgs? 
  - test offline? (if window.firebase)
- Github
  - platform_id/repo.platform mismatch (can't leave repository)
  - handle overwrite logic
  - what to do about included files?
  - can published files retain path?
  - what if import interrupted and partial files?
  - CORS for some blobs?
  - don't import useless files
  - support projects with subdirectories, file list?
  - switching platform of a repo?
  - make sure to flatten subdirs
  - re-publish repo (bug: doesn't put all files in local repo after publishing)
  - allow text/binary change
  - importing from subtree commits to root anyway
  - publishing Markdown file loads default file? 
  - better text/binary detection (e.g. 0xa9 copyright)
  - going into repo chooses wrong file if republished with different main
  - renaming main file doesn't change repo def.
  - can't edit or push files until successful compile
  - changing platform of repo makes one platform redirect to another platform
- keyboard shortcuts
  - ctrl+alt+l on ubuntu locks screen
  - alt-D doesn't work anymore
  - facade/kbd shortcuts for emulators, focus
  - maybe eat key events? ("'" messes things up)
- cookie
  - list of stuff for policy
  - popup
- convert binary to hex stmts
- "suggestions" (vblank overrun, variable # scanlines, etc)
- SMS
  - can't step back twice?
  - compiler bug in chase
- "shared" in URL doesn't work, leave in URL? (also importURL)
- 6502
  - KIL stops debugger
- TypeError: null is not an object (evaluating 'n.destination')
  https://8bitworkshop.com/v3.4.1/javatari.js/release/javatari/javatari.js
  (32:443651)	Safari	12.1.2
- Safari: doesn't send good exception reasons ("undefined")
  - probably XMLHttpRequest.timeout (https://github.com/getsentry/sentry-javascript/issues/2210)
- C64
  - disk image support
  - https://github.com/cc65/cc65/issues/946
  - player 2 joystick and keyboard conflict
  - problems with cgetc()

- upgrade to ES2020?
  - https://github.com/microsoft/TypeScript/issues/16577
  - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
  - need Edge 79+
  - no import in workers
  - copy to gen/ directory (allowJs is weird)
- ca65 line numbers are not aligned with source code
  - neither are DASM when you change comments
  - segments not read properly
- Debug Browser
  - more stuff like 7800 display lists
  - don't include start/end line on platforms w/o raster timing
- BIOS symbols
- show current tool for file
- download non-text incbin source file
- show hidden header files that only exist in Emscripten FS
- WASI modules: https://docs.wasmer.io/integrations/js/wasi/browser
- FS Access: https://web.dev/file-system-access/
  - https://wicg.github.io/file-system-access/#api-showdirectorypicker

Probing
- probe log doesn't start @ reset
- scroll to current probe log location
Debug, play then halt cpu doesn't highlight final line
- illegal instruction should show debug info + jump to line
- halt cpu should show video too
vcs: input not preserved when replaying frames?

compile errors disappear when focus returns


WEB WORKER FORMAT

{code,platform,tool,dependencies}
{preload}

new:

{updates,buildsteps}
[{filepath,platform,tool}]

implicit rules
- push/shift build steps
- preprocessor, compile, assemble, link
- access to intermediate files

only build files that have changed

build options


BUILD PROJECT

local/foo.project/*.*
build all files in project
send update for dependencies at startup (single file version)
should be able to change file w/o reloading (Not platform tho)

pulldown selects file in project, or goes back to parent
gotta preserve editor windows for each one - window list
make source/disasm window visible when debugging
gutter info/errors in all files



UI REFACTOR

editor
debugger
disasm view
memory
profile
errors

separate into files

window methods:
- set
- mode
- get
- changes
- cursorActivity (inspect)
- gutters (setCompileOutput)
- current line / gutter marker (setCurrentLine / clearCurrentLine)
- source map
- global symbols
- pixel editor / find comment (openBitmapEditorAtCursor)
- update debug window (200 ms)
- inspect variable

file store mirrors that on worker

worker result:
{
	output:<rom>
	sources:{
		<path>:{lines, asmlines, listing}
	}
}

add file to errors

http://www.playvectrex.com/designit/chrissalo/vectordisplay.htm
http://oldies.malban.de/secondvectrex/index.htm


PIXEL EDITOR

everything is an editor
back/forward propogation
encoded <-> raw + spec + palette(s) <-> full tilemap <-> selected tile/sprite/metasprite
need references
panes: source code, metadata tree, graphics panes
decoded info:
- CHR tiles
- palettes
- maps/rooms
- metasprites
- metatiles
- sprite data (williams etc)
store in intermediate single file or embed in C/ASM?
we'd then have to generate C/ASM probably automatically
intermediate file could still be edited
switch between hex/graphic editor? (palettes should edit via hex)
final display types: number, color, sprite, etc
CHR editor has palette selector, obj selector
individual objects in single file or multiple files?
RLE compression

Types
- byte
- RGBA color
- structured object
  - metasprite
  - metatile
  - level actor
- bitmap
- array of stuff, array can have a shape (width,height) like numpy
Mappers can refer to multiple objs
Slice (window) of array for selections

AssetEditorView
- scan files for assets
- build hierarchical view of assets
- expand/collapse
- create editor upon expansion
- double-click to source file

Assets come from:
- chr files
- bitmap data in files
- structured data (palette, sprites, metasprites, levels, etc)
- think about new comment format, platform-specific types

Programmatic Asset Language
- load PNG, draw image, or generate bitmap font
- split into images
- paletteize
- fit into tileset/spriteset
  - NES: 8x8 or 8x16 tiles
  - 7800: 256xN slice
  - VCS: 24xN playfield, 8xN sprite, 32xN big sprite
- generate data file (asm/c/bin)
- generate char mapping
- tile generator (makechr-like)
- metasprites too
- RLE compression
- check constraints


---

Github Support

Import
Export
Login
Pull
Push

Git metadata kept in local storage

Converting from NESASM to DASM
- asl a -> asl
- subroutine keyword on labels
- [zp],y to (zp),y
- LOW(x) and HIGH(x) to <() and >()
- .db to .byte, .dw to .word
- use NES_HEADER macros
- no .bank

Cross platform NES/SMS/GG library
- use CHR RAM
  - create flipped tiles/sprites
  - create alternate palette tiles
- metatiles
- cross platform music/sound
- scrolling
  - row/column mask
  - no nametable mirroring in SMS
  - 256x240 vs 256x192

Emulator Lib
- move getPresets() (into presets/ dir?)
- CPU interface
  - execCycle(), execInsn()
  - fix/unfix PC
  - interrupt
- generic raster scanline platform
- PlatformRunner
  - handles rewind, intra-frame breakpoint, debugging
  - profiling log, exec/read/write/intr (for each bus?)
- expose video, audio, controller interfaces
- new debugging info
- memory map interface
- "About" metadata
- auto load/save state?
- handle legacy
  - VCS
  - NES
  - MAME
- MAME
  - debugging?
  - kbd instructions don't work
  - https://emscripten.org/docs/porting/asyncify.html

Markdown (showdown) interface
- add code patches to files
- cursor shows current state/errors (must map markdown->src lines)
- show preview emulator at each step (play button? run when viewed?)


DOCUMENTATION

memory map
BIOS routines
cc65 standard libs
cc65 headers
example headers (presets/*/*.h)
libcv headers (src/worker/lib)
ASM includes


NETPLAY

runs alongside of emulator, doesn't modify controls (just state)
when controls change: player sends control inputs + frame#
add latency so clients more often are in sync
if miss latency window, client syncs state (moves forward a few frames?)
state checksum?
socket.io


X86

https://github.com/freebasic/fbc
GW-BASIC
http://www.grifo.com/SOFT/Pacific/uk_pacific.html
http://www.cpm.z80.de/small_c.html
https://github.com/open-watcom
Free Pascal
https://bellard.org/tcc/
https://wiki.osdev.org/Smaller_C
https://yasm.tortall.net/
https://wiki.osdev.org/Tool_Comparison


COMPONENT EMULATION

Emulate discrete chips
- verilog
- js
- wasm? (overhead?)
Block diagram level
Buses
Insn/cycle timing
Pos/neg clock edge
Timers
Polling vs. callbacks (https://github.com/floooh/chips)
- callbacks might only affect devices internally, until next cycle
CRT simulator
Move leaf nodes to workers (sound chips)
CPU opcode-step switch: https://floooh.github.io/2019/12/13/cycle-stepped-6502.html
- macros are cool!
Inspect bus edges and internal state

type Bits<N> = number;
interface Clocked { }
interface BusListener<N> {
    recv(value : Bits<N>) : void;
}
class Bus<N> {
    listeners : BusListener<N>;
    send(value : Bits<N>) : void {
    }
}
function bus(bits : number) {
    return function(
      target: any,
      propertyKey: string,
      descriptor: PropertyDescriptor
    ) {
      //descriptor.configurable = value;
    };
}
class M6502_T {
    IR : Bits<16>;        /* internal instruction register */
    addr : Bus<16>;
    data : Bus<8>;

    @bus(16) address : Bus<16>;
}

Optimizations
- ordered/delayed assignments
- skip unused exprs
- opcode -> fn table
- bus protocols -> functions
- state -> lookup tables or switch statements
- vec[] -> bitmask
- multiclock execution?



STATE REWIND

in Platform:

  advance?(novideo? : boolean) : number;
  advanceFrameClock?(trap:DebugCondition, step:number) : number;

in devices:

    advanceFrame(trap:TrapCondition) : number;
    advanceClock() : void;
    advanceInsn() : number;

Should call trap() every cycle or insn of frame, or exit when returns true?


BETTER DEBUGGING

Need to mark start/end columns, not just line number
Know if we are actively debugging or trap occurred
isRunning() = stopped, running, waiting, debugging...
Showing running PC may be distracting, maybe lines visited?
Don't grab cursor focus when trap occurs (how do we know?)
Use tick() and refresh(), not callbacks
Show current datum when using READ
Use https://codemirror.net/doc/manual.html#markText
Reset doesn't break @ start unless debugging tools expanded


PORTING CC65 TO IDE

flat directory for .c files
#include "file.h" vs <file.h>
//#link "foo.c" for each C file
preprocessor differences (#define FOO 1 so #if works)
extern void do_func(void)
#pragma warnings
CFG files