On Tuesday 09 January 2007 04:52, Timothy Miller wrote: > Please have a look at the documentation I just wrote for the video > controller. I think Patrick especially could help, but others are > familiar with it, and anyone can check for inconsistenties and > general nonsense.
First, I would like to say that it's well-written and that the style is excellent. Good work! I'd like some more explanation of the concept behind FETCH and SEND; from the instruction definitions it's not immediately clear what they do and how they work. Something along the lines of "The VC fetches pixels from video memory and sends them to the display. The programme should first use the FETCH instruction to load image data into an internal buffer, which takes some time, and then it can SEND it to the output. It can FETCH and SEND at the same time (I think?) ... ". And a question: all instructions take 1 cycle to execute? I don't think that that's made explicit anywhere. Also, IIRC from the mailing list discussions, the clock of the VC is locked to the pixel clock. That should probably be in an introductory section, together with the overview of fetching and sending. The learning curve is just a little too steep as is I think. Third, the x field is currently undefined, perhaps it should always be set to 0 to ease future extensions? I think that setting unused bits to 0 is common. About the licence, I've never heard of the Free Art licence, but perhaps it could be published under the GNU FDL or a Creative Commons licence instead? Those are more widely spread, which would help compatibility. Unless of course there's something in the Free Art licence but not in the others that you really want to have. Language remarks: 3.1: - Typo: "COUNT indicates" rather than "COUNT indicated" 3.2: - "top level" suggests that there is a hierarchy, which there really isn't since there is no recursion. Perhaps "outer level" would be better - "a return [from the called subroutine] ..." given the contrast with the previous sentence this would clarify things a bit 3.3: - COUNT refers to the bit field in 3.1, but now you're switching it to mean its value, and CountField to be the field itself. I can't help but think that there must be a better solution. Perhaps name the field COUNT, and then have a RepeatCount and a FetchCount for the values? 3.4: - You've defined two instruction formats earlier, but they're not being referred to here. Each instruction should have [A] or [B] to signify its format. 3.4.5: - "predeeding" should probably be "preceding" 4: - In the description for VID_RESET, it says "to cause reset". I don't think it'll fool anyone into believing TT is a big Taiwanese manufacturer :-). 5: - "Preample" -> "Preamble" Lourens
pgp4ZeUO8kMXL.pgp
Description: PGP signature
_______________________________________________ Open-graphics mailing list [email protected] http://lists.duskglow.com/mailman/listinfo/open-graphics List service provided by Duskglow Consulting, LLC (www.duskglow.com)
