Shop OBEX P1 Docs P2 Docs Learn Events
Formatting the P2 instructions spreadsheet — Parallax Forums

Formatting the P2 instructions spreadsheet

Peter JakackiPeter Jakacki Posts: 10,193
in Propeller 2
Every time I look at the P2 instruction set document I get a headache. Since I already had a headache this morning and couldn't do much else I decided to look at it and try some minimal reformatting to see if that would help my head. I think it did.

Tell me what you think and maybe it's something that Chip will be agreeable to incorporating back into the main document from this color column copy.

I want to be able to link in examples and perhaps if the main P2 documentation had bookmarks, I could link to there as well.


Screenshot from 2020-02-04 14-00-50.png
1716 x 687 - 238K

Comments

  • roglohrogloh Posts: 5,787
    Yeah I find it tedious to scan/search through the pdf too, and it is quite wide for a portrait oriented 1200 pixel wide monitor. I actually think having a second table ordered by MNEMONIC would be good here too. Ideally we have one table ordered by opcode to help us disassemble things and another one to find the reference information for an instruction by its name. Especially handy if these can then be printed out as a hard copy reference and not simply text searched for in a file which I find matches extra things in the original document.

    Perhaps having a raw spreadsheet would be useful in other cases too.
  • evanhevanh Posts: 15,916
    That's interesting Peter, I've not spent much time checking the encodings so those details not being obvious never bothered me. I can see it being educationally useful too though.

    Roger, it is a google spreadsheet! I download it as an ods file rather than pdf and then view it with LibreOffice. That'll be why Peter has bothered to hack something up at all. As for the width of the spreedsheet, I've got a 4k monitor so I don't even need it as full screen. Cluso already did sorted versions a while back I'm pretty sure.
  • jmgjmg Posts: 15,173
    rogloh wrote: »
    Yeah I find it tedious to scan/search through the pdf too, and it is quite wide for a portrait oriented 1200 pixel wide monitor. I actually think having a second table ordered by MNEMONIC would be good here too. Ideally we have one table ordered by opcode to help us disassemble things and another one to find the reference information for an instruction by its name. Especially handy if these can then be printed out as a hard copy reference and not simply text searched for in a file which I find matches extra things in the original document.

    Perhaps having a raw spreadsheet would be useful in other cases too.

    Yes, I was thinking along the same lines of two tables.
    One form is good for assembler/compiler-writers and disassemblers, and another format for those actually writing in Assembler.
    eg The COND & INS CODE binary level columns are only needed for the (small) first group, but the second (larger) group are only interested in the mnemonic and needed/possible parameters.

    The description needs to expand from a terse few words.

    I've seen PDFs with hyperlinks and popups, but I'm not sure how to create those from a spread sheet.
    Maybe each table line can work like an index in a PDF, so a click can go to a paragraph example ?
  • Peter JakackiPeter Jakacki Posts: 10,193
    It's easy enough to group columns, especially those that are not normally relevant, and collapse them so that you can print the pertinent info on a standard page. This is the way I set them up and you will notice the little + and - icons on the row above the volume indices A,B,C etc.

    There is also no reason why we can't add sheets to the document and have pivot tables for different needs. But columns and color already make it a lot easier to see what instructions can and can't do.
  • Peter JakackiPeter Jakacki Posts: 10,193
    I have moved the columns around and placed all the main assembler mnemonic and operands on the left as well as grouping functions together as well. Now I can read this spreadsheet easily on my phone. Still a WIP but very usable and I have discovered some instructions and modes I didn't know about in the process.
  • ersmithersmith Posts: 6,053
    Where did the cycle counts go? I don't see those in the google sheet any more.
  • Peter JakackiPeter Jakacki Posts: 10,193
    ersmith wrote: »
    Where did the cycle counts go? I don't see those in the google sheet any more.

    Ooops! I had made those columns a group and having forgotten that I had hidden them :)
    I'm put all the timings on another sheet and will incorporate it back into the main instruction sheet in a more compact format.
  • Peter JakackiPeter Jakacki Posts: 10,193
    edited 2020-02-05 03:40
    Instruction timings have been added back into the main instruction sheet as well as listed in a sub-sheet. However I just found out that they were there all the time but hidden due to some strange googlebug to do with the group button.
    P2 Rev B INSTRUCTIONS (COLOR COLUMNS VERSION)

    I'm making other improvements as well. For example I've printed out the preliminary shortform version of it as a PDF without the code and timings, very simply.

    @cgracey
    On the subject of documentation I'd like to add a table of contents to the main P2 document as well as more headings. Here's a copy I just made of the P2 document that has a table of contents inserted making it very easy to go to the relevant section.

    pdf
    pdf
    Parallax Propeller 2 Instructions v33 - Rev B Silicon - PBJ Color Columns version - INSTRUCTIONS.pdf
    179K
  • kwinnkwinn Posts: 8,697
    I find spreadsheets to be a great way to document assembler instructions. Once I have my P2 board I intend to download the current version and add more detailed descriptions and examples for the instructions as comments in the spreadsheet to get up to speed.
  • pilot0315pilot0315 Posts: 910
    @"Peter Jakacki"

    Thanks for doing that. Made my headache go away.
  • cgraceycgracey Posts: 14,155
    Peter, I like your list. I did notice that SCA/SCAS should go under arithmetic and REP probably needs to go under branching.

    Your list is very useful and needs to exist along with the one I made. I ordered mine the same way the Verilog is set up, with bit patterns in ascending order. It's like my own notes to myself, if nothing else.

    Your groupings are really nice and make clear sense. Yours is more valuable to the programmer than mine is.
  • Peter JakackiPeter Jakacki Posts: 10,193
    edited 2020-02-12 00:54
    Sounds good then Chip, I'm only trying to reformat this at least for my own use (and sanity), but it would be good too if it linked in with the main P2 document. It's still a wip at present and I was toying with which instructions could be grouped together more logically (and some were sitting on the fence in the meantime).

    The P2 document requires more headings to link to, even if it doesn't include a table of contents. But at present I am linking into my copy of the P2 document since I am adding headings etc. While the instruction set may be complete now, the P2 documentation is an ongoing process and I can also see how it would be beneficial to have sub-documents that are linked to from the main document. Google docs can still be rather slow with large documents.

    Do you think this is something that could be merged?
  • cgraceycgracey Posts: 14,155
    Of course we could merge your list. It needs a link from the documentation, at least.
  • Peter JakackiPeter Jakacki Posts: 10,193
    edited 2020-02-23 13:56
    I'm hoping the main documentation page hasn't been updated since I have been adding links into my copy to make it easier to cross reference between the document and the instruction spreadsheet. However, while implementing an interactive assembler I realized that the instruction codes for the TESTx and BITx instructions are duplicated. I'm sure I could run p2asm and see what it produces in the listing but am I seeing things cross-eyed or is there really an error in the instruction sheet?
    TESTB   eeee	01000	0	0	C	Z	I	DDDDDDDDD	SSSSSSSSS
