C HAL function to check Serial FIFO status

[bridadan]

Description

• Type: Enhancement
• Related issue: There is no tests to verify that UART TX is complete #1849
• Priority: Minor

---

Enhancement

Reason to enhance or problem with existing solution
When using the Serial API, most implementations take the to-be-transmitted data and place it in the UART hardware's FIFO. At this point the function returns, however there is no way to actually check via the mbed API whether this data has actually been transmitted "on the wire".

Suggested enhancement
It has been suggested in past discussions (#1849, #3132, #2966) to add a C HAL function that would allow applications to check if the FIFO buffer is empty. This would allow applications to ensure all data has been transmitted before doing certain actions that affect the serial hardware (eg. sleep/deepsleep).

Pros

• Allows applications to delay until all data has been transmitted before moving on to other tasks.

Cons

• Time intensive task of ensure all targets implement this function
• Not all targets may support this functionality

FYI @LMESTM @0xc0170

[LMESTM]

@bridadan sounds good to me - problem is clearly exposed. Thx
[Mirrored to Jira]

[LMESTM]

@bridadan : any plan for adding the C API that is suggested here ?
[Mirrored to Jira]

[0xc0170]

@bridadan : any plan for adding the C API that is suggested here ?

It has been asked few times recently (due to reset of MCU and sleep). We will consider this while reviewing the current serial HAL API. I can't comment on any specific date at the moment. Thanks for bringing this up again.

cc @c1728p9 @bulislaw @scartmell-arm
[Mirrored to Jira]

[adbridge]

Internal Jira reference: https://jira.arm.com/browse/IOTHAL-75

[daniel-maiorano]

Any news on this?

[amak-cy]

Hello is there any updates here?

One additional question:
Whom responsibility is to provide HW readiness to enter or not into the Deep Sleep? mbed-os (hal) or application level?

I mean for example the UART has not empty TX buffer and all data in this buffer would be lost if we just enter Deep Sleep (without any additional actions).

[cmonr]

Hmm... @ARMmbed/mbed-os-hal Any updates?

@kjbracey-arm might know as well.

[amak-cy]

simple example

With enable MBED_TICKLESS we have the following code:

int main()
{
unsigned int i=0,m;
while (true) {
led1 = !led1;
printf("%d", ++i);
printf(" ");
if(!(i%10)) {
printf("\n");
}
wait(0.1f); // When this delay is commented the deep sleep is not entered and prints work fine
}
}

1. When the wait(0.1) is in the code here the default idle hook function see that there is a lot of ticks and decides to put the CPU into Deep Sleep instead of Sleep. Then the buffer lost it data and there is nothing to print out after the the Deep Sleep.

2. If we comment the wait(0.1) then the Deep Sleep is not entered and prints work just fine.

So how to avoid situation in #1? Should we update the hal_deepsleep not enter into the Deep Sleep if some HW indicated that it is not yet ready to enter into Deep Sleep.

More over, it looks like that greentea tests do not support such graceful low power transitions.
If the UART buffer is not empty before Deep Sleep and for this reason we did not have a Deep Sleep the "deep-sleep - high-speed clocks are turned off" case fails. As the test do not expect to have a kind of valid rejection of putting the CPU into Deep Sleep.

I think the following should discussed in a separate thread but lets start from here
We found one more interesting thing in sleep greentea tests -
SERIAL_FLUSH_TIME_MS 20 - this define considers that all FIFO buffers are 16 bits?
16 * 8 * 1000 / 9600 = 13.3 (ms). So set wait time to 40 * 20ms here for safe.

What if we have 128 bits wide buffer?
For this buffer we need to have SERIAL_FLUSH_TIME_MS -> 150:
128 * 10 * 1000 / 9600 = 133.3 ms

Can I get a justification about the 20 ms for SERIAL_FLUSH_TIME_MS define?

I think it is too much here, but let it be the starting point of discussion. Will continue in whatever thread you tell me to jump.

[donatieng]

Hello, We're planning to improve the UART HAL APIs - this is something we've flagged and take into account.

@amak-cy Currently drivers can prevent the MCU to go into deep sleep.

[kjbracey]

Related issue: #9770

[amak-cy]

Hello

Any updates on this request?

[ciarmcom]

Thank you for raising this issue. Please note we have updated our policies and
now only defects should be raised directly in GitHub. Going forward questions and
enhancements will be considered in our forums, https://forums.mbed.com/ . If this
issue is still relevant please re-raise it there.
This GitHub issue will now be closed.