[PATCH] mailbox: add API to query available TX queue slots

[PATCH] mailbox: add API to query available TX queue slots

[jassisinghbrar]

From: Jassi Brar <jassisinghbrar@gmail.com>

Clients sometimes need to know whether the mailbox TX queue has room
before posting a new message. Rather than exposing internal queue state
through a struct field, provide a proper accessor function that returns
the number of available slots for a given channel.

This lets clients choose to back off when the queue is full instead of
hitting the -ENOBUFS error path and the misleading "Try increasing
MBOX_TX_QUEUE_LEN" warning.

Signed-off-by: Jassi Brar <jassisinghbrar@gmail.com>
---
 drivers/mailbox/mailbox.c      | 23 +++++++++++++++++++++++
 include/linux/mailbox_client.h |  1 +
 2 files changed, 24 insertions(+)

diff --git a/drivers/mailbox/mailbox.c b/drivers/mailbox/mailbox.c
index 2acc6ec229a4..22eb8f3213be 100644
--- a/drivers/mailbox/mailbox.c
+++ b/drivers/mailbox/mailbox.c
@@ -218,6 +218,29 @@ bool mbox_client_peek_data(struct mbox_chan *chan)
 }
 EXPORT_SYMBOL_GPL(mbox_client_peek_data);
 
+/**
+ * mbox_chan_tx_slots_available - Query the number of available TX queue slots.
+ * @chan: Mailbox channel to query.
+ *
+ * Clients may call this to check how many messages can be queued via
+ * mbox_send_message() before the channel's TX queue is full. This helps
+ * clients avoid the -ENOBUFS error without needing to increase
+ * MBOX_TX_QUEUE_LEN.
+ * This can be called from atomic context.
+ *
+ * Return: Number of available slots in the channel's TX queue.
+ */
+unsigned int mbox_chan_tx_slots_available(struct mbox_chan *chan)
+{
+	unsigned int ret;
+
+	guard(spinlock_irqsave)(&chan->lock);
+	ret = MBOX_TX_QUEUE_LEN - chan->msg_count;
+
+	return ret;
+}
+EXPORT_SYMBOL_GPL(mbox_chan_tx_slots_available);
+
 /**
  * mbox_send_message -	For client to submit a message to be
  *				sent to the remote.
diff --git a/include/linux/mailbox_client.h b/include/linux/mailbox_client.h
index c6eea9afb943..e5997120f45c 100644
--- a/include/linux/mailbox_client.h
+++ b/include/linux/mailbox_client.h
@@ -45,6 +45,7 @@ int mbox_send_message(struct mbox_chan *chan, void *mssg);
 int mbox_flush(struct mbox_chan *chan, unsigned long timeout);
 void mbox_client_txdone(struct mbox_chan *chan, int r); /* atomic */
 bool mbox_client_peek_data(struct mbox_chan *chan); /* atomic */
+unsigned int mbox_chan_tx_slots_available(struct mbox_chan *chan); /* atomic */
 void mbox_free_channel(struct mbox_chan *chan); /* may sleep */
 
 #endif /* __MAILBOX_CLIENT_H */
-- 
2.43.0

Re: [PATCH] mailbox: add API to query available TX queue slots

[Shah, Tanmay]

Tested-by: Tanmay Shah <tanmay.shah@amd.com>

