When to use modify() vs write()?

[wpd]

Great! I'll start the first discussion!
I am working through the examples in your book and am currently on chapter 8, "LEDs Again". I appreciate how much of the work in that chapter you left as an "exercise to the reader", even if I might have grumbled a bit trying to figure out how to figure out what I needed to do. But eventually, I got there, and I lit all 8 LEDs. :-)

But I noticed that my solution differed from yours in one significant detail... I called gpioe.moder.write() where you called gpioe.moder.modify(). Reading the discussion in The Embedded Rust Book about the modify(), function, I see "If we wish to change only one particular sub-field in this register and leave the other sub-fields unchanged, we can use the modify function." That explains why you chose the modify() function. But I would have naively assumed that a statement of the form:

rcc.ahbenr.write(|w| w.iopeen().set_bit());

would have implicitly read the AHBENR register and only manipulated the IOPEEN bit. I notice that you called write() when you turned the LEDs on.

When/why should I use the modify() API when accessing a register field directly (such as via iopeen(), moder8(), or odr11()) vs using the write() API? Or (to be blunt :-) ) why were you inconsistent in your use of the two API functions?

--wpd

[adamgreig]

Thanks for starting the first discussion!

The read/modify/write methods are documented on svd2rust, but the gist is:

• write() starts from the register's reset value (which might not be zero), then changes just the fields you specify, and writes the result
• modify() starts with a read of the register, then changes the fields you specify and writes the result
• the lesser-used write_with_zero() starts from 0, changes your fields, writes.

So, whenever you only want to change a few fields, you have to use modify(), otherwise you'll wipe out any changes to the other fields.

In the book's case, it's fine to use write() since we are happy to set all the other pins (0-7) to 0 and just turn on 8-15. Since the chip powers up with all those pins set to 0 anyway, using modify() would have the same effect, and might be less confusing to the reader...

Later, if you're just changing a single pin, using write() would turn off all the pins you're not turning on, which probably isn't what you want.

[wpd]

Thanks for the explanation, and especially for the pointer to svd2rust. (Aside, I wish I had found that when I was working through the chapter 8 example.) That will take some getting-used-to on my part, but now I see where you're coming from. I was focusing on the iopeen() part of the statement and not on the write() part of the statement. So I was thinking that I would only be fiddling with the IOPEEN field in the register. You're explanation makes perfect sense. Hopefully I'll internalize it so as to avoid shooting myself in the foot later. Wish me luck! :-)

--wpd