New documentation idea

Wuerfel_21

Been thinking about the sorry state of the P2 docs...

Currently everything is split between multiple slow-loading Google Docs, so it takes a long time to get to where you need to be. Though the same applies to a lesser extent to every documentation format I've seen.

UNTIL NOW.

INTRODUCING HyperJump! TECHNOLOGY! (Pat. pending)

Or in other words: If you use VS Code, you should be familiar with the quick access thing that pops up when you press Ctrl+P. I switch files almost exclusively using this method.

I've never seen it applied to a website / document though. So I quickly proof-of-concepted something up. You can see it here: https://p2docs.github.io . Since a static website doesn't need any text input normally, the the search activates automatically when you start typing, no key combo required. Of course there isn't any actual content in there, just wanted to prototype the idea. All the instruction entries go to 404s. You can try searching for "CORDIC" or "Table" and a few other manually created pages though.

Circuitsoft

There are a lot of documentation generators that, while made for code/libraries, can also be applied to hardware pretty easily. I'm a fan of Rust mdBook. Seems that your hyperJump! could be written into a theme for it, making the doc generation much easier. There's also Zeal and Dash which are offline document browsers for Linux/Windows and Mac (respectively). See https://kapeli.com/docsets to build a docset.

Wuerfel_21

Yea, the jumper code is really just one small file that could be loaded into pretty much any website (it even brings its own DOM elements. Just needs to have appropriate CSS loaded) and the data it needs is just a JSON file with let $hyperJumpList = prepended onto it: https://p2docs.github.io/hjlist.js

On the other hand, don't underestimate my homebrewn site generator. It has all the markdowns, ERBs and SCSSes you could ever want (though ERB and markdown together creates some friction). ERB templating in particular is really powerful in the sense that you can just suck up data files and work with them (the instruction table is directly read from the CSV that google sheets exports). I also have a plugin that can auto-create small versions of images, but the p2docs site doesn't have it loaded.

Maciek

Let's assume I know nothing about documentation (not entirely true but..).

This is shockingly fast! I mean it. Really. I've just tried.

The real problem is the actual documentation needs to exist in the first place. If we could only have both corners covered equaly well...

There is always hope, always.

Thanks for that @Wuerfel_21.

Wuerfel_21

Yea, need to get all the instructions together. The instruction sheet is a bit obnoxiously formatted, so I may have to create a new machine-readable instruction description file from almost-scratch.

Wuerfel_21

Well, I created all the pages and instruction headers now (still using data scraped from the spreadsheet). No more 404s.

I also added the all-important images for the bit permutes already.

Wuerfel_21

Oh, forgot to mention, there's an issue currently wherein the multiple JMP/CALL opcodes aren't shown. Also, IDK what's going on with AKPIN.
I should probably set it up such that it can also merge multiple similar instructions (SETSEx etc).

I also should probably make the H3s a bit bigger.

rogloh

Just tried it, nice and fast. Once complete it will be handy for instruction lookup reference material. I like how pressing space can bring up a list of other topics.

Wuerfel_21

@rogloh said:
Just tried it, nice and fast. Once complete it will be handy for instruction lookup reference material. I like how pressing space can bring up a list of other topics.

That's not even an intentional feature. It's just that most of the "Topic" entries have a space in their name. Most of them just link to the top of one of the instruction pages - The intent is to have the general explanation of the streamer/cordic/etc there and the individual instructions below.

EDIT: (Relatedly, I think the web hosted version is somehow actually even more responsive than my localhost, lol. Blame WEBrick?)

Wuerfel_21

