media: dvb: add missing DVB-S2X FEC parameter values

This commit is adding the missing short FEC
Missed on commit 6508a50fe84f9858e8b59b53dce3847aaeeab744

More info: https://dvb.org/wp-content/uploads/2021/02/A083-2r2_DVB-S2X_Draft-EN-302-307-2-v131_Feb_2021.pdf
Table 1: S2X System configurations and application areas

Please note that 128APSK, 256APSK and 256APSK-L
and FEC 29/45, 31/45 are still missing from enums.

Link: https://lore.kernel.org/linux-media/20230111194608.1853-1-athoik@gmail.com
Cc: Robert Schlabbach <robert_s@gmx.net>
Cc: Tom Richardson <trichardson@availink.com>
Signed-off-by: Athanasios Oikonomou <athoik@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

headers: Remove some left-over license text in include/uapi/linux/dvb/

Remove some left-over from commit e2be04c7f995 ("License cleanup: add
SPDX license identifier to uapi header files with a license")

When the SPDX-License-Identifier tag has been added, the corresponding
license text has not been removed.

Remove it now.

Signed-off-by: Christophe JAILLET <christophe.jaillet@wanadoo.fr>
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>

media: dvb/frontend.h: fix kernel-doc warnings

scripts/kernel-doc spouts multiple warnings, so fix them:

include/uapi/linux/dvb/frontend.h:399: warning: Enum value 'QAM_1024' not described in enum 'fe_modulation'
include/uapi/linux/dvb/frontend.h:399: warning: Enum value 'QAM_4096' not described in enum 'fe_modulation'
frontend.h:286: warning: contents before sections
frontend.h:780: warning: missing initial short description on line:
* enum atscmh_rs_code_mode

Fixes: 8220ead805b6 ("media: dvb/frontend.h: document the uAPI file")
Fixes: 6508a50fe84f ("media: dvb: add DVB-C2 and DVB-S2X parameter values")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Robert Schlabbach <robert_s@gmx.net>
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

media: dvb: add DVB-C2 and DVB-S2X parameter values

Extend the DVB frontend parameter enums with additional values specified
by the DVB-C2 (ETSI EN 302 769) and DVB-S2X (ETSI EN 302 307-2)
standards to be ready for frontend drivers for such receivers.

While most parameters will be "read-only" due to being autodetected by
the receiver and only being reported back for informational purposes,
the addition of SYS_DVBC2 to the delivery systems enum is required,
because there are DVB-C2 capable receivers which are not capable of
DVB-C/C2 autodetection and thus need this enum value to be explicitly
instructed to search for a DVB-C2 signal.

As for DVB-S2X, as that is an extension to DVB-S2, the same delivery
system enum as for DVB-S2 can be used.

Add the additional enum values and comments to the documentation.

Link: https://lore.kernel.org/linux-media/trinity-1b7c5a66-85d4-4595-a690-0fde965d49b3-1642146228587@3c-app-gmx-bap69
Signed-off-by: Robert Schlabbach <robert_s@gmx.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

media: dvb_frontend: add physical layer scrambling support

This commit adds a new property DTV_SCRAMBLING_SEQUENCE_INDEX.

This 18 bit field, when present, carries the index of the DVB-S2 physical
layer scrambling sequence as defined in clause 5.5.4 of EN 302 307.
There is no explicit signalling method to convey scrambling sequence index
to the receiver. If S2 satellite delivery system descriptor is available
it can be used to read the scrambling sequence index (EN 300 468 table 41).

By default, gold scrambling sequence index 0 is used. The valid scrambling
sequence index range is from 0 to 262142.

Increase the DVB API version in order userspace to be aware of the changes.

Signed-off-by: Athanasios Oikonomou <athoik@gmail.com>
Acked-by: Ralph Metzler <rjkm@metzlerbros.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

media: frontend: describe nested structs

There are some nested structs on this header, with aren't
properly document them.

This should solve some warnings after the addition of
a patche at kernel-doc adding support for nested structs/unions.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

License cleanup: add SPDX license identifier to uapi header files with a license

Many user space API headers have licensing information, which is either
incomplete, badly formatted or just a shorthand for referring to the
license under which the file is supposed to be. This makes it hard for
compliance tools to determine the correct license.

Update these files with an SPDX license identifier. The identifier was
chosen based on the license information in the file.

GPL/LGPL licensed headers get the matching GPL/LGPL SPDX license
identifier with the added 'WITH Linux-syscall-note' exception, which is
the officially assigned exception identifier for the kernel syscall
exception:

NOTE! This copyright does *not* cover user programs that use kernel
services by normal system calls - this is merely considered normal use
of the kernel, and does *not* fall under the heading of "derived work".

This exception makes it possible to include GPL headers into non GPL
code, without confusing license compliance tools.

Headers which have either explicit dual licensing or are just licensed
under a non GPL license are updated with the corresponding SPDX
identifier and the GPLv2 with syscall exception identifier. The format
is:
((GPL-2.0 WITH Linux-syscall-note) OR SPDX-ID-OF-OTHER-LICENSE)

SPDX license identifiers are a legally binding shorthand, which can be
used instead of the full boiler plate text. The update does not remove
existing license information as this has to be done on a case by case
basis and the copyright holders might have to be consulted. This will
happen in a separate step.

This patch is based on work done by Thomas Gleixner and Kate Stewart and
Philippe Ombredanne. See the previous patch in this series for the
methodology of how this patch was researched.

Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

media: dvb_frontend: fix return values for FE_SET_PROPERTY

There are several problems with regards to the return of
FE_SET_PROPERTY. The original idea were to return per-property
return codes via tvp->result field, and to return an updated
set of values.

However, that never worked. What's actually implemented is:

- the FE_SET_PROPERTY implementation doesn't call .get_frontend
callback in order to get the actual parameters after return;

- the tvp->result field is only filled if there's no error.
So, it is always filled with zero;

- FE_SET_PROPERTY doesn't call memdup_user() nor any other
copy_to_user() function. So, any changes to the properties
will be lost;

- FE_SET_PROPERTY is declared as a write-only ioctl (IOW).

While we could fix the above, it could cause regressions.

So, let's just assume what the code really does, updating
the documentation accordingly and removing the logic that
would update the discarded tvp->result.

Reviewed-by: Shuah Khan <shuahkh@osg.samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

media: dvb headers: make checkpatch happier

Adjust dvb ca.h, dmx.h and frontend.h in order to make
checkpatch happier. Now, it only complains about the typedefs,
and those are there just to provide backward userspace
compatibility.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

media: frontend.h: Avoid the term DVB when doesn't refer to a delivery system

The DVB term can either refer to the subsystem or to a delivery
system. Avoid it in the first case at the kernel-doc markups.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

media: dvb frontend docs: use kernel-doc documentation

Now that frontend.h contains most documentation for the frontend,
remove the duplicated information from Documentation/ and use the
kernel-doc auto-generated one instead.

That should simplify maintainership of DVB frontend uAPI, as most
of the documentation will stick with the header file.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

media: dvb/frontend.h: document the uAPI file

Most of the stuff at the Digital TV frontend header file
are documented only at the Documentation. However, a few
kernel-doc markups are there, several of them with parsing
issues.

Add the missing documentation, copying definitions from the
Documentation when it applies, fixing some bugs.

Please notice that DVBv3 stuff that were deprecated weren't
commented by purpose. Instead, they were clearly tagged as
such.

This patch prepares to move part of the documentation from
Documentation/ to kernel-doc comments.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

media: dvb/frontend.h: move out a private internal structure

struct dtv_cmds_h is just an ancillary struct used by the
dvb_frontend.c to internally store frontend commands.

It doesn't belong to the userspace header, nor it is used anywhere,
except inside the DVB core. So, remove it from the header.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

media: dvb_frontend: ensure that inital front end status initialized

The fe_status variable s is not initialized meaning it can have any
random garbage status. This could be problematic if fe->ops.tune is
false as s is not updated by the call to fe->ops.tune() and a
subsequent check on the change status will using a garbage value.
Fix this by adding FE_NONE to the enum fe_status and initializing
s to this.

Detected by CoverityScan, CID#112887 ("Uninitialized scalar variable")

Signed-off-by: Colin Ian King <colin.king@canonical.com>
Reviewed-by: Shuah Khan <shuahkh@osg.samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

[media] dvb: frontend.h: add a note for the deprecated enums/structs

Let be clear, at the header, about what got deprecated.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] dvb: frontend.h: improve dvb_frontent_parameters comment

