Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Quan Nguyen <quan@os.amperecomputing.com>
To:     Wolfram Sang <wsa@kernel.org>, linux-i2c@vger.kernel.org,
        linux-kernel@vger.kernel.org,
        Open Source Submission <patches@amperecomputing.com>
Cc:     quan@os.amperecomputing.com,
        Phong Vo <phong@os.amperecomputing.com>,
        Thang Nguyen <thang@os.amperecomputing.com>
Subject: [PATCH] docs: i2c: slave-interface: return errno when handle I2C_SLAVE_WRITE_REQUESTED
Date:   Thu, 15 Sep 2022 10:54:40 +0700
Message-Id: <20220915035440.2862532-1-quan@os.amperecomputing.com>
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?LcEi+/JfA86hMnpaTf2H0AgvGlTTWny3THSKcIPZCd5j9o1bUcsIWpiEVVra?=
 =?us-ascii?Q?sbpaNkQsOJ3cK++u+/jxqdh2yaedGqKRdvrdjIRKixTDjK2UEJbXyP9BZihF?=
 =?us-ascii?Q?2rkixplDxQlgiTyJWvSG6NY/NX7yoBSGOJazSGb7w5eAjpspWJx3ks/u4GxI?=
 =?us-ascii?Q?xq/DHzAKhFzPc7f3KZPGDNq1+JBQP8BrvSsT84H6I62ckQLVRh2uT03Gtk2Z?=
 =?us-ascii?Q?XSLXnbw1PfHvUJQ5HmQC06MWuHADt0Js25gq2VyKeBkz8FfPrpyG/AJQjDGI?=
 =?us-ascii?Q?m9p4WcxB6VlzO9ENYBDXT8mgFLYxbmtid/KyEE3cHCydEnTNNpbZcBj+EsnF?=
 =?us-ascii?Q?aVIJ5IiKIjQP6gVpFtkny06GbN3AQBBnhcCslqbBWvOA1yXQE9fUZZl3HzzX?=
 =?us-ascii?Q?pPSA8NszgWY+xm9qltGXjvX4vc6hmAUgGniC5YYYG0QTAo045rXTH4itw1/q?=
 =?us-ascii?Q?GXY1BybIHlGpbZ0PfgoEsifJGs5j9JLkfK9Xf4LiOR7Nvoh7iHIsPso5csGn?=
 =?us-ascii?Q?sfjqbc3XQfzHw1Ycs3ILQIuSUrWcGq5HJdiQTN3Djp4nH62TpsALneGN/K7J?=
 =?us-ascii?Q?0FzSHi+EEAkBqUkqvxO7eyIMyciC3un8neG13IbRL7CdU0z45wg8duNHEEHI?=
 =?us-ascii?Q?vwWPodo8Tp1+HL9E2em71kgKb4tKbxDHDJ9qOL/+7R7RPcAMSmhD1VhesnGC?=
 =?us-ascii?Q?fqe76ZBawyUnlk3FgHnZQaBsXOvKFI94ELenldc1K4rxKmin8jLIzrQ9g+rZ?=
 =?us-ascii?Q?6OOrt/HqpvsdnFmULzv0E7ROeG1pUKEZk+rOl6kLPJAUgp6VaxfU0JwLufvQ?=
 =?us-ascii?Q?Z6fJR9vWuTuXqj7K2JxYwEW8NJJQaVAJx11PhVjMnoXdUqdKlqN9f3epGbbP?=
 =?us-ascii?Q?E4yEPJ73UiSo9Lc07x0QQozWyCSzAPYb8cYI4bIUuEw3WXKVpJZJzm+kNl3S?=
 =?us-ascii?Q?2ZNrM5AWdkHqvfwRK8mYNXSIL+nFWohvkCKGgyKsPfW9mtQoErig5ZrXwekj?=
 =?us-ascii?Q?jtfk9A6NJbsdFKkYL8EA1ePiNymf7+cfxY4LVITGB83dcQo9a1ycwnDUMhzT?=
 =?us-ascii?Q?S504WCRxg4IuqggAOhScZ7h+/h6WACDbHwEyjhK1us4r7ZCIWxQZqkiSKhAa?=
 =?us-ascii?Q?bEvF0IyphA5ZQ6VNgOL+cu8rN7Oz7BJCPBbUsDqtJvW5ECuaiejc+kEUv4Wf?=
 =?us-ascii?Q?eDUGUGADiEcM5OAaIoZl4VJZLeZ/uM/myIQ1/+dTFjc78uekNr6ldDhn+nnN?=
 =?us-ascii?Q?Zh6vBglAD5mxKZr2+t8qtsDfm7oGC/bNq5+cHBgsIFZCV8H4yWivjbJ0/UZS?=
 =?us-ascii?Q?bw8S4HZmQW6PVvgfZz5XOy75zj1iSu8zaSTUVbBO6LhQuAY9poYG3jL9GKlN?=
 =?us-ascii?Q?lolYi03N1qPCS7KdBl3fWF4T/H8B4jWwZgUx0v+Dj8pVgn/kDAFLG1FjKKzS?=
 =?us-ascii?Q?kmLA45ZXqATOzVoLmCqPs6tVhUWQNlYpVmZ2FNS8HNC4pizpY38XhlbujGDN?=
 =?us-ascii?Q?x9jow1EmIJqSX0/koGaO26iSgRZtXwHDbSoWdCxNGNtQ9hi6Z0y+DMv/TlLO?=
 =?us-ascii?Q?88iB9Lew3NA7l+qoF79sLFVgCiT254TNoTikkdzt5F3v+ebYu/q0XdLgscfG?=
 =?us-ascii?Q?3VsbaqHoeKz+52QesBJxRt8=3D?=
