Add sketches folder

sketches/raster-generator.md

@@ -0,0 +1,74 @@
+=== Generator ===
+
+The raster generator should be able to display a 500x400 frame onscreen.
+However, most frames will be sparse, and it should finish as fast as possible.
+It should also emulate dual-port access into the video RAM for the MPU to write
+more graphics out. A candidate design is:
+
+50 MHz main clock
+2 MHz pixel clock
+2 bit monochrome in an 8 bit vram
+Video RAM writes go into a FIFO (should only need to be 2 (addr+data) long
+  given 20 MHz max SPI clock)
+Cyclic machine with 25 steps, following:
+
+STEP 0
+	fifo.pop = 0
+	if rising_edge(should_be_displaying) video_pointer <= (0, 0)
+	else
+		video_pointer <= video_pointer + 1
+		if video_pointer (after assignment) == 0
+			clear should_be_displaying
+
+	if rising_edge(should_be_displaying)
+		video <= Z      /* we weren't ready yet, don't show anything */
+	else if (!should_be_displaying)
+		video <= Z
+	else
+		video <= vram[video_pointer]
+
+STEPS 1...24
+	if fifo.ready
+		vram[fifo.data[addr]] <= vram[fifo.data[data]]
+		fifo.pop = 1
+	else
+		fifo.pop = 0
+		get the 4 pixels around video_pointer
+		if the next N pixels are black,
+			video_pointer <= video_pointer + N
+
+
+It may be necessary, to improve video quality, to blank the intensity during
+beam transit by inserting "0" data for the cycle just before and after a change
+in video output. This should not be done if 1) the beam is staying the same
+intensity AND 2) the next video pointer locaation is the pixel immediately to
+the right.
+
+=== Data interface ===
+
+The SPI data interface is designed to allow efficient writing of arbitrary
+rectangular regions. Messages are formatted as follows:
+
+1wwwwwww aaaaaaaa aaaaaaaa data...
+
+The first 1 bit selects the vram mailbox (a 0 selects the display sequencer,
+cohabitant on this FPGA). w... sets the width of the rectangular region in fours
+of pixels (this can cover the entire 500 pixel width of the display, if needed)
+minus 1 (so w=0 means a column 4(0 + 1) = 4 pixels wide), and a... sets the
+starting value of the video write pointer. This is set up as follows:
+
+At beginning of message:
+	left_pointer <= msg.start_address
+	write_pointer <= msg.start_address
+	width_max <= msg.width_max
+	width_counter <= 0
+
+On each data byte:
+	fifo.in = (write_pointer, data)
+	fifo.push = 1
+	if width_counter == width_max:
+		width_counter <= 0
+		write_pointer <= left_pointer + length_of_a_line
+		left_pointer <= left_pointer + length_of_a_line
+	else:
+		width_counter <= width_counter + 1