All of lore.kernel.org
 help / color / mirror / Atom feed
* [Qemu-devel] [PULL 0/4] More block layer patches for 2.7.0-rc2
@ 2016-08-08 11:52 Kevin Wolf
  2016-08-08 11:52 ` [Qemu-devel] [PULL 1/4] block/qdev: Let 'drive' property fall back to node name Kevin Wolf
                   ` (4 more replies)
  0 siblings, 5 replies; 6+ messages in thread
From: Kevin Wolf @ 2016-08-08 11:52 UTC (permalink / raw)
  To: qemu-block; +Cc: kwolf, peter.maydell, qemu-devel

The following changes since commit cf5198d58088e3b416fe517b3946e5120b342761:

  Merge remote-tracking branch 'remotes/rth/tags/pull-tcg-20160805' into staging (2016-08-08 10:39:18 +0100)

are available in the git repository at:


  git://repo.or.cz/qemu/kevin.git tags/for-upstream

for you to fetch changes up to a752e4786c19b0b368f4521a5dcbcce14882c3b1:

  iotests: fix 109 (2016-08-08 13:05:43 +0200)

----------------------------------------------------------------
More block layer patches for 2.7.0-rc2

----------------------------------------------------------------
Alberto Garcia (1):
      tests: Test blockjob IDs

Kevin Wolf (1):
      block/qdev: Let 'drive' property fall back to node name

Vladimir Sementsov-Ogievskiy (2):
      mirror: finish earlier on error
      iotests: fix 109

 block/mirror.c                   |   4 ++
 hw/core/qdev-properties-system.c |  11 ++-
 tests/Makefile.include           |   2 +
 tests/qemu-iotests/109           |   2 +-
 tests/qemu-iotests/109.out       |   8 +--
 tests/qemu-iotests/common.filter |   6 ++
 tests/test-blockjob.c            | 147 +++++++++++++++++++++++++++++++++++++++
 7 files changed, 174 insertions(+), 6 deletions(-)
 create mode 100644 tests/test-blockjob.c

^ permalink raw reply	[flat|nested] 6+ messages in thread

* [Qemu-devel] [PULL 1/4] block/qdev: Let 'drive' property fall back to node name
  2016-08-08 11:52 [Qemu-devel] [PULL 0/4] More block layer patches for 2.7.0-rc2 Kevin Wolf
@ 2016-08-08 11:52 ` Kevin Wolf
  2016-08-08 11:52 ` [Qemu-devel] [PULL 2/4] tests: Test blockjob IDs Kevin Wolf
                   ` (3 subsequent siblings)
  4 siblings, 0 replies; 6+ messages in thread
From: Kevin Wolf @ 2016-08-08 11:52 UTC (permalink / raw)
  To: qemu-block; +Cc: kwolf, peter.maydell, qemu-devel

If a qdev block device is created with an anonymous BlockBackend (i.e.
a node name rather than a BB name was given for the drive property),
qdev used to return an empty string when the property was read. This
patch fixes it to return the node name instead.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 hw/core/qdev-properties-system.c | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/hw/core/qdev-properties-system.c b/hw/core/qdev-properties-system.c
index 2ba2504..e55afe6 100644
--- a/hw/core/qdev-properties-system.c
+++ b/hw/core/qdev-properties-system.c
@@ -126,7 +126,16 @@ static void release_drive(Object *obj, const char *name, void *opaque)
 
 static char *print_drive(void *ptr)
 {
-    return g_strdup(blk_name(ptr));
+    const char *name;
+
+    name = blk_name(ptr);
+    if (!*name) {
+        BlockDriverState *bs = blk_bs(ptr);
+        if (bs) {
+            name = bdrv_get_node_name(bs);
+        }
+    }
+    return g_strdup(name);
 }
 
 static void get_drive(Object *obj, Visitor *v, const char *name, void *opaque,
-- 
1.8.3.1

^ permalink raw reply related	[flat|nested] 6+ messages in thread

* [Qemu-devel] [PULL 2/4] tests: Test blockjob IDs
  2016-08-08 11:52 [Qemu-devel] [PULL 0/4] More block layer patches for 2.7.0-rc2 Kevin Wolf
  2016-08-08 11:52 ` [Qemu-devel] [PULL 1/4] block/qdev: Let 'drive' property fall back to node name Kevin Wolf
