@"Christof Eb." said:
My first impression was positive, because the text has a nice appearance. But then I saw this:
This is the point. LLM slop mimics the surface-level appearance of well-written text (to some degree of success). Any possibly correct information relayed therein is a statistical side-effect.
How exactly did you measure this: "The impact: 3-5x acceleration in development iteration cycles when paired-coding with Claude."
The clanker told him? idk. Extraordinary claim without extraordinary evidence. Programming does not follow the rules of Esotericism (and vice versa!). In actual studies done on this you just get measurement error. One guy was 20% faster, another guy was 20% slower, etc. Additionally, if the claim was true for some blessed combination of LLM/MCP/workflow/whatever, this would produce evidence thereof in the form of large quantities of published high-quality code. We do not observe this, so empirically it's untrue. What we do observe is guys at Microsoft et al. bragging about how much % of their code is now "written by AI" and the quality of the software immediately cratering to lows never known before. (I would in general recommend doing the opposite of what post-2010 Microsoft/Google/etc are doing, even before this LLM nonsense, their methods clearly did not result in high-quality software)
@"Christof Eb." said:
?????
Stephen, have you ever used _RET_ ?????
Apparently yes! https://github.com/ironsheep/P2-HUB75-LED-Matrix-Driver/blame/ad22fada85ad7d4ffe90f7530ab9294abfda85f3/driver/isp_hub75_rgb3bit.spin2#L903
And this once again illustrates the point that this is a fundamentally bad methodology for producing documentation if horrible errors like this can ever even come into existence.
If you point them out, he can fix the egregious ones, but can you trust anything else after that?
And even if you're 100% sure you got rid of all the errors, you'll have spent longer to get there, still have to deal with the previous errors being "out there" in older copies of the document and still have the odious LLM association. (I am of a mind the people you could get to want to work and play with expensive P2 chips and their quirky one-off architecture have a large overlap with people who don't want anything to do with "AI" - such is my opinion and I happen to often run into people with similar opinions and interests. If I was checking out Parallax products for the first time ~today and saw AI slop quasi-officially endorsed I would turn around and not look back)
@"Christof Eb." said:
Uih, where did you find getmulh? Perhaps I should not have followed Wuerfels game suggestion, I seem to be a little bit high....
I did issue a warning, didn't I? ;3
And I'd like to take the time to once again state that I'm not just trying to stir shit for the sake of it. I want there to be good P2 documentation and I want the community to be healty. Infact, as is well known, I have had my own go at a P2ASM reference. It's not entirely complete, because it turns out it's a hard job and writing instructive text is not my best skill (and I have many other projects on my slate). A large portion of my 5000+ forum posts are spent helping people in the trenches with their code. I want what's good for P2 and the community and this is just not it. When I get mean about this, it's because more polite methods have failed to take effect. If anyone has got any questions or problems in need of settling, my private messages or email are available in the usual places.
After reading the PDF documents a bit more, here are my observations.
It is possible that I am wrong on something, I tried to verify what I can but is mostly based on my knowledge that isn't exacly precise, so please forgive me if I have reported something incorrectly.
A suggestion: would be possible to make the code examples copy-able ? Right now, selecting the text is a mess and make nearly impossible to verify the examples.
P2-PASM-deSilva.pdf
Page 17, the aformentioned wrong jump back (4 instructions instead of 6), repeated on page 18
Page 32, the mov value, $1000 can't compile, $1000 is greater than $1FF
Page 32, the Cog Counter example, the description seems a bit misleading, it starts 7 COGs incrementing the hub location, the 8th is the Spin COG itself that is not replaced by COGEXE_NEW (the loop counts from 0 to 7, 8 times)
Page 55, MUL is 16x16 -> 32 (not 32x32 -> 64 as written), the already reported GETMULH (doesn't exsists, repeated multiple times through the document), this needs a big review, there is a also the comment "lower 32 bit" that's wrong
Page 81, the screen buffer clear example, while maybe correct, it isn't really usable since it needs a 1,2MB buffer while the hub RAM is 512KB, maybe use a smaller screen size, or divide the loop by 4, that is 307KB
Page 84, the data filter pipeline, it starts both RDFAST and WRFAST, as far as I know, the FIFO is one, it can either read or write, not both. This also needs a big review
Page 87, the HUB execution cycles, seems a bit wrong, for most instructions are the same as the COG execution cycles, only branch instructions or instructions that interfers with the FIFO needs more cycles (the PASM instructions spreadsheet illustrates that better)
Page 104, WRLONG value --ptra++, can either pre-decrement or post-increment, not both
Page 109, instructions pairing, the AUGS example can't work, MOV x, #$678 can't compile
Page 113, WRLUT with a long constant without ##.
Page 114, the bulk LUT load, I don't think that RDLONG $200, hub_table_ptr is correct, aside from overflowing, SETQ2 already sets the LUT target, it should be RDLONG 0, hub_table_ptr
Page 115, LUT sharing, RDLUTS doesn't exists, the example doesn't seems correct as it stands, COG1 needs to start first, generally this needs a really big review because seems that SETLUTS merges the COG LUT ram but it enable an implicit copy with the WRLUT instruction. Sharing is a bit misleading, maybe it is time to use a more correct description.
Page 136, the COGINIT are unbelievable wrong, there isn't a 3rd parameter, if you want to set PTRA you need SETQ before COGINIT
P2-Assembly-Language-Manual.pdf
All instruction tables have the C, Z and Result columns mixed
Page 19, the aformentioned COG diagram with wrong LUT sharing
Page 26, the LUT sharing description doesn't seems correct, SETLUTS doesn't give COGs 1024 longs of LUT space, the LUT space is still 512 longs.
Page 30, the RET condition example is wrong, ADD is executed, it is a combination of ADD and RET
Page 49, the condition execution timing, if I'm not wrong the false condition still uses 2 cycles, not 1 as written
Page 50, the complete conditions table doesn't seems so complete and have non esistent conditions like if_always and if_never, seems taken from P1 conditions.
Page 55, modc/modz/modcz needs wc and/or wz effects, otherwise they won't work, and the immediate #1 and #0 doesn't seems to work, it needs the corresponding flags always
Generally, the documents seems good, however given the number of "hallucinations" they are not ready for the public, especially newbyes that will certainly be confused.
The AI needs a lot more training, in my opinion, I don't want to offend anyone but the most disturbing thing is that after all that training it still presents errors on the basics, like overflowing constant, inexistent instructions, wrong concepts and don't know what else, not surprising that some are reluctant to use it. Hope it will get better in the future.
@macca said:
After reading the PDF documents a bit more, here are my observations.
It is possible that I am wrong on something, I tried to verify what I can but is mostly based on my knowledge that isn't exacly precise, so please forgive me if I have reported something incorrectly.
Seriously, this feedback is amazing. I really appreciate your time on this. I couldn't have asked for better.
A suggestion: would be possible to make the code examples copy-able ? Right now, selecting the text is a mess and make nearly impossible to verify the examples.
I'll likely provide a .zip (or .tar.gz) of all of the code files. will this work?
P2-PASM-deSilva.pdf
Page ....
I focused on the language manual audit yesterday, but the DeSilva manual is happening today. Watch for version 1.1 in less than 24 hours.
P2-Assembly-Language-Manual.pdf
Version 1.1 has been released, and a changelog is now available for the document. A comprehensive list of fixes is provided. Most of what you cited are in the fixed column, now. I'll check your list to make sure.
Page 19, the aformentioned COG diagram with wrong LUT sharing
I'll fix this across all documents in a subsequent update.
Page 26, the LUT sharing description doesn't seems correct, SETLUTS doesn't give COGs 1024 longs of LUT space, the LUT space is still 512 longs.
Hrmf... I don't remember if the audit caught this, good catch. I'll check and if not fixed, will update in the next release.
@macca said:
That's really a big improvement in the documentation (finally I must add...).
The experiment seems to be bearing fruit... time will tell.
Also, in the COG Architecture on the P2-Assembly-Language-Manual.pdf seems that there is a single LUT ram shared between COG pairs, that's wrong, each COG has its own LUT ram that can be shared with the dedicated enablement instruction. And shared is a bit misleading, because it actually means that writes to a LUT on a COG is copied to the other COG LUT, if I'm not wrong, each LUT can be loaded with independent data, only wrlut instructions cause the shared copy.
This was entirely my mental image after reading the docs. Totally my mistake. Cleaning this up will be pretty straightforward. So stay tuned! ;-)
A suggestion: would be possible to make the code examples copy-able ? Right now, selecting the text is a mess and make nearly impossible to verify the examples.
I'll likely provide a .zip (or .tar.gz) of all of the code files. will this work?
Generally I prefer to be able to select the code from the document and copy/paste to the source editor.
I think a separate archive is more suitable for full code examples rather than snippets.
@macca said:
A suggestion: would be possible to make the code examples copy-able ?
Excellent point! I'll see if that's possible. This is using a .md -> pandoc/LaTeX generation system, so it's all automated. Lot's of things are possible and that copy approach would be really great. I'm hunting to see if I can do it.
@macca Ok, it seems that if what I'm learning is correct, I'm unable to do copy buttons that support all PDF viewers. Adobe Acrobat would be supported through a JavaScript approach, but macOS Preview and other tools won't work, and its PDF internal scripts are generally blocked by security...
Another approach might be to provide a .zip/.tar.gz file of the code file, snippets, and add clickable links within the document for each example. If the user unpacks the source next to the PDF, these links should work.
What are your thoughts about this approach?
I'm still looking for more alternatives, and we can certainly experiment with any technique we think would be helpful.
@macca (Thank you!) pointed out a systemic badness in the tables and more... These are being fixed now. Watch for v1.2.0 of the P2 Assembly Language Manual in a couple of hours.
@"Stephen Moraco" said:
Excellent point! I'll see if that's possible. This is using a .md -> pandoc/LaTeX generation system, so it's all automated. Lot's of things are possible and that copy approach would be really great. I'm hunting to see if I can do it.
Is the markdown source in your repo somewhere? I looked, but it wasn't particularly obvious
@"Stephen Moraco" said:
@macca Ok, it seems that if what I'm learning is correct, I'm unable to do copy buttons that support all PDF viewers. Adobe Acrobat would be supported through a JavaScript approach, but macOS Preview and other tools won't work, and its PDF internal scripts are generally blocked by security...
That's not what I mean. I think it is a matter of how the code blocks are translated to PDF.
I did a bit of digging through the source files.
This is the original code block, which is good.
**Basic Usage:**
```pasm
_ret_ add x, y ' ADD then return (flags same)
_ret_ drvnot #0 ' Toggle pin 0, then return
_ret_ mov result, temp ' Copy to result, then return
The PDF generator translates it to what seems a table with columns representing the indentation.
In the image above I tried to select just the first row but also selected the columns below, and all indentation spaces are trimmed.
What I was expecting is the code block to be translated verbatim so it can be selected.
I was going to try to suggest something, but I see that other documents suffer from the same issue (PropellerManual and also HydraGameDevManual), maybe it is a limitation of the PDF format or the translation (I think it skips the spaces entirely and prints just the text at the expected column). I used iText to generate PDF documents several years ago but I don't remember the details.
If not possible, a separate archive would be fine.
I like it, that the tone in the site is now much more modest now!
Stephen, You seem to not read, what I write. I already had pointed you to the fact, that mul is not 32x32 in August.
I still do not understand, why you print the exactly same table twice following each other????
In 1.3 the memory layout is an example but not mandatory. For example Taqoz uses the top end for serial and SD buffers.
In 1.4 in my opinion the best use of LUT memory is missing: For code space. Reason is that it is as fast as cog code, but not as precious as cog space. Also in my opinion it is quite valuable to know that direct access to LUT is only possible in the lower half of it.
In my opinion 1.5 must be completely reformulated, because in hub execution the streamer is involved as micro-cache. It is essential to understand this, if you are looking for speed or want to use the streamer for other purposes. In 1.6.2 the second sentence is downright wrong.
In 5.6.6 there seem to be errors, I would have to dive in.
I do not understand, why marketing blabla is included in this manual. See 5.6.7 . It is a waste of time for the readers. 5.6. already has the same information.
All in all, the paragraph about XBYTE is very difficult to read and therefore probably not very helpful to many readers. In my opinion this is insufficient for a manual.
There are many places in this manual, where I would have to look up information and would have to dive in for hours. Obviously the writers and copyright owners did not bother to do so themselves resulting in the given quality. The problem is, that if there are bugs in such manual, they will cost customers hours.
@"Christof Eb." said:
I like it, that the tone in the site is now much more modest now!
Stephen, You seem to not read, what I write. I already had pointed you to the fact, that mul is not 32x32 in August.
I still do not understand, why you print the exactly same table twice following each other????
I apologize for not attending to your responses. I've had really full days, but this is not an excuse.
When we draft documents and convert regions of them into visual representations, it's common to accidentally leave a 2nd copy. It's not intentional. It's just incomplete editing. If this were done traditionally in-house, we would have multiple passes with reviewers and editors.
Our experiment here is to ask for help from you and the rest of our community in locating these issues and reporting them. This is an attempt at crowdsourcing the reviewer phase of our document creation. Does this make sense?
Your feedback is invaluable. I will incorporate it!
@blittled said:
When I run the fetch-kb-file.ps1 in powershell ....
After testing the scripts on Windows, I had to fix several minor script errors. The scripts are now updated in the repo. I've updated the relevant pages at the repo. Another script has been added to the mix (and yes, I tested it on PowerShell ;-), so following the newly identified bootstrap process should get you all the latest scripts. Please let me know how this works for you.
Comments
Uih, where did you find getmulh? Perhaps I should not have followed Wuerfels game suggestion, I seem to be a little bit high....
This is the point. LLM slop mimics the surface-level appearance of well-written text (to some degree of success). Any possibly correct information relayed therein is a statistical side-effect.
The clanker told him? idk. Extraordinary claim without extraordinary evidence. Programming does not follow the rules of Esotericism (and vice versa!). In actual studies done on this you just get measurement error. One guy was 20% faster, another guy was 20% slower, etc. Additionally, if the claim was true for some blessed combination of LLM/MCP/workflow/whatever, this would produce evidence thereof in the form of large quantities of published high-quality code. We do not observe this, so empirically it's untrue. What we do observe is guys at Microsoft et al. bragging about how much % of their code is now "written by AI" and the quality of the software immediately cratering to lows never known before. (I would in general recommend doing the opposite of what post-2010 Microsoft/Google/etc are doing, even before this LLM nonsense, their methods clearly did not result in high-quality software)
Apparently yes! https://github.com/ironsheep/P2-HUB75-LED-Matrix-Driver/blame/ad22fada85ad7d4ffe90f7530ab9294abfda85f3/driver/isp_hub75_rgb3bit.spin2#L903
And this once again illustrates the point that this is a fundamentally bad methodology for producing documentation if horrible errors like this can ever even come into existence.
If you point them out, he can fix the egregious ones, but can you trust anything else after that?
And even if you're 100% sure you got rid of all the errors, you'll have spent longer to get there, still have to deal with the previous errors being "out there" in older copies of the document and still have the odious LLM association. (I am of a mind the people you could get to want to work and play with expensive P2 chips and their quirky one-off architecture have a large overlap with people who don't want anything to do with "AI" - such is my opinion and I happen to often run into people with similar opinions and interests. If I was checking out Parallax products for the first time ~today and saw AI slop quasi-officially endorsed I would turn around and not look back)
I did issue a warning, didn't I? ;3
And I'd like to take the time to once again state that I'm not just trying to stir shit for the sake of it. I want there to be good P2 documentation and I want the community to be healty. Infact, as is well known, I have had my own go at a P2ASM reference. It's not entirely complete, because it turns out it's a hard job and writing instructive text is not my best skill (and I have many other projects on my slate). A large portion of my 5000+ forum posts are spent helping people in the trenches with their code. I want what's good for P2 and the community and this is just not it. When I get mean about this, it's because more polite methods have failed to take effect. If anyone has got any questions or problems in need of settling, my private messages or email are available in the usual places.
After reading the PDF documents a bit more, here are my observations.
It is possible that I am wrong on something, I tried to verify what I can but is mostly based on my knowledge that isn't exacly precise, so please forgive me if I have reported something incorrectly.
A suggestion: would be possible to make the code examples copy-able ? Right now, selecting the text is a mess and make nearly impossible to verify the examples.
P2-PASM-deSilva.pdf
P2-Assembly-Language-Manual.pdf
Generally, the documents seems good, however given the number of "hallucinations" they are not ready for the public, especially newbyes that will certainly be confused.
The AI needs a lot more training, in my opinion, I don't want to offend anyone but the most disturbing thing is that after all that training it still presents errors on the basics, like overflowing constant, inexistent instructions, wrong concepts and don't know what else, not surprising that some are reluctant to use it. Hope it will get better in the future.
Seriously, this feedback is amazing. I really appreciate your time on this. I couldn't have asked for better.
I'll likely provide a .zip (or .tar.gz) of all of the code files. will this work?
I focused on the language manual audit yesterday, but the DeSilva manual is happening today. Watch for version 1.1 in less than 24 hours.
Version 1.1 has been released, and a changelog is now available for the document. A comprehensive list of fixes is provided. Most of what you cited are in the fixed column, now. I'll check your list to make sure.
I'll fix this across all documents in a subsequent update.
Hrmf... I don't remember if the audit caught this, good catch. I'll check and if not fixed, will update in the next release.
The experiment seems to be bearing fruit... time will tell.
This was entirely my mental image after reading the docs. Totally my mistake. Cleaning this up will be pretty straightforward. So stay tuned! ;-)
Thank you for the kind words. They mean a lot.
Generally I prefer to be able to select the code from the document and copy/paste to the source editor.
I think a separate archive is more suitable for full code examples rather than snippets.
Excellent point! I'll see if that's possible. This is using a .md -> pandoc/LaTeX generation system, so it's all automated. Lot's of things are possible and that copy approach would be really great. I'm hunting to see if I can do it.
@macca Ok, it seems that if what I'm learning is correct, I'm unable to do copy buttons that support all PDF viewers. Adobe Acrobat would be supported through a JavaScript approach, but macOS Preview and other tools won't work, and its PDF internal scripts are generally blocked by security...
Another approach might be to provide a .zip/.tar.gz file of the code file, snippets, and add clickable links within the document for each example. If the user unpacks the source next to the PDF, these links should work.
What are your thoughts about this approach?
I'm still looking for more alternatives, and we can certainly experiment with any technique we think would be helpful.
NEWS
v1.1.0 of both documents is now available. There is also a detailed changelog for each. Latest Versions w/ChangeLogs
@macca (Thank you!) pointed out a systemic badness in the tables and more... These are being fixed now. Watch for v1.2.0 of the P2 Assembly Language Manual in a couple of hours.
Is the markdown source in your repo somewhere? I looked, but it wasn't particularly obvious
That's not what I mean. I think it is a matter of how the code blocks are translated to PDF.
I did a bit of digging through the source files.
This is the original code block, which is good.
**Basic Usage:** ```pasm _ret_ add x, y ' ADD then return (flags same) _ret_ drvnot #0 ' Toggle pin 0, then return _ret_ mov result, temp ' Copy to result, then returnThe PDF generator translates it to what seems a table with columns representing the indentation.
In the image above I tried to select just the first row but also selected the columns below, and all indentation spaces are trimmed.
What I was expecting is the code block to be translated verbatim so it can be selected.
I was going to try to suggest something, but I see that other documents suffer from the same issue (PropellerManual and also HydraGameDevManual), maybe it is a limitation of the PDF format or the translation (I think it skips the spaces entirely and prints just the text at the expected column). I used iText to generate PDF documents several years ago but I don't remember the details.
If not possible, a separate archive would be fine.
I like it, that the tone in the site is now much more modest now!
Stephen, You seem to not read, what I write. I already had pointed you to the fact, that mul is not 32x32 in August.
I still do not understand, why you print the exactly same table twice following each other????
In 1.3 the memory layout is an example but not mandatory. For example Taqoz uses the top end for serial and SD buffers.
In 1.4 in my opinion the best use of LUT memory is missing: For code space. Reason is that it is as fast as cog code, but not as precious as cog space. Also in my opinion it is quite valuable to know that direct access to LUT is only possible in the lower half of it.
In my opinion 1.5 must be completely reformulated, because in hub execution the streamer is involved as micro-cache. It is essential to understand this, if you are looking for speed or want to use the streamer for other purposes. In 1.6.2 the second sentence is downright wrong.
In 5.6.6 there seem to be errors, I would have to dive in.
I do not understand, why marketing blabla is included in this manual. See 5.6.7 . It is a waste of time for the readers. 5.6. already has the same information.
All in all, the paragraph about XBYTE is very difficult to read and therefore probably not very helpful to many readers. In my opinion this is insufficient for a manual.
There are many places in this manual, where I would have to look up information and would have to dive in for hours. Obviously the writers and copyright owners did not bother to do so themselves resulting in the given quality. The problem is, that if there are bugs in such manual, they will cost customers hours.
When I run the fetch-kb-file.ps1 in powershell I get the following error:
.\fetch-kb-file.ps1 p2kbArchCog
.\fetch-kb-file.ps1 : A parameter with the name 'Verbose' was defined multiple times for the command.
At line:1 char:1
I tried it with various keys and get the same error. What do I need to do to run it?
Let me look into this today and get a fix back out which you can prove works.
I apologize for not attending to your responses. I've had really full days, but this is not an excuse.
When we draft documents and convert regions of them into visual representations, it's common to accidentally leave a 2nd copy. It's not intentional. It's just incomplete editing. If this were done traditionally in-house, we would have multiple passes with reviewers and editors.
Our experiment here is to ask for help from you and the rest of our community in locating these issues and reporting them. This is an attempt at crowdsourcing the reviewer phase of our document creation. Does this make sense?
Your feedback is invaluable. I will incorporate it!
After testing the scripts on Windows, I had to fix several minor script errors. The scripts are now updated in the repo. I've updated the relevant pages at the repo. Another script has been added to the mix (and yes, I tested it on PowerShell ;-), so following the newly identified bootstrap process should get you all the latest scripts. Please let me know how this works for you.