BITL    eeee	01000	0	0	C	Z	I	DDDDDDDDD	SSSSSSSSS

    BTW, I checked the original and it's the same, plus I also keep a copy of that for reference as a sub-sheet.

    EDIT, I found p2asm generate this: 
    00e4c     f4004422 		bitl	tos,tos
00e50     f4104422 		testb	tos,tos wc
    So the wc changes the bitl to a testb but both instructions list czi fields available,

    Ok, going a bit further I see the pattern. There's some juggling of the cz fields (xx18xxxx) to allow for two types of instructions. 
    00e4c     f41c4402 		bitl	tos,#2 wcz
00e50     f4044402 		bitl	tos,#2
00e54     f4144402 		testb	tos,#2 wc
00e58     f40c4402 		testb	tos,#2 wz
  • cgraceycgracey Posts: 14,155
    Peter, it looks like a documentation error on my part.
  • ozpropdevozpropdev Posts: 2,792
    This might help Peter
    https://forums.parallax.com/discussion/comment/1449208/#Comment_1449208
  • Peter JakackiPeter Jakacki Posts: 10,193
    ozpropdev wrote: »
    This might help Peter
    https://forums.parallax.com/discussion/comment/1449208/#Comment_1449208

    Thanks for that confirmation and link. I figured that with either C or Z set that it became a TESTx but with CZ = 00 or 11 then it was a BITx. Tricky!
  • cgraceycgracey Posts: 14,155
    Actually, there is no conflict. BITx effects both C and Z, or neither, while TESTB(N) affect either C or Z, only.
    TESTB   D,{#}S         WC/WZ
TESTBN  D,{#}S         WC/WZ
TESTB   D,{#}S     ANDC/ANDZ
TESTBN  D,{#}S     ANDC/ANDZ
TESTB   D,{#}S       ORC/ORZ
TESTBN  D,{#}S       ORC/ORZ
TESTB   D,{#}S     XORC/XORZ
TESTBN  D,{#}S     XORC/XORZ
BITL    D,{#}S         {WCZ}
BITH    D,{#}S         {WCZ}
BITC    D,{#}S         {WCZ}
BITNC   D,{#}S         {WCZ}
BITZ    D,{#}S         {WCZ}
BITNZ   D,{#}S         {WCZ}
BITRND  D,{#}S         {WCZ}
BITNOT  D,{#}S         {WCZ}
  • Cluso99Cluso99 Posts: 18,069
    Yes, I had seen your tricks of using the mix of C & Z flags to get more instructions back when I used to create a spreadsheet with the instruction mapping. I must dig out the last version I did and update it.
Sign In or Register to comment.