The comment for struct dvb_frontend_parameters is weird, as it
mixes delivery system name (ATSC) with modulation names
(QPSK, QAM, OFDM).

Use delivery system names there on the frequency comment, as this
is clearer, specially after 2GEN delivery systems.

While here, add comments at the union, to make live easier for ones
that may try to understand the convention used by the legacy API.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] frontend: Fix a typo at the comments

The description of struct dtv_stats has a spmall typo:
FE_SCALE_DECIBELS instead of FE_SCALE_DECIBEL

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] frontend: move legacy typedefs to the end

Just userspace need those typedefs. So, put it in the compat part
of the header.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] frontend: Move legacy API enums/structs to the end

In order to better organize the header file, move the legacy
API (DVBv3) support to the end, just before the ioctl definitions.

This way, we can use just one #if for all of them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] dvb: Get rid of typedev usage for enums

The DVB API was originally defined using typedefs. This is against
Kernel CodingStyle, and there's no good usage here. While we can't
remove its usage on userspace, we can avoid its usage in Kernelspace.

So, let's do it.

This patch was generated by this shell script:

for j in $(grep typedef include/uapi/linux/dvb/frontend.h |cut -d' ' -f 3); do for i in $(find drivers/media -name '*.[ch]' -type f) $(find drivers/staging/media -name '*.[ch]' -type f); do sed "s,${j}_t,enum $j," <$i >a && mv a $i; done; done

