* Change Doxygen groups structure, splitting first by Public/Internal
This commit also does the following:
* groups the documentation of related API
* moves `events/internal/equeue.h` to `events/equeue.h`
* merges `events/source/README.md` to `events/README.md`
Also includes:
* rename `mbed_sleep_manager.c` to `mbed_power_mgmt.c` to match its
header file
* create Doxygen groups for public and internal APIs
* use relative path to include header files where inconsistent
* update references to internal APIs throughout libraries
* update the copyright year for all modified files
Add API to dynamically enable/disable input and output on FileHandles.
Aim is to allow power saving by indicating that we permanently or
temporarily do not require input, so that for example serial Rx
interrupts can be released, and deep sleep permitted.
There was no way to check current blocking state, so no way to modify
and restore status.
Also have default FileHandle::set_blocking() used by real files return a
correct error code when asked for non-blocking, and success when asked
for blocking.
These were minor omissions that are required to implement POSIX fcntl
properly.
fixup! Add `is_blocking()` method to FileHandle
Rationalise layers a little more to add the POSIX standard fdopen(int)
and a local open(FileHandle) to map a FileHandle to a POSIX file
descriptor.
fdopen(FileHandle) is now a composite of those two, rather than being
a primitive.
Previously, write() was somewhat soft - it only ever made one attempt to
wait for buffer space, so it would take as much data as would fit in the
buffer in one call.
This is not the intent of a POSIX filehandle write. It should try to
send everything if blocking, and only send less if interrupted by a
signal:
- If the O_NONBLOCK flag is clear, write() shall block the calling
thread until the data can be accepted.
- If the O_NONBLOCK flag is set, write() shall not block the thread.
If some data can be written without blocking the thread, write()
shall write what it can and return the number of bytes written.
Otherwise, it shall return -1 and set errno to [EAGAIN].
This "send all" behaviour is of slightly limited usefulness in POSIX, as
you still usually have to worry about the interruption possibility:
- If write() is interrupted by a signal before it writes any data, it
shall return -1 with errno set to [EINTR].
- If write() is interrupted by a signal after it successfully writes
some data, it shall return the number of bytes written.
But as mbed OS does not have the possibility of signal interruption, if we
strengthen write to write everything, we can make applications' lives
easier - they can just do "write(large amount)" confident that it will
all go in one call (if no errors).
So, rework to make multiple writes to the buffer, blocking as necessary,
until all data is written.
This change does not apply to read(), which is correct in only blocking until
some data is available:
- If O_NONBLOCK is set, read() shall return -1 and set errno to [EAGAIN].
- If O_NONBLOCK is clear, read() shall block the calling thread until some
data becomes available.
- The use of the O_NONBLOCK flag has no effect if there is some data
available.
There is currently no proper wake up mechanism provided
by mbed-os. _poll_change() was supposed to wake upa blocking
poll() in case of a POLL event but the implementation was dependent
upon underlying wake up mechanism. In the absence of conditioanl
variables or some other alternative, _poll_change() wasn't able to
serve its purpose. Removing it for now. Should be implemented at some later stage
Make FileHandle more of an interface class, by requiring implementers to
provide the sigio() functionality themselves.
sigio() and poll() remain parallel independent mechanisms, so FileHandle
implementations must trigger both on state changes.
This has been an attempt to extend existing FileHandle to behave like POSIX
file descriptor for input/output resources/devices too.
This will now provide an abstract indicator/handle any arbitrary file or device
type resource. May be in future, sockets too.
In order to correctly detect availability of read/write a FileHandle, we needed
a select or poll mechanisms. We opted for poll as POSIX defines in
http://pubs.opengroup.org/onlinepubs/009695399/functions/poll.html Currently,
mbed::poll() just spins and scans filehandles looking for any events we are
interested in. In future, his spinning behaviour will be replaced with
condition variables.
In retarget.cpp we have introduced an mbed::fdopen() function which is
equivalent to C fdopen(). It attaches a std stream to our FileHandle stream.
newlib-nano somehow does not seem to call isatty() so retarget doesn't work for
device type file handles. We handle this by checking ourselves in
mbed::fdopen() if we wish to attach our stream to std stream. We also turn off
buffering by C library as our stuff will be buffered already.
sigio() is also provided, matching the API of the Socket class, with a view to
future unification. As well as unblocking poll(), _poll_change calls the user
sigio callback if an event happens, i.e., when FileHandle becomes
readable/writable.
stop using scope for \addtogroup. It was placing class methods into the
group documentation instead of the class documentation. The new style is
to explicitly tag the class as @ingroup. This new method will allow the
class to be linked in the group page, and the class page will contain
the detailed documentation of the class methods.
Should follow same path as FileHandle, although this is less used
and there is currently no route to introduce a hook for a customized
DirHandle in retarget.
Rajkumar Kanagaraj
Kevin Bracey
Hugues Kamba
Martin Kojtal
Amanda Butler
Kevin Gilbert
Yossi Levy
Senthil Ramakrishnan
Vincent Coubard
Deepika Bhavnani
Sam Grove
Hasnain Virk
Jimmy Brisson
Christopher Haster