I just redid the jumplist generator so it can now handle linking to arbitrary ids within a page (as opposed to only doing that for the auto-generated instruction entries). There can also now be a "hidden" field to help guide searches. For example, "ptra" will give you the "pointer expressions" section, "irq" finds you the page on interrupts and "fumo" will bring up the funny plushie (do not ask why that's there in the first place).

Also a few minor other improvements. Still need to think about how to handle the tricky opcodes (JMP/CALL/CALLD and the many per-event opcodes).

Firefox screenshot for a change. Ignore the funky fonts, my FF install is bugged or smth.

Wuerfel_21

I have apparently discovered a new hardware feature? Never head of the U flag before...

Wuerfel_21

Also, retracting the previous statement, scraping the instruction table for info does seem to work fine enough after all. Might still need to manually override a few values, but oh well. Less work and potential for error than doing it by hand.

msrobots

nice

Wuerfel_21

Also @cgracey there's an error in the instruction sheet. LOCKREL should have register write as "D if reg and WC", shouldn't it?

Wuerfel_21

Highlighting which instructions can take SETQ:

cgracey

@Wuerfel_21 said:
Also @cgracey there's an error in the instruction sheet. LOCKREL should have register write as "D if reg and WC", shouldn't it?

The instruction spreadsheet says:

"Release LOCK D[3:0]. If D is a register and WC, get current/last cog id of LOCK owner into D and LOCK status into C."

Doesn't that say the same thing? I will change "id" to "ID" for clarity.

Wuerfel_21

@cgracey said:

@Wuerfel_21 said:
Also @cgracey there's an error in the instruction sheet. LOCKREL should have register write as "D if reg and WC", shouldn't it?

The instruction spreadsheet says:

"Release LOCK D[3:0]. If D is a register and WC, get current/last cog id of LOCK owner into D and LOCK status into C."

Doesn't that say the same thing? I will change "id" to "ID" for clarity.

Yeah, that's how I noticed, but the "Register Write" column should have correct data in it, shouldn't it?

Wuerfel_21

Actually documented the XORO32 algorithm... @"Jeff Martin" can feel free to copy it: https://p2docs.github.io/alu.html#xoro32

I think the verbiage about D=0 being an undesirable state could be clearer.

TonyB_

@Wuerfel_21 said:
Actually documented the XORO32 algorithm... @"Jeff Martin" can feel free to copy it: https://p2docs.github.io/alu.html#xoro32

I think the verbiage about D=0 being an undesirable state could be clearer.

Info about XORO32:

• The pseudo-random number generator (PRNG) algorithm is xoroshire32++ which has a 32-bit state and a 16-bit result.
• XORO32 does a double iteration of xoroshire32++ to generate a 32-bit result.
• The low word of the result comes from the first iteration, the high word from the second.
• The 32-bit PRN result is put into the S field of the instruction after XORO32.
• D is the 32-bit state and must be preserved between XORO32 instructions, otherwise PRN values will be skipped and randomness reduced.
• The state after the second xoroshire32+ iteration is written back to D; the intermediate state after the first is not available to the user.
• The initial state can be any non-zero value.
• The PRN sequence repeats after 2^32-1 XORO32 instructions. xoroshiro32++ results repeat after 2^32-1 iterations. There are two xoroshiro32++ sequences in the XORO32 sequence with the 16-bit result for each state occurring twice, first in the low word and then in the high word or vice-versa.
• Any arbitrary group of bits entirely within the low or high word of the PRN result has almost perfect equidistribution: all possible values occur with frequency of all non-zero values the same and one more than frequency of all zeroes.
• 32-bit PRN results do not have equidistribution. Instead of all non-zero values occuring only once, some occur two or more times and others never. The actual distribution is close to the binomial distribution that would be produced by a true 32-bit PRNG with 32-bit state. For example, the number of different 32-bit values that occur once is the the same (almost) as the number of values that never occur (1/e or 36.8%).

I think a PASM2 version of the algorithm could be included.

Wuerfel_21

Most of those points are covered, aren't they? The info about the value distribution is surely useful. Will have to integrate that. Just got mostly done with all the CORDIC stuff: https://p2docs.github.io/cordic.html

Wuerfel_21

Maffs.

Maciek

@Wuerfel_21
totally off topic here and probably weird as hell but I couldn't resist...

Is she holding the Edge or wearing it ?

My brain is obviously defunct and it starts to show

Wuerfel_21

@Maciek said:
@Wuerfel_21
totally off topic here and probably weird as hell but I couldn't resist...

Is she holding the Edge or wearing it ?

My brain is obviously defunct and it starts to show

Well, "holding" would require articulated fingers. She kinda just has it on her lap. How would you wear an edge?

Also, don't worry, my brain is as full of plush filling as hers is.

Maciek

Right.
It's the eyes then and not only the brain.

I was just looking at the miniature picture and out of the blue the question popped up.
I thought maybe she wears the Edge as a womens purse or a hanbag.

How would you wear an edge?

Intersting question. I'll give it some thought but don't count on the answer.

Great job on the p2docs site ! (a bit of understatement, I know)

Wuerfel_21

@Rayman can you make a version of this diagram with transparent background?

Wuerfel_21

Preliminary entries for SKIPF, REP and friends written: https://p2docs.github.io/branch.html#skipf

TonyB_

@Wuerfel_21 said:
Preliminary entries for SKIPF, REP and friends written: https://p2docs.github.io/branch.html#skipf

Spelling/grammar:
cannot (one word)
corresponds
different from (not to)
is not (not is'nt)

General comment:
Define S and D as Source and Destination at top, then use S and D thereafter to avoid longwinded text. E.g. "based on the bit pattern loaded from Destination" could be simply "based on the bit pattern in D."

SKIP:

Suggest changing

The skipping continues normally after branches, but any subroutine call (or interrupt) will “suspend” the SKIP function and it will resume only after a return instruction. This also works with nested calls. However, any subroutine called while a SKIP sequence is suspended can not use SKIP/SKIPF itself

to

Skipping continues after jump instructions and the same skip pattern applies whether or not a conditional jump is made. A call instruction suspends skipping until after the corresponding return instruction. Nested calls are allowed up to a level of eight, matching the size of the hardware stack. A routine called from a skip sequence and any subroutines it calls consume only one skip bit. A SKIP/SKIPF/EXECF within the routine destroys the original skip sequence and starts a new one, which provides a way of ending skipping earlier than normal but otherwise should be avoided.

More later.

Wuerfel_21

@TonyB_ said:

@Wuerfel_21 said:
Preliminary entries for SKIPF, REP and friends written: https://p2docs.github.io/branch.html#skipf

Spelling/grammar:
cannot (one word)
corresponds
different from (not to)
is not (not is'nt)

Except for the "corrosponds" misspelling (lol), I believe these are all valid grammar choices (who even says "different from"?).

General comment:
Define S and D as Source and Destination at top, then use S and D thereafter to avoid longwinded text. E.g. "based on the bit pattern loaded from Destination" could be simply "based on the bit pattern in D."

Yeah, currently using Destination with the bold D. Jeff uses "Dest" and I've actually manually changed that in all the text that I've adapted from the official doc. But I'm kinda undecided, so I might change it afterall (to either Dest/Src or D/S - which do you think is better?)

SKIP:

Suggest changing

The skipping continues normally after branches, but any subroutine call (or interrupt) will “suspend” the SKIP function and it will resume only after a return instruction. This also works with nested calls. However, any subroutine called while a SKIP sequence is suspended can not use SKIP/SKIPF itself

to

Skipping continues after jump instructions and the same skip pattern applies whether or not a conditional jump is made. A call instruction suspends skipping until after the corresponding return instruction. Nested calls are allowed up to a level of eight, matching the size of the hardware stack. A routine called from a skip sequence and any subroutines it calls consume only one skip bit. A SKIP/SKIPF/EXECF within the routine destroys the original skip sequence and starts a new one, which provides a way of ending skipping earlier than normal but otherwise should be avoided.

A SKIP/SKIPF/EXECF within the routine destroys the original skip sequence and starts a new one, which provides a way of ending skipping earlier than normal but otherwise should be avoided.

Are you sure / have verified that's actually what happens? Also, I think "destroys" should be "replaces" for clarity.

Anyways, thank you very much, will apply changes later (got to bathe lol)

Electrodude

@Wuerfel_21 said:

@TonyB_ said:

@Wuerfel_21 said:
Preliminary entries for SKIPF, REP and friends written: https://p2docs.github.io/branch.html#skipf

Spelling/grammar:
cannot (one word)
corresponds
different from (not to)
is not (not is'nt)

Except for the "corrosponds" misspelling (lol), I believe these are all valid grammar choices (who even says "different from"?).

"Can not" has a different logical meaning that's almost never what you actually want - that it's possible for the predicate to not be the case, as opposed to "cannot", which means the predicate can never be the case. So your sentence "The first instruction after SKIPF can not be fast-skipped." means the option exists to not fast-skip it, but it is in fact impossible to fast-skip the first instruction. See here: https://faculty.math.illinois.edu/~west/grammar.html#cannot

"Different from" is the correct wording: https://faculty.math.illinois.edu/~west/grammar.html#differentthan

I've found that page to be a great reference for technical writing in general. It covers lots of things normal grammar guides don't, like how to deal with mathematical expressions inside sentences.

Mickster

Q: How many grammar nazis does it take to change a light bulb?

A: Too

JRoark

@Electrodude That website is a goldmine for folks like me. Thanks for that.
@Mickster Pssst! “Nazis” should be capitalized. Just sayin’… 🤣