@ 2016-08-08 11:52 ` Kevin Wolf
  2016-08-08 11:52 ` [Qemu-devel] [PULL 3/4] mirror: finish earlier on error Kevin Wolf
                   ` (2 subsequent siblings)
  4 siblings, 0 replies; 6+ messages in thread
From: Kevin Wolf @ 2016-08-08 11:52 UTC (permalink / raw)
  To: qemu-block; +Cc: kwolf, peter.maydell, qemu-devel

From: Alberto Garcia <berto@igalia.com>

Since 7f0317cfc8da6 we have API to specify the ID of block jobs and we
also guarantee that they are well-formed and unique.

This patch adds tests to check some common scenarios.

Signed-off-by: Alberto Garcia <berto@igalia.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 tests/Makefile.include |   2 +
 tests/test-blockjob.c  | 147 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 149 insertions(+)
 create mode 100644 tests/test-blockjob.c

diff --git a/tests/Makefile.include b/tests/Makefile.include
index ebecfa4..14be491 100644
--- a/tests/Makefile.include
+++ b/tests/Makefile.include
@@ -52,6 +52,7 @@ gcov-files-test-thread-pool-y = thread-pool.c
 gcov-files-test-hbitmap-y = util/hbitmap.c
 check-unit-y += tests/test-hbitmap$(EXESUF)
 gcov-files-test-hbitmap-y = blockjob.c
+check-unit-y += tests/test-blockjob$(EXESUF)
 check-unit-y += tests/test-blockjob-txn$(EXESUF)
 check-unit-y += tests/test-x86-cpuid$(EXESUF)
 # all code tested by test-x86-cpuid is inside topology.h
@@ -449,6 +450,7 @@ tests/test-coroutine$(EXESUF): tests/test-coroutine.o $(test-block-obj-y)
 tests/test-aio$(EXESUF): tests/test-aio.o $(test-block-obj-y)
 tests/test-rfifolock$(EXESUF): tests/test-rfifolock.o $(test-util-obj-y)
 tests/test-throttle$(EXESUF): tests/test-throttle.o $(test-block-obj-y)
+tests/test-blockjob$(EXESUF): tests/test-blockjob.o $(test-block-obj-y) $(test-util-obj-y)
 tests/test-blockjob-txn$(EXESUF): tests/test-blockjob-txn.o $(test-block-obj-y) $(test-util-obj-y)
 tests/test-thread-pool$(EXESUF): tests/test-thread-pool.o $(test-block-obj-y)
 tests/test-iov$(EXESUF): tests/test-iov.o $(test-util-obj-y)
diff --git a/tests/test-blockjob.c b/tests/test-blockjob.c
new file mode 100644
index 0000000..5b0e934
--- /dev/null
+++ b/tests/test-blockjob.c
@@ -0,0 +1,147 @@
+/*
+ * Blockjob tests
+ *
+ * Copyright Igalia, S.L. 2016
+ *
+ * Authors:
+ *  Alberto Garcia   <berto@igalia.com>
+ *
+ * This work is licensed under the terms of the GNU LGPL, version 2 or later.
+ * See the COPYING.LIB file in the top-level directory.
+ */
+
+#include "qemu/osdep.h"
+#include "qapi/error.h"
+#include "qemu/main-loop.h"
+#include "block/blockjob.h"
+#include "sysemu/block-backend.h"
+
+static const BlockJobDriver test_block_job_driver = {
+    .instance_size = sizeof(BlockJob),
+};
+
+static void block_job_cb(void *opaque, int ret)
+{
+}
+
+static BlockJob *do_test_id(BlockBackend *blk, const char *id,
+                            bool should_succeed)
+{
+    BlockJob *job;
+    Error *errp = NULL;
+
+    job = block_job_create(id, &test_block_job_driver, blk_bs(blk), 0,
+                           block_job_cb, NULL, &errp);
+    if (should_succeed) {
+        g_assert_null(errp);
+        g_assert_nonnull(job);
+        if (id) {
+            g_assert_cmpstr(job->id, ==, id);
+        } else {
+            g_assert_cmpstr(job->id, ==, blk_name(blk));
+        }
+    } else {
+        g_assert_nonnull(errp);
+        g_assert_null(job);
+        error_free(errp);
+    }
+
+    return job;
+}
+
+/* This creates a BlockBackend (optionally with a name) with a
+ * BlockDriverState inserted. */
+static BlockBackend *create_blk(const char *name)
+{
+    BlockBackend *blk = blk_new();
+    BlockDriverState *bs = bdrv_new();
+
+    blk_insert_bs(blk, bs);
+    bdrv_unref(bs);
+
+    if (name) {
+        Error *errp = NULL;
+        monitor_add_blk(blk, name, &errp);
+        g_assert_null(errp);
+    }
+
+    return blk;
+}
+
+/* This destroys the backend */
+static void destroy_blk(BlockBackend *blk)
+{
+    if (blk_name(blk)[0] != '\0') {
+        monitor_remove_blk(blk);
+    }
+
+    blk_remove_bs(blk);
+    blk_unref(blk);
+}
+
+static void test_job_ids(void)
+{
+    BlockBackend *blk[3];
+    BlockJob *job[3];
+
+    blk[0] = create_blk(NULL);
+    blk[1] = create_blk("drive1");
+    blk[2] = create_blk("drive2");
+
+    /* No job ID provided and the block backend has no name */
+    job[0] = do_test_id(blk[0], NULL, false);
+
+    /* These are all invalid job IDs */
+    job[0] = do_test_id(blk[0], "0id", false);
+    job[0] = do_test_id(blk[0], "",    false);
+    job[0] = do_test_id(blk[0], "   ", false);
+    job[0] = do_test_id(blk[0], "123", false);
+    job[0] = do_test_id(blk[0], "_id", false);
+    job[0] = do_test_id(blk[0], "-id", false);
+    job[0] = do_test_id(blk[0], ".id", false);
+    job[0] = do_test_id(blk[0], "#id", false);
+
+    /* This one is valid */
+    job[0] = do_test_id(blk[0], "id0", true);
+
+    /* We cannot have two jobs in the same BDS */
+    do_test_id(blk[0], "id1", false);
+
+    /* Duplicate job IDs are not allowed */
+    job[1] = do_test_id(blk[1], "id0", false);
+
+    /* But once job[0] finishes we can reuse its ID */
+    block_job_unref(job[0]);
+    job[1] = do_test_id(blk[1], "id0", true);
+
+    /* No job ID specified, defaults to the backend name ('drive1') */
+    block_job_unref(job[1]);
+    job[1] = do_test_id(blk[1], NULL, true);
+
+    /* Duplicate job ID */
+    job[2] = do_test_id(blk[2], "drive1", false);
+
+    /* The ID of job[2] would default to 'drive2' but it is already in use */
+    job[0] = do_test_id(blk[0], "drive2", true);
+    job[2] = do_test_id(blk[2], NULL, false);
+
+    /* This one is valid */
+    job[2] = do_test_id(blk[2], "id_2", true);
+
+    block_job_unref(job[0]);
+    block_job_unref(job[1]);
+    block_job_unref(job[2]);
+
+    destroy_blk(blk[0]);
+    destroy_blk(blk[1]);
+    destroy_blk(blk[2]);
+}
+
+int main(int argc, char **argv)
+{
+    qemu_init_main_loop(&error_abort);
+
+    g_test_init(&argc, &argv, NULL);
+    g_test_add_func("/blockjob/ids", test_job_ids);
+    return g_test_run();
+}
-- 
1.8.3.1

^ permalink raw reply related	[flat|nested] 6+ messages in thread

* [Qemu-devel] [PULL 3/4] mirror: finish earlier on error
  2016-08-08 11:52 [Qemu-devel] [PULL 0/4] More block layer patches for 2.7.0-rc2 Kevin Wolf
  2016-08-08 11:52 ` [Qemu-devel] [PULL 1/4] block/qdev: Let 'drive' property fall back to node name Kevin Wolf
  2016-08-08 11:52 ` [Qemu-devel] [PULL 2/4] tests: Test blockjob IDs Kevin Wolf
@ 2016-08-08 11:52 ` Kevin Wolf
  2016-08-08 11:52 ` [Qemu-devel] [PULL 4/4] iotests: fix 109 Kevin Wolf
  2016-08-08 14:56 ` [Qemu-devel] [PULL 0/4] More block layer patches for 2.7.0-rc2 Peter Maydell
  4 siblings, 0 replies; 6+ messages in thread
