Lots of usability improvements for the I2C API. Better docs and new top-level functions. (#64) ...

* Lots of usability improvements for the I2C API.  Better docs and new top-level functions.

* Document frequencies

* Tabs to spaces

* More style fixes

* Run astyle

* Clean up docs

* Add note about addressing, change 10 bit to 11 bit

* Fix spellcheck

* Fix paste error

* Oops, fix accidental change

Fix hanging with multiple I2C buses ...

Make the _mutex non-static and remove _owner and acquire()

When two or more I2C buses are used then static__mutex and _owner are
shared between all I2C class instances in the program. That
wastes time to reconfigure periphery on every transfer.

Make _mutex non-static. Remove _owner and acquire() method
because in non-static case they have no practical meaning.

i2c: `start()` should aquire the bus ...

From the history it looks like aquire was not added explicitely to start. I do not see
why as it's the condition that must be sent when communication is initiated.

write/read/transfer invoke `aquire()`

Change explicit pinmap to static pinmap

I2C: Add explicit pinmap support

Drivers/Events/RTOS Public and internal APIs cleanup (#10955) ...

Separate drivers, events, and rtos internal APIs from public APIs.

* Move source files to source subdirs
* Move internal headers to internal subdirs
* Add Doxygen comments for documenting internal and public APIs
* Remove source code from header files in order to remove include pre-processor directives
that included header files not directly used by said header files
* Explicitly include header files instead of implicit inclusions via third-party header files.

Release Notes

This will break user code that was using an internal API as the internal header files have been moved.
This will only break if the user was including the header file using a namespace (i.e #include "foo/bar.h" instead of #include "bar.h"