Re: [PATCH v2 03/22] media: docs: split cpia2.rst on two files

[Hans Verkuil <hverkuil@xs4all.nl>]

On 3/10/20 2:42 PM, Mauro Carvalho Chehab wrote:
> In order to be able to better organize the subsystem, split the
> cpia2 information on two files: one user-facing and another one
> from Kernel development PoV.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/media/v4l-drivers/cpia2.rst     | 46 ---------------
>  .../media/v4l-drivers/cpia2_devel.rst         | 56 +++++++++++++++++++

In other patches the devel file is called foo-devel.rst, here it is cpia2_devel.rst
Can you change this to cpia2-devel.rst as well?

Also, IMHO using -dev instead of -devel feels nicer, although that might be
because I use debian where all developer packages use -dev as suffix :-)

Regards,

	Hans

>  Documentation/media/v4l-drivers/index.rst     |  2 +
>  3 files changed, 58 insertions(+), 46 deletions(-)
>  create mode 100644 Documentation/media/v4l-drivers/cpia2_devel.rst
> 
> diff --git a/Documentation/media/v4l-drivers/cpia2.rst b/Documentation/media/v4l-drivers/cpia2.rst
> index a86baa1c83f1..6f4258aebbfe 100644
> --- a/Documentation/media/v4l-drivers/cpia2.rst
> +++ b/Documentation/media/v4l-drivers/cpia2.rst
> @@ -147,49 +147,3 @@ We are providing a modified gqcam application to view the output. In
>  order to avoid confusion, here it is called mview.  There is also the qx5view
>  program which can also control the lights on the qx5 microscope. MJPEG Tools
>  (http://mjpeg.sourceforge.net) can also be used to record from the camera.
> -
> -Notes to developers
> -~~~~~~~~~~~~~~~~~~~
> -
> -   - This is a driver version stripped of the 2.4 back compatibility
> -     and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support.
> -
> -Programmer's overview of cpia2 driver
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -Cpia2 is the second generation video coprocessor from VLSI Vision Ltd (now a
> -division of ST Microelectronics).  There are two versions.  The first is the
> -STV0672, which is capable of up to 30 frames per second (fps) in frame sizes
> -up to CIF, and 15 fps for VGA frames.  The STV0676 is an improved version,
> -which can handle up to 30 fps VGA.  Both coprocessors can be attached to two
> -CMOS sensors - the vvl6410 CIF sensor and the vvl6500 VGA sensor.  These will
> -be referred to as the 410 and the 500 sensors, or the CIF and VGA sensors.
> -
> -The two chipsets operate almost identically.  The core is an 8051 processor,
> -running two different versions of firmware.  The 672 runs the VP4 video
> -processor code, the 676 runs VP5.  There are a few differences in register
> -mappings for the two chips.  In these cases, the symbols defined in the
> -header files are marked with VP4 or VP5 as part of the symbol name.
> -
> -The cameras appear externally as three sets of registers. Setting register
> -values is the only way to control the camera.  Some settings are
> -interdependant, such as the sequence required to power up the camera. I will
> -try to make note of all of these cases.
> -
> -The register sets are called blocks.  Block 0 is the system block.  This
> -section is always powered on when the camera is plugged in.  It contains
> -registers that control housekeeping functions such as powering up the video
> -processor.  The video processor is the VP block.  These registers control
> -how the video from the sensor is processed.  Examples are timing registers,
> -user mode (vga, qvga), scaling, cropping, framerates, and so on.  The last
> -block is the video compressor (VC).  The video stream sent from the camera is
> -compressed as Motion JPEG (JPEGA).  The VC controls all of the compression
> -parameters.  Looking at the file cpia2_registers.h, you can get a full view
> -of these registers and the possible values for most of them.
> -
> -One or more registers can be set or read by sending a usb control message to
> -the camera.  There are three modes for this.  Block mode requests a number
> -of contiguous registers.  Random mode reads or writes random registers with
> -a tuple structure containing address/value pairs.  The repeat mode is only
> -used by VP4 to load a firmware patch.  It contains a starting address and
> -a sequence of bytes to be written into a gpio port.
> diff --git a/Documentation/media/v4l-drivers/cpia2_devel.rst b/Documentation/media/v4l-drivers/cpia2_devel.rst
> new file mode 100644
> index 000000000000..decaa4768c78
> --- /dev/null
> +++ b/Documentation/media/v4l-drivers/cpia2_devel.rst
> @@ -0,0 +1,56 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +The cpia2 driver
> +================
> +
> +Authors: Peter Pregler <Peter_Pregler@email.com>,
> +Scott J. Bertin <scottbertin@yahoo.com>, and
> +Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which
> +this one was modelled from.
> +
> +
> +Notes to developers
> +~~~~~~~~~~~~~~~~~~~
> +
> +   - This is a driver version stripped of the 2.4 back compatibility
> +     and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support.
> +
> +Programmer's overview of cpia2 driver
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Cpia2 is the second generation video coprocessor from VLSI Vision Ltd (now a
> +division of ST Microelectronics).  There are two versions.  The first is the
> +STV0672, which is capable of up to 30 frames per second (fps) in frame sizes
> +up to CIF, and 15 fps for VGA frames.  The STV0676 is an improved version,
> +which can handle up to 30 fps VGA.  Both coprocessors can be attached to two
> +CMOS sensors - the vvl6410 CIF sensor and the vvl6500 VGA sensor.  These will
> +be referred to as the 410 and the 500 sensors, or the CIF and VGA sensors.
> +
> +The two chipsets operate almost identically.  The core is an 8051 processor,
> +running two different versions of firmware.  The 672 runs the VP4 video
> +processor code, the 676 runs VP5.  There are a few differences in register
> +mappings for the two chips.  In these cases, the symbols defined in the
> +header files are marked with VP4 or VP5 as part of the symbol name.
> +
> +The cameras appear externally as three sets of registers. Setting register
> +values is the only way to control the camera.  Some settings are
> +interdependant, such as the sequence required to power up the camera. I will
> +try to make note of all of these cases.
> +
> +The register sets are called blocks.  Block 0 is the system block.  This
> +section is always powered on when the camera is plugged in.  It contains
> +registers that control housekeeping functions such as powering up the video
> +processor.  The video processor is the VP block.  These registers control
> +how the video from the sensor is processed.  Examples are timing registers,
> +user mode (vga, qvga), scaling, cropping, framerates, and so on.  The last
> +block is the video compressor (VC).  The video stream sent from the camera is
> +compressed as Motion JPEG (JPEGA).  The VC controls all of the compression
> +parameters.  Looking at the file cpia2_registers.h, you can get a full view
> +of these registers and the possible values for most of them.
> +
> +One or more registers can be set or read by sending a usb control message to
> +the camera.  There are three modes for this.  Block mode requests a number
> +of contiguous registers.  Random mode reads or writes random registers with
> +a tuple structure containing address/value pairs.  The repeat mode is only
> +used by VP4 to load a firmware patch.  It contains a starting address and
> +a sequence of bytes to be written into a gpio port.
> diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst
> index eca22b82de94..72fbb394f6a2 100644
> --- a/Documentation/media/v4l-drivers/index.rst
> +++ b/Documentation/media/v4l-drivers/index.rst
> @@ -65,3 +65,5 @@ For more details see the file COPYING in the source distribution of Linux.
>  	vimc
>  	vivid
>  	zr364xx
> +
> +	cpia2_devel
>