Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs/library/uos.rst Clarify AbstractBlockDev section #5520

Closed
wants to merge 3 commits into from

Conversation

@peterhinch
Copy link
Contributor

peterhinch commented Jan 12, 2020

Implements the change requested in #5478

The statement in the last para on ioctl op 6 is based on experiment and existing code samples. I'd like to clarify the meaning of the return value if someone can provide guidance.

Copy link
Contributor

tve left a comment

Small nitpicks.

but an actual block device class must implement the methods described below.

A concrete implementation of this class will usually allow access to the
memory-like functionality a piece of hardware (like flash memory). A block

This comment has been minimized.

Copy link
@tve

tve Jan 12, 2020

Contributor

"a piece of hardware" -> "of a piece of hardware"

See :ref:`filesystem` for example implementations of block devices using both
protocols.
Unless otherwise stated ``ioctl(op, arg)`` can return None. Consequently an
implementation can ignore unused values of ``op``. As a minimum value 4 must be

This comment has been minimized.

Copy link
@tve

tve Jan 12, 2020

Contributor

"As a minimum value 4" -> "As a minimum, value 4" (or As a minimum ioctl(4,...)), I was reading "minimum value" and that didn't make sense, took me while to understand that you mean "minimum implementation".

@peterhinch

This comment has been minimized.

Copy link
Contributor Author

peterhinch commented Jan 13, 2020

Thank you, now done.

Unless otherwise stated ``ioctl(op, arg)`` can return None. Consequently an
implementation can ignore unused values of ``op``. As a minimum
``ioctl(4, ...)`` must be intercepted; for littlefs ``ioctl(6, ...)`` must be
intercepted and return 0. The need for others is hardware dependent.

This comment has been minimized.

Copy link
@dpgeorge

dpgeorge Jan 14, 2020

Member

Perhaps this para would be better indented so it's part of the ioctl method description?

So the intended semantics for the return value is:

  • if it's not implemented then return None (so unused op's can be safely ignored, as you point out)
  • 4 and 5 should return ints (as already documented)
  • others, if implemented, should return 0 for success and non-zero for failure, with the value returned being an OSError errno code

This comment has been minimized.

Copy link
@peterhinch

peterhinch Jan 15, 2020

Author Contributor

Thank you for that. I've now updated the doc.

@dpgeorge dpgeorge added the docs label Jan 14, 2020
@dpgeorge

This comment has been minimized.

Copy link
Member

dpgeorge commented Jan 22, 2020

Thank you! Squashed and merged in 59746ac

@dpgeorge dpgeorge closed this Jan 22, 2020
@peterhinch peterhinch deleted the peterhinch:filesystem-docs branch Jan 22, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.