Explain UnsafeCell and Interior Mutability

[RalfJung]

It seems to be a reoccurring pattern that people are confused about UnsafeCell and interior mutability, what it does, when they need it and when they don't. And this kind of stuff fits squarely in the scope of the Nomicon, so it'd be great to have some material on that!

In particular, one point of confusion seems to be about shared mutability with raw pointers (see e.g. this forum thread): People read "you need UnsafeCell whenever you mutate data behind a shared reference", and then generalize this to "whenever you mutate shared data" and think that they might need UnsafeCell even when the data they mutate is just behind a *mut T. We should point out somewhere that mutating behind a &*mut T is not in contradiction with any aliasing assumptions made by the compiler.

[andre-richter]

Hi @RalfJung,

Google led me here when I tried to resolve comprehension issues I currently have regarding creation of *mut T in a bare metal context.
I hope it is okay to hijack this issue, maybe it will help others who are also landing here while googling?

What I am trying to understand is: What is a canonical way of creating an *mut T in the following case. My objective is zeroing the bss range while I boot an OS kernel. To know the boundaries of bss, I export two symbols through the kernel's linker script.

Then, I take the symbols and create two *mut T.

Eventually, those will written to by core::ptr::write_volatile() once during boot, when only a single CPU core is online and IRQs are disabled.
Is this UB, because I created *mut T from &T and mutated it through write_volatile()?

Is a more correct way to do it something like this?:

extern "C" {
    static __bss_start: UnsafeCell<u64>;
    static __bss_end: UnsafeCell<u64>;
}

pub fn bss_range() -> Range<*mut u64> {
    unsafe {
        Range {
            start: __bss_start.get(),
            end: __bss_end.get(),
        }
    }
}

Thanks,
Andre

[RalfJung]

@andre-richter we don't usually use Nomicon threads for such support questions -- in the future, asking on Zulip or the UCG repo is probably better. But it's fine, I know all these repos we have can be confusing. :)

You used UnsafeCell::get to go from &UnsafeCell<u64> to *mut u64, so this seems just fine in terms of mutation. I am confused by this sentence:

Is this UB, because I created *mut T from &T and mutated it through write_volatile()?

If you did that (with the same T) it would be UB. But I don't think you did that. Specifically, what is T here? There is no &u64, just an &UnsafeCell<u64>, right? You created *mut T from &U, but since U = UnsafeCell<T> that is fine. That is exactly what UnsafeCell::get is for.

Note however that you should probably use UnsafeCell<()> for the __bss_* symbols -- u64 is 8 bytes in size, but if I understand you correctly, then there are not actually 8 bytes of usable memory starting at __bss_end.

[andre-richter]

Hi Ralf,

I am confused by this sentence:

Is this UB, because I created *mut T from &T and mutated it through write_volatile()?

This sentence was meant for the way I am currently doing it:

extern "C" {
    static __bss_start: usize;
    static __bss_end: usize;
}

pub fn bss_range() -> Range<*mut u64> {
    unsafe {
        Range {
            start: &__bss_start as *const _ as *mut u64,
            end: &__bss_end as *const _ as *mut u64,
        }
    }
}

I am preparing to switch to the UnsafeCell<> code at the moment, and wanted to check first if this is aligned with how it's supposed to be used.

Note however that you should probably use UnsafeCell<()> for the _bss* symbols -- u64 is 8 bytes in size, but if I understand you correctly, then there are not actually 8 bytes of usable memory starting at __bss_end.

Its true that there is no usable memory at the bss symbols. We can and must only use the addresses of the symbols, never the data. So I thought it doesn't matter what type of data we pretend living there, since we anyways must never use it.

The unit type () really seems more idiomatic to use in this case. Thanks for the hint, I'll incorporate it.

Thanks a lot,
Andre

[RalfJung]

This sentence was meant for the way I am currently doing it:

Oh I see -- yeah that is UB.

Its true that there is no usable memory at the bss symbols. We can and must only use the addresses of the symbols, never the data. So I thought it doesn't matter what type of data we pretend living there, since we anyways must never use it.

The rules for this are not fully settled yet, but I think it would be reasonable to require that a static is at least as big as the type it is given indicates, no matter how it is used.