uma: Hide 'uma_align_cache'; Create/rename accessors

[olce]

Summary

Create the uma_get_cache_align_mask() accessor and put it in a separate
header so as to minimize namespace pollution in header/source files that
need only this function and not the whole 'uma.h' header.

Make sure the accessors have '_mask' as a suffix, so that callers are
aware that the real alignment is the power of two that is the mask plus
one. Rename the stem to something more explicit. Rename
uma_set_cache_align_mask()'s single parameter to 'mask'.

Hide 'uma_align_cache' to ensure that it cannot be set in any other way
then by a call to uma_set_cache_align_mask(), which will perform sanity
checks in a further commit. While here, rename it to
'uma_cache_align_mask'.

This is also in preparation for some further changes, such as improving
the sanity checks, eliminating internal resolving of UMA_ALIGN_CACHE and
changing the type of the 'uma_cache_align_mask' variable.

MFC after: 2 weeks
Sponsored by: The FreeBSD Foundation

[markj]

sys/compat/linuxkpi/common/include/linux/dma-mapping.h

354

You can't include uma.h in this file?

sys/vm/uma.h

490

Is __pure really appropriate, given that the return value can be modified by a call to uma_set_cache_align_mask()?

[olce]

sys/compat/linuxkpi/common/include/linux/dma-mapping.h

354

I didn't even try, because I suspect that the intention of the original code was to minimize namespace pollution, since these are Linux headers.

Should I go ahead regardless?

sys/vm/uma.h

490

I think so because uma_cache_align_mask is supposed to be set early at boot, before any reads (now, calls to uma_get_cache_align_mask()).

Note that, in this series, I've not changed the fact that uma_cache_align_mask is initialized to 64-1 for all architectures and then overriden at boot for arm only, and that there are no checks enforcing the access flow I've just described.

But this change also opens up the possibility to implement such a scheme. We could initialize uma_cache_align_mask to some sentinel invalid value, forcing each architecture to issue a call to uma_set_cache_align_mask(). This way, we could then enforce the value was correctly initialized in uma_get_cache_align_mask(). Not sure if it's worth it but now it is possible.

[markj]

sys/compat/linuxkpi/common/include/linux/dma-mapping.h

354

I suppose it's better to avoid the pollution, ok.

[kib]

sys/compat/linuxkpi/common/include/linux/dma-mapping.h

354

Best is to create a new header for this prototype, included from dma-mapping.h and uma.h.

sys/vm/uma.h

490

It seems pure is fine but const would be not.

[olce]

Put uma_get_cache_align_mask() in its own header.

[kib]

sys/vm/_uma_align_mask.h

36

I think leaving just this sentence as a comment, and moving it to the place where the function is provided (as we usually do with herald commit) would be much more concise and faster to read.

sys/vm/uma.h

484

This is too trivial to explain.

Also, this header is supposed to be used by external consumers, right? Then I propose to name it vm/uma_align_mask.h, it is not internal.

[olce]

sys/vm/_uma_align_mask.h

36

I just moved what was in uma.h without touching anything else. Going to change that as requested.

sys/vm/uma.h

484

Not sure what "external consumers" are. External to UMA, yes. But internal to the kernel, yes again.

The only real reason I used the _ prefix is because the header uses __pure, which requires sys/cdefs.h, and I didn't bother to put the corresponding #include in the new header since the two including files already pull that one.

Do you advise to add #include <sys/cdefs.h>, or shall I assume it is always included by including files?

[olce]

Change comments as requested.

[kib]

sys/vm/uma.h

484

external are 'outside of uma.h'.

You can assume that sys/cdefs.h is provided by consumers

[olce]

Rename the header (suppress the leading _).