Thanks for the suggestion. Just to clarify, we preferred
u32p_replace_bits() over FIELD_PREP() because the former does
a clear-and-set operation against a given mask, where as with
FIELD_PREP(), we need to clear the bits first before we use the
macro and then set it. Due to this, we preferred using
u32_replace_bits() since it made the macro definitions to modify
the registers simpler. Given this, would it be acceptable to
document u32p_replace_bits() better, as it is already being used
by other drivers as well?

I suggest you submit a patch to those who maintain that file and see
what they say.

But maybe also look at how others are using u32p_replace_bits() and
should it be wrapped up in a macro? FIELD_MOD()? These macros do a lot
of build time checking that you are not overflowing the type. It would
be good to have that to catch bugs at build time, rather than years
later at runtime.

      Andrew