Add FileHandle/poll documentation

[kjbracey]

Was asked to do poll documentation, but can't really do it without FileHandle documentation.

First attempt at a combined document. Examples will need extracting.

[AnotherButler]

@kjbracey-arm Thanks for the PR. Whom should I tag for content review?

[SeppoTakalo]

ping @geky and @bulislaw

Please review.

[AnotherButler]

ping @geky

[deepikabhavnani]

Looks good to me

[AnotherButler]

Please create separate pages for FileHandle and Poll because they're separate APIs.

[geky]

This looks great! Sorry it took so long before I could review it. Thanks for the writing.

Left some suggestions, though it looks good to me.

[geky]

Small suggestion, feel free to tweak/reject:

Suggested change

	For general information on [files](file.html) and [filing systems](filesystem.html), see the respective documentation. This chapter covers the abstract API, with an emphasis on devices, as they're less straightforward.
	For general information on [files](file.html) and [filing systems](filesystem.html), classes specifically for persistant storage, see the respective documentation. This chapter covers the abstract API, with an emphasis on devices, as they're less straightforward.

[geky]

It may help to add a picture here. Maybe something like this?

C stdio API:                  FILE *fopen(const char *path, const char *mode);
                                      |
                                      v
POSIX API:                    int open(const char *path, int flags);
                                      |
                                      v
Mbed OS C++ FileHandle API:   int FileHandle::open(const char *path, int flags);
                                      |
                                      v
Mbed OS C++ File:             int File::open(FileSystem *fs, const char *path, int flags);
                                      |
                                      v
Mbed OS C++ FileSystem:       int FileSystem::file_open(mbed::fs_file_t *f, const char *path, int flags);
                                      |
                                      v
Mbed OS C++ FATFileSystem:    int FATFileSystem::file_open(mbed::fs_file_t *f, const char *path, int flags);
                                      |
                                      v
ChanFS FAT File System:       FRESULT f_open (FIL* fp, const TCHAR* path, BYTE mode);

Ok I may have gotten a bit carried away. Feel free to cut that off where it's relevant.

[kjbracey]

Probably helps. Think we fall out of scope after File - a concrete implementation of FileHandle.

And open is a special case. Maybe stick to a core call.

[geky]

Can we link to event queue documentation?

[geky]

Shoud we note that if not supported, implementations should return ENOSYS?

[kjbracey]

Will note that "not supported" errors should be indicated - sometimes there's a more specific code, eg ESPIPE for invalid seek.

[geky]

Good point

[geky]

Maybe add UARTSerial here?

Eventually it would be nice to make a "implementation" list section similar to the blockdevices. Though we're probably not there yet with a single non-filesystem implementation 😆

[geky]

This does kinda come out of no where. Should we describe the Stream class?

Suggested change

	Note that `FileHandle` implementations derived from `Stream`, such as `Serial`, have various limitations:
	`Stream` is a legacy class that provides an abstract interface for streams similar to the `FileHandle` class. The difference is that the `Stream` API is built around the `getc` and `putc` set of functions, whereas `FileHandle` is build around `read` and `write`. This makes implementations simpler but limits what is possible with the API. Because of this, the FileHandle API is suggested API for new designs.
	Note that `FileHandle` implementations derived from `Stream`, such as `Serial`, have various limitations:

[kjbracey]

True. Will add an introductory paragraph along those lines.

[AnotherButler]

What's the status of this?

[kjbracey]

Reworked incorporating @geky's feedback, and splitting into separate FileHandle and poll pages.

Notes:

• Not certain that the links to other documents are necessarily correct for position in tree.
• Is diagram acceptable size/colour/whatever?
• Examples need extracting.

[AnotherButler]

Thanks for the hard work 👍 Please review my edits to make sure I didn't accidentally change the meaning of anything.

[kjbracey]

Gah, just pressed "Cancel review" to close the "review comment" box and deleted all my pending review comments.

[kjbracey]

Thanks for edits - good stuff. Just a couple of points that have ended up not quite right.

[kjbracey]

I meant "As per the POSIX specification, poll always indicates that ordinary files (as opposed to devices) are readable and writable".

[kjbracey]

Last sentence doesn't want the "You can also retarget".

After than, not sure if it flows right. This is giving 3 examples of device-independence

• Console retargetting stuff
• ATCmdParser
• PPP connection to lwIP

Maybe rework to:

The FileHandle abstraction permits stream-handling code to be device-independent, rather than tied to a specific device like a serial port. Examples of such code in Mbed OS are:

• the console input and output streams (stdin and stdout)
• the ATCmdParser helper
• the PPP connection to lwIP

[kjbracey]

POSX->POSIX

How about "You can use a FileHandle directly, or you can use standard POSIX or C/C++ APIs to manipulate it".

[kjbracey]

This paragraph is dangling a bit with the "currently no call to map from POSIX fd to FileHandle" paragraph gone.

Change the intro to "As it is not possible to map from higher levels to lower levels,".

Final sentence should be imperative to match previous. "Then bind that to the higher level."

[kjbracey]

I thought the last comma clause was necessary to spell out the logic, but maybe it was going too far. Up to you.

• The sigio callback is only guaranteed when a FileHandle becomes readable or writable
• Ordinary files are always readable and writable
• Therefore they never become readable or writable
• Therefore they never generate a sigio callback.