Background thread documentation inconsistency

9 posts / 0 new
Last post
Eugene Gershtein
Eugene Gershtein's picture
Offline
Last seen: 6 days 17 hours ago
Joined: 03/19/2019 - 12:23pm
Background thread documentation inconsistency

In the AWE Core Integration Guide, Section 2.6.1 (Basic Threading Model) says:

Background Processing – In the background / main() thread, non-real-time tasks are
processed. The AWE Core has a single function that must be called from this context:
awe_fwTick();
This function handles all background tasks in AWE Core, including,
among other things, the processing of tuning commands.

Later, in Section 3.2 on integrating the tuning interface, Step 7 contradicts this by saying:

In the background thread, add repeated calls awe_fwTuningTick() to continually process
data as it arrives. This function will execute commands (once they’re fully received), and
will return REPLY_READY when a reply packet has been generated.

Which of these is actually correct?  Are there actually two APIs to call from the background thread?  Is there a different thread from which awe_fwTuningTick() needs to be called?

Andrew
Offline
Last seen: 1 week 2 days ago
Joined: 04/12/2018 - 9:25am

Hi Eugene,

Although similarly named, these API calls do different things. They both need to be called in separate threads, where awe_fwTuningTick is at a higher priority.

awe_fwTuningTick actually processes the incoming command packets, and awe_fwTick is used internally to do what we call "Deferred Processing", where operations that may take more time (computing filter coeff, etc) can happen in a background thread without interrupting packet processing or RT audio. Hope this helps!

 

Eugene Gershtein
Eugene Gershtein's picture
Offline
Last seen: 6 days 17 hours ago
Joined: 03/19/2019 - 12:23pm

Andrew,

I understand that they're not the same API even though they're not similarly named.  My question has to do with the inconsistency in the documentation.  Are you saying, then, that the four-thread model discussed in Section 2.6.1 is actually a five-thread model with two "background" threads?

Andrew
Offline
Last seen: 1 week 2 days ago
Joined: 04/12/2018 - 9:25am

Hi Eugene, yes this is an error in the documentation. Thank you for pointing it out, and we are working on a new API and improved documentation. awe_fwTick does not do packet processing, only deferred processing. So there are still only four threads, however we now recommend doing  both deferred processing and packet processing in the same low priority thread. Here is an example of an idle loop that would do packet processing and deferred processing. 

  while(TRUE)
   {
       // Do any packet processing
       awe_pltTick();
            
       // DO any deferred processing
          awe_fwTick();

   }   // End while

Eugene Gershtein
Eugene Gershtein's picture
Offline
Last seen: 6 days 17 hours ago
Joined: 03/19/2019 - 12:23pm

The fact that there's a completely undocumented awe_pltTick() API that needs to be called from the same thread as the awe_fwTick() API is good to know but isn't the question I was asking.

Can you please confirm that there does indeed need to be a fifth thread in the "four-thread model" mentioned in Sectino 2.6.1, sitting inbetween "Audio Processing" and "Background Processing" in terms of priority, which calls the awe_fwTuningTick() API?

And is it possible to get more than one response a day so that this issue doesn't take a week to resolve?

Thanks.

Chris Perry
Offline
Last seen: 3 weeks 2 hours ago
Joined: 07/16/2017 - 9:45am

awe_pltTick was a method that we wrote as sample code. It calls the API in question awe_fwTuningTick().

We require you to call in the same low priority thread awe_fwTick() to do any background deferred processing and then to call awe_fwTuningTick() to do any packet processing. The BSP author is responsible for making sure these two methods are atomic from each other and the easiest way to do that is to call first one and then the other in an idle loop context.

Here is an example:

awe_fwTick();

bReplyReady = awe_fwTuningTick();

if (bReplyReady)
{
      userSendReply();  // This is a user method that sends the reply back to the host
}

 

Chris Perry
Offline
Last seen: 3 weeks 2 hours ago
Joined: 07/16/2017 - 9:45am

The threading model is as follows from highest priority to lowest:

UART driver or interrupt handler to send a byte or receive a byte 
audio frame DMA complete interrupt (this implements our notion of a master clock)
high level AWE processing
lower level AWE processing
idle loop  (perform deferred processing, tuning packet processing, control I/O processing)

Eugene Gershtein
Eugene Gershtein's picture
Offline
Last seen: 6 days 17 hours ago
Joined: 03/19/2019 - 12:23pm

Ok, I'm really confused now.  In your original response, you said:

these API calls do different things. They both need to be called in separate threads, where awe_fwTuningTick is at a higher priority

In your latest response, you say:

We require you to call in the same low priority thread awe_fwTick() to do any background deferred processing and then to call awe_fwTuningTick() to do any packet processing

Which one of these statements is correct?

Chris Perry
Offline
Last seen: 3 weeks 2 hours ago
Joined: 07/16/2017 - 9:45am

Please assume that the most recent responses are corrections for previous comments.