How about a community-sourced "Technical Supplement" to the P8X32A?
Wossname
Posts: 174
1. Suppose a group of knowledgeable and devoted Propeller community volunteers were to collaborate on a new document, let's call it "Technical Supplement to the Parallax P8X32A".
2. Suppose the document's minimum scope was to fully and unambiguously* document every excruciating detail of the P8X32A not already covered by the "Manual" or the "Datasheet". There is a fair amount of information that falls into this category (scrambled ROM blocks, a comprehensive list of all Spin opcodes and all bit fields, why is the "runner" not written in normal Spin language?... the list goes on). Items covered by the Manual or Datasheet need not be repeated.
3. Suppose the document's maximum scope stretched no further than governed by the physically embodied silicon of the P8X32A. If the P8X32A silicon doesn't know about it, it doesn't go in the document. Information regarding the various FPGA/verilog implementations is NOT to be included, because it is highly experimental and very subject to change over short time periods. The Document should be representative of the behaviour of the real, actual hardware P8X32A.
4. Suppose the target audience was the same as for the Datasheet, plus also the person wanting to create an emulator or a simulator (guess what I've been doing lately!). The questions that are incredibly obscure and frankly *tiresome* to the Propeller forum community can be thoroughly laid out in this document. This is feasilble, there is only a finite amount of activity between power-on and the user's code commencing. Much is lacking in official canonical documentation.
5. Suppose that the document was compiled and reviewed iteratively by said members and was published in conjunction with Parallax after further reviews and was regarded as "canonical".
Epilogue:
It sounds like a lot of work but I don't think it is really. We have a vast amount of esoteric and arcane knowledge only fleetingly stored in the squishy, warm, grey matter of our members' heads. The hard copies are going moldy on shelves or going 404 on abandoned wikia sites.
* Unambiguously. I'm not kidding here. We would explain every possible detail with utter clarity. The Manual and Datasheet have many ambiguities. Why not fill them in? I do not think it would be a long document, actually. Certainly only a fraction the size of the Manual. A few dozen pages at most. With a good index and cross linking of content it could be a breeze to use.
**I apologise that people are getting annoyed with me harping on about this documentation problem we've got. I do want to solve it but I need the community's help. If this thread leads nowhere then I'll stop, promise.
2. Suppose the document's minimum scope was to fully and unambiguously* document every excruciating detail of the P8X32A not already covered by the "Manual" or the "Datasheet". There is a fair amount of information that falls into this category (scrambled ROM blocks, a comprehensive list of all Spin opcodes and all bit fields, why is the "runner" not written in normal Spin language?... the list goes on). Items covered by the Manual or Datasheet need not be repeated.
3. Suppose the document's maximum scope stretched no further than governed by the physically embodied silicon of the P8X32A. If the P8X32A silicon doesn't know about it, it doesn't go in the document. Information regarding the various FPGA/verilog implementations is NOT to be included, because it is highly experimental and very subject to change over short time periods. The Document should be representative of the behaviour of the real, actual hardware P8X32A.
4. Suppose the target audience was the same as for the Datasheet, plus also the person wanting to create an emulator or a simulator (guess what I've been doing lately!). The questions that are incredibly obscure and frankly *tiresome* to the Propeller forum community can be thoroughly laid out in this document. This is feasilble, there is only a finite amount of activity between power-on and the user's code commencing. Much is lacking in official canonical documentation.
5. Suppose that the document was compiled and reviewed iteratively by said members and was published in conjunction with Parallax after further reviews and was regarded as "canonical".
Epilogue:
It sounds like a lot of work but I don't think it is really. We have a vast amount of esoteric and arcane knowledge only fleetingly stored in the squishy, warm, grey matter of our members' heads. The hard copies are going moldy on shelves or going 404 on abandoned wikia sites.
* Unambiguously. I'm not kidding here. We would explain every possible detail with utter clarity. The Manual and Datasheet have many ambiguities. Why not fill them in? I do not think it would be a long document, actually. Certainly only a fraction the size of the Manual. A few dozen pages at most. With a good index and cross linking of content it could be a breeze to use.
**I apologise that people are getting annoyed with me harping on about this documentation problem we've got. I do want to solve it but I need the community's help. If this thread leads nowhere then I'll stop, promise.
Comments
The first problem is : one reader's clarity, is another reader's confusion.
So, there is no such thing as 'fully and unambiguously' for every reader.
Secondly, there is also a fragmentation in 'a new document, let's call it "Technical Supplement to the Parallax P8X32A"., generally you are better to improve the DOCs that already exist, by identifying specific areas and fixing them.
The Prop docs are already quite good, & rather than a new DOC, some additions to existing ones would be better. (and faster to do)
So, let's take the specific start up area you have asked about already...
Introducing the Propeller Chip : Boot Up Procedure
Yes, that can be improved. It is superficial, and does not detail all the timed decisions.
Users could reasonably want to also know :
* How long after reset release, does the UART window first open, then close ?
* What Baud rate range is supported for download ? (modern USB bridge devices can output almost any baud value VirtualBaudClock/N)
* What download times does that map to ?
* How long from reset release to i2c load and first-line-of-user code. (ideally in SysCLKS + SysCLK value range)
* If someone wants fastest possible RST-RUN, what are their options ?
Looking at the present docs, there is (+100ms) that seems a red-herring power-stable type value, or is there a BOD-release timer, from Vdd rise ?
The 50ms does not say if that is Min/typ/max ?? from the ~20kHz slow Osc, and it is mentioned as just the time to switch gears, not time to earliest start-bit edge, which is more useful.
If someone wanted to push down from a MAX time to a typ time, is there a ping-like scheme possible to detect UART is alive ?
The P8X32A is a fully defined system. Everything about it's function is known, at least somewhere. That "somewhere" is problematical and thus is the subject of the topic at hand.
The DOCs that already exist have resisted improvements by everyone for several years.
Are we to be happy with "quite good" documentation and call it a day? What am I doing if not "identifying specific areas and fixing them"?
To create a pseudo "Wiki" within the forums, start a thread with a title beginning with the text "Parallax Wiki:" and then an appropriate title. So, in the example of the related thread about the Propeller Boot Sequence, it would be "Parallax Wiki: Propeller - Boot Sequence".
The top post would include the most current data for the topic and all added posts would be the discussion as to the content of the first post.
Once these Wiki style threads begin accumulating, an index thread could be started, similar to how Duane Degn set up his personal index.
It also sounds like having to repeat all the useful conversations of the last 15 years or so. Which ain't goint to happen.