Fix comments and internal names about SEEK operation.
Legacy radio HAL named it SCAN and the name slipped through HAL 1.x
into HAL 2.0. I finally noticed it after HAL 2.0 was locked down.
Bug: 109740376
Test: build ow
Change-Id: I5ca4147227a7dd0c32248a279f03fb632d97258e
diff --git a/broadcastradio/2.0/ITunerCallback.hal b/broadcastradio/2.0/ITunerCallback.hal
index b20a0b2..a174c9c 100644
--- a/broadcastradio/2.0/ITunerCallback.hal
+++ b/broadcastradio/2.0/ITunerCallback.hal
@@ -18,7 +18,8 @@
interface ITunerCallback {
/**
* Method called by the HAL when a tuning operation fails asynchronously
- * following a step(), scan() or tune() command.
+ * following ITunerSession::tune(), ITunerSession::scan() or
+ * ITunerSession::step().
*
* This callback is only called when the step(), scan() or tune() command
* returned OK at first.
diff --git a/broadcastradio/2.0/ITunerSession.hal b/broadcastradio/2.0/ITunerSession.hal
index e891a23..3c27246 100644
--- a/broadcastradio/2.0/ITunerSession.hal
+++ b/broadcastradio/2.0/ITunerSession.hal
@@ -19,7 +19,7 @@
/**
* Tune to a specified program.
*
- * Automatically cancels pending scan, step or tune.
+ * Automatically cancels pending tune(), scan() or step().
* If the method returns OK, tuneFailed or currentProgramInfoChanged
* callback must be called.
*
@@ -33,9 +33,16 @@
tune(ProgramSelector program) generates (Result result);
/**
- * Tune to the next valid program.
+ * Tune (seek) to the next valid program on the "air".
*
- * Automatically cancels pending scan, step or tune.
+ * This might more naturally be called "seek" but for legacy reasons, the
+ * entry point remains "scan". This should not be confused with the actual
+ * scan operation (where the radio seeks through programs in a loop until
+ * user chooses to stay on one of them) nor background scan operation (that
+ * a tuner may do in order to locate all available programs. This function
+ * is meant to advance to the next detected program and stay there.
+ *
+ * Automatically cancels pending tune(), scan() or step().
* If the method returns OK, tuneFailed or currentProgramInfoChanged
* callback must be called.
*
@@ -44,20 +51,20 @@
* - DAB secondary service.
*
* As an implementation detail, the HAL has the option to perform an actual
- * scan or select the next program from the list retrieved in the
+ * seek or select the next program from the list retrieved in the
* background, if one is not stale.
*
* @param directionUp True to change towards higher numeric values
* (frequency, channel number), false towards lower.
* @param skipSubChannel Don't tune to subchannels.
- * @return result OK if the scan has successfully started.
+ * @return result OK if the operation has successfully started.
*/
scan(bool directionUp, bool skipSubChannel) generates (Result result);
/**
* Tune to the adjacent channel, which may not be occupied by any program.
*
- * Automatically cancels pending scan, step or tune.
+ * Automatically cancels pending tune(), scan() or step().
* If the method returns OK, tuneFailed or currentProgramInfoChanged
* callback must be called.
*
@@ -70,7 +77,7 @@
step(bool directionUp) generates (Result result);
/**
- * Cancel a scan, step or tune operation.
+ * Cancel a pending tune(), scan() or step().
*
* If there is no such operation running, the call must be ignored.
*/
diff --git a/broadcastradio/2.0/default/TunerSession.cpp b/broadcastradio/2.0/default/TunerSession.cpp
index 56a3508..da97562 100644
--- a/broadcastradio/2.0/default/TunerSession.cpp
+++ b/broadcastradio/2.0/default/TunerSession.cpp
@@ -42,7 +42,7 @@
namespace delay {
-static constexpr auto scan = 200ms;
+static constexpr auto seek = 200ms;
static constexpr auto step = 100ms;
static constexpr auto tune = 150ms;
static constexpr auto list = 1s;
@@ -131,11 +131,11 @@
if (list.empty()) {
mIsTuneCompleted = false;
auto task = [this, directionUp]() {
- ALOGI("Performing failed scan up=%d", directionUp);
+ ALOGI("Performing failed seek up=%d", directionUp);
mCallback->onTuneFailed(Result::TIMEOUT, {});
};
- mThread.schedule(task, delay::scan);
+ mThread.schedule(task, delay::seek);
return Result::OK;
}
@@ -162,12 +162,12 @@
mIsTuneCompleted = false;
auto task = [this, tuneTo, directionUp]() {
- ALOGI("Performing scan up=%d", directionUp);
+ ALOGI("Performing seek up=%d", directionUp);
lock_guard<mutex> lk(mMut);
tuneInternalLocked(tuneTo);
};
- mThread.schedule(task, delay::scan);
+ mThread.schedule(task, delay::seek);
return Result::OK;
}
diff --git a/broadcastradio/2.0/default/VirtualProgram.h b/broadcastradio/2.0/default/VirtualProgram.h
index e1c4f75..6502616 100644
--- a/broadcastradio/2.0/default/VirtualProgram.h
+++ b/broadcastradio/2.0/default/VirtualProgram.h
@@ -40,8 +40,8 @@
operator ProgramInfo() const;
/**
- * Defines order on how virtual programs appear on the "air" with
- * ITunerSession::scan operation.
+ * Defines order in which virtual programs appear on the "air" with
+ * ITunerSession::scan().
*
* It's for default implementation purposes, may not be complete or correct.
*/
diff --git a/broadcastradio/2.0/types.hal b/broadcastradio/2.0/types.hal
index 1ce61df..987572a 100644
--- a/broadcastradio/2.0/types.hal
+++ b/broadcastradio/2.0/types.hal
@@ -184,18 +184,20 @@
* lowerBound + channelNumber * spacing, up to upperBound.
*/
struct AmFmBandRange {
- /** The frequency of the first channel within the range. */
+ /** The frequency (in kHz) of the first channel within the range. */
uint32_t lowerBound;
- /** The frequency of the last channel within the range. */
+ /** The frequency (in kHz) of the last channel within the range. */
uint32_t upperBound;
- /** Channel grid resolution, how far apart are the channels. */
+ /** Channel grid resolution (in kHz), how far apart are the channels. */
uint32_t spacing;
/**
- * Spacing used when scanning for channels. It's a multiply of spacing and
- * allows to skip some channels when scanning to make it faster.
+ * Channel spacing (in kHz) used to speed up seeking to the next station
+ * via the ITunerSession::scan() operation.
+ *
+ * It must be a multiple of channel grid resolution.
*
* Tuner may first quickly check every n-th channel and if it detects echo
* from a station, it fine-tunes to find the exact frequency.
@@ -415,9 +417,10 @@
TRAFFIC_ANNOUNCEMENT = 1 << 3,
/**
- * Tuned to a program (not playing a static).
+ * Tuned to a program (not playing static).
*
- * It's the same condition that would stop scan() operation.
+ * It's the same condition that would stop a seek operation
+ * (ie: ITunerSession::scan()).
*
* By definition, this flag must be set for all items on the program list.
*/
diff --git a/broadcastradio/2.0/vts/functional/VtsHalBroadcastradioV2_0TargetTest.cpp b/broadcastradio/2.0/vts/functional/VtsHalBroadcastradioV2_0TargetTest.cpp
index 62b0037..3d7039d 100644
--- a/broadcastradio/2.0/vts/functional/VtsHalBroadcastradioV2_0TargetTest.cpp
+++ b/broadcastradio/2.0/vts/functional/VtsHalBroadcastradioV2_0TargetTest.cpp
@@ -308,7 +308,7 @@
* - there is at least one AM/FM band configured;
* - FM Deemphasis and RDS are correctly configured for FM-capable radio;
* - all channel grids (frequency ranges and spacings) are valid;
- * - scan spacing is a multiply of manual spacing value.
+ * - seek spacing is a multiple of the manual spacing value.
*/
TEST_F(BroadcastRadioHalTest, GetAmFmRegionConfig) {
AmFmRegionConfig config;
@@ -341,7 +341,7 @@
* - there is at least one AM/FM range supported;
* - there is at least one de-emphasis filter mode supported for FM-capable radio;
* - all channel grids (frequency ranges and spacings) are valid;
- * - scan spacing is not set.
+ * - seek spacing is not set.
*/
TEST_F(BroadcastRadioHalTest, GetAmFmRegionConfigCapabilities) {
AmFmRegionConfig config;
@@ -501,14 +501,14 @@
}
/**
- * Test scanning to next/prev station.
+ * Test seeking to next/prev station via ITunerSession::scan().
*
* Verifies that:
* - the method succeeds;
* - the program info is changed within timeout::tune;
* - works both directions and with or without skipping sub-channel.
*/
-TEST_F(BroadcastRadioHalTest, Scan) {
+TEST_F(BroadcastRadioHalTest, Seek) {
ASSERT_TRUE(openSession());
// TODO(b/69958777): see FmTune workaround
@@ -564,8 +564,8 @@
ASSERT_TRUE(openSession());
for (int i = 0; i < 10; i++) {
- auto scanResult = mSession->scan(true /* up */, true /* skip subchannel */);
- ASSERT_EQ(Result::OK, scanResult);
+ auto result = mSession->scan(true /* up */, true /* skip subchannel */);
+ ASSERT_EQ(Result::OK, result);
auto cancelResult = mSession->cancel();
ASSERT_TRUE(cancelResult.isOk());