While here, make CodingStyle fixes on the affected lines.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: Stefan Richter <stefanr@s5r6.in-berlin.de> # for drivers/media/firewire/*

[media] DocBook: add xrefs for enum fe_type

The only enum that was missing xrefs at frontend.h is fe_type.
Add xrefs for them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: properly document the delivery systems

Use a table for the delivery systems. The table is organized
by the type (cable, satellite, terrestrial) and shows what
standards are not fully implemented.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: better document the DVB-S2 rolloff factor

Instead of using a program listing, use a table and make clearer
what each define means.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: document DVB-S2 pilot in a table

Putting it into a table allows to comment each possible
values, with makes more clear what field means.

Also, it allows to do cross-references with the frontend.h.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: improve documentation for hierarchy

Format it as a table and links it with the legacy API xml.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: improve documentation for guard interval

Format it as a table and add more details, in special for
DTMB guard intervals.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: improve documentation for FEC fields

Format it as a table and add more details. Also, remove the
duplicated occurrences.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: move fe_bandwidth to the frontend legacy section

fe_bandwidth/fe_bandwidth_t is used only on DVBv3 API. So, move
it to the frontend legacy xml, and convert it into a table.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: improve documentation for OFDM transmission mode

Format it as a table and add more details, in special, for
the DTMB modes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: improve documentation for DVB spectral inversion

Format it as a table and provide more details.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: Better document enum fe_modulation

Instead of using programlisting, use a table, as this provides
a better view of the structure.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: better document FE_DISEQC_SEND_BURST ioctl

Use the proper format for FE_DISEQC_SEND_BURST documentation
and improve the documentation.

Keep the enum fe_sec_mini_cmd description together with
the ioctl, as both are used together.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: better document FE_SET_TONE ioctl

Use the proper format for FE_SET_TONE documentation and
improve the documentation.

Keep the enum fe_sec_tone_mode description together with
the ioctl, as both are used together.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] DocBook: better document FE_SET_VOLTAGE ioctl

Use the proper format for FE_SET_VOLTAGE documentation and fix
the documentation. The description for the enum is not 100%,
and it is missing the voltage off value.

Also, it is better to keep the enum description together with
the ioctl, as both are used together.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] dvb: split enum from typedefs at frontend.h

Using typedefs is already bad enough, but doing it together
with enum declaration is even worse.

Also, it breaks the scripts at DocBook that would be generating
reference pointers for the enums.

Well, we can't get rid of typedef right now, but let's at least
declare it on a separate line, and let the scripts to generate
the cross-reference, as this is needed for the next DocBook
patches.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] dvb: Document FE_SCALE_DECIBEL units consistently

In comments and in the documentation, the units of properties marked
with the FE_SCALE_DECIBEL scale are specified in terms of 1/1000 dB
or 0.0001 dB. This is inconsistent, however, as 1/1000 is 0.001,
not 0.0001.

Note that the v4l-utils divide the value by 1000 for the signal
strength suggesting that the 1/1000 is correct.

Settle on millidecibels, ie. 1/1000dB or 0.001dB.

Signed-off-by: David Howells <dhowells@redhat.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

[media] dvb: Add DVBv5 statistics properties

The DVBv3 statistics parameters are limited on several ways:
- It doesn't provide any way to indicate the used measure,
so userspace need to guess how to calculate/use it;
- Only a limited set of stats are supported;
- Can't be called in a way to require them to be filled
all at once (atomic reads from the hardware), with may
cause troubles on interpreting them on userspace;
- On some OFDM delivery systems, the carriers can be
independently modulated, having different properties.
Currently, there's no way to report per-layer stats.
To address the above issues, adding a new DVBv5-based stats API.
While here, correct inner code nomenclature on a few places.

Reviewed-by: Antti Palosaari <crope@iki.fi>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

UAPI: (Scripted) Disintegrate include/linux/dvb

Signed-off-by: David Howells <dhowells@redhat.com>
Acked-by: Arnd Bergmann <arnd@arndb.de>
Acked-by: Thomas Gleixner <tglx@linutronix.de>
Acked-by: Michael Kerrisk <mtk.manpages@gmail.com>
Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Acked-by: Dave Jones <davej@redhat.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>