From nobody Mon Feb 9 04:28:22 2026 Received: from mail-pl1-f194.google.com (mail-pl1-f194.google.com [209.85.214.194]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 24FC233123B for ; Thu, 18 Dec 2025 21:40:48 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.194 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1766094054; cv=none; b=DLzw0eXGkzYw3TP9+rVxjvwFw+WQfrTPwVh9cZ39k4ZrS/7axEIsb7+yBVK/B/2kNDoAGdFt6Vvi6CH19DdaRAiM6o6zVjBmWooQ6r3+nJgl29QrjnDSMrgXBwmlv5zfAag5Dg1EGda6aVJLpd7Vq9jvLqU7VuK36SCjGTY41hM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1766094054; c=relaxed/simple; bh=JAiArZdSLQKAdhF8pIyj1h6WQqgJY7pxqg9zvWiZiDQ=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version; b=T/BbtS402/YwXshwD3x9FxfFEvuIR6tDQumO146ZbHn/AT5IgbuGdVK4j2fE+IubEANLNmb4RDSvdnt3F+6IiG+GBVJuZ/ThsU0DMflb1IRA9xNUrkifIN7OaYp0Bppldj8HVFBm1xXuEeNzaFYcmJnky0IIT/ApRQ8uxdhfniE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org; spf=pass smtp.mailfrom=chromium.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b=Cn9Tlw8p; arc=none smtp.client-ip=209.85.214.194 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=chromium.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b="Cn9Tlw8p" Received: by mail-pl1-f194.google.com with SMTP id d9443c01a7336-2a12ed4d205so10232635ad.0 for ; Thu, 18 Dec 2025 13:40:47 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; t=1766094046; x=1766698846; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=uczdJgzeaI+lnfz5g1VHxQw0Qaj9EOMwMBp4+jWOya0=; b=Cn9Tlw8py6gG+fSpT9v6o7Wpq/4/yDuA2idEzWFdWhEgte0L0Kt+c0G9KEE1K6Tz8Y 6wuBDy0L951HqYvTcGdJaOOTYXkVwzUe8tGk5hP2MNgno7W+FRtSwHLooNnRm+YFsMaC T9N1DXa7PnBuKo6CldaKMR+zGPz6Z+ZNSOejU= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1766094046; x=1766698846; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=uczdJgzeaI+lnfz5g1VHxQw0Qaj9EOMwMBp4+jWOya0=; b=bSscrgRiAeufUPZnPKwKhrW7Nw8LRjZqXDL3usrb7YIdmzCFwr8BkXHvtRGaTuQ1ej VPAJm3Q/H07cPWZnFiOwrBFQpl7BqynBBDQ6m7vgfEgqt/+YUH1LsRJ6Vtc0uY5JhETg euLK+3MckxL5WNhDOI5HlBIAgzzidQkun4jlgRzWq7GNBOcaa1ROeLMJ1+x81A3zvbi6 oZLkpsDkPsHsDSZPeKjVvcM9w/B7m1pkG8zTwDCGdoIi59X1jNPhwi9eCGfnZnXzflzF TWHAU1MN8wW5h5e+L5Mg66ANNQ0ZkhOe50T0NEiPDmVuYXi99pGGJ1LgU+v9czpYI+Kg dXcA== X-Forwarded-Encrypted: i=1; AJvYcCV9GW+YkNLX5rUqzNiLj9RTT+bocN/2llVESHlab5wOECX1pVIUMi1A5hvbcCpwe4VJZ1fjbm2lKzpjKIM=@vger.kernel.org X-Gm-Message-State: AOJu0YyPJRAhGxfkqtFyzrTf3i0q99jYUUpHaeHISuYjWeSAwxnTxk+9 ga1Kt0gJOGLII7H2ssYjtggZTzQ9EAoVZQ1V54JVFD2Zee0rmTgM3Zt/VNYjgntegw== X-Gm-Gg: AY/fxX5x3WbquMO5IaBa2u3zLgMBjEut8Q+Xmkb+W/4fw5kRuVQdo7g19pYwJk80J/U d7NbKEN7zoKMV6W8gbUjIWEgtk9GKdY3XMK8WcHGiYcngvcehFfz4gg4Lxi3oIznC2OBkUL6Kwm PPeztMyHPvTf0d/JNm+fA/FRCyI6ARH5HxKYW1G3Sqi0ZOVlV6zzFslpVxFujiMKGbWIt+15FhP TepdCh1AYGM2UtZSqdXx8rs4zoGvdPt0VXwPLJBGFLRtbHYKhS5e/hVme4MYXkuflg2hGTm+AbI 1L8olR1KBYqXc4Bk3X1ZEAmZiIYd2T0UHwFyn/LSxxCAdLHAkoroKS8NXEH51HqSv44vES9DA5s rrDq1/4uXo7M+zDzK67OzQQsQi7WY3Zz12wTEhxeeEQAxMJRR3Gt2E8qaEIjQSP5YSAOjoCRjE3 eBu+7/7JXD8t4s748G9p+3LEYGeuU6QY1Ingg6NdggWCbQz7rOU5opo1rcBe2lPoTtxMNptXsea e2qF+V6kA== X-Google-Smtp-Source: AGHT+IEUakaLWRO6XMiPgNGQJ0M2AzTANeUQETB4A4L4PZsQ9TWwfE/ncCXDopHKIPXdsFQfw7xuNA== X-Received: by 2002:a05:7022:6294:b0:11b:9b9f:427a with SMTP id a92af1059eb24-121722b4fdfmr987182c88.21.1766094046120; Thu, 18 Dec 2025 13:40:46 -0800 (PST) Received: from dianders.sjc.corp.google.com ([2a00:79e0:2e7c:8:30ed:82df:6cac:3ff6]) by smtp.gmail.com with ESMTPSA id a92af1059eb24-1217254c734sm1399110c88.13.2025.12.18.13.40.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 18 Dec 2025 13:40:45 -0800 (PST) From: Douglas Anderson To: Jassi Brar Cc: Douglas Anderson , linux-kernel@vger.kernel.org Subject: [PATCH] mailbox: Document the behavior of mbox_send_message() w/ NULL mssg Date: Thu, 18 Dec 2025 13:40:13 -0800 Message-ID: <20251218134012.1.I614e18fb4f7b9121e9702d15ffc715cb26ee9afc@changeid> X-Mailer: git-send-email 2.52.0.322.g1dd061c0dc-goog Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The way the mailbox core behaves when you pass a NULL `mssg` parameter to mbox_send_message() seems a little questionable. Specifically, the mailbox core stores the currently active message directly in its `active_req` field. In at least two places it decides that if this field is `NULL` then there is no active request. That means if `mssg` is NULL it will always think there is no active request. The two places where it does this are: 1. If a client calls mbox_send_message(), if `active_req` is NULL then it will call the mailbox controller to send the new message even if the mailbox controller hasn't yet called mbox_chan_txdone() on the previous (NULL) message. 2. The mailbox core will never call the client's `tx_done()` callback with a NULL message because `tx_tick()` returns early whenever the message is NULL. The above could be seen as bugs and perhaps could be fixed. However, doing a `git grep mbox_send_message.*NULL` shows 14 hits in mainline today and people may be relying on the current behavior. It is, perhaps, better to accept the current behavior. The current behavior can actually serve the purpose of providing a simple way to assert an edge-triggered interrupt to the remote processor on the other side of the mailbox. Specifically: 1. Like a normal edge-triggered interrupt, if multiple edges arrive before the interrupt is Acked they are coalesced. 2. Like a normal edge-triggered interrupt, as long as the receiver (the remote processor in this case) "Ack"s the interrupt _before_ checking for work and the sender (the mailbox client in this case) posts the interrupt _after_ adding new work then we can always be certain that new work will be noticed. This assumes that the mailbox clienut and remote processor have some out-of-band way to communicate work and the mailbox is just being used as an interrupt. Document the current behavior so that people can rely on it and know that it will keep working the same way. NOTE: if a given mailbox client mixes and matches some NULL and some non-NULL messages, things could get loopy without additional code changes and rules. Without code changes, if we transfer a non-NULL message then we'd stop coalescing future NULL messages until the queue clears. Also: if we were transferring a NULL message and a non-NULL came in, we'd send it right away but potentially report `tx_done()` too early. For now, document mixing and matching NULL and non-NULL messages as undefined. Signed-off-by: Douglas Anderson --- This feels hacky, but I'm worried that if we do something else we'll break people. I haven't spent tons of time analyzing all of the existing mailbox users that pass NULL for the message, but I do know that at least downstream some Pixel code does it and seems to rely on the current "don't queue up another message but instead just make sure the remote processor will get an interrupt in the future." drivers/mailbox/mailbox.c | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/drivers/mailbox/mailbox.c b/drivers/mailbox/mailbox.c index 2acc6ec229a4..80861caeb848 100644 --- a/drivers/mailbox/mailbox.c +++ b/drivers/mailbox/mailbox.c @@ -238,6 +238,15 @@ EXPORT_SYMBOL_GPL(mbox_client_peek_data); * This function could be called from atomic context as it simply * queues the data and returns a token against the request. * + * NOTE: If 'mssg' is NULL, the function has some rather different behavio= r. + * - The mailbox controller will be informed of the message but it + * won't be considered "busy". Future messages will continue to be + * passed onto the controller even if it never called mbox_chan_txdone() + * - The client's tx_done() callback will never be called. + * The above rules allow asserting an "edge-triggered" interrupt to the + * remote processor in a race-free way. Behavior is undefined if a given + * channel sometimes has NULL message and sometimes doesn't. + * * Return: Non-negative integer for successful submission (non-blocking mo= de) * or transmission over chan (blocking mode). * Negative value denotes failure. --=20 2.52.0.322.g1dd061c0dc-goog