From: Kevin Wolf @ 2016-08-08 11:52 UTC (permalink / raw)
  To: qemu-block; +Cc: kwolf, peter.maydell, qemu-devel

From: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>

Stop to produce new async copy requests from mirror_iteration if
critical error (error action = BLOCK_ERROR_ACTION_REPORT) detected.

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 block/mirror.c | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/block/mirror.c b/block/mirror.c
index d6034f5..e0b3f41 100644
--- a/block/mirror.c
+++ b/block/mirror.c
@@ -419,6 +419,10 @@ static uint64_t coroutine_fn mirror_iteration(MirrorBlockJob *s)
             mirror_wait_for_io(s);
         }
 
+        if (s->ret < 0) {
+            return 0;
+        }
+
         mirror_clip_sectors(s, sector_num, &io_sectors);
         switch (mirror_method) {
         case MIRROR_METHOD_COPY:
-- 
1.8.3.1

^ permalink raw reply related	[flat|nested] 6+ messages in thread

* [Qemu-devel] [PULL 4/4] iotests: fix 109
  2016-08-08 11:52 [Qemu-devel] [PULL 0/4] More block layer patches for 2.7.0-rc2 Kevin Wolf
                   ` (2 preceding siblings ...)
  2016-08-08 11:52 ` [Qemu-devel] [PULL 3/4] mirror: finish earlier on error Kevin Wolf
@ 2016-08-08 11:52 ` Kevin Wolf
  2016-08-08 14:56 ` [Qemu-devel] [PULL 0/4] More block layer patches for 2.7.0-rc2 Peter Maydell
  4 siblings, 0 replies; 6+ messages in thread
From: Kevin Wolf @ 2016-08-08 11:52 UTC (permalink / raw)
  To: qemu-block; +Cc: kwolf, peter.maydell, qemu-devel

From: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>

109 iotest is broken for raw after 0965a41e998ab820b5
[mirror: double performance of the bulk stage if the disc is full]

The problem is with finishing block-job with error: before specified
patch mirror was not very async and it created one big request at disk
start, this request finished with error and qemu produced
BLOCK_JOB_COMPLETED with zero progress.

After 0965a41, mirror starts several smaller requests in parallel, when
BLOCK_JOB_COMPLETED emited we have some successful non-zero progress.

This patch solves the issue by filtering out progress from 109 test
output.

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 tests/qemu-iotests/109           | 2 +-
 tests/qemu-iotests/109.out       | 8 ++++----
 tests/qemu-iotests/common.filter | 6 ++++++
 3 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/tests/qemu-iotests/109 b/tests/qemu-iotests/109
index adf9889..280ed27 100755
--- a/tests/qemu-iotests/109
+++ b/tests/qemu-iotests/109
@@ -100,7 +100,7 @@ for sample_img in empty.bochs iotest-dirtylog-10G-4M.vhdx parallels-v1 \
     _make_test_img 64M
     bzcat "$SAMPLE_IMG_DIR/$sample_img.bz2" > "$TEST_IMG.src"
 
-    run_qemu "$TEST_IMG" "$TEST_IMG.src" "" "BLOCK_JOB_ERROR"
+    run_qemu "$TEST_IMG" "$TEST_IMG.src" "" "BLOCK_JOB_ERROR" | _filter_block_job_offset
     $QEMU_IO -c 'read -P 0 0 64k' "$TEST_IMG" | _filter_qemu_io
 
     run_qemu "$TEST_IMG" "$TEST_IMG.src" "'format': 'raw'," "BLOCK_JOB_READY"
diff --git a/tests/qemu-iotests/109.out b/tests/qemu-iotests/109.out
index 7c797ed..e5d70d7 100644
--- a/tests/qemu-iotests/109.out
+++ b/tests/qemu-iotests/109.out
@@ -135,7 +135,7 @@ Automatically detecting the format is dangerous for raw images, write operations
 Specify the 'raw' format explicitly to remove the restrictions.
 {"return": {}}
 {"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_ERROR", "data": {"device": "src", "operation": "write", "action": "report"}}
-{"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_COMPLETED", "data": {"device": "src", "len": 2560, "offset": 0, "speed": 0, "type": "mirror", "error": "Operation not permitted"}}
+{"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_COMPLETED", "data": {"device": "src", "len": 2560, "offset": OFFSET, "speed": 0, "type": "mirror", "error": "Operation not permitted"}}
 {"return": []}
 read 65536/65536 bytes at offset 0
 64 KiB, X ops; XX:XX:XX.X (XXX YYY/sec and XXX ops/sec)
@@ -155,7 +155,7 @@ Automatically detecting the format is dangerous for raw images, write operations
 Specify the 'raw' format explicitly to remove the restrictions.
 {"return": {}}
 {"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_ERROR", "data": {"device": "src", "operation": "write", "action": "report"}}
-{"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_COMPLETED", "data": {"device": "src", "len": 31457280, "offset": 0, "speed": 0, "type": "mirror", "error": "Operation not permitted"}}
+{"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_COMPLETED", "data": {"device": "src", "len": 31457280, "offset": OFFSET, "speed": 0, "type": "mirror", "error": "Operation not permitted"}}
 {"return": []}
 read 65536/65536 bytes at offset 0
 64 KiB, X ops; XX:XX:XX.X (XXX YYY/sec and XXX ops/sec)
@@ -175,7 +175,7 @@ Automatically detecting the format is dangerous for raw images, write operations
 Specify the 'raw' format explicitly to remove the restrictions.
 {"return": {}}
 {"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_ERROR", "data": {"device": "src", "operation": "write", "action": "report"}}
-{"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_COMPLETED", "data": {"device": "src", "len": 327680, "offset": 0, "speed": 0, "type": "mirror", "error": "Operation not permitted"}}
+{"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_COMPLETED", "data": {"device": "src", "len": 327680, "offset": OFFSET, "speed": 0, "type": "mirror", "error": "Operation not permitted"}}
 {"return": []}
 read 65536/65536 bytes at offset 0
 64 KiB, X ops; XX:XX:XX.X (XXX YYY/sec and XXX ops/sec)
@@ -195,7 +195,7 @@ Automatically detecting the format is dangerous for raw images, write operations
 Specify the 'raw' format explicitly to remove the restrictions.
 {"return": {}}
 {"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_ERROR", "data": {"device": "src", "operation": "write", "action": "report"}}
-{"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_COMPLETED", "data": {"device": "src", "len": 2048, "offset": 0, "speed": 0, "type": "mirror", "error": "Operation not permitted"}}
+{"timestamp": {"seconds":  TIMESTAMP, "microseconds":  TIMESTAMP}, "event": "BLOCK_JOB_COMPLETED", "data": {"device": "src", "len": 2048, "offset": OFFSET, "speed": 0, "type": "mirror", "error": "Operation not permitted"}}
 {"return": []}
 read 65536/65536 bytes at offset 0
 64 KiB, X ops; XX:XX:XX.X (XXX YYY/sec and XXX ops/sec)
diff --git a/tests/qemu-iotests/common.filter b/tests/qemu-iotests/common.filter
index 7853dbb..3ab6e4d 100644
--- a/tests/qemu-iotests/common.filter
+++ b/tests/qemu-iotests/common.filter
@@ -77,6 +77,12 @@ _filter_qmp()
         -e '    QMP_VERSION'
 }
 
