Introduce PushPullFIFO class and remove other FIFOs

third_party/WebKit/Source/platform/audio/PushPullFIFOTest.cpp

+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#include "platform/audio/PushPullFIFO.h"
+
+#include "platform/audio/AudioUtilities.h"
+#include "platform/testing/TestingPlatformSupport.h"
+#include "testing/gtest/include/gtest/gtest.h"
+#include "wtf/PtrUtil.h"
+#include <memory>
+#include <vector>
+
+namespace blink {
+
+namespace {
+
+// Check the basic contract of FIFO.
+TEST(PushPullFIFOBasicTest, BasicTests) {
+  // This suppresses the multi-thread warning for GTest. Potently it increases
+  // the test execution time, but this specific test is very short and simple.
+  ::testing::FLAGS_gtest_death_test_style = "threadsafe";
+
+  // FIFO length exceeding the maximum length allowed will cause crash.
+  EXPECT_DEATH(new PushPullFIFO(2, kMaxFIFOLength + 1),
+               "m_fifoLength <= kMaxFIFOLength");
+
+  std::unique_ptr<PushPullFIFO> testFifo =
+      WTF::wrapUnique(new PushPullFIFO(2, 1024));
+
+  // The input bus length must be |AudioUtilities::kRenderQuantumFrames|.
+  RefPtr<AudioBus> inputBusOf129Frames =
+      AudioBus::create(2, AudioUtilities::kRenderQuantumFrames + 1);
+  EXPECT_DEATH(testFifo->push(inputBusOf129Frames.get()),
+               "inputBus->length.* == .*kRenderQuantumFrames");
+  RefPtr<AudioBus> inputBusOf127Frames =
+      AudioBus::create(2, AudioUtilities::kRenderQuantumFrames - 1);
+  EXPECT_DEATH(testFifo->push(inputBusOf127Frames.get()),
+               "inputBus->length.* == .*kRenderQuantumFrames");
+
+  // Pull request frames cannot exceed the length of output bus.
+  RefPtr<AudioBus> outputBusOf512Frames = AudioBus::create(2, 512);
+  EXPECT_DEATH(testFifo->pull(outputBusOf512Frames.get(), 513),
+               "framesRequested <= outputBus->length.*");
+
+  // Pull request frames cannot exceed the length of FIFO.
+  RefPtr<AudioBus> outputBusOf1025Frames = AudioBus::create(2, 1025);
+  EXPECT_DEATH(testFifo->pull(outputBusOf1025Frames.get(), 1025),
+               "framesRequested <= m_fifoLength");
+}
+
+// Fills each AudioChannel in an AudioBus with a series of linearly increasing
+// values starting from |startingValue| and incrementing by 1. Then return value
+// will be |startingValue| + |bus_length|.
+size_t fillBusWithLinearRamp(AudioBus* targetBus, size_t startingValue) {
+  for (unsigned c = 0; c < targetBus->numberOfChannels(); ++c) {
+    float* busChannel = targetBus->channel(c)->mutableData();
+    for (size_t i = 0; i < targetBus->channel(c)->length(); ++i) {
+      busChannel[i] = static_cast<float>(startingValue + i);
+    }
+  }
+  return startingValue + targetBus->length();
+}
+
+// Inspect the content of AudioBus with a given set of index and value across
+// channels.
+bool verifyBusValueAtIndex(AudioBus* targetBus,
+                           int index,
+                           float expectedValue) {
+  for (unsigned c = 0; c < targetBus->numberOfChannels(); ++c) {
+    float* busChannel = targetBus->channel(c)->mutableData();
+    if (busChannel[index] != expectedValue) {
+      LOG(ERROR) << ">> [FAIL] expected " << expectedValue << " at index "
+                 << index << " but got " << busChannel[index] << ".";
+      return false;
+    }
+  }
+  return true;
+}
+
+struct FIFOAction {
+  // The type of action; "PUSH" or "PULL".
+  const char* action;
+  // Number of frames for the operation.
+  const size_t numberOfFrames;
+};
+
+struct AudioBusSample {
+  // The frame index of a sample in the bus.
+  const size_t index;
+  // The value at the |index| above.
+  const float value;
+};
+
+struct FIFOTestSetup {
+  // Length of FIFO to be created for test case.
+  const size_t fifoLength;
+  // Channel count of FIFO to be created for test case.
+  const unsigned numberOfChannels;
+  // A list of |FIFOAction| entries to be performed in test case.
+  const std::vector<FIFOAction> fifoActions;
+};
+
+struct FIFOTestExpectedState {
+  // Expected read index in FIFO.
+  const size_t indexRead;
+  // Expected write index in FIFO.
+  const size_t indexWrite;
+  // Expected overflow count in FIFO.
+  const unsigned overflowCount;
+  // Expected underflow count in FIFO.
+  const unsigned underflowCount;
+  // A list of expected |AudioBusSample| entries for the FIFO bus.
+  const std::vector<AudioBusSample> fifoSamples;
+  // A list of expected |AudioBusSample| entries for the output bus.
+  const std::vector<AudioBusSample> outputSamples;
+};
+
+// The data structure for the parameterized test cases.
+struct FIFOTestParam {
+  FIFOTestSetup setup;
+  FIFOTestExpectedState expectedState;
+};
+
+std::ostream& operator<<(std::ostream& out, const FIFOTestParam& param) {
+  out << "fifoLength=" << param.setup.fifoLength
+      << " numberOfChannels=" << param.setup.numberOfChannels;
+  return out;
+}
+
+class PushPullFIFOFeatureTest : public ::testing::TestWithParam<FIFOTestParam> {
+};
+
+TEST_P(PushPullFIFOFeatureTest, FeatureTests) {
+  const FIFOTestSetup setup = GetParam().setup;
+  const FIFOTestExpectedState expectedState = GetParam().expectedState;
+
+  // Create a FIFO with a specified configuration.
+  std::unique_ptr<PushPullFIFO> fifo = WTF::wrapUnique(
+      new PushPullFIFO(setup.numberOfChannels, setup.fifoLength));
+
+  RefPtr<AudioBus> outputBus;
+
+  // Iterate all the scheduled push/pull actions.
+  size_t frameCounter = 0;
+  for (const auto& action : setup.fifoActions) {
+    if (strcmp(action.action, "PUSH") == 0) {
+      RefPtr<AudioBus> inputBus =
+          AudioBus::create(setup.numberOfChannels, action.numberOfFrames);
+      frameCounter = fillBusWithLinearRamp(inputBus.get(), frameCounter);
+      fifo->push(inputBus.get());
+      LOG(INFO) << "PUSH " << action.numberOfFrames
+                << " frames (frameCounter=" << frameCounter << ")";
+    } else {
+      outputBus =
+          AudioBus::create(setup.numberOfChannels, action.numberOfFrames);
+      fifo->pull(outputBus.get(), action.numberOfFrames);
+      LOG(INFO) << "PULL " << action.numberOfFrames << " frames";
+    }
+  }
+
+  // Get FIFO config data.
+  const PushPullFIFOStateForTest actualState = fifo->getStateForTest();
+
+  // Verify the read/write indexes.
+  EXPECT_EQ(expectedState.indexRead, actualState.indexRead);
+  EXPECT_EQ(expectedState.indexWrite, actualState.indexWrite);
+  EXPECT_EQ(expectedState.overflowCount, actualState.overflowCount);
+  EXPECT_EQ(expectedState.underflowCount, actualState.underflowCount);
+
+  // Verify in-FIFO samples.
+  for (const auto& sample : expectedState.fifoSamples) {
+    EXPECT_TRUE(verifyBusValueAtIndex(fifo->bus(), sample.index, sample.value));
+  }
+
+  // Verify samples from the most recent output bus.
+  for (const auto& sample : expectedState.outputSamples) {
+    EXPECT_TRUE(
+        verifyBusValueAtIndex(outputBus.get(), sample.index, sample.value));
+  }
+}
+
+FIFOTestParam featureTestParams[] = {
+    // Test cases 0 ~ 3: Regular operation on various channel configuration.
+    //  - Mono, Stereo, Quad, 5.1.
+    //  - FIFO length and pull size are RQ-aligned.
+    {{512, 1, {{"PUSH", 128}, {"PUSH", 128}, {"PULL", 256}}},
+     {256, 256, 0, 0, {{0, 0}}, {{0, 0}, {255, 255}}}},
+
+    {{512, 2, {{"PUSH", 128}, {"PUSH", 128}, {"PULL", 256}}},
+     {256, 256, 0, 0, {{0, 0}}, {{0, 0}, {255, 255}}}},
+
+    {{512, 4, {{"PUSH", 128}, {"PUSH", 128}, {"PULL", 256}}},
+     {256, 256, 0, 0, {{0, 0}}, {{0, 0}, {255, 255}}}},
+
+    {{512, 6, {{"PUSH", 128}, {"PUSH", 128}, {"PULL", 256}}},
+     {256, 256, 0, 0, {{0, 0}}, {{0, 0}, {255, 255}}}},
+
+    // Test case 4: Unusual FIFO and Pull length.
+    //  - FIFO and pull length that are not RQ-aligned.
+    //  - Check if the indexes are wrapping around correctly.
+    //  - Check if the output bus starts and ends with correct values.
+    {{997,
+      1,
+      {
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PULL", 449},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PULL", 449},
+      }},
+     {898, 27, 0, 0, {{898, 898}, {27, 27}}, {{0, 449}, {448, 897}}}},

[o1ka, 2017/02/02 16:30:25]

These values require comments, otherwise it;s really hard to understand what is
verified.

[hongchan, 2017/02/02 19:55:23]

Done.

+
+    // Test case 5: Overflow
+    //  - Check overflow counter.
+    //  - After the overflow occurs, the read index must be moved to the write
+    //    index. Thus pulled frames must not contain overwritten data.
+    {{512,
+      3,
+      {
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PULL", 256},
+      }},
+     {384, 128, 1, 0, {{384, 384}, {128, 128}}, {{0, 128}, {255, 383}}}},
+
+    // Test case 6: Overflow in unusual FIFO and pull length.
+    //  - Check overflow counter.
+    //  - After the overflow occurs, the read index must be moved to the write
+    //    index. Thus pulled frames must not contain overwritten data.
+    {{577,
+      5,
+      {
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PULL", 227},
+      }},
+     {290, 63, 1, 0, {{63, 63}, {290, 290}}, {{0, 63}, {226, 289}}}},
+
+    // Test case 7: Underflow
+    //  - Check underflow counter.
+    //  - After the underflow occurs, the write index must be moved to the read
+    //    index. Frames pulled after FIFO underflows must be zeroed.
+    {{512,
+      7,
+      {
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PULL", 384},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PULL", 384},
+      }},
+     {128,
+      128,
+      0,
+      1,
+      {{128, 128}},
+      {{0, 384}, {255, 639}, {256, 0}, {383, 0}}}},
+
+    // Test case 8: Underflow in unusual FIFO and pull length.
+    //  - Check underflow counter.
+    //  - After the underflow occurs, the write index must be moved to the read
+    //    index. Frames pulled after FIFO underflows must be zeroed.
+    {{523,
+      11,
+      {
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PULL", 383},
+          {"PUSH", 128},
+          {"PUSH", 128},
+          {"PULL", 383},
+      }},
+     {117,
+      117,
+      0,
+      1,
+      {{117, 117}},
+      {{0, 383}, {256, 639}, {257, 0}, {382, 0}}}}};

[o1ka, 2017/02/02 16:30:25]

Another corner case to consider: Multiple pulls from an empty FIFO. (Whith such
a good testing framework we need to configure as may corner cases as we can.)

[hongchan, 2017/02/02 19:55:23]

Done.

[o1ka, 2017/02/03 10:41:17]

Right, but how about starting with Pull, without any pushes?

[hongchan, 2017/02/03 17:20:12]

I'll add another for this case. Done.

+
+INSTANTIATE_TEST_CASE_P(PushPullFIFOFeatureTest,
+                        PushPullFIFOFeatureTest,
+                        ::testing::ValuesIn(featureTestParams));
+
+}  // namespace
+
+}  // namespace blink