media: staging: rkisp1: rsz: remove redundant if statement and add inline doc
The statement "if (rsz->fmt_type == V4L2_PIXEL_ENC_YUV)"
can be removed since the value of rsz->fmt_type is either
V4L2_PIXEL_ENC_YUV or V4L2_PIXEL_ENC_BAYER and the function
returns if it is bayer. In addition some doc with clarification
is added.
media: staging: rkisp1: rsz: get the capture format info from the capture struct
Currently the format info of the capture is retrieved by calling
the function v4l2_format_info. This is not needed since it is
already saved in the capture object.
Sakari Ailus [Thu, 16 Apr 2020 07:45:07 +0000 (09:45 +0200)]
media: staging: ipu3-imgu: Add a sanity check for the parameter struct size
There have been cases where seemingly innocuous patches have broken the
uAPI by changing the memory layout of the parameter struct. Generally such
changes also introduce a change in the size of the entire struct. This
patch adds a sanity check to avoid such cases happening in the future.
Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com> Tested-by: Tested-by: Bingbu Cao <bingbu.cao@intel.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Sakari Ailus [Wed, 15 Apr 2020 15:40:09 +0000 (17:40 +0200)]
media: staging: ipu3-imgu: Move alignment attribute to field
Move the alignment attribute of struct ipu3_uapi_awb_fr_config_s to the
field in struct ipu3_uapi_4a_config, the other location where the struct
is used.
Fixes: commit c9d52c114a9f ("media: staging: imgu: Address a compiler warning on alignment") Reported-by: Tomasz Figa <tfiga@chromium.org> Tested-by: Bingbu Cao <bingbu.cao@intel.com> Cc: stable@vger.kernel.org # for v5.3 and up Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
The patch being reverted changed the memory layout of struct
ipu3_uapi_acc_param. Revert it, and address the compiler warning issues in
further patches.
Fixes: commit c9d52c114a9f ("media: staging: imgu: Address a compiler warning on alignment") Reported-by: Tomasz Figa <tfiga@chromium.org> Tested-by: Bingbu Cao <bingbu.cao@intel.com> Cc: stable@vger.kernel.org # for v5.3 and up Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tomasz Figa [Sat, 11 Apr 2020 17:37:10 +0000 (19:37 +0200)]
media: staging: ipu3: Fix stale list entries on parameter queue failure
When queuing parameters fails, current code bails out without deleting
the corresponding vb2 buffer from the driver buffer list, but the buffer
is returned to vb2. This leads to stale list entries and a crash when
the driver stops streaming:
According to stateful Codec API the decoder will process all
remaining buffers from before the source change event in
dynamic-resolution-change state and mark the last buffer with
V4L2_BUF_FLAG_LAST.
In Venus case the firmware doesn't mark that last buffer and
some mechanism have to be created in v4l decoder driver.
Fortunately the firmware interface (HFI) claims that the
decoder output buffers will be returned to v4l decoder
driver before it send the insufficient event.
In order to do that we save last queued in the driver capture
buffer in the event_notify and issue flush on output firmware
buffers queue. Once the saved buffer is returned (as a result of
flush command) we mark it as LAST. For all that possible we
extend HFI flush command with one more argument and one more
flush_done HFI driver callback.
media: venus: vdec: Init registered list unconditionally
Presently the list initialization is done only in
dynamic-resolution-change state, which leads to list corruptions
and use-after-free. Init list_head unconditionally in
vdec_stop_capture called by vb2 stop_streaming without takeing
into account current codec state.
Stanimir Varbanov [Tue, 31 Mar 2020 16:19:51 +0000 (18:19 +0200)]
media: venus: vdec: Mark flushed buffers with error state
Once the hfi_session_flush is issued by the vdec all queued
buffers to firmware should be returned to the v4l driver. Some
of those buffers are not processed at the time of flush command,
those buffers has filled len zero (no data). Catch that in
buffer_done callback and mark not filled capture buffers with
error state so that client can discard them.
Stanimir Varbanov [Tue, 31 Mar 2020 15:47:38 +0000 (17:47 +0200)]
media: venus: helpers: Done buffers per queue type
Currently calling venus_helper_buffers_done() will return buffers to
user for both capture and output queues in the same call. This is
wrong because both queues are really separate and calling
stop_streaming on one queue shouldn't return buffers for the other.
Solve this by add a new queue type argument and fix the clients of
the helper function.
Stanimir Varbanov [Tue, 31 Mar 2020 15:37:02 +0000 (17:37 +0200)]
media: venus: core: Fix mutex destroy in remove
The hfi_destroy function is called too early in remove method. It
destroys a mutex which is used later in the .remove from pmruntime.
Solve the issue by moving hfi_destroy after last usage of the mutex.
gpiod_get_value() can return negative values if an error occurs.
In several places this error code was ignored.
Ensure that errors codes are handled correctly throughout the CEC
pin framework and CEC pin drivers.
The return code of the cec_pin_ops read() callback had to be changed
from 'bool' to 'int', which mean the prototype of that callback in the
sun4i drm driver also had to be changed.
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Reported-by: Dan Carpenter <dan.carpenter@oracle.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
media: MAINTAINERS: adjust entries to moving CEC USB drivers
Commit a81068181aad ("media: move CEC USB drivers to a separate directory")
moved drivers/media/usb/{pulse8,rainshadow}-cec to
drivers/media/cec/usb/{rainshadow,pulse8}, but did not adjust the entries
in MAINTAINERS.
Since then, ./scripts/get_maintainer.pl --self-test=patterns complains:
warning: no file matches F: drivers/media/usb/pulse8-cec/*
warning: no file matches F: drivers/media/usb/rainshadow-cec/*
Update the MAINTAINERS entries to the new file locations.
The colorspace reported by a video nodes should not be
V4L2_COLORSPACE_DEFAULT. Instead a default colorspace should be picked
by the driver if V4L2_COLORSPACE_DEFAULT is given by userspace to
{G,S,TRY}_FMT.
The colorspace V4L2_COLORSPACE_SRGB is arbitrary chosen as the vimc
default format to report as it's used for most webcams.
Signed-off-by: Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se> Acked-by: Helen Koike <helen.koike@collabora.com> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
There are some tuners used by a few pure DVB boards that use
internally V4L2 function calls. Due to that, such drivers now
depends on v4l2 core support, and can't be auto-selected
if !VIDEO_V4L2:
Some media entry attributes got out of the order after the
bug was split into 3. Also, as reported by Johan, the
Rockchip VPU entry also had their attributes at the wrong
order.
As those entries weren't merged yet upstream, let's reorder
them with:
media: MAINTAINERS: Fix Hantro, Rga and Rkvdec entries
It seems recent merges introduced a couple issues
here, so let's fix them all. Also, reorder Rockchip
video decoder as per parse-maintainers.pl script
and add linux-rockchip mailing list.
Having a table with a list of all USB drivers seems worth,
and it comes almost for free, as we can just use Kconfig
descriptions (with some adjustments).
The DVB cards.rst file is old and outdated. It also contains
data that are contained on other cardlists. Remove the
duplicated information and split frontends and PCI cards on
separate files.
As all USB cards already have their own card lists, just drop
the old USB data there.
media: admin-guide: add a cardlist for all other USB cards
There are several other USB cards. Most of them support just
one device. The only exception is the "pwc" driver. But, as
updates to it are not frequent, let's just place everything
manually into a single file.
media: pwc-if.c: Update comments about each pwc supported model
The USB_DEVICE() list contain some of the product names, but
some are missing, and others are different than the message
printed during device detection.
Update the comments in order to match what the driver prints.
That makes easier to discover what model matches what physical
device.
Instead of using USB_DEVICE() macro directly, use the
DVB_USB_DEVICE() one, as other dvb-usb-v2 devices.
The usage of the new macro makes cleaner and easier to
parse the supported device names in a way that it would
be easily parseable to generate cardlists.
In the old txt situation we add/describe only properties that are used
by the driver/hardware itself. With yaml it also filters things in a
node that are used by other drivers like 'power-domains' for rk3399,
so add it to 'rockchip-rga.yaml'.
Signed-off-by: Johan Jonker <jbx6244@gmail.com> Reviewed-by: Rob Herring <robh@kernel.org> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
media: staging: rkisp1: cap: support uv swap only for semiplanar formats
The register RKISP1_CIF_MI_XTD_FORMAT_CTRL is relevant only
for semiplanar formats, therefore the uv swap can be supported
through this register only for semiplanar formats.
media: staging: rkisp1: cap: change the logic for writing to uv swap register
The register RKISP1_CIF_MI_XTD_FORMAT_CTRL is currently written
with "on" only if the u,v streams need to be swapped. This patch
also write to it with "off" if they don't need to be swapped.
media: staging: rkisp1: cap: cleanup in mainpath config for uv swap format
The value RKISP1_CIF_MI_XTD_FMT_CTRL_MP_CB_CR_SWAP equals BIT(0),
Therefore when writing it to the register there is no need to mask
it first with ~BIT(0).
Philipp Zabel [Wed, 18 Mar 2020 18:36:49 +0000 (19:36 +0100)]
media: coda: add RC enable controls
Currently the encoder enables the rate control algorithms if the bitrate
control is non-zero. Implement the V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE
and V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE controls to allow userspace to
choose frame-level or macroblock-level rate control updates, or to
explicitly disable rate control. Both controls are initially enabled to
keep the current behavior.
Signed-off-by: Philipp Zabel <p.zabel@pengutronix.de> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Dafna Hirschfeld [Tue, 17 Mar 2020 18:07:01 +0000 (19:07 +0100)]
media: staging: rkisp1: replace the call to v4l2_async_notifier_parse_fwnode_endpoints_by_port
don't call 'v4l2_async_notifier_parse_fwnode_endpoints_by_port'
in order to register async subdevices. Instead call
'v4l2_fwnode_endpoint_parse' to parse the remote endpoints
and then register each async subdev with
'v4l2_async_notifier_add_fwnode_remote_subdev'
Also remove the relevant item in the TODO file
Signed-off-by: Dafna Hirschfeld <dafna.hirschfeld@collabora.com> Acked-by: Helen Koike <helen.koike@collabora.com> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Helen Koike [Mon, 16 Mar 2020 21:00:43 +0000 (22:00 +0100)]
media: staging: rkisp1: cap: fix return values from pm functions
If no errors occurs, pm functions return usage counters, so they can
return positive numbers.
This happens when streaming from multiple capture devices (mainpath and
selfpath).
Fix simultaneous streaming from mainpath and selfpath by not failing
when pm usage counters returns a positive number.
Signed-off-by: Helen Koike <helen.koike@collabora.com> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Hans Verkuil [Tue, 3 Mar 2020 11:01:59 +0000 (12:01 +0100)]
media: v4l2-ctrls: v4l2_ctrl_g/s_ctrl*(): don't continue when WARN_ON
If the v4l2_ctrl_g_ctrl*() or __v4l2_ctrl_s_ctrl*() functions
are called for the wrong control type then they call WARN_ON
since that is a driver error. But they still continue, potentially
overwriting data. Change this to return an error (s_ctrl) or 0
(g_ctrl), just to be safe.
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:04:08 +0000 (21:04 +0100)]
media: cx25840: Register labeling, chip specific correction
Remove vbi_regs_offset from a group of registers that are 888 specific,
include those registers names. Sources used for reference are 885 and 888
datasheets.
Add labels to some undocumented registers.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:04:07 +0000 (21:04 +0100)]
media: lgdt3306a: Add CNR v5 stat
The CNR is already calculated, so populate DVBv5 CNR stat
during read_status.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:04:06 +0000 (21:04 +0100)]
media: si2157: add on-demand rf strength func
Add get_rf_strength callback to get RSSI from the tuner. DVBv5
stat cache is updated. get_rf_strength is called by tuner_core
for analog tuners and is also used by some bridge drivers to
obtain RSSI directly from the tuner.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:04:05 +0000 (21:04 +0100)]
media: cx231xx: Add i2c device analog tuner support
The boards listed below use i2c device drivers and have
tuner_type equal TUNER_ABSENT. This means additional support
is required to enable the analog tuning capability, a case
statement is used to identify these models.
Models with analog tuning enabled:
- CX231XX_BOARD_HAUPPAUGE_930C_HD_1114xx (tested)
- CX231XX_BOARD_HAUPPAUGE_935C (tested)
- CX231XX_BOARD_HAUPPAUGE_955Q (tested)
- CX231XX_BOARD_HAUPPAUGE_975 (tested)
- CX231XX_BOARD_EVROMEDIA_FULL_HYBRID_FULLHD (untested)
The EvroMedia model was added, since it uses the si2157
tuner and the board profile claims it has analog inputs.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:04:04 +0000 (21:04 +0100)]
media: cx23885: Add i2c device analog tuner support
Hauppauge QuadHD/1265/5525 boards all use i2c device drivers and
have tuner_type equal TUNER_ABSENT. This means additional support
is required to enable the analog tuning capability, a case
statement is used to identify these models.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:04:03 +0000 (21:04 +0100)]
media: cx23885: Add analog frontend to HVR5525
Enables the analog tuning frontend for Hauppauge HVR-5525.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:04:02 +0000 (21:04 +0100)]
media: cx23885: Add analog frontend to 1265_K4
Enables the analog tuning frontend for Hauppauge HVR-1265_K4.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:04:01 +0000 (21:04 +0100)]
media: cx23885: Add analog frontend to Hauppauge QuadHD
Add analog tuner frontend to 888 Hauppauge QuadHD boards
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:04:00 +0000 (21:04 +0100)]
media: si2157: module debug option to wait on signal lock
In some debugging cases it is useful to know how long it took
signal lock to happen after tuning. This can help diagnose
line issues.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:03:59 +0000 (21:03 +0100)]
media: si2157: Briefly wait for tuning operation to complete
To detect errors in the tuning operation, this waits up 40ms for operation
completion status. This allows for error detection and prevents issuing
additional commands to the tuner before it is finished.
Tuning typically completes in 20-30ms.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:03:58 +0000 (21:03 +0100)]
media: si2157: Add analog tuning related functions
Include set_analog_params, get_frequency, and get_bandwidth.
Tested with NTSC and PAL standards via ch3/4 generator. Other standards
are included, but are untested due to lack of generator.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:03:57 +0000 (21:03 +0100)]
media: si2157: Better check for running tuner in init
Getting the Xtal trim property to check if running is less error prone.
Reset if_frequency if state is unknown.
Replaces the previous "garbage check".
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:03:56 +0000 (21:03 +0100)]
media: si2157: Check error status bit on cmd execute
Check error status bit on command execute, if error bit is
set return -EAGAIN. Ignore -EAGAIN in probe during device check.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Brad Love [Thu, 14 Nov 2019 20:03:55 +0000 (21:03 +0100)]
media: si2157: Enable tuner status flags
Enable flags to get status of commands sent to the tuner.
Signed-off-by: Brad Love <brad@nextdimension.cc> Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Boris Brezillon [Fri, 3 Apr 2020 22:13:44 +0000 (00:13 +0200)]
media: rkvdec: Add the rkvdec driver
The rockchip vdec block is a stateless decoder that's able to decode
H264, HEVC and VP9 content. This commit adds the core infrastructure
and the H264 backend. Support for VP9 and HEVS will be added later on.
[mchehab+huawei@kernel.org: select MEDIA_CONTROLLER and REQUEST_API] Signed-off-by: Boris Brezillon <boris.brezillon@collabora.com> Signed-off-by: Ezequiel Garcia <ezequiel@collabora.com> Tested-by: Nicolas Dufresne <nicolas.dufresne@collabora.com> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Boris Brezillon [Fri, 3 Apr 2020 22:13:41 +0000 (00:13 +0200)]
media: v4l2-core: Add helpers to build the H264 P/B0/B1 reflists
Building those list is a standard procedure described in section
'8.2.4 Decoding process for reference picture lists construction' of
the H264 specification.
We already have 2 drivers needing the same logic (hantro and rkvdec) and
I suspect we will soon have more.
Let's provide generic helpers to create those lists.
Signed-off-by: Boris Brezillon <boris.brezillon@collabora.com> Signed-off-by: Ezequiel Garcia <ezequiel@collabora.com> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Instead of depending on the Rockchip PHY driver the ISP driver
should really depend on CONFIG_GENERIC_PHY_MIPI_DPHY,
given all it needs is the phy_mipi_dphy_get_default_config() symbol.
Fix it.
Signed-off-by: Ezequiel Garcia <ezequiel@collabora.com> Acked-by: Helen Koike <helen.koike@collabora.com> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Seungchul Kim [Thu, 26 Mar 2020 09:09:46 +0000 (10:09 +0100)]
media: v4l2-fh: define v4l2_fh struct regardless of condition
v4l2_fh struct define differently by CONFIG_V4L2_MEM2MEM_DEV.
If some vendors use CONFIG_V4L2_MEM2MEM_DEV by module,
it can make the mismatch of v4l2_fh sturct.
By the mismatch, the following error occurs.
===============================
[ 7.533506] v4l2_mem2mem: disagrees about version of symbol video_devdata
[ 7.533594] v4l2_mem2mem: Unknown symbol video_devdata (err -22)
[ 7.535319] v4l2_mem2mem: disagrees about version of symbol v4l2_event_pending
[ 7.542532] v4l2_mem2mem: Unknown symbol v4l2_event_pending (err -22)
===============================
So v4l2_fh struct is modified to does not have dependency
for CONFIG_V4L2_MEM2MEM_DEV.
Signed-off-by: Seungchul Kim <sc377.kim@samsung.com> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
media: staging: rkisp1: change fields names from fmt_type to pixel_enc
The fields 'fmt_type' in the structs
'rkisp1_rsz_config', 'rkisp1_isp_mbus_info' are of type
'v4l2_pixel_encoding' so it is nicer to change their name to
'pixel_enc'. Also change the define 'RKISP1_DEF_FMT_TYPE' to
'RKISP1_DEF_PIXEL_ENC'
media: platform: fcp: Set appropriate DMA parameters
Enabling CONFIG_DMA_API_DEBUG=y and CONFIG_DMA_API_DEBUG_SG=y will
enable extra validation on DMA operations ensuring that the size
restraints are met.
When using the FCP in conjunction with the VSP1/DU, and display frames,
the size of the DMA operations is larger than the default maximum
segment size reported by the DMA core (64K). With the DMA debug enabled,
this produces a warning such as the following:
"DMA-API: rcar-fcp fea27000.fcp: mapping sg segment longer than device
claims to support [len=3145728] [max=65536]"
We have no specific limitation on the segment size which isn't already
handled by the VSP1/DU which actually handles the DMA allcoations and
buffer management, so define a maximum segment size of up to 4GB (a 32
bit mask).
media: staging: rkisp1: remove TODO item - uapi structs compatibility
remove the TODO item:
* Make sure uapi structs have the same size and layout in 32 and 62 bits,
and that there are no holes in the structures (pahole is a utility that
can be used to test this).