[PATCH v2 1/9] dm: core: Document the common error codes

[Simon Glass <sjg@chromium.org>]

Hi Sean,

On Thu, 25 Mar 2021 at 05:00, Sean Anderson <seanga2@gmail.com> wrote:
>
> On 3/23/21 1:40 AM, Simon Glass wrote:
> > HI Sean,
> >
> > On Tue, 23 Mar 2021 at 17:45, Sean Anderson <seanga2@gmail.com> wrote:
> >>
> >> On 3/23/21 12:14 AM, Simon Glass wrote:
> >>> Driver model uses quite strong conventions on error codes, but these are
> >>> currently not clearly documented. Add a description of the commonly used
> >>> errors.
> >>>
> >>> Signed-off-by: Simon Glass <sjg@chromium.org>
> >>> ---
> >>>
> >>> Changes in v2:
> >>> - Add a patch to document the common error codes
> >>>
> >>>    doc/driver-model/design.rst | 111 ++++++++++++++++++++++++++++++++++++
> >>>    1 file changed, 111 insertions(+)
> >>>
> >>> diff --git a/doc/driver-model/design.rst b/doc/driver-model/design.rst
> >>> index 4e5cecbab6a..30a07bdf768 100644
> >>> --- a/doc/driver-model/design.rst
> >>> +++ b/doc/driver-model/design.rst
> >>> @@ -900,6 +900,117 @@ Some special flags are used to determine whether to remove the device:
> >>>    The dm_remove_devices_flags() function can be used to remove devices based on
> >>>    their driver flags.
> >>>
> >>> +
> >>> +Error codes
> >>> +-----------
> >>> +
> >>> +Driver model tries to use errors codes in a consistent way, as follows:
> >>> +
> >>> +\-EAGAIN
> >>> +   Try later, e.g. dependencies not ready
> >>> +
> >>> +\-EINVAL
> >>> +   Invalid argument, such as `dev_read_...()` failed or any other
> >>> +   devicetree-related access. Also used when a driver method is passed an
> >>> +   argument it considers invalid or does not support.
> >>> +
> >>> +\-EIO
> >>> +   Failed to perform I/O
> >>
> >> Do you mind providing a longer explanation here? What sort of IO
> >> failures should return EIO instead of (e.g.) ETIMEDOUT? Would ECOMM as
> >> used by the MMC subsystem be a good example of what to use EIO for in
> >> new code?
> >
> > I forgot about -ETIMEDOUT, will add.
> >
> > How about:
> >
> > Failed to perform an I/O operation. This is used when a local device
> > (i.e. part of the SOC) does not work as expected. Use -EREMOTEIO for
> > failures to talk to a separate device, e.g. over an I2C or SPI
> > channel.
> >
> >>
> >>> +
> >>> +\-ENODEV
> >>> +   Do not bind the device. This should not be used to indicate an
> >>> +   error probing the device or for any other purpose, lest driver model get
> >>> +   confused. Using `-ENODEV` inside a driver method makes no sense, since
> >>> +   clearly there is a device.
> >>> +
> >>> +\-ENOENT
> >>> +   Entry or object not found
> >>
> >> Could we add some examples here? Off the top of my head, this is used
> >> for missing device-tree properties/nodes, non-udevice devices (clocks,
> >> pinctrl groups, etc.) and of course files and directories.
> >
> > How about:
> >
> > Entry or object not found. This is used when a device, file, directory
> > cannot be found (e.g. when looked up by name), It can also indicate a
> > missing devicetree subnode.
>
> Sounds good.
>
> >>
> >>> +
> >>> +\-ENOMEM
> >>> +   Out of memory
> >>> +
> >>> +\-ENOSPC
> >>> +   Ran out of space (e.g. in a buffer or limited-size array)
> >>> +
> >>> +\-ENOSYS
> >>> +   Function not implemented. This is returned by uclasses where the driver does
> >>> +   not implement a particular method. It can also be returned by drivers when
> >>> +   a particular sub-method is not implemented. This is widely checked in the
> >>> +   wider code base, where a feature may or may not be compiled into U-Boot. It
> >>> +   indicates that the feature is not available, but this is often just normal
> >>> +   operation. Please do not use -ENOSUPP. If an incorrect or unknown argument
> >>> +   is provided to a method (e.g. an unknown clock ID), return -EINVAL.
> >>> +
> >>> +\-ENXIO
> >>> +   Couldn't find device/address
> >>
> >> How does this differ from ENODEV and ENOENT?
> >
> > How about:
> >
> > Couldn't find device/address. This is used when a device or address
> > could not be obtained or is not valid.
>
> I think this still needs to be clarified. Both ENODEV and ENOENT may be
> used to indicate a missing device. From what I have seen, this tends to
> be used as a "third error code" when ENOENT is already used for some
> purpose.

OK I can say that.

>
> >>
> >>> +
> >>> +\-EPERM
> >>> +   This is -1 so some older code may use it as a generic error. This indicates
> >>> +   that an operation is not permitted, e.g. a security violation or policy
> >>> +   constraint. It is returned internally when binding devices before relocation,
> >>> +   if the device is not marked for pre-relocation use.
> >>> +
> >>> +\-EPFNOSUPPORT
> >>> +   Missing uclass. This is deliberately an uncommon error code so that it can
> >>> +   easily be distinguished. If you see this very early in U-Boot, it means that
> >>> +   a device exists with a particular uclass but the uclass does not (mostly
> >>> +   likely because it is not compiled in). Enable DEBUG in uclass.c or lists.c
> >>> +   to see which uclass ID or driver is causing the problem.
> >>> +
> >>> +\-EREMOTEIO
> >>> +   Cannot talk to peripheral, e.g. i2c
> >>
> >> How does this differ from EIO or ECOMM?
> >
> > This indicates an error in talking to a peripheral over a comms link,
> > such as I2C or SPI. It might indicate that the device is not present
> > or is not responding as expected.
>
> Should ECOMM be used in new code? The current users are the MMC
> subsystem for when there is a CRC error, and dm_i2c_ops.xfer for
> unsupported speeds (though no one seems to implement that).

The comment says 'communication error on send'.  It sounds like EREMOTEIO to me.

I can add a note about it.

Regards,
Simon