X-OriginatorOrg: os.amperecomputing.com
X-MS-Exchange-CrossTenant-Network-Message-Id: ff7a5dee-d77c-48ef-4071-08da96ce0e65
X-MS-Exchange-CrossTenant-AuthSource: SJ0PR01MB7282.prod.exchangelabs.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 15 Sep 2022 03:54:57.8885
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 3bc2b170-fd94-476d-b0ce-4229bdc904a7
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: tXODtYV4G81oLXCiaftw3huX3lgDSHCERp3TDy22JCPBluR+SUz+5sCSJ96McEO+1O93ths7h7NWPN7Bn0et0tdVjM/Eq8fK5hR3J37C0Fk=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN0PR01MB7659
X-Spam-Status: No, score=-2.0 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,DKIM_VALID_AU,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,
        SPF_HELO_PASS,SPF_PASS,T_SCC_BODY_TEXT_LINE autolearn=ham
        autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

In case backend is not ready, ie: fail to wakeup or initialization, on
the returning of the I2C_SLAVE_WRITE_REQUESTED event, bus driver should
aware the backend status and might auto sending NACK on the next
incoming bytes for I2C master to retry.

Signed-off-by: Quan Nguyen <quan@os.amperecomputing.com>
Links:https://lore.kernel.org/linux-arm-kernel/556fa9e1-c54b-8370-4de7-c2d3ec7d6906@os.amperecomputing.com/
---
 Documentation/i2c/slave-interface.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/i2c/slave-interface.rst b/Documentation/i2c/slave-interface.rst
index 82ea3e1d6fe4..03b15b21d392 100644
--- a/Documentation/i2c/slave-interface.rst
+++ b/Documentation/i2c/slave-interface.rst
@@ -72,12 +72,15 @@ Event types:
 
   'val': unused
 
-  'ret': always 0
+  'ret': 0 if backend ready, otherwise, returns some errno
 
 Another I2C master wants to write data to us. This event should be sent once
 our own address and the write bit was detected. The data did not arrive yet, so
-there is nothing to process or return. Wakeup or initialization probably needs
-to be done, though.
+there is nothing to process or return. After returning, the bus driver should
+always ack on this address phase. If 'ret' is zero, backend initialization or
+wakeup is done and ready. If 'ret' is an errno, bus driver should aware the
+backend status and might need to nack all next incoming bytes for I2C master to
+retry.
 
 * I2C_SLAVE_READ_REQUESTED (mandatory)
 
-- 
2.35.1