Re: [PATCH RFC v5 11/12] DocBook: Software Defined Radio Interface
More nits... On 12/20/2013 06:49 AM, Antti Palosaari wrote: > Document V4L2 SDR interface. > > Cc: Hans Verkuil > Signed-off-by: Antti Palosaari > --- > Documentation/DocBook/media/v4l/compat.xml | 10 +++ > Documentation/DocBook/media/v4l/dev-sdr.xml | 99 > > Documentation/DocBook/media/v4l/io.xml | 6 ++ > Documentation/DocBook/media/v4l/v4l2.xml | 1 + > Documentation/DocBook/media/v4l/vidioc-g-fmt.xml | 6 ++ > 5 files changed, 122 insertions(+) > create mode 100644 Documentation/DocBook/media/v4l/dev-sdr.xml > > diff --git a/Documentation/DocBook/media/v4l/compat.xml > b/Documentation/DocBook/media/v4l/compat.xml > index 0c7195e..85fb864 100644 > --- a/Documentation/DocBook/media/v4l/compat.xml > +++ b/Documentation/DocBook/media/v4l/compat.xml > @@ -2523,6 +2523,16 @@ that used it. It was originally scheduled for removal > in 2.6.35. > > > > + > + V4L2 in Linux 3.14 > + > + > + Added Software Defined Radio (SDR) Interface. > + > + > + > + > + > >Relation of V4L2 to other Linux multimedia APIs > > diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml > b/Documentation/DocBook/media/v4l/dev-sdr.xml > new file mode 100644 > index 000..3caf44d > --- /dev/null > +++ b/Documentation/DocBook/media/v4l/dev-sdr.xml > @@ -0,0 +1,99 @@ > + Software Defined Radio Interface (SDR) > + > + > +SDR is an abbreviation of Software Defined Radio, the radio device > +which uses application software for modulation or demodulation. That > interface s/That/This/ > +is intended for controlling and data streaming of such devices. > + > + > + > +SDR devices are accessed through character device special files named > +/dev/swradio0 to /dev/swradio255 > +with major number 81 and dynamically allocated minor numbers 0 to 255. > + > + > + > +Querying Capabilities > + > + > +Devices supporting the SDR receiver interface set the > +V4L2_CAP_SDR_CAPTURE and > +V4L2_CAP_TUNER flag in the > +capabilities field of &v4l2-capability; > +returned by the &VIDIOC-QUERYCAP; ioctl. That flag means device has s/device has/the device has an/ > +Analog to Digital Converter (ADC), which is mandatory element for SDR > receiver. s/is/is a/ s/SDR/the SDR/ > +At least one of the read/write, streaming or asynchronous I/O methods must > +be supported. > + > + > + > + > +Supplemental Functions > + > + > +SDR devices can support controls, and must > +support the tuner ioctls. Tuner ioctls are used > +for setting ADC sampling rate (sampling frequency) and possible RF tuner s/ADC/the ADC/ s/RF/the RF/ > +frequency. > + > + > + > +V4L2_TUNER_ADC is used as a tuner type when ADC is in > +question and V4L2_TUNER_RF is used as a tuner type when > +RF tuner is in question. Possible RF tuner index number is always next one > +from the ADC index number. Normally ADC tuner is #0 and RF tuner is #1. > + I would rewrite this paragraph. How about: The V4L2_TUNER_ADC tuner type is used for ADC tuners, and the V4L2_TUNER_RF is used for RF tuners. The tuner index of the RF tuner (if any) must always follow the ADC tuner index. Normally the ADC tuner is #0 and the RF tuner is #1. > + > + > +VIDIOC_S_HW_FREQ_SEEK ioctl is not supported. Replace by: The &VIDIOC-S-HW-FREQ-SEEK; ioctl is not supported. > + > + > + > + > +Data Format Negotiation > + > + > +SDR capture device uses format ioctls to select s/SDR/The SDR/ s/uses/uses the/ > +capture format. Both sampling resolution and data streaming format are bind s/capture/the capture/ s/sampling/the sampling/ s/data/the data/ s/bind/bound/ > +to that selectable format. In addition to basic s/selectable/selected/ s/basic/the basic/ > +format ioctls, the > +VIDIOC_ENUM_FMT ioctl must be supported too. Use '&VIDIOC-ENUM-FMT;' instead. > + > + > + > +To use format ioctls applications set the s/use/use the/ > +type field of a &v4l2-format; to > +V4L2_BUF_TYPE_SDR_CAPTURE and use the &v4l2-format-sdr; > +sdr member of the fmt > +union as needed per desired operation. s/per/per the/ > +Currently there is only pixelformat field of > +&v4l2-format-sdr; used. Content of that field is data format V4L2 fourcc > code. Replace with: "Currently only the pixelformat field of &v4l2-format-sdr; is used. The content of that field is the V4L2 fourcc code of the data format." > + > + > + > + struct v4l2_format_sdr > + > +&cs-str; > + > + > +__u32 > +pixelformat > +little endian four character code (fourcc) That's a bit obscure. Look at Table 2.1 (struct v4l2_pix_format) how pixelformat is described there and copy-and-paste that. You also need to document the SDR pixelformats that you define. > + > + > +__u8 > +reserved[28] > +This array is reserv
[PATCH RFC v5 11/12] DocBook: Software Defined Radio Interface
Document V4L2 SDR interface. Cc: Hans Verkuil Signed-off-by: Antti Palosaari --- Documentation/DocBook/media/v4l/compat.xml | 10 +++ Documentation/DocBook/media/v4l/dev-sdr.xml | 99 Documentation/DocBook/media/v4l/io.xml | 6 ++ Documentation/DocBook/media/v4l/v4l2.xml | 1 + Documentation/DocBook/media/v4l/vidioc-g-fmt.xml | 6 ++ 5 files changed, 122 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/dev-sdr.xml diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 0c7195e..85fb864 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2523,6 +2523,16 @@ that used it. It was originally scheduled for removal in 2.6.35. + + V4L2 in Linux 3.14 + + + Added Software Defined Radio (SDR) Interface. + + + + + Relation of V4L2 to other Linux multimedia APIs diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml b/Documentation/DocBook/media/v4l/dev-sdr.xml new file mode 100644 index 000..3caf44d --- /dev/null +++ b/Documentation/DocBook/media/v4l/dev-sdr.xml @@ -0,0 +1,99 @@ + Software Defined Radio Interface (SDR) + + +SDR is an abbreviation of Software Defined Radio, the radio device +which uses application software for modulation or demodulation. That interface +is intended for controlling and data streaming of such devices. + + + +SDR devices are accessed through character device special files named +/dev/swradio0 to /dev/swradio255 +with major number 81 and dynamically allocated minor numbers 0 to 255. + + + +Querying Capabilities + + +Devices supporting the SDR receiver interface set the +V4L2_CAP_SDR_CAPTURE and +V4L2_CAP_TUNER flag in the +capabilities field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl. That flag means device has +Analog to Digital Converter (ADC), which is mandatory element for SDR receiver. +At least one of the read/write, streaming or asynchronous I/O methods must +be supported. + + + + +Supplemental Functions + + +SDR devices can support controls, and must +support the tuner ioctls. Tuner ioctls are used +for setting ADC sampling rate (sampling frequency) and possible RF tuner +frequency. + + + +V4L2_TUNER_ADC is used as a tuner type when ADC is in +question and V4L2_TUNER_RF is used as a tuner type when +RF tuner is in question. Possible RF tuner index number is always next one +from the ADC index number. Normally ADC tuner is #0 and RF tuner is #1. + + + +VIDIOC_S_HW_FREQ_SEEK ioctl is not supported. + + + + +Data Format Negotiation + + +SDR capture device uses format ioctls to select +capture format. Both sampling resolution and data streaming format are bind +to that selectable format. In addition to basic +format ioctls, the +VIDIOC_ENUM_FMT ioctl must be supported too. + + + +To use format ioctls applications set the +type field of a &v4l2-format; to +V4L2_BUF_TYPE_SDR_CAPTURE and use the &v4l2-format-sdr; +sdr member of the fmt +union as needed per desired operation. +Currently there is only pixelformat field of +&v4l2-format-sdr; used. Content of that field is data format V4L2 fourcc code. + + + + struct v4l2_format_sdr + +&cs-str; + + +__u32 +pixelformat +little endian four character code (fourcc) + + +__u8 +reserved[28] +This array is reserved for future extensions. +Drivers and applications must set it to zero. + + + + + + +A SDR device may support read/write +and/or streaming (memory mapping +or user pointer) I/O. + + + diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 2c4c068..1fb11e8 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -1005,6 +1005,12 @@ should set this to 0. Buffer for video output overlay (OSD), see . + + V4L2_BUF_TYPE_SDR_CAPTURE + 11 + Buffer for Software Defined Radio (SDR), see . + diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 8469fe1..a27fcae 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -529,6 +529,7 @@ and discussions on the V4L mailing list. &sub-dev-teletext; &sub-dev-radio; &sub-dev-rds; + &sub-dev-sdr; &sub-dev-event; &sub-dev-subdev; diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml index ee8f56e..60bf9b2 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml +++ b/Documentation/DocBoo
