doc: Add errors.txt to describe errors of D-Bus method returns

Signed-off-by: Anuj Jain <anuj01.jain@samsung.com>
Signed-off-by: Ayush Garg <ayush.garg@samsung.com>

diff --git a/doc/errors.txt b/doc/errors.txt
new file mode 100644 (file)
index 0000000..047610c
--- /dev/null
+++ b/doc/errors.txt
@@ -0,0 +1,233 @@
+D-Bus Method Return Error Codes
+===============================
+
+The motivation of having detailed error is to provide context-based failure
+reasons along with D-Bus method return so that D-Bus clients can build metrics
+and optimize their application based on these failure reasons. For instance, a
+client can build retry mechanism for a connection failure or improve the
+bottleneck of use scenario based on actionable metrics.
+
+These error codes are context-based but not necessarily tied to interface or
+method calls. For instance, if a pairing request failed due to connection
+failure, connection error would be attached to the method return of Pair().
+
+BR/EDR connection already connected
+===================================
+       errno:  EALREADY, EISCONN
+
+       Either the profile is already connected or ACL connection is in place.
+
+BR/EDR connection page timeout
+==============================
+       errno:  EHOSTDOWN
+
+       Failed due to page timeout.
+
+BR/EDR connection profile unavailable
+=====================================
+       errno:  ENOPROTOOPT
+
+       Failed to find connectable services or the target service.
+
+BR/EDR connection SDP search
+============================
+       errno:  none
+
+       Failed to complete the SDP search.
+
+BR/EDR connection create socket
+===============================
+       errno:  EIO
+
+       Failed to create or connect to BT IO socket. This can also indicate
+       hardware failure in the controller.
+
+BR/EDR connection invalid arguments
+===================================
+       errno:  EHOSTUNREACH
+
+       Failed due to invalid arguments.
+
+BR/EDR connection not powered
+=============================
+       errno:  EHOSTUNREACH
+
+       Failed due to adapter not powered.
+
+BR/EDR connection not supported
+===============================
+       errno:  EOPNOTSUPP, EPROTONOSUPPORT
+
+       Failed due to unsupported state transition of L2CAP channel or other
+       features either by the local host or the remote.
+
+BR/EDR connection bad socket
+============================
+       errno:  EBADFD
+
+       Failed due to the socket is in bad state.
+
+BR/EDR connection memory allocation
+===================================
+       errno:  ENOMEM
+
+       Failed to allocate memory in either host stack or controller.
+
+BR/EDR connection busy
+======================
+       errno:  EBUSY
+
+       Failed due to other ongoing operations, such as pairing, busy L2CAP
+       channel or the operation disallowed by the controller.
+
+BR/EDR connection concurrent connection limit
+=============================================
+       errno:  EMLINK
+
+       Failed due to reaching the concurrent connection limit to a device.
+
+BR/EDR connection timeout
+=========================
+       errno:  ETIMEDOUT
+
+       Failed due to connection timeout
+
+BR/EDR connection refused
+=========================
+       errno:  ECONNREFUSED
+
+       Refused by the remote device due to limited resource, security reason
+       or unacceptable address type.
+
+BR/EDR connection aborted by remote
+===================================
+       errno:  ECONNRESET
+
+       Terminated by the remote device due to limited resource or power off.
+
+BR/EDR connection aborted by local
+==================================
+       errno:  ECONNABORTED
+
+       Aborted by the local host.
+
+BR/EDR connection LMP protocol error
+====================================
+       errno:  EPROTO
+
+       Failed due to LMP protocol error.
+
+BR/EDR connection canceled
+==========================
+       errno:  none
+
+       Failed due to cancellation caused by adapter drop, unexpected device
+       drop, orincoming disconnection request before connection request is
+       completed.
+
+BR/EDR connection unknown error
+===============================
+       errno:  ENOSYS
+
+       Failed due to unknown reason.
+
+LE connection invalid arguments
+===============================
+       errno:  EINVAL
+
+       Failed due to invalid arguments.
+
+LE connection not powered
+=========================
+       errno:  EHOSTUNREACH
+
+       Failed due to adapter not powered.
+
+LE connection not supported
+===========================
+       errno:  EOPNOTSUPP, EPROTONOSUPPORT
+
+       Failed due to unsupported state transition of L2CAP channel or other
+       features (e.g. LE features) either by the local host or the remote.
+
+LE connection already connected
+===============================
+       errno: EALREADY, EISCONN
+
+       Either the BT IO is already connected or LE link connection in place.
+
+LE connection bad socket
+========================
+       errno: EBADFD
+
+       Failed due to the socket is in bad state.
+
+LE connection memory allocation
+===============================
+       errno: ENOMEM
+
+       Failed to allocate memory in either host stack or controller.
+
+LE connection busy
+==================
+       errno:  EBUSY
+
+       Failed due to other ongoing operations, such as pairing, connecting,
+       busy L2CAP channel or the operation disallowed by the controller.
+
+LE connection refused
+=====================
+       errno:  ECONNREFUSED
+
+       Failed due to that LE is not enabled or the attempt is refused by the
+       remote device due to limited resource, security reason or unacceptable
+       address type.
+
+LE connection create socket
+===========================
+       errno:  EIO
+
+       Failed to create or connect to BT IO socket. This can also indicate
+       hardware failure in the controller.
+
+LE connection timeout
+=====================
+       errno:  ETIMEDOUT
+
+       Failed due to connection timeout
+
+LE connection concurrent connection limit
+=========================================
+       errno:  EMLINK
+
+       Failed due to reaching the synchronous connection limit to a device.
+
+LE connection abort by remote
+=============================
+       errno:  ECONNRESET
+
+       Aborted by the remote device due to limited resource or power off.
+
+LE connection abort by local
+============================
+       errno:  ECONNABORTED
+
+       Aborted by the local host.
+
+LE connection link layer protocol error
+=======================================
+       errno:  EPROTO
+
+       Failed due to link layer protocol error.
+
+LE connection GATT browsing
+===========================
+       errno:  none
+
+       Failed to complete the GATT browsing.
+
+LE connection unknown error
+===========================
+       errno:  ENOSYS
+
+       Failed due to unknown reason.