On 2/9/2026 5:44 PM, jassisinghbrar@gmail.com wrote:
> From: Jassi Brar <jassisinghbrar@gmail.com>
> 
> Clients sometimes need to know whether the mailbox TX queue has room
> before posting a new message. Rather than exposing internal queue state
> through a struct field, provide a proper accessor function that returns
> the number of available slots for a given channel.
> 
> This lets clients choose to back off when the queue is full instead of
> hitting the -ENOBUFS error path and the misleading "Try increasing
> MBOX_TX_QUEUE_LEN" warning.
> 
> Signed-off-by: Jassi Brar <jassisinghbrar@gmail.com>
> ---
>  drivers/mailbox/mailbox.c      | 23 +++++++++++++++++++++++
>  include/linux/mailbox_client.h |  1 +
>  2 files changed, 24 insertions(+)
> 
> diff --git a/drivers/mailbox/mailbox.c b/drivers/mailbox/mailbox.c
> index 2acc6ec229a4..22eb8f3213be 100644
> --- a/drivers/mailbox/mailbox.c
> +++ b/drivers/mailbox/mailbox.c
> @@ -218,6 +218,29 @@ bool mbox_client_peek_data(struct mbox_chan *chan)
>  }
>  EXPORT_SYMBOL_GPL(mbox_client_peek_data);
>  
> +/**
> + * mbox_chan_tx_slots_available - Query the number of available TX queue slots.
> + * @chan: Mailbox channel to query.
> + *
> + * Clients may call this to check how many messages can be queued via
> + * mbox_send_message() before the channel's TX queue is full. This helps
> + * clients avoid the -ENOBUFS error without needing to increase
> + * MBOX_TX_QUEUE_LEN.
> + * This can be called from atomic context.
> + *
> + * Return: Number of available slots in the channel's TX queue.
> + */
> +unsigned int mbox_chan_tx_slots_available(struct mbox_chan *chan)
> +{
> +	unsigned int ret;
> +
> +	guard(spinlock_irqsave)(&chan->lock);
> +	ret = MBOX_TX_QUEUE_LEN - chan->msg_count;
> +
> +	return ret;
> +}
> +EXPORT_SYMBOL_GPL(mbox_chan_tx_slots_available);
> +
>  /**
>   * mbox_send_message -	For client to submit a message to be
>   *				sent to the remote.
> diff --git a/include/linux/mailbox_client.h b/include/linux/mailbox_client.h
> index c6eea9afb943..e5997120f45c 100644
> --- a/include/linux/mailbox_client.h
> +++ b/include/linux/mailbox_client.h
> @@ -45,6 +45,7 @@ int mbox_send_message(struct mbox_chan *chan, void *mssg);
>  int mbox_flush(struct mbox_chan *chan, unsigned long timeout);
>  void mbox_client_txdone(struct mbox_chan *chan, int r); /* atomic */
>  bool mbox_client_peek_data(struct mbox_chan *chan); /* atomic */
> +unsigned int mbox_chan_tx_slots_available(struct mbox_chan *chan); /* atomic */
>  void mbox_free_channel(struct mbox_chan *chan); /* may sleep */
>  
>  #endif /* __MAILBOX_CLIENT_H */

Re: [PATCH] mailbox: add API to query available TX queue slots

[Bjorn Andersson]

On Mon, Feb 09, 2026 at 05:44:30PM -0600, jassisinghbrar@gmail.com wrote:
> From: Jassi Brar <jassisinghbrar@gmail.com>
> 
> Clients sometimes need to know whether the mailbox TX queue has room
> before posting a new message.

This is rather vague, could you be more specific?

> Rather than exposing internal queue state
> through a struct field, provide a proper accessor function that returns
> the number of available slots for a given channel.
> 
> This lets clients choose to back off when the queue is full instead of
> hitting the -ENOBUFS error path and the misleading "Try increasing
> MBOX_TX_QUEUE_LEN" warning.
> 

In the event that we're using the mailbox framework as a doorbell, I
presume that the queue is full of duplicate rings already - so backing
off it perfectly fine.

But in the case where the client actually uses the interface to convey
data, what is the expected way for the client to know when to make
another attempt?

Regards,
Bjorn

> Signed-off-by: Jassi Brar <jassisinghbrar@gmail.com>
> ---
>  drivers/mailbox/mailbox.c      | 23 +++++++++++++++++++++++
>  include/linux/mailbox_client.h |  1 +
>  2 files changed, 24 insertions(+)
> 
> diff --git a/drivers/mailbox/mailbox.c b/drivers/mailbox/mailbox.c
> index 2acc6ec229a4..22eb8f3213be 100644
> --- a/drivers/mailbox/mailbox.c
> +++ b/drivers/mailbox/mailbox.c
> @@ -218,6 +218,29 @@ bool mbox_client_peek_data(struct mbox_chan *chan)
>  }
>  EXPORT_SYMBOL_GPL(mbox_client_peek_data);
>  
> +/**
> + * mbox_chan_tx_slots_available - Query the number of available TX queue slots.
> + * @chan: Mailbox channel to query.
> + *
> + * Clients may call this to check how many messages can be queued via
> + * mbox_send_message() before the channel's TX queue is full. This helps
> + * clients avoid the -ENOBUFS error without needing to increase
> + * MBOX_TX_QUEUE_LEN.
> + * This can be called from atomic context.
> + *
> + * Return: Number of available slots in the channel's TX queue.
> + */
> +unsigned int mbox_chan_tx_slots_available(struct mbox_chan *chan)
> +{
> +	unsigned int ret;
> +
> +	guard(spinlock_irqsave)(&chan->lock);
> +	ret = MBOX_TX_QUEUE_LEN - chan->msg_count;
> +
> +	return ret;
> +}
> +EXPORT_SYMBOL_GPL(mbox_chan_tx_slots_available);
> +
>  /**
>   * mbox_send_message -	For client to submit a message to be
>   *				sent to the remote.
> diff --git a/include/linux/mailbox_client.h b/include/linux/mailbox_client.h
> index c6eea9afb943..e5997120f45c 100644
> --- a/include/linux/mailbox_client.h
> +++ b/include/linux/mailbox_client.h
> @@ -45,6 +45,7 @@ int mbox_send_message(struct mbox_chan *chan, void *mssg);
>  int mbox_flush(struct mbox_chan *chan, unsigned long timeout);
>  void mbox_client_txdone(struct mbox_chan *chan, int r); /* atomic */
>  bool mbox_client_peek_data(struct mbox_chan *chan); /* atomic */
> +unsigned int mbox_chan_tx_slots_available(struct mbox_chan *chan); /* atomic */
>  void mbox_free_channel(struct mbox_chan *chan); /* may sleep */
>  
>  #endif /* __MAILBOX_CLIENT_H */
> -- 
> 2.43.0
> 

Re: [PATCH] mailbox: add API to query available TX queue slots

[Shah, Tanmay]

On 2/23/2026 9:29 AM, Bjorn Andersson wrote:
> On Mon, Feb 09, 2026 at 05:44:30PM -0600, jassisinghbrar@gmail.com wrote:
>> From: Jassi Brar <jassisinghbrar@gmail.com>
>>
>> Clients sometimes need to know whether the mailbox TX queue has room
>> before posting a new message.
> 
> This is rather vague, could you be more specific?
> 
>> Rather than exposing internal queue state
>> through a struct field, provide a proper accessor function that returns
>> the number of available slots for a given channel.
>>
>> This lets clients choose to back off when the queue is full instead of
>> hitting the -ENOBUFS error path and the misleading "Try increasing
>> MBOX_TX_QUEUE_LEN" warning.
>>
> 
> In the event that we're using the mailbox framework as a doorbell, I
> presume that the queue is full of duplicate rings already - so backing
> off it perfectly fine.
> 
> But in the case where the client actually uses the interface to convey
> data, what is the expected way for the client to know when to make
> another attempt?
> 

Hi Bjorn,

Thanks for the reviews.
As per my understanding client would have to poll this API and make sure
queue is not full to send the new data.

Polling can happen at regular interval. I think mbox tx client data
structure can set interval time at which rate the next
mbox_send_message() will be called if queue has data. Client can poll
this API at the same interval. minimum time is I think 1ms.

I will let Jassi add more to this understanding.

Thanks,
Tanmay

> Regards,
> Bjorn
> 
>> Signed-off-by: Jassi Brar <jassisinghbrar@gmail.com>
>> ---
>>  drivers/mailbox/mailbox.c      | 23 +++++++++++++++++++++++
>>  include/linux/mailbox_client.h |  1 +
>>  2 files changed, 24 insertions(+)
>>
>> diff --git a/drivers/mailbox/mailbox.c b/drivers/mailbox/mailbox.c
>> index 2acc6ec229a4..22eb8f3213be 100644
>> --- a/drivers/mailbox/mailbox.c
>> +++ b/drivers/mailbox/mailbox.c
>> @@ -218,6 +218,29 @@ bool mbox_client_peek_data(struct mbox_chan *chan)
>>  }
>>  EXPORT_SYMBOL_GPL(mbox_client_peek_data);
>>  
>> +/**
>> + * mbox_chan_tx_slots_available - Query the number of available TX queue slots.
>> + * @chan: Mailbox channel to query.
>> + *
>> + * Clients may call this to check how many messages can be queued via
>> + * mbox_send_message() before the channel's TX queue is full. This helps
>> + * clients avoid the -ENOBUFS error without needing to increase
>> + * MBOX_TX_QUEUE_LEN.
>> + * This can be called from atomic context.
>> + *
>> + * Return: Number of available slots in the channel's TX queue.
>> + */
>> +unsigned int mbox_chan_tx_slots_available(struct mbox_chan *chan)
>> +{
>> +	unsigned int ret;
>> +
>> +	guard(spinlock_irqsave)(&chan->lock);
>> +	ret = MBOX_TX_QUEUE_LEN - chan->msg_count;
>> +
>> +	return ret;
>> +}
>> +EXPORT_SYMBOL_GPL(mbox_chan_tx_slots_available);
>> +
>>  /**
>>   * mbox_send_message -	For client to submit a message to be
>>   *				sent to the remote.
>> diff --git a/include/linux/mailbox_client.h b/include/linux/mailbox_client.h
>> index c6eea9afb943..e5997120f45c 100644
>> --- a/include/linux/mailbox_client.h
>> +++ b/include/linux/mailbox_client.h
>> @@ -45,6 +45,7 @@ int mbox_send_message(struct mbox_chan *chan, void *mssg);
>>  int mbox_flush(struct mbox_chan *chan, unsigned long timeout);
>>  void mbox_client_txdone(struct mbox_chan *chan, int r); /* atomic */
>>  bool mbox_client_peek_data(struct mbox_chan *chan); /* atomic */
>> +unsigned int mbox_chan_tx_slots_available(struct mbox_chan *chan); /* atomic */
>>  void mbox_free_channel(struct mbox_chan *chan); /* may sleep */
>>  
>>  #endif /* __MAILBOX_CLIENT_H */
>> -- 
>> 2.43.0
>>

Re: [PATCH] mailbox: add API to query available TX queue slots

[Jassi Brar]

On Mon, Feb 23, 2026 at 9:29 AM Bjorn Andersson <andersson@kernel.org> wrote:
>
> On Mon, Feb 09, 2026 at 05:44:30PM -0600, jassisinghbrar@gmail.com wrote:
> > From: Jassi Brar <jassisinghbrar@gmail.com>
> >
> > Clients sometimes need to know whether the mailbox TX queue has room
> > before posting a new message.
>
> This is rather vague, could you be more specific?
>
> > Rather than exposing internal queue state
> > through a struct field, provide a proper accessor function that returns
> > the number of available slots for a given channel.
> >
> > This lets clients choose to back off when the queue is full instead of
> > hitting the -ENOBUFS error path and the misleading "Try increasing
> > MBOX_TX_QUEUE_LEN" warning.
> >
>
> In the event that we're using the mailbox framework as a doorbell, I
> presume that the queue is full of duplicate rings already - so backing
> off it perfectly fine.
>
> But in the case where the client actually uses the interface to convey
> data, what is the expected way for the client to know when to make
> another attempt?
>
Whatever the client is currently using. It just backs off for another
such signal when mbox_chan_tx_slots_available() returns 0.
If a client submits periodically, it will back off for another period.
If a client submits upon receiving ack packet for last submission, it
will back off until it gets another ack packet.

Cheers!
Jassi

Re: [PATCH] mailbox: add API to query available TX queue slots

[Bjorn Andersson]

On Mon, Feb 23, 2026 at 06:35:16PM -0600, Jassi Brar wrote:
> On Mon, Feb 23, 2026 at 9:29 AM Bjorn Andersson <andersson@kernel.org> wrote:
> >
> > On Mon, Feb 09, 2026 at 05:44:30PM -0600, jassisinghbrar@gmail.com wrote:
> > > From: Jassi Brar <jassisinghbrar@gmail.com>
> > >
> > > Clients sometimes need to know whether the mailbox TX queue has room
> > > before posting a new message.
> >
> > This is rather vague, could you be more specific?
> >
> > > Rather than exposing internal queue state
> > > through a struct field, provide a proper accessor function that returns
> > > the number of available slots for a given channel.
> > >
> > > This lets clients choose to back off when the queue is full instead of
> > > hitting the -ENOBUFS error path and the misleading "Try increasing
> > > MBOX_TX_QUEUE_LEN" warning.
> > >
> >
> > In the event that we're using the mailbox framework as a doorbell, I
> > presume that the queue is full of duplicate rings already - so backing
> > off it perfectly fine.
> >
> > But in the case where the client actually uses the interface to convey
> > data, what is the expected way for the client to know when to make
> > another attempt?
> >
> Whatever the client is currently using. It just backs off for another
> such signal when mbox_chan_tx_slots_available() returns 0.
> If a client submits periodically, it will back off for another period.
> If a client submits upon receiving ack packet for last submission, it
> will back off until it gets another ack packet.
> 

Thanks for clarifying.

Regards,
Bjorn

> Cheers!
> Jassi

Re: [PATCH] mailbox: add API to query available TX queue slots

[Shah, Tanmay]

