Neywiny
Posts: 11
Joined: Thu Jan 23, 2020 9:57 pm

Oddities in PIO section of manual

Thu Jan 21, 2021 7:52 pm

I've been reading the datasheet on the PIO and I see that on page 339 it says
PULL IFEMPTY is useful if an OUT with autopull would stall in an inappropriate location when the TX FIFO is empty. For
example, a UART transmitter should not stall immediately after asserting the start bit. IfEmpty permits some of the same
program simplifications as autopull, but the stall occurs at a controlled point in the program.
But that doesn't really make sense. I would want as follows:
  1. wait for TX FIFO data
  2. assert a 0 on TX line (start bit)
  3. shift out data
  4. assert a 1 on TX line (stop bit)
Why would I use IFEMPTY for that instead of BLOCK?

So I headed to the examples, and found the UART TX example code on page 361, which has

Code: Select all

 
 7 .program uart_tx
 8 .side_set 1 opt
 9
10 ; An 8n1 UART transmit program.
11 ; OUT pin 0 and side-set pin 0 are both mapped to UART TX pin.
12
13 pull side 1 [7] ; Assert stop bit, or stall with line in idle state
14 set x, 7 side 0 [7] ; Preload bit counter, assert start bit for 8 clocks
15 bitloop: ; This loop will run 8 times (8n1 UART)
16 out pins, 1 ; Shift 1 bit from OSR to the first OUT pin
17 jmp x-- bitloop [6] ; Each loop iteration is 8 cycles.
(side note, pull blocks by default, so it's blocking here)

Which is, you know, exactly what I thought it would be except for no outer jump back to the start. Note it says "or stall with line in idle state" which is exactly what I would expect. Wait until there's data, when there is, shift it out. I'm sure there are a lot of great examples for IFEMPTY, but the only place I see it used is in a different example that seems like it isn't an existing peripheral interface specification. It just seems weird, is all. Why explicitly mention a use case that doesn't make sense and then not even show me how it's supposed to be used?

Another side note, the whole section seems kind of "off." On page 329 it uses a "nop [5]" instead of a "wait [5]" which is odd considering the last I read on the ISA on page 325, there was no NOP instruction (this oddity also shows up on page 355). Also on page 325 is the same example code twice and without any identifier like "example x.yz" (which would allow the text to refer to it twice without it appearing twice) and that made me think there was some difference I didn't see until I read the information on where the code was from. And on page 332 it says "Expressions may be freely (boldly?) used within pioasm values." Why include that? Why not just "Expressions may be used within pioasm values." Seems like something left in from editing. I'm more curious about the IFEMPTY thing, but those kinds of oddities in a manual with something that is, to my knowledge, an industry leading technology (programmable QSPI is common but this is a whole new level), is confusing.

EDIT:::: Some more oddities I found since making the post
  1. I was reminded when I saw again about space requirements that this section occasionally seems like it's trying to market the PIO system. This is weird. I'm not the layout person, I don't really care if things take up more or less physical die space. I don't know why it's included every now and then.
  2. The use of push/pull instead of push/pop is odd but not impossible to deal with. But in figure 44, it has a "TX Fifo Pop" line. So that's inconsistent. This inconsistency happens again at the top of page 355.

jamesh
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 30111
Joined: Sat Jul 30, 2011 7:41 pm

Re: Oddities in PIO section of manual

Thu Jan 21, 2021 9:57 pm

Thanks, been reported back the guy who designed it and wrote the docs!
Principal Software Engineer at Raspberry Pi (Trading) Ltd.
Working in the Applications Team.

Neywiny
Posts: 11
Joined: Thu Jan 23, 2020 9:57 pm

Re: Oddities in PIO section of manual

Thu Jan 21, 2021 11:05 pm

Great, thank you. What I'd give to talk to the guy. I have so many questions on specifics.

Like, why do delay timers start counting down after the blocking is done? I'd assume it'd be better to have it be the other way so things have an upper bound in normal operation (for example, if I give 16 cycles of delay, 10 could be used for the CPU to get data read in or something and 6 could be kept as a buffer).

And the index section of the IRQ instruction isn't explained very well, seems like the explanation is needlessly complicated in favour of an easier table. Is it encoded as [ relative | dummy? | IRQ #[2:0] ] ? I'm still confused on what bit 3 does.

Side-set seems really cool but it's explained so far down in the datasheet, I feel like by the time I got to it I've already kind of figured it out with much confusion along the way.

What's the deal with the blank space on page 386?

Why only 32 instructions? Is it because a 1-write/4-read memory is so complicated? Or because you needed to encode the jump address absolutely and only had space for 5 bits? answered

What advantage is there to side-set executing without waiting for blocks? (that's something that doesn't deserve to be in a manual but I'm just curious about)

Any plans for an instruction with 0b110 like IRQ but a 1 in bit 7? (again not desired in the manual, just curious if there's anything that'd be good to put there) answered

And finally, I can guess that a nop is a pseudoinstruction that gets compiled into a jump to the next address, but I'm not sure on that. Is that how it's done? answered
Last edited by Neywiny on Fri Jan 22, 2021 12:49 am, edited 1 time in total.

kilograham
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 1024
Joined: Fri Apr 12, 2019 11:00 am
Location: austin tx

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 12:34 am

I'll answer a couple
Why only 32 instructions? Is it because a 1-write/4-read memory is so complicated? Or because you needed to encode the jump address absolutely and only had space for 5 bits?
Instruction encoding space, chip area, and the fact that the instructon set is compact, you can do video data generation, video timing, and audio pwm or i2s all in 32 instructions (so one PIO)
Any plans for an instruction with 0b110 like IRQ but a 1 in bit 7?
main thing to note is those bits are reserved for future use, so be sure to set them to 0 (if you are hand-crafting instructions)
And finally, I can guess that a nop is a pseudoinstruction that gets compiled into a jump to the next address, but I'm not sure on that. Is that how it's done?
It was once a jmp to the next instruction, however that doesnt work with .,wrap, it is now mov y, y see https://github.com/raspberrypi/pico-sdk ... pes.h#L384

Neywiny
Posts: 11
Joined: Thu Jan 23, 2020 9:57 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 1:05 am

Great, thanks. All very helpful. I was unaware the toolchain was on github, that's good stuff.

andyg0808
Posts: 1
Joined: Fri Jan 22, 2021 3:42 am

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 3:54 am

Another somewhat odd line from the PIO section (page 331):
Additionally opt may be specified to indicate that a side <value> is optional for instructions (not using this requires stealing an extra bit - in addition to the <count> bits - from those available for the instruction delay).
I'm wondering if the extra bit is stolen when `code` is used, rather than when it's not used (as it currently seems to read).

(The PIO peripheral is really cool, by the way!)

User avatar
dickon
Posts: 2104
Joined: Sun Dec 09, 2012 3:54 pm
Location: Home, in Towcester

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 10:43 am

The whole PIO examples section of the datasheet is a tad more jokey than I'm used to seeing in what are normally very dry documents. A reference to I2C dating to the Dead Sea Scrolls on pp372 and the whole of 3.6.9 ('Addition') make for some light relief.
As it is apparently board policy to disallow any criticism of anything, as it appears to criticise something is to criticise all the users of that something, I will no longer be commenting in threads which are not directly relevant to my uses of the Pi.

jamesh
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 30111
Joined: Sat Jul 30, 2011 7:41 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 10:59 am

dickon wrote:
Fri Jan 22, 2021 10:43 am
The whole PIO examples section of the datasheet is a tad more jokey than I'm used to seeing in what are normally very dry documents. A reference to I2C dating to the Dead Sea Scrolls on pp372 and the whole of 3.6.9 ('Addition') make for some light relief.
After a year writing documentation, things can get that way! The whole team spent huge amounts of time on the docs for this product, sometimes the humour can escape!
Principal Software Engineer at Raspberry Pi (Trading) Ltd.
Working in the Applications Team.

User avatar
dickon
Posts: 2104
Joined: Sun Dec 09, 2012 3:54 pm
Location: Home, in Towcester

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 11:03 am

jamesh wrote:
Fri Jan 22, 2021 10:59 am
dickon wrote:
Fri Jan 22, 2021 10:43 am
The whole PIO examples section of the datasheet is a tad more jokey than I'm used to seeing in what are normally very dry documents. A reference to I2C dating to the Dead Sea Scrolls on pp372 and the whole of 3.6.9 ('Addition') make for some light relief.
After a year writing documentation, things can get that way! The whole team spent huge amounts of time on the docs for this product, sometimes the humour can escape!
It certainly looks like it. I wasn't expecting a 600+ page document when I downloaded the thing yesterday morning. Good job all round.
As it is apparently board policy to disallow any criticism of anything, as it appears to criticise something is to criticise all the users of that something, I will no longer be commenting in threads which are not directly relevant to my uses of the Pi.

jamesh
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 30111
Joined: Sat Jul 30, 2011 7:41 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 11:09 am

dickon wrote:
Fri Jan 22, 2021 11:03 am
jamesh wrote:
Fri Jan 22, 2021 10:59 am
dickon wrote:
Fri Jan 22, 2021 10:43 am
The whole PIO examples section of the datasheet is a tad more jokey than I'm used to seeing in what are normally very dry documents. A reference to I2C dating to the Dead Sea Scrolls on pp372 and the whole of 3.6.9 ('Addition') make for some light relief.
After a year writing documentation, things can get that way! The whole team spent huge amounts of time on the docs for this product, sometimes the humour can escape!
It certainly looks like it. I wasn't expecting a 600+ page document when I downloaded the thing yesterday morning. Good job all round.
Well over a thousand pages once you take all the other documents in to account.
Principal Software Engineer at Raspberry Pi (Trading) Ltd.
Working in the Applications Team.

User avatar
LukeW
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 62
Joined: Tue Jul 07, 2015 2:19 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 12:39 pm

But that doesn't really make sense. I would want as follows:

wait for TX FIFO data
assert a 0 on TX line (start bit)
shift out data
assert a 1 on TX line (stop bit)

Why would I use IFEMPTY for that instead of BLOCK?
Well the short answer is that I hadn't used that particular side set trick when I wrote the older UART example that existed at the time that part of documentation was written, and this wasn't picked up during editing :) This was at an earlier point where we didn't have datasheet examples linked to actual code which gets CI'd, and you can check out and build.

Definitely needs fixing as it's misleading. There is a bit more to it though. The older example was something like (a sketch):

Code: Select all

start:
    pull ifempty
    set x, 7 side 0
bitloop:
    out pins, 1
    jmp x-- bitloop
    jmp start set 0
And the missing context here is that that example allowed four UART bytes to be packed into a FIFO word, which requires one of

[*] An outer loop with a counter (which you may not in general have spare)
[*] Autopull with a threshold enabled
[*] Regular (non-auto) pull, but conditioned on the autopull threshold (i.e. pull ifempty)

The UART example gets lucky because you can get the stall to be effectively after the side set due to how side set operates, so you can use the regular stalling of out with autopull. This doesn't work if you need the stall to be hoisted even one instruction higher, which is the reason pull ifempty still exists at all in the final hardware, even though most of its use cases are now covered by autopull.

Thank you for the feedback, it's really easy to develop blindspots when you work on the docs and hardware for too long (like nop never being explicitly called out as a pseudoinstruction, except for in a tutorial in the SDK book).

User avatar
LukeW
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 62
Joined: Tue Jul 07, 2015 2:19 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 12:53 pm

Also on page 325 is the same example code twice and without any identifier like "example x.yz" (which would allow the text to refer to it twice without it appearing twice)
Good point, doesn't flow well and as you say causes unnecessary confusion. Will caption the first instance and replace the second with a reference to it.
The use of push/pull instead of push/pop is odd but not impossible to deal with. But in figure 44, it has a "TX Fifo Pop" line. So that's inconsistent. This inconsistency happens again at the top of page 355.
Thank you, text is fixed, will get the diagram reexported. (the port name on our standard FIFO implementation is called pop, this probably leaked through my brain)
Side-set seems really cool but it's explained so far down in the datasheet, I feel like by the time I got to it I've already kind of figured it out with much confusion along the way.
Yes think it is worth introducing this earlier on. There is also a chapter in the SDK book that flows better in this regard -- we need to work on discoverability though.
but those kinds of oddities in a manual with something that is, to my knowledge, an industry leading technology (programmable QSPI is common but this is a whole new level), is confusing.
Agreed, the documentation is the most important part, thank you for helping to improve it.

Neywiny
Posts: 11
Joined: Thu Jan 23, 2020 9:57 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 3:07 pm

jamesh wrote:
Fri Jan 22, 2021 11:09 am
dickon wrote:
Fri Jan 22, 2021 11:03 am
It certainly looks like it. I wasn't expecting a 600+ page document when I downloaded the thing yesterday morning. Good job all round.
Well over a thousand pages once you take all the other documents in to account.
I'm kind of a datasheet junkie so honestly seeing it was only 636 pages of datasheet and reference manual combined instead of the ~3.5k I'm used to was a bit relieving. The chip is certainly much more similar to the ATMEGA328p than something like the i.MX 1060 in the Teensy 4, but I think that's a good thing. I've noticed some rpi users not even really understand what a microcontroller should be used for, so an easy entry is good.

I think I'm still a tad confused on the UART example, but it makes sense if I switch the "jmp start" side-set to a 1 for the stop bit. But the point that there is a way to use ifempty here gets across. I think what would be really helpful for me is to see more things like figure 44, maybe with a "need to pull" signal, but that's just me and my fascination with the UART example.
LukeW wrote:
Fri Jan 22, 2021 12:39 pm
which is the reason pull ifempty still exists at all in the final hardware, even though most of its use cases are now covered by autopull.
That makes a lot of sense. I noticed that ifempty seems like something that would be very rarely used. Might be useful for explaining autopull in a tutorial, but who knows.
LukeW wrote:
Fri Jan 22, 2021 12:39 pm
Thank you for the feedback, it's really easy to develop blindspots when you work on the docs and hardware for too long (like nop never being explicitly called out as a pseudoinstruction, except for in a tutorial in the SDK book).
You're very welcome. If I find time I can go over the whole manual, but frankly the PIO was what interested me. Maybe if the foundation sought to compensate me as a technical editor. I saw that this chip has been in development since 2016, so I can only imagine that after 4+ years it's hard to remember what is or isn't common sense. I feel that way after only a few months.

I do stand minorly corrected on "industry leading technology" though as there are other companies making uC's with similar functionality. But nothing that's as mainstream as this is at launch even after they've been around for years. And those are usually glorified shift registers, which a SPI module could be used for anyway.

I really do appreciate the willingness to accept the criticism. Other companies and even other engineers would/have not been as kind.

jamesh
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 30111
Joined: Sat Jul 30, 2011 7:41 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 3:44 pm

Neywiny wrote:
Fri Jan 22, 2021 3:07 pm
I really do appreciate the willingness to accept the criticism. Other companies and even other engineers would/have not been as kind.
We want the documentation to be best in class, in accuracy, ease of reading, and actually teaching people how to use the device, so all thoughts are welcome!
Principal Software Engineer at Raspberry Pi (Trading) Ltd.
Working in the Applications Team.

User avatar
MikeDB
Posts: 717
Joined: Sun Oct 12, 2014 8:27 am
Contact: Website

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 4:45 pm

jamesh wrote:
Fri Jan 22, 2021 3:44 pm
Neywiny wrote:
Fri Jan 22, 2021 3:07 pm
I really do appreciate the willingness to accept the criticism. Other companies and even other engineers would/have not been as kind.
We want the documentation to be best in class, in accuracy, ease of reading, and actually teaching people how to use the device, so all thoughts are welcome!
Well should you ever want an example on how NOT to do it, look up one of the competing STMicroelectronics ARM M0+ MCUs like the STM32G series. You're definitely well ahead on the documentation front !

And of course their CubeIDE 'programming' system and HAL libraries are definitely not for the faint-hearted ! Takes newcomers several days just to get a led flashing.
Always interested in innovative audio startups needing help and investment. Find me on our website.

Neywiny
Posts: 11
Joined: Thu Jan 23, 2020 9:57 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 6:56 pm

MikeDB wrote:
Fri Jan 22, 2021 4:45 pm
Well should you ever want an example on how NOT to do it, look up one of the competing STMicroelectronics ARM M0+ MCUs like the STM32G series. You're definitely well ahead on the documentation front !

And of course their CubeIDE 'programming' system and HAL libraries are definitely not for the faint-hearted ! Takes newcomers several days just to get a led flashing.
(small pedantic note, you mean the STM32G0 series, the STM32G4 is an M4F)
<rant>
All things considered, the STM32 manuals take some getting used to but after you learn their language, they're quite simple. There are a few things I'm not a fan of, sure, but compared to some others, it's good. One of the things I like about the EP2040 datasheet that ST doesn't do is including the base registers in the section on the registers. But on the other hand we have things like page 616, which says 0x60 is DR0, the first of 36 registers. ST would say something like: DRx is at "0x60 + 0x4*x, (x = 1 to 36)" which is still one line, but is just slightly more informative. Sure you can notice the next register is at 0xF0, which is 36 32-bit words after 0x60 indicating they're packed together, but why not just put that little bit of extra detail? Maybe it's because I've read more of ST's manuals than I've read of other companies, but I really like them.

A better example might be the DMA. RP2040 puts "CH0_READ_ADDR, CH1_READ_ADDR, …, CH10_READ_ADDR, CH11_READ_ADDR Registers" then "Offsets: 0x000, 0x040, …, 0x280, 0x2c0" for the READ_ADDR registers. Why not just "CHN_READ_ADDR" and "0x000 + 0x40*N (N = 0 to 11)?" Or even better, N ∈ [0, 11]. When I'm programming these peripherals and I want to know something specific like that, I don't want to have to figure out the formula for myself. Often times I'll have a mental note of which channels I've used and think "ok I want channel 6" in the ST way, I can just plug that in. In the RP2040 way, I have to think "ok 0x40 - 0x00 is 0x40, so it's incrementing by 40, and we're starting at 0, so I want 0x40 * 6" and no it's not going to frustrate me greatly, but it'll just be another minor annoyance.

I think my gripes come down to: If you've already done the work of writing the docs, why not just give me the data I need to get the job done? Which is exactly why I hate ST not putting in the base registers, but overall they're good about that.
</rant>

As a side note, I'm very confused on why the DMA channels' CTRL_TRIG registers are all broken out differently for each channel instead of grouped like READ_ADDR and the like. The only difference I can find in the registers is the reset value of the CHAIN_TO, but if you generalize it to just be N, you'd save something like 25 pages. Unless there's another difference I'm not seeing.

jamesh
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 30111
Joined: Sat Jul 30, 2011 7:41 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 8:25 pm

Neywiny wrote:
Fri Jan 22, 2021 6:56 pm
MikeDB wrote:
Fri Jan 22, 2021 4:45 pm
Well should you ever want an example on how NOT to do it, look up one of the competing STMicroelectronics ARM M0+ MCUs like the STM32G series. You're definitely well ahead on the documentation front !

And of course their CubeIDE 'programming' system and HAL libraries are definitely not for the faint-hearted ! Takes newcomers several days just to get a led flashing.
(small pedantic note, you mean the STM32G0 series, the STM32G4 is an M4F)
<rant>
All things considered, the STM32 manuals take some getting used to but after you learn their language, they're quite simple. There are a few things I'm not a fan of, sure, but compared to some others, it's good. One of the things I like about the EP2040 datasheet that ST doesn't do is including the base registers in the section on the registers. But on the other hand we have things like page 616, which says 0x60 is DR0, the first of 36 registers. ST would say something like: DRx is at "0x60 + 0x4*x, (x = 1 to 36)" which is still one line, but is just slightly more informative. Sure you can notice the next register is at 0xF0, which is 36 32-bit words after 0x60 indicating they're packed together, but why not just put that little bit of extra detail? Maybe it's because I've read more of ST's manuals than I've read of other companies, but I really like them.

A better example might be the DMA. RP2040 puts "CH0_READ_ADDR, CH1_READ_ADDR, …, CH10_READ_ADDR, CH11_READ_ADDR Registers" then "Offsets: 0x000, 0x040, …, 0x280, 0x2c0" for the READ_ADDR registers. Why not just "CHN_READ_ADDR" and "0x000 + 0x40*N (N = 0 to 11)?" Or even better, N ∈ [0, 11]. When I'm programming these peripherals and I want to know something specific like that, I don't want to have to figure out the formula for myself. Often times I'll have a mental note of which channels I've used and think "ok I want channel 6" in the ST way, I can just plug that in. In the RP2040 way, I have to think "ok 0x40 - 0x00 is 0x40, so it's incrementing by 40, and we're starting at 0, so I want 0x40 * 6" and no it's not going to frustrate me greatly, but it'll just be another minor annoyance.

I think my gripes come down to: If you've already done the work of writing the docs, why not just give me the data I need to get the job done? Which is exactly why I hate ST not putting in the base registers, but overall they're good about that.
</rant>

As a side note, I'm very confused on why the DMA channels' CTRL_TRIG registers are all broken out differently for each channel instead of grouped like READ_ADDR and the like. The only difference I can find in the registers is the reset value of the CHAIN_TO, but if you generalize it to just be N, you'd save something like 25 pages. Unless there's another difference I'm not seeing.
The SDK abstracts all this away for you, and is very well optimised. There's really no need to poke registers directly.
Principal Software Engineer at Raspberry Pi (Trading) Ltd.
Working in the Applications Team.

Neywiny
Posts: 11
Joined: Thu Jan 23, 2020 9:57 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 9:33 pm

That's an unexpected answer to say the least. Primarily because I thought we were on the same page with wanting the best and easiest to use documentation possible. But also because having seen what the HAL did for ST, where it's taken as gospel and suffers from it, I'm wary. When I read an ST datasheet and it says to just trust the HAL and the IDE to calculate everything right, that's a red flag. And then when it doesn't work, I'm just stuck. I get that the HAL covers a lot more chips than the SDK, but I'm assuming there will be more RP chips, and mistakes will happen just like they happen for bigger companies with more experience. I'd rather feel confident knowing that I can get things working even if there are bugs in the SDK. Might just be a me thing. I can speak only for myself.

cleverca22
Posts: 4897
Joined: Sat Aug 18, 2012 2:33 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 10:01 pm

jamesh wrote:
Fri Jan 22, 2021 11:09 am
dickon wrote:
Fri Jan 22, 2021 11:03 am
It certainly looks like it. I wasn't expecting a 600+ page document when I downloaded the thing yesterday morning. Good job all round.
Well over a thousand pages once you take all the other documents in to account.
thats the kind of documentation ive been wanting from pi products!

i'm guessing the bcm chips arent getting it due to a combination of broadcom saying no, and that your not planning to sell the chip bare, so very few people need that much detail, and then no point in investing time into writing them and filtering the sensitive stuff out

the RP2040 docs are so detailed that its obvious the chip will be sold bare in the future, and users can just make their own PCB for it

jdb
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 2656
Joined: Thu Jul 11, 2013 2:37 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 10:14 pm

Neywiny wrote:
Fri Jan 22, 2021 9:33 pm
That's an unexpected answer to say the least. Primarily because I thought we were on the same page with wanting the best and easiest to use documentation possible. But also because having seen what the HAL did for ST, where it's taken as gospel and suffers from it, I'm wary. When I read an ST datasheet and it says to just trust the HAL and the IDE to calculate everything right, that's a red flag. And then when it doesn't work, I'm just stuck. I get that the HAL covers a lot more chips than the SDK, but I'm assuming there will be more RP chips, and mistakes will happen just like they happen for bigger companies with more experience. I'd rather feel confident knowing that I can get things working even if there are bugs in the SDK. Might just be a me thing. I can speak only for myself.
The SDK and canned examples (available on day 0) are for the singular purpose of making the on-ramp to developing with RP2040 as gentle as possible. This is the part of the product that needs the most battle-testing. You, as an early adopter, are going to trip over all the bugs first.

If you find an instance where the datasheet describing the chip does one thing, and your code can provoke it into doing a different thing, then please raise an issue on Github in the appropriate place.
Rockets are loud.
https://astro-pi.org

jamesh
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 30111
Joined: Sat Jul 30, 2011 7:41 pm

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 11:01 pm

Neywiny wrote:
Fri Jan 22, 2021 9:33 pm
That's an unexpected answer to say the least. Primarily because I thought we were on the same page with wanting the best and easiest to use documentation possible. But also because having seen what the HAL did for ST, where it's taken as gospel and suffers from it, I'm wary. When I read an ST datasheet and it says to just trust the HAL and the IDE to calculate everything right, that's a red flag. And then when it doesn't work, I'm just stuck. I get that the HAL covers a lot more chips than the SDK, but I'm assuming there will be more RP chips, and mistakes will happen just like they happen for bigger companies with more experience. I'd rather feel confident knowing that I can get things working even if there are bugs in the SDK. Might just be a me thing. I can speak only for myself.
You don't need to use the SDK, all the register descriptions are also documented. But as I said, you really should have no need to use direct register access, although its obviously very easy to do so. Just not as easy as using the SDK. The functions are VERY simply wrappers that mean you don't have to know all the stuff you posted about in your first post.

Just to explain how to docs works - all the register description stuff is auto generated from the chip design files, so that's where all the naming comes from. That's why you don't get the sort of *N stuff you mentioned, that would require human intervention to add, with the associated increased workloads and possibility of error.
Principal Software Engineer at Raspberry Pi (Trading) Ltd.
Working in the Applications Team.

User avatar
MikeDB
Posts: 717
Joined: Sun Oct 12, 2014 8:27 am
Contact: Website

Re: Oddities in PIO section of manual

Fri Jan 22, 2021 11:57 pm

jamesh wrote:
Fri Jan 22, 2021 8:25 pm
The SDK abstracts all this away for you, and is very well optimised. There's really no need to poke registers directly.
Well I'll give it a go. But I've been poking STM32 registers for years as the alternative of using HAL is just too horrendous to contemplate.
Always interested in innovative audio startups needing help and investment. Find me on our website.

Neywiny
Posts: 11
Joined: Thu Jan 23, 2020 9:57 pm

Re: Oddities in PIO section of manual

Sun Jan 24, 2021 12:57 am

MikeDB wrote:
Fri Jan 22, 2021 11:57 pm
jamesh wrote:
Fri Jan 22, 2021 8:25 pm
The SDK abstracts all this away for you, and is very well optimised. There's really no need to poke registers directly.
Well I'll give it a go. But I've been poking STM32 registers for years as the alternative of using HAL is just too horrendous to contemplate.
Yeah, big agreement on this. Sure there are times when the HAL is nice, but then there's times where it's stuck in an infinite loop or something and I have to debug like 16 functions deep just to find out what's going on. And it seems most of the SDK is done as inline functions, but that can still be a rabbit hole. And from what I've seen of the SDK, it doesn't support 10-bit I2C and doesn't tell the user that in the docs, they'd just have to wait for the compilation warning. So unless I'm missing something with the "invalid_params_if(I2C, addr >= 0x80); // 7-bit addresses" lines, that's just odd. That's the vibe I get from all of this. Odd. Different is one thing, but that's odd.
jamesh wrote: Just to explain how to docs works - all the register description stuff is auto generated from the chip design files, so that's where all the naming comes from. That's why you don't get the sort of *N stuff you mentioned, that would require human intervention to add, with the associated increased workloads and possibility of error.
Fair enough, I've not used autodocs like these but I can extrapolate. NXP decided, at least for the chip on the teensy 4, to put the reset values as a table elsewhere (IMXRT1060RM REV. 1, page 153) for some of their eDMA things, but then information becomes split even though it's right after the register description. Would cut the datasheet by ~4% though if it can be done with the current toolchain.

hippy
Posts: 10901
Joined: Fri Sep 09, 2011 10:34 pm
Location: UK

Re: Oddities in PIO section of manual

Fri Feb 12, 2021 2:47 am

andyg0808 wrote:
Fri Jan 22, 2021 3:54 am
Another somewhat odd line from the PIO section (page 331):
Additionally opt may be specified to indicate that a side <value> is optional for instructions (not using this requires stealing an extra bit - in addition to the <count> bits - from those available for the instruction delay).
I'm wondering if the extra bit is stolen when `code` is used, rather than when it's not used (as it currently seems to read).
It took me a while to figure out what that fully meant. It's basically describing the format of the five bit Delay/Side-Set field in every instruction whose format depends on how many side-sets are used and whether optional or not.

When there are no side-set pins used -

Code: Select all

.-------------------.
| d   d   d   d   d |  No side-set pins, delay can be 0 to 31
`-------------------'
When side-sets are specified as optional the msb of the field is used as a flag to indicate if the instruction side-set should be executed or not. This is the bit which is 'stolen' from the field -

Code: Select all

.---.---.-----------.
| f | s | d   d   d |  1 side-set pin,  delay can be 0 to 7
|---|---^---.-------|
| f | s   s | d   d |  2 side-set pins, delay can be 0 to 3
|---|-------^---.---|
| f | s   s   s | d |  3 side-set pins, delay can be 0 or 1
|---|-----------^---|
| f | s   s   s   s |  4 side-set pins, delay not allowed
`---^---------------'
When the side-set is not optional, and every opcode must specify a side-set, there is no need to have a flag bit to indicate whether an opcode will or will not do a side-set and the full five bits can be used for side-set and delay -

Code: Select all

.---.---------------.
| s | d   d   d   d |  1 side-set pin,  delay can be 0 to 15
|---^---.-----------|
| s   s | d   d   d |  2 side-set pins, delay can be 0 to 7
|-------^---.-------|
| s   s   s | d   d |  3 side-set pins, delay can be 0 to 3
|-----------^---.---|
| s   s   s   s | d |  4 side-set pins, delay can be 0 or 1
|---------------^---|
| s   s   s   s   s |  5 side-set pins, delay not allowed
`-------------------'
So, if you need to maximise the number of side-set pins and use the largest delay possible; the side-set needs to be non-optional but that does of course mean having to specify a side-set for every instruction.

hippy
Posts: 10901
Joined: Fri Sep 09, 2011 10:34 pm
Location: UK

Re: Oddities in PIO section of manual

Fri Feb 12, 2021 3:07 am

Neywiny wrote:
Thu Jan 21, 2021 11:05 pm
And the index section of the IRQ instruction isn't explained very well, seems like the explanation is needlessly complicated in favour of an easier table. Is it encoded as [ relative | dummy? | IRQ #[2:0] ] ? I'm still confused on what bit 3 does.
Indeed. Encoding and decoding "IRQ" and "WAIT IRQ" instructions are what I am really struggling with. I can't make head nor tail of it and it doesn't help that I can't get 'pioasm' to accept a 'rel' specification.

If it wasn't for that my own Assembler and Disassembler would be finished by now. I'll have to see if the Sleep Pixies leave any enlightenment.

Return to “General”