On 1/9/07, Lourens Veen <[EMAIL PROTECTED]> wrote:
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!
Thank you for the feedback! I've made a number of changes. Tell me
what you think.
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?) ... ".
I've added a section on this. See what you think. I've also
reordered those subjections, so see if you think things flow well
enough.
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.
I'd had a statement to that effect, but I have attempted to make that
even clearer.
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.
Done.
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.
When reading about document licenses on Wikipedia, it stated that the
FSF's recommended document license is the Free Art license. I guess
wikipedia is out of date on that.
However, reading about the FDL, it doens't sound so good. Apparently,
the FDL isn't GPL compatible or vice versa.
Language remarks:
3.1:
- Typo: "COUNT indicates" rather than "COUNT indicated"
Done.
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
Done.
- "a return [from the called subroutine] ..." given the contrast with
the previous sentence this would clarify things a bit
I couldn't figure out what you were referring to here. Perhaps I'd
already changed it beyond recognition. Could you look to see if I
still have the same problem?
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?
Good catch on that one. Pretty bad. I've retooled all references to
count 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.
Done.
3.4.5:
- "predeeding" should probably be "preceding"
I think I've edited this out completely.
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 :-).
Fixed.
5:
- "Preample" -> "Preamble"
Done.
Thank you again!
--
Timothy Miller
http://www.cse.ohio-state.edu/~millerti
_______________________________________________
Open-graphics mailing list
[email protected]
http://lists.duskglow.com/mailman/listinfo/open-graphics
List service provided by Duskglow Consulting, LLC (www.duskglow.com)