On 2/26/2026 9:53 PM, Bjorn Andersson wrote:
> On Mon, Feb 23, 2026 at 06:35:16PM -0600, Jassi Brar wrote:
>> On Mon, Feb 23, 2026 at 9:29 AM Bjorn Andersson <andersson@kernel.org> wrote:
>>>
>>> On Mon, Feb 09, 2026 at 05:44:30PM -0600, jassisinghbrar@gmail.com wrote:
>>>> From: Jassi Brar <jassisinghbrar@gmail.com>
>>>>
>>>> Clients sometimes need to know whether the mailbox TX queue has room
>>>> before posting a new message.
>>>
>>> This is rather vague, could you be more specific?
>>>
>>>> Rather than exposing internal queue state
>>>> through a struct field, provide a proper accessor function that returns
>>>> the number of available slots for a given channel.
>>>>
>>>> This lets clients choose to back off when the queue is full instead of
>>>> hitting the -ENOBUFS error path and the misleading "Try increasing
>>>> MBOX_TX_QUEUE_LEN" warning.
>>>>
>>>
>>> In the event that we're using the mailbox framework as a doorbell, I
>>> presume that the queue is full of duplicate rings already - so backing
>>> off it perfectly fine.
>>>
>>> But in the case where the client actually uses the interface to convey
>>> data, what is the expected way for the client to know when to make
>>> another attempt?
>>>
>> Whatever the client is currently using. It just backs off for another
>> such signal when mbox_chan_tx_slots_available() returns 0.
>> If a client submits periodically, it will back off for another period.
>> If a client submits upon receiving ack packet for last submission, it
>> will back off until it gets another ack packet.
>>
> 
> Thanks for clarifying.
> 

Hi Jassi,

What is the next step for this patch? When it is expected to merge?


Thank You,
Tanmay

> Regards,
> Bjorn
> 
>> Cheers!
>> Jassi

Re: [PATCH] mailbox: add API to query available TX queue slots

[Jassi Brar]

On Mon, Feb 9, 2026 at 5:44 PM <jassisinghbrar@gmail.com> wrote:
>
> From: Jassi Brar <jassisinghbrar@gmail.com>
>
> Clients sometimes need to know whether the mailbox TX queue has room
> before posting a new message. Rather than exposing internal queue state
> through a struct field, provide a proper accessor function that returns
> the number of available slots for a given channel.
>
> This lets clients choose to back off when the queue is full instead of
> hitting the -ENOBUFS error path and the misleading "Try increasing
> MBOX_TX_QUEUE_LEN" warning.
>
> Signed-off-by: Jassi Brar <jassisinghbrar@gmail.com>
> ---
>  drivers/mailbox/mailbox.c      | 23 +++++++++++++++++++++++
>  include/linux/mailbox_client.h |  1 +
>  2 files changed, 24 insertions(+)
>
> diff --git a/drivers/mailbox/mailbox.c b/drivers/mailbox/mailbox.c
> index 2acc6ec229a4..22eb8f3213be 100644
> --- a/drivers/mailbox/mailbox.c
> +++ b/drivers/mailbox/mailbox.c
> @@ -218,6 +218,29 @@ bool mbox_client_peek_data(struct mbox_chan *chan)
>  }
>  EXPORT_SYMBOL_GPL(mbox_client_peek_data);
>
> +/**
> + * mbox_chan_tx_slots_available - Query the number of available TX queue slots.
> + * @chan: Mailbox channel to query.
> + *
> + * Clients may call this to check how many messages can be queued via
> + * mbox_send_message() before the channel's TX queue is full. This helps
> + * clients avoid the -ENOBUFS error without needing to increase
> + * MBOX_TX_QUEUE_LEN.
> + * This can be called from atomic context.
> + *
> + * Return: Number of available slots in the channel's TX queue.
> + */
> +unsigned int mbox_chan_tx_slots_available(struct mbox_chan *chan)
> +{
> +       unsigned int ret;
> +
> +       guard(spinlock_irqsave)(&chan->lock);
> +       ret = MBOX_TX_QUEUE_LEN - chan->msg_count;
> +
> +       return ret;
> +}
> +EXPORT_SYMBOL_GPL(mbox_chan_tx_slots_available);
> +
>  /**
>   * mbox_send_message - For client to submit a message to be
>   *                             sent to the remote.
> diff --git a/include/linux/mailbox_client.h b/include/linux/mailbox_client.h
> index c6eea9afb943..e5997120f45c 100644
> --- a/include/linux/mailbox_client.h
> +++ b/include/linux/mailbox_client.h
> @@ -45,6 +45,7 @@ int mbox_send_message(struct mbox_chan *chan, void *mssg);
>  int mbox_flush(struct mbox_chan *chan, unsigned long timeout);
>  void mbox_client_txdone(struct mbox_chan *chan, int r); /* atomic */
>  bool mbox_client_peek_data(struct mbox_chan *chan); /* atomic */
> +unsigned int mbox_chan_tx_slots_available(struct mbox_chan *chan); /* atomic */
>  void mbox_free_channel(struct mbox_chan *chan); /* may sleep */
>
>  #endif /* __MAILBOX_CLIENT_H */
> --
> 2.43.0
>
Applied to mailbox/for-next