Shop OBEX P1 Docs P2 Docs Learn Events
P2 Datasheet Progress — Parallax Forums

P2 Datasheet Progress

sjgallagher2sjgallagher2 Posts: 22
edited 2021-01-29 19:46 in Propeller 2
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


«13

Comments

  • Welcome to the forums!

    This has to be the best first post I have seen in 5 years! Thanks for sharing your labor of love.
  • doggiedocdoggiedoc Posts: 2,239
    edited 2021-01-19 18:18
    Publison wrote: »
    ....This has to be the best first post I have seen in 5 years!...
    Agreed!

    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
  • That looks splendid, well done.

    @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.
  • Cluso99Cluso99 Posts: 18,066
    Publison wrote: »
    Welcome to the forums!

    This has to be the best first post I have seen in 5 years! Thanks for sharing your labor of love.

    +1
  • sjgallagher2sjgallagher2 Posts: 22
    edited 2021-01-21 02:16
    Update. I split the documentation into a datasheet and a reference manual, and added a memory map based on what I could find. I added the relevant files to this google drive folder. Could someone verify the memory map image? The svg is in the svg/ folder, the png is in the img/ folder and in the datasheet. It's the memory map for the P2X8C4M64PES silicon, with the 512kB hub RAM (the remaining memory space is labeled 'reserved'). I labeled the last 16kB as 'default boot memory' but there might be a more appropriate label.

    Here's an embedded image:
    Memory-Map-hires.png

    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.
  • - That's only the memory map from the instruction fetcher's point of view, RDLONG and friends will access hub RAM between $000 and $3FF (that region just can never contain hubexec code).
    - 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)
  • Thanks for the quick feedback. Here's a revision:
    Memory-Map-rev1.png
  • Would also be good to somehow show that cog/lut ram are 32 bit wide vs 8 bit wide hub RAM.
  • evanhevanh Posts: 15,126
    Wuerfel_21 wrote: »
    Would also be good to somehow show that cog/lut ram are 32 bit wide vs 8 bit wide hub RAM.
    HubRAM's addressing granularity is 8-bit, the databus width is 32-bit.

  • evanh wrote: »
    Wuerfel_21 wrote: »
    Would also be good to somehow show that cog/lut ram are 32 bit wide vs 8 bit wide hub RAM.
    HubRAM's addressing granularity is 8-bit, the databus width is 32-bit.

    Yes, that's what I meant.
  • evanh wrote: »
    Wuerfel_21 wrote: »
    Would also be good to somehow show that cog/lut ram are 32 bit wide vs 8 bit wide hub RAM.
    HubRAM's addressing granularity is 8-bit, the databus width is 32-bit.

    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.
  • COG/LUT RAM is always 32-bits although there are special instructions for dealing with words/bytes/nibbles.
    HUB RAM is 32-bits but is byte addressable and word and long accesses do not need to be aligned.
  • COG/LUT RAM is always 32-bits although there are special instructions for dealing with words/bytes/nibbles.
    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?
    1686 x 812 - 212K
    800 x 309 - 43K
  • Wuerfel_21Wuerfel_21 Posts: 4,370
    edited 2021-01-21 16:19
    You might want to use $ABCD instead of 0xABCD style hexadecimals, as the former is used in P2 ASM and Spin2.
  • I think 0xABCD is correct as I have never seen $ABCD until SPIN.

    This is documentation independent of the languages.

    Mike
  • Hi

    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

  • cgraceycgracey Posts: 14,133
    edited 2021-01-21 17:00
    Sjgallagher2, glad to have you here! I like your ideas. I hadn't noticed your post earlier, because I've been doing some other work. I'm going to be busy all day, but will look closely at your work tonight.
  • Wuerfel_21 wrote: »
    You might want to use $ABCD instead of 0xABCD style hexadecimals, as the former is used in P2 ASM and Spin2.

    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 $.
    cgracey wrote: »
    Sjghallager2, glad to have you here! I like your ideas. I hadn't noticed your post earlier, because I've been doing some other work. I'm going to be busy all day, but will look closely at your work tonight.

    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.
  • cgraceycgracey Posts: 14,133
    Sjghallager, I've been working outside all day and I'm really worn out. I want to look at what you've done on a proper screen, not my cell phone. I've got one more day of work outside, but I should be free tomorrow evening. I'm sorry for the delay. Please hold on.
  • Sam, thank you very much, great work! I especially like that the PDFs can be used both as online and as printed paper document as there is a good table of contents and index tab. In my office I have two large 1900x1000 monitors so I can view docimentation on one screen while programming on the other. But at home I only have a small screen so I prefer printed docs on my desk.
  • 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

  • cgraceycgracey Posts: 14,133

    Wow! That datasheet is looking awesome!!!


    I see a few details that need fixing. Is there any way I could do that?

  • AribaAriba Posts: 2,682

    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

  • sjgallagher2sjgallagher2 Posts: 22
    edited 2021-01-28 23:50

    @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).

  • evanhevanh Posts: 15,126
    edited 2021-01-30 01:50

    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.

    • The pad-ring is physically in a ring around the outer edge of the die, matching the I/O pins. Each pad-ring I/O circuit is custom laid beside its physical I/O pin bonding pad. These circuits were fixed in place before the chip synthesis was begun.
    • The smartpin logic is synthesised and therefore not placed beside its associated pin in the same manner. In fact indications are that all smartpins will be packed in the centre of the die along with the hub control logic.
    • So that dividing line defines where the routing delays begin from. Internally, and not indicated in the block diagram, there is a number of staging flops between the cogs/hub/smartpins and the pad-ring. These put a minimum number clock cycles to any I/O interactions.


  • sjgallagher2sjgallagher2 Posts: 22
    edited 2021-01-29 18:31

    @evanh Thanks for the tip, I redrew it to help clarify and keep information from the original. See attached.


  • evanhevanh Posts: 15,126

    Good stuff. Thanks.

    There is a couple more things I now think could help as well:

    • The dotted line for M=0 inside each smartpin block, that could be reworked to A) have an arrow head and B) make it a switch. A changeover between SmartA and the internal smartpin status would be best but more complicated to draw.
    • The term "Physical" pin can be misinterpreted too easy as meaning the package pin numbering rather than the I/O pin numbering. I haven't thought of a better labelling though.


Sign In or Register to comment.