+# replace block job offset
+_filter_block_job_offset()
+{
+    sed -e 's/, "offset": [0-9]\+,/, "offset": OFFSET,/'
+}
+
 # replace driver-specific options in the "Formatting..." line
 _filter_img_create()
 {
-- 
1.8.3.1

^ permalink raw reply related	[flat|nested] 6+ messages in thread

* Re: [Qemu-devel] [PULL 0/4] More block layer patches for 2.7.0-rc2
  2016-08-08 11:52 [Qemu-devel] [PULL 0/4] More block layer patches for 2.7.0-rc2 Kevin Wolf
                   ` (3 preceding siblings ...)
  2016-08-08 11:52 ` [Qemu-devel] [PULL 4/4] iotests: fix 109 Kevin Wolf
@ 2016-08-08 14:56 ` Peter Maydell
  4 siblings, 0 replies; 6+ messages in thread
From: Peter Maydell @ 2016-08-08 14:56 UTC (permalink / raw)
  To: Kevin Wolf; +Cc: Qemu-block, QEMU Developers

On 8 August 2016 at 12:52, Kevin Wolf <kwolf@redhat.com> wrote:
> The following changes since commit cf5198d58088e3b416fe517b3946e5120b342761:
>
>   Merge remote-tracking branch 'remotes/rth/tags/pull-tcg-20160805' into staging (2016-08-08 10:39:18 +0100)
>
> are available in the git repository at:
>
>
>   git://repo.or.cz/qemu/kevin.git tags/for-upstream
>
> for you to fetch changes up to a752e4786c19b0b368f4521a5dcbcce14882c3b1:
>
>   iotests: fix 109 (2016-08-08 13:05:43 +0200)
>
> ----------------------------------------------------------------
> More block layer patches for 2.7.0-rc2

Applied, thanks.

-- PMM

^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2016-08-08 14:57 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-08-08 11:52 [Qemu-devel] [PULL 0/4] More block layer patches for 2.7.0-rc2 Kevin Wolf
2016-08-08 11:52 ` [Qemu-devel] [PULL 1/4] block/qdev: Let 'drive' property fall back to node name Kevin Wolf
2016-08-08 11:52 ` [Qemu-devel] [PULL 2/4] tests: Test blockjob IDs Kevin Wolf
2016-08-08 11:52 ` [Qemu-devel] [PULL 3/4] mirror: finish earlier on error Kevin Wolf
2016-08-08 11:52 ` [Qemu-devel] [PULL 4/4] iotests: fix 109 Kevin Wolf
2016-08-08 14:56 ` [Qemu-devel] [PULL 0/4] More block layer patches for 2.7.0-rc2 Peter Maydell

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.