P2 Datasheet Progress
sjgallagher2
Posts: 22
Hey all, I'm new to the forum but I've been learning to use the P2 for a bit after a friend of mine turned me onto it. Like a lot of beginners, the documentation problems were a stumbling block (and continue to be) so I thought creating better documentation would be a good approach to learning. In that vain, I've spent a few hours reformatting the P2 reference google doc into a properly formatted datasheet. But as I go through it, I realize that the google doc combines a few different aspects of technical documentation, sort of like it "doesn't know what to be" (but not in a bad way! I use it as a reference constantly!). So instead I'd like to just share my thoughts on what's needed and I'd love to get input on how information should be organized from Chip et al.
Normally the starting point for something like this would be previous documentation, like the P1 datasheet, but I think there's room for improvement. So with that in mind, we should document the device like a DSP, as it has its own ISA and architecture (rather than e.g. using an ARM core) and its signal processing and math functionalities are prioritized. No need to market it as a DSP, but documentation-wise that's what I'm using as inspiration. Similar DSPs tend to have:
* Datasheet and Technical Overview/Product Brief - Companion to Processor Reference Manual, reference for pinouts and packaging, block diagrams and memory map, electrical characteristics, peripheral overviews, device comparisons where applicable; the standard "can it do what I want" starter pack
* Processor Reference Manual - CPU architecture and registers, system configuration, details of memory and IO space, addressing modes, interrupts/resets/exceptions, timing diagrams, language reference when needed (most similar to current doc)
* Instruction Set Reference - Reference for ISA
* Programmer's Guide - Details about programming: languages, compilers, optimizations, debugging
Along with optional user manuals and reference guides for peripherals and such.
Currently the documentation (google doc, ISA spreadsheet) fits the Processor Reference Manual and the Instruction Set Reference, but there's a lot of work to be done for the Datasheet and Programmer's Guide; a Product Brief would be easy enough to assemble from a datasheet. How is this all sounding so far?
If I had a wishlist of things still needed, it would be:
1. A block diagram, memory map (as applicable, might already exist), simplified schematics for pins and peripherals, comparison chart with P1
2. Electrical characteristics - So far I've only found pin drive, some information on power at room temperature, loose references to pin limits, ESD specs, and some pitfalls like how blowing a pin can brick the chip if you damage the right bank. Specs of frequency behavior are also loose, the PLL VCO is suggested to be kept between 100-200MHz, but overclocking seems to have gotten it up to 300MHz, would like some guaranteed figures and figures of merit
Technical documentation is no easy feat, but this should get things started. Please contribute any and all information, existing (up to date or outdated with notes) diagrams and specifications, etc!
PS. Reformatted datasheet (work in progress) is attached to show what I mean by reformatting
--Edit-- Updated files to include full text
--Update-- Replacing files with Drive link. Updated 21 jan 20201
--Update-- Added Instruction Set Reference Manual outline. Updated 22 jan 2021
--Update-- Improved code listing formatting, added smart pin block diagram, notation notes. 26 jan 2021
--Update-- Added remaining tables, timing diagrams, finished streamer table
--Update-- Created an outline for a programmer's manual, fixed smart pin diagram. 29 jan 2021
Google Drive Folder: https://drive.google.com/drive/folders/1L7nEBhNtQs9h0TgUppIpekLyL-knm3oT?usp=sharing
Normally the starting point for something like this would be previous documentation, like the P1 datasheet, but I think there's room for improvement. So with that in mind, we should document the device like a DSP, as it has its own ISA and architecture (rather than e.g. using an ARM core) and its signal processing and math functionalities are prioritized. No need to market it as a DSP, but documentation-wise that's what I'm using as inspiration. Similar DSPs tend to have:
* Datasheet and Technical Overview/Product Brief - Companion to Processor Reference Manual, reference for pinouts and packaging, block diagrams and memory map, electrical characteristics, peripheral overviews, device comparisons where applicable; the standard "can it do what I want" starter pack
* Processor Reference Manual - CPU architecture and registers, system configuration, details of memory and IO space, addressing modes, interrupts/resets/exceptions, timing diagrams, language reference when needed (most similar to current doc)
* Instruction Set Reference - Reference for ISA
* Programmer's Guide - Details about programming: languages, compilers, optimizations, debugging
Along with optional user manuals and reference guides for peripherals and such.
Currently the documentation (google doc, ISA spreadsheet) fits the Processor Reference Manual and the Instruction Set Reference, but there's a lot of work to be done for the Datasheet and Programmer's Guide; a Product Brief would be easy enough to assemble from a datasheet. How is this all sounding so far?
If I had a wishlist of things still needed, it would be:
1. A block diagram, memory map (as applicable, might already exist), simplified schematics for pins and peripherals, comparison chart with P1
2. Electrical characteristics - So far I've only found pin drive, some information on power at room temperature, loose references to pin limits, ESD specs, and some pitfalls like how blowing a pin can brick the chip if you damage the right bank. Specs of frequency behavior are also loose, the PLL VCO is suggested to be kept between 100-200MHz, but overclocking seems to have gotten it up to 300MHz, would like some guaranteed figures and figures of merit
Technical documentation is no easy feat, but this should get things started. Please contribute any and all information, existing (up to date or outdated with notes) diagrams and specifications, etc!
PS. Reformatted datasheet (work in progress) is attached to show what I mean by reformatting
--Edit-- Updated files to include full text
--Update-- Replacing files with Drive link. Updated 21 jan 20201
--Update-- Added Instruction Set Reference Manual outline. Updated 22 jan 2021
--Update-- Improved code listing formatting, added smart pin block diagram, notation notes. 26 jan 2021
--Update-- Added remaining tables, timing diagrams, finished streamer table
--Update-- Created an outline for a programmer's manual, fixed smart pin diagram. 29 jan 2021
Google Drive Folder: https://drive.google.com/drive/folders/1L7nEBhNtQs9h0TgUppIpekLyL-knm3oT?usp=sharing
Comments
This has to be the best first post I have seen in 5 years! Thanks for sharing your labor of love.
It’s nice to see the excitement the P2 is generating especially in this early phase of development release. I like seeing all the early adopter’s efforts!
Thanks for sharing @sjgallagher2 and welcome to the Forums!
Paul
@cgracey - surely this should make a great template for the datasheet for you to work on? Of course, there are the DC and AC tables but we can start populating it with what we already know.
+1
Here's an embedded image:
Most of the datasheet is missing or tentative, still need to convert information from the smartpin documentation for peripherals, and I'm working on building a system block diagram. It'll take a while, I have a rough block diagram with key components (hand drawn, not in the folder) but I'll probably need to use the hdl to keep strict accuracy. (edit: got confused and thought P2 was open source, but it was the P1! Duly noted)
Thanks everyone for the warm welcome! The P2 community is great to be a part of.
- You've got a second PA instead of PB
- The last 16K is probably better labeled as "Boot ROM shadow / Debug RAM" or smth to that extent
- It is mirrored at both $FC000 and $7C000 (but the $7C000 mirror disappears when it is set to read-only mode and turns into unmapped memory)
Yes, that's what I meant.
Further reading - https://forums.parallax.com/discussion/172756/p2-electrical-characteristics/p1
and - https://forums.parallax.com/discussion/169542/p2-links-for-where-to-obtain-tools-sample-test-code-reference-only/p1
and we did a block diagram too - https://forums.parallax.com/discussion/171420/smartpin-diagram-now-with-p-p-bit-mode-table/p1
Does this mean that hub RAM granularity is 8-bit and cog/lut RAM is 32-bit (long addressing), or are they both 8-bit granularity (both byte addressing) and the data bus between them is 32-bit? I'll add to the diagram to clarify.
HUB RAM is 32-bits but is byte addressable and word and long accesses do not need to be aligned.
Looking at the addressing it's apparent that each address corresponds to a byte rather than a long for hub RAM, so I think the attached memory map will better reflect this. It only shows memory mapping, not the data bus, so while hub RAM is accessed in longs, that's not shown because it's addressed as bytes. I'm thinking that memory accessing information should go in a separate diagram, like the other attached image. Also, I replaced the reference to execution with (rw) for read-write and (rwx) for read-write-execute, I think it's much cleaner that way. Thoughts?
This is documentation independent of the languages.
Mike
I presume the prop2 hub ram is like the P1, byte adressed but can be read as bytes words and longs.
However because of its 'endianess' if you write sequentially bytes to hub and then read back as a long you may not get back what you expect.
ie if you write 1,2,3,4 to hub ram and then read back as a long you get 4321.
Dave
I was torn between using $ and 0x, it's really just a matter of context. Still, 0x is more familiar to new/prospective developers, who need the datasheet more, so I decided to go with that. The reference manual on the other hand uses $.
Thanks Chip, appreciate the welcome. Excited to get some critique on things! I'll make sure everything in the Drive folder is up to date by tonight.
Update: I reformatted all the code listings to have equal spacing/indentation. They're now all in a text file as well for making indentation change. I took the Smart Pin block diagram, which was in color, and made it print-friendly by redrawing it in black and white. The scope images were also converted to black and white. Some information was moved to the datasheet where it was better suited, and some front-matter about notation, document purpose, and related documents was added. Some tables still need to be added, and lots of things need formatting. There's an instruction set reference manual document but it only has a table of mnemonics with brief descriptions so far, I'm working towards it. The datasheet has also sort of been neglected while I work through the reference manual. All documents and resources are in the Drive!
Nice work!
I just got a chance to look at it all, and you've done a great job! Good timing too as I've got someone interested and looking for info. Sending this along.
Reference Manual Update: Nearly there, not missing any more tables (I think) so it can be used in place of the original document without issue. Added a lot of text formatting, added tables to fill in missing information, organized the Smart Pin section to actually include subsections and sub-subsections; added timing diagrams in place of the ASCII-art diagrams; finished the streamer table section, which still could use a little more work to put information into the sections. There are still unwritten sections and WIP sections (e.g. section 6. Boot Process), as in the original document.
Datasheet Update: Moved some things, added an outline for desired content that will both advertise the part's strengths and explain some of its peculiarities for prospective buyers. Lots to be done still, most of the sections need to be written from scratch to fit the datasheet context. This should be done by someone more knowledgeable than me. There's also the block diagram which now at least has a placeholder that bears some resemblance to the actual system...
No updates for instruction set manual or programmer's manual
Wow! That datasheet is looking awesome!!!
I see a few details that need fixing. Is there any way I could do that?
Very nice work, sjgallagher2.
What would be helpful in the smart pin section is the constant name used in Spin and other languages for this mode. Maybe it should be even in the title, so that you see it in the index - that makes it easy to find the mode description, if you see the constant in a code.
Also the description of the lowlevel pin modes should show the constant names in the reference manual. Now you always need to look up the constant name in the Spin document, sometimes you have to compare the bitpatterns to be sure you choose the right one.
Andy
@cgracey Oh good! Corrections are welcome! Ill just have to make sure the google drive files allow commenting. Im working in .odt so it depends on how drive handles it.
-- Edit -- Added comment versions "xxxxCommentCopy" in the google drive, I think that should work.
@Ariba The important thing here is keeping the programming separate from the architecture, but I'll experiment, I think those things could fit in anyway (especially with how close Spin2 is to the architecture).
Sam,
Your block diagram has lost the dividing line between the pad-ring and the core-logic. It's a useful thing to know that exists for a few reasons.
@evanh Thanks for the tip, I redrew it to help clarify and keep information from the original. See attached.
Good stuff. Thanks.
There is a couple more things I now think could help as well: