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 hverk...@xs4all.nl Signed-off-by: Antti Palosaari cr...@iki.fi --- 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. /orderedlist /section +section + titleV4L2 in Linux 3.14/title + orderedlist +listitem + paraAdded Software Defined Radio (SDR) Interface. + /para +/listitem + /orderedlist +/section + section id=other titleRelation of V4L2 to other Linux multimedia APIs/title 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 @@ + titleSoftware Defined Radio Interface (SDR)/title + + para +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. + /para + + para +SDR devices are accessed through character device special files named +filename/dev/swradio0/filename to filename/dev/swradio255/filename +with major number 81 and dynamically allocated minor numbers 0 to 255. + /para + + section +titleQuerying Capabilities/title + +para +Devices supporting the SDR receiver interface set the +constantV4L2_CAP_SDR_CAPTURE/constant and +constantV4L2_CAP_TUNER/constant flag in the +structfieldcapabilities/structfield 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. +/para + /section + + section +titleSupplemental Functions/title + +para +SDR devices can support link linkend=controlcontrols/link, and must +support the link linkend=tunertuner/link 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. +/para + +para +constantV4L2_TUNER_ADC/constant is used as a tuner type when ADC is in +question and constantV4L2_TUNER_RF/constant 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. +/para I would rewrite this paragraph. How about: The constantV4L2_TUNER_ADC/constant tuner type is used for ADC tuners, and the constantV4L2_TUNER_RF/constant 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. + +para +constantVIDIOC_S_HW_FREQ_SEEK/constant ioctl is not supported. Replace by: The VIDIOC-S-HW-FREQ-SEEK; ioctl is not supported. +/para + /section + + section +titleData Format Negotiation/title + +para +SDR capture device uses link linkend=formatformat/link 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/ +link linkend=formatformat/link ioctls, the +constantVIDIOC_ENUM_FMT/constant ioctl must be supported too. Use 'VIDIOC-ENUM-FMT;' instead. +/para + +para +To use link linkend=formatformat/link ioctls applications set the s/use/use the/ +structfieldtype/structfield field of a v4l2-format; to +constantV4L2_BUF_TYPE_SDR_CAPTURE/constant and use the v4l2-format-sdr; +structfieldsdr/structfield member of the structfieldfmt/structfield +union as needed per desired operation. s/per/per the/ +Currently there is only structfieldpixelformat/structfield field of +v4l2-format-sdr; used. Content of that field is data format V4L2 fourcc code. Replace with: Currently only the structfieldpixelformat/structfield field
[PATCH RFC v5 11/12] DocBook: Software Defined Radio Interface
Document V4L2 SDR interface. Cc: Hans Verkuil hverk...@xs4all.nl Signed-off-by: Antti Palosaari cr...@iki.fi --- 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. /orderedlist /section +section + titleV4L2 in Linux 3.14/title + orderedlist +listitem + paraAdded Software Defined Radio (SDR) Interface. + /para +/listitem + /orderedlist +/section + section id=other titleRelation of V4L2 to other Linux multimedia APIs/title 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 @@ + titleSoftware Defined Radio Interface (SDR)/title + + para +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. + /para + + para +SDR devices are accessed through character device special files named +filename/dev/swradio0/filename to filename/dev/swradio255/filename +with major number 81 and dynamically allocated minor numbers 0 to 255. + /para + + section +titleQuerying Capabilities/title + +para +Devices supporting the SDR receiver interface set the +constantV4L2_CAP_SDR_CAPTURE/constant and +constantV4L2_CAP_TUNER/constant flag in the +structfieldcapabilities/structfield 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. +/para + /section + + section +titleSupplemental Functions/title + +para +SDR devices can support link linkend=controlcontrols/link, and must +support the link linkend=tunertuner/link ioctls. Tuner ioctls are used +for setting ADC sampling rate (sampling frequency) and possible RF tuner +frequency. +/para + +para +constantV4L2_TUNER_ADC/constant is used as a tuner type when ADC is in +question and constantV4L2_TUNER_RF/constant 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. +/para + +para +constantVIDIOC_S_HW_FREQ_SEEK/constant ioctl is not supported. +/para + /section + + section +titleData Format Negotiation/title + +para +SDR capture device uses link linkend=formatformat/link ioctls to select +capture format. Both sampling resolution and data streaming format are bind +to that selectable format. In addition to basic +link linkend=formatformat/link ioctls, the +constantVIDIOC_ENUM_FMT/constant ioctl must be supported too. +/para + +para +To use link linkend=formatformat/link ioctls applications set the +structfieldtype/structfield field of a v4l2-format; to +constantV4L2_BUF_TYPE_SDR_CAPTURE/constant and use the v4l2-format-sdr; +structfieldsdr/structfield member of the structfieldfmt/structfield +union as needed per desired operation. +Currently there is only structfieldpixelformat/structfield field of +v4l2-format-sdr; used. Content of that field is data format V4L2 fourcc code. +/para + +table pgwide=1 frame=none id=v4l2-format-sdr + titlestruct structnamev4l2_format_sdr/structname/title + tgroup cols=3 +cs-str; +tbody valign=top + row +entry__u32/entry +entrystructfieldpixelformat/structfield/entry +entrylittle endian four character code (fourcc)/entry + /row + row +entry__u8/entry +entrystructfieldreserved[28]/structfield/entry +entryThis array is reserved for future extensions. +Drivers and applications must set it to zero./entry + /row +/tbody + /tgroup +/table + +para +A SDR device may support link linkend=rwread/write/link +and/or streaming (link linkend=mmapmemory mapping/link +or link linkend=userpuser pointer/link) I/O. +/para + + /section diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index