chardev_map undocumented / doesn't support non page size size

[bennoleslie]

The chardev_map is used by many serial drivers in the platform code for mapping the serial registers into virtual memory.

Given the extensive use of the function it should really be documented.

It takes as a parameter a struct dev_defn, which has a size field.

It is somewhat implied (or at least it was to me from usage!) that size could be an arbitrary power-of-2 size.

However, that turns out to not be the case! It must be page-sized. Passing a non-page sized value results in a very difficult to debug error occurring (and when you are trying to map the UART registers you don't have any debug output!).

Could this function be please be documented to make it clear that only page-size sizes may be passed and/or could the chardev_map function perform that check early. That would make manually tracing the error much easier, rather than it failing about 12 functions deep otherwise.