borrowed from ubuntu git://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux-firmware
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

LICENCE.go7007 20KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457
  1. The README file from the original package from Micronas appears below. Only
  2. the part about the firmware redistribution in section 0 is relevant, all
  3. other sections are completely obsolete.
  4. ---------------------------------------------------------------------------
  5. WIS GO7007SB Public Linux Driver
  6. ---------------------------------------------------------------------------
  7. *** Please see the file RELEASE-NOTES for important last-minute updates ***
  8. 0. OVERVIEW AND LICENSING/DISCLAIMER
  9. This driver kit contains Linux drivers for the WIS GO7007SB multi-format
  10. video encoder. Only kernel version 2.6.x is supported. The video stream
  11. is available through the Video4Linux2 API and the audio stream is available
  12. through the ALSA API (or the OSS emulation layer of the ALSA system).
  13. The files in kernel/ and hotplug/ are licensed under the GNU General Public
  14. License Version 2 from the Free Software Foundation. A copy of the license
  15. is included in the file COPYING.
  16. The example applications in apps/ and C header files in include/ are
  17. licensed under a permissive license included in the source files which
  18. allows copying, modification and redistribution for any purpose without
  19. attribution.
  20. The firmware files included in the firmware/ directory may be freely
  21. redistributed only in conjunction with this document; but modification,
  22. tampering and reverse engineering are prohibited.
  23. MICRONAS USA, INC., MAKES NO WARRANTIES TO ANY PERSON OR ENTITY WITH
  24. RESPECT TO THE SOFTWARE OR ANY DERIVATIVES THEREOF OR ANY SERVICES OR
  25. LICENSES AND DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION
  26. WARRANTIES OF MERCHANTABILITY, SUPPORT, AND FITNESS FOR A PARTICULAR
  27. PURPOSE AND NON-INFRINGEMENT.
  28. 1. SYSTEM REQUIREMENTS
  29. This driver requires Linux kernel 2.6. Kernel 2.4 is not supported. Using
  30. kernel 2.6.10 or later is recommended, as earlier kernels are known to have
  31. unstable USB 2.0 support.
  32. A fully built kernel source tree must be available. Typically this will be
  33. linked from "/lib/modules/<KERNEL VERSION>/build" for convenience. If this
  34. link does not exist, an extra parameter will need to be passed to the
  35. `make` command.
  36. All vendor-built kernels should already be configured properly. However,
  37. for custom-built kernels, the following options need to be enabled in the
  38. kernel as built-in or modules:
  39. CONFIG_HOTPLUG - Support for hot-pluggable devices
  40. CONFIG_MODULES - Enable loadable module support
  41. CONFIG_KMOD - Automatic kernel module loading
  42. CONFIG_FW_LOADER - Hotplug firmware loading support
  43. CONFIG_I2C - I2C support
  44. CONFIG_VIDEO_DEV - Video For Linux
  45. CONFIG_SOUND - Sound card support
  46. CONFIG_SND - Advanced Linux Sound Architecture
  47. CONFIG_USB - Support for Host-side USB
  48. CONFIG_USB_DEVICEFS - USB device filesystem
  49. CONFIG_USB_EHCI_HCD - EHCI HCD (USB 2.0) support
  50. Additionally, to use the example application, the following options need to
  51. be enabled in the ALSA section:
  52. CONFIG_SND_MIXER_OSS - OSS Mixer API
  53. CONFIG_SND_PCM_OSS - OSS PCM (digital audio) API
  54. The hotplug scripts, along with the fxload utility, must also be installed.
  55. These scripts can be obtained from <http://linux-hotplug.sourceforge.net/>.
  56. Hotplugging is used for loading firmware into the Cypruss EZ-USB chip using
  57. fxload and for loading firmware into the driver using the firmware agent.
  58. 2. COMPILING AND INSTALLING THE DRIVER
  59. Most users should be able to compile the driver by simply running:
  60. $ make
  61. in the top-level directory of the driver kit. First the kernel modules
  62. will be built, followed by the example applications.
  63. If the build system is unable to locate the kernel source tree for the
  64. currently-running kernel, or if the module should be built for a kernel
  65. other than the currently-running kernel, an additional parameter will need
  66. to be passed to make to specify the appropriate kernel source directory:
  67. $ make KERNELSRC=/usr/src/linux-2.6.10-custom3
  68. Once the compile completes, the driver and firmware files should be
  69. installed by running:
  70. $ make install
  71. The kernel modules will be placed in "/lib/modules/<KERNEL VERSION>/extra"
  72. and the firmware files will be placed in the appropriate hotplug firmware
  73. directory, usually /lib/firmware. In addition, USB maps and scripts will
  74. be placed in /etc/hotplug/usb to enable fxload to initialize the EZ-USB
  75. control chip when the device is connected.
  76. 3. PAL/SECAM TUNER CONFIGURATION (TV402U-EU only)
  77. The PAL model of the Plextor ConvertX TV402U may require additional
  78. configuration to correctly select the appropriate TV frequency band and
  79. audio subchannel.
  80. Users with a device other than the Plextor ConvertX TV402U-EU should skip
  81. this section.
  82. The wide variety of PAL TV systems used in Europe requires that additional
  83. information about the local TV standards be passed to the driver in order
  84. to properly tune TV channels. The two necessary parameters are (a) the PAL
  85. TV band, and (b) the audio subchannel format in use.
  86. In many cases, the appropriate TV band selection is passed to the driver
  87. from applications. However, in some cases, the application only specifies
  88. that the driver should use PAL but not the specific information about the
  89. appropriate TV band. To work around this issue, the correct TV band may be
  90. specified in the "force_band" parameter to the wis-sony-tuner module:
  91. TV band force_band
  92. ------- ----------
  93. PAL B/G B
  94. PAL I I
  95. PAL D/K D
  96. SECAM L L
  97. If the "force_band" parameter is specified, the driver will ignore any TV
  98. band specified by applications and will always use the band provided in the
  99. module parameter.
  100. The other parameter that can be specified is the audio subchannel format.
  101. There are several stereo audio carrier systems in use, including NICAM and
  102. three varieties of A2. To receive audio broadcast on one of these stereo
  103. carriers, the "force_mpx_mode" parameter must be specified to the
  104. wis-sony-tuner module.
  105. TV band Audio subcarrier force_mpx_mode
  106. ------- ---------------- --------------
  107. PAL B/G Mono (default) 1
  108. PAL B/G A2 2
  109. PAL B/G NICAM 3
  110. PAL I Mono (default) 4
  111. PAL I NICAM 5
  112. PAL D/K Mono (default) 6
  113. PAL D/K A2 (1) 7
  114. PAL D/K A2 (2) 8
  115. PAL D/K A2 (3) 9
  116. PAL D/K NICAM 10
  117. SECAM L Mono (default) 11
  118. SECAM L NICAM 12
  119. If the "force_mpx_mode" parameter is not specified, the correct mono-only
  120. mode will be chosen based on the TV band. However, the tuner will not
  121. receive stereo audio or bilingual broadcasts correctly.
  122. To pass the "force_band" or "force_mpx_mode" parameters to the
  123. wis-sony-tuner module, the following line must be added to the modprobe
  124. configuration file, which varies from one Linux distribution to another.
  125. options wis-sony-tuner force_band=B force_mpx_mode=2
  126. The above example would force the tuner to the PAL B/G TV band and receive
  127. stereo audio broadcasts on the A2 carrier.
  128. To verify that the configuration has been placed in the correct location,
  129. execute:
  130. $ modprobe -c | grep wis-sony-tuner
  131. If the configuration line appears, then modprobe will pass the parameters
  132. correctly the next time the wis-sony-tuner module is loaded into the
  133. kernel.
  134. 4. TESTING THE DRIVER
  135. Because few Linux applications are able to correctly capture from
  136. Video4Linux2 devices with only compressed formats supported, the new driver
  137. should be tested with the "gorecord" application in the apps/ directory.
  138. First connect a video source to the device, such as a DVD player or VCR.
  139. This will be captured to a file for testing the driver. If an input source
  140. is unavailable, a test file can still be captured, but the video will be
  141. black and the audio will be silent.
  142. This application will auto-detect the V4L2 and ALSA/OSS device names of the
  143. hardware and will record video and audio to an AVI file for a specified
  144. number of seconds. For example:
  145. $ apps/gorecord -duration 60 capture.avi
  146. If this application does not successfully record an AVI file, the error
  147. messages produced by gorecord and recorded in the system log (usually in
  148. /var/log/messages) should provide information to help resolve the problem.
  149. Supplying no parameters to gorecord will cause it to probe the available
  150. devices and exit. Use the -help flag for usage information.
  151. 5. USING THE DRIVER
  152. The V4L2 device implemented by the driver provides a standard compressed
  153. format API, within the following criteria:
  154. * Applications that only support the original Video4Linux1 API will not
  155. be able to communicate with this driver at all.
  156. * No raw video modes are supported, so applications like xawtv that
  157. expect only uncompressed video will not function.
  158. * Supported compression formats are: Motion-JPEG, MPEG1, MPEG2 and MPEG4.
  159. * MPEG video formats are delivered as Video Elementary Streams only.
  160. Program Stream (PS), Transport Stream (TS) and Packetized Elementary
  161. Stream (PES) formats are not supported.
  162. * Video parameters such as format and input port may not be changed while
  163. the encoder is active.
  164. * The audio capture device only functions when the video encoder is
  165. actively capturing video. Attempts to read from the audio device when
  166. the encoder is inactive will result in an I/O error.
  167. * The native format of the audio device is 48Khz 2-channel 16-bit
  168. little-endian PCM, delivered through the ALSA system. No audio
  169. compression is implemented in the hardware. ALSA may convert to other
  170. uncompressed formats on the fly.
  171. The include/ directory contains a C header file describing non-standard
  172. features of the GO7007SB encoder, which are described below:
  173. GO7007IOC_S_COMP_PARAMS, GO7007IOC_G_COMP_PARAMS
  174. These ioctls are used to negotiate general compression parameters.
  175. To query the current parameters, call the GO7007IOC_G_COMP_PARAMS ioctl
  176. with a pointer to a struct go7007_comp_params. If the driver is not
  177. set to MPEG format, the EINVAL error code will be returned.
  178. To change the current parameters, initialize all fields of a struct
  179. go7007_comp_params and call the GO7007_IOC_S_COMP_PARAMS ioctl with a
  180. pointer to this structure. The driver will return the current
  181. parameters with any necessary changes to conform to the limitations of
  182. the hardware or current compression mode. Any or all fields can be set
  183. to zero to request a reasonable default value. If the driver is not
  184. set to MPEG format, the EINVAL error code will be returned. When I/O
  185. is in progress, the EBUSY error code will be returned.
  186. Fields in struct go7007_comp_params:
  187. __u32 The maximum number of frames in each
  188. gop_size Group Of Pictures; i.e. the maximum
  189. number of frames minus one between
  190. each key frame.
  191. __u32 The maximum number of sequential
  192. max_b_frames bidirectionally-predicted frames.
  193. (B-frames are not yet supported.)
  194. enum go7007_aspect_ratio The aspect ratio to be encoded in the
  195. aspect_ratio meta-data of the compressed format.
  196. Choices are:
  197. GO7007_ASPECT_RATIO_1_1
  198. GO7007_ASPECT_RATIO_4_3_NTSC
  199. GO7007_ASPECT_RATIO_4_3_PAL
  200. GO7007_ASPECT_RATIO_16_9_NTSC
  201. GO7007_ASPECT_RATIO_16_9_PAL
  202. __u32 Bit-wise OR of control flags (below)
  203. flags
  204. Flags in struct go7007_comp_params:
  205. GO7007_COMP_CLOSED_GOP Only produce self-contained GOPs, used
  206. to produce streams appropriate for
  207. random seeking.
  208. GO7007_COMP_OMIT_SEQ_HEADER Omit the stream sequence header.
  209. GO7007IOC_S_MPEG_PARAMS, GO7007IOC_G_MPEG_PARAMS
  210. These ioctls are used to negotiate MPEG-specific stream parameters when
  211. the pixelformat has been set to V4L2_PIX_FMT_MPEG.
  212. To query the current parameters, call the GO7007IOC_G_MPEG_PARAMS ioctl
  213. with a pointer to a struct go7007_mpeg_params. If the driver is not
  214. set to MPEG format, the EINVAL error code will be returned.
  215. To change the current parameters, initialize all fields of a struct
  216. go7007_mpeg_params and call the GO7007_IOC_S_MPEG_PARAMS ioctl with a
  217. pointer to this structure. The driver will return the current
  218. parameters with any necessary changes to conform to the limitations of
  219. the hardware or selected MPEG mode. Any or all fields can be set to
  220. zero to request a reasonable default value. If the driver is not set
  221. to MPEG format, the EINVAL error code will be returned. When I/O is in
  222. progress, the EBUSY error code will be returned.
  223. Fields in struct go7007_mpeg_params:
  224. enum go7007_mpeg_video_standard
  225. mpeg_video_standard The MPEG video standard in which to
  226. compress the video.
  227. Choices are:
  228. GO7007_MPEG_VIDEO_MPEG1
  229. GO7007_MPEG_VIDEO_MPEG2
  230. GO7007_MPEG_VIDEO_MPEG4
  231. __u32 Bit-wise OR of control flags (below)
  232. flags
  233. __u32 The profile and level indication to be
  234. pali stored in the sequence header. This
  235. is only used as an indicator to the
  236. decoder, and does not affect the MPEG
  237. features used in the video stream.
  238. Not valid for MPEG1.
  239. Choices for MPEG2 are:
  240. GO7007_MPEG2_PROFILE_MAIN_MAIN
  241. Choices for MPEG4 are:
  242. GO7007_MPEG4_PROFILE_S_L0
  243. GO7007_MPEG4_PROFILE_S_L1
  244. GO7007_MPEG4_PROFILE_S_L2
  245. GO7007_MPEG4_PROFILE_S_L3
  246. GO7007_MPEG4_PROFILE_ARTS_L1
  247. GO7007_MPEG4_PROFILE_ARTS_L2
  248. GO7007_MPEG4_PROFILE_ARTS_L3
  249. GO7007_MPEG4_PROFILE_ARTS_L4
  250. GO7007_MPEG4_PROFILE_AS_L0
  251. GO7007_MPEG4_PROFILE_AS_L1
  252. GO7007_MPEG4_PROFILE_AS_L2
  253. GO7007_MPEG4_PROFILE_AS_L3
  254. GO7007_MPEG4_PROFILE_AS_L4
  255. GO7007_MPEG4_PROFILE_AS_L5
  256. Flags in struct go7007_mpeg_params:
  257. GO7007_MPEG_FORCE_DVD_MODE Force all compression parameters and
  258. bitrate control settings to comply
  259. with DVD MPEG2 stream requirements.
  260. This overrides most compression and
  261. bitrate settings!
  262. GO7007_MPEG_OMIT_GOP_HEADER Omit the GOP header.
  263. GO7007_MPEG_REPEAT_SEQHEADER Repeat the MPEG sequence header at
  264. the start of each GOP.
  265. GO7007IOC_S_BITRATE, GO7007IOC_G_BITRATE
  266. These ioctls are used to set and query the target bitrate value for the
  267. compressed video stream. The bitrate may be selected by storing the
  268. target bits per second in an int and calling GO7007IOC_S_BITRATE with a
  269. pointer to the int. The bitrate may be queried by calling
  270. GO7007IOC_G_BITRATE with a pointer to an int where the current bitrate
  271. will be stored.
  272. Note that this is the primary means of controlling the video quality
  273. for all compression modes, including V4L2_PIX_FMT_MJPEG. The
  274. VIDIOC_S_JPEGCOMP ioctl is not supported.
  275. ----------------------------------------------------------------------------
  276. Installing the WIS PCI Voyager Driver
  277. ---------------------------------------------------------------------------
  278. The WIS PCI Voyager driver requires several patches to the Linux 2.6.11.x
  279. kernel source tree before compiling the driver. These patches update the
  280. in-kernel SAA7134 driver to the newest development version and patch bugs
  281. in the TDA8290/TDA8275 tuner driver.
  282. The following patches must be downloaded from Gerd Knorr's website and
  283. applied in the order listed:
  284. http://dl.bytesex.org/patches/2.6.11-2/i2c-tuner
  285. http://dl.bytesex.org/patches/2.6.11-2/i2c-tuner2
  286. http://dl.bytesex.org/patches/2.6.11-2/v4l2-api-mpeg
  287. http://dl.bytesex.org/patches/2.6.11-2/saa7134-update
  288. The following patches are included with this SDK and can be applied in any
  289. order:
  290. patches/2.6.11/saa7134-voyager.diff
  291. patches/2.6.11/tda8275-newaddr.diff
  292. patches/2.6.11/tda8290-ntsc.diff
  293. Check to make sure the CONFIG_VIDEO_SAA7134 option is enabled in the kernel
  294. configuration, and build and install the kernel.
  295. After rebooting into the new kernel, the GO7007 driver can be compiled and
  296. installed:
  297. $ make SAA7134_BUILD=y
  298. $ make install
  299. $ modprobe saa7134-go7007
  300. There will be two V4L video devices associated with the PCI Voyager. The
  301. first device (most likely /dev/video0) provides access to the raw video
  302. capture mode of the SAA7133 device and is used to configure the source
  303. video parameters and tune the TV tuner. This device can be used with xawtv
  304. or other V4L(2) video software as a standard uncompressed device.
  305. The second device (most likely /dev/video1) provides access to the
  306. compression functions of the GO7007. It can be tested using the gorecord
  307. application in the apps/ directory of this SDK:
  308. $ apps/gorecord -vdevice /dev/video1 -noaudio test.avi
  309. Currently the frame resolution is fixed at 720x480 (NTSC) or 720x576 (PAL),
  310. and the video standard must be specified to both the raw and the compressed
  311. video devices (xawtv and gorecord, for example).
  312. --------------------------------------------------------------------------
  313. RELEASE NOTES FOR WIS GO7007SB LINUX DRIVER
  314. ---------------------------------------------------------------------------
  315. Last updated: 5 November 2005
  316. - Release 0.9.7 includes new support for using udev to run fxload. The
  317. install script should automatically detect whether the old hotplug
  318. scripts or the new udev rules should be used. To force the use of
  319. hotplug, run "make install USE_UDEV=n". To force the use of udev, run
  320. "make install USE_UDEV=y".
  321. - Motion detection is supported but undocumented. Try the `modet` app
  322. for a demonstration of how to use the facility.
  323. - Using USB2.0 devices such as the TV402U with USB1.1 HCDs or hubs can
  324. cause buffer overruns and frame drops, even at low framerates, due to
  325. inconsistency in the bitrate control mechanism.
  326. - On devices with an SAA7115, including the Plextor ConvertX, video height
  327. values of 96, 128, 160, 192, 256, 320, and 384 do not work in NTSC mode.
  328. All valid heights up to 512 work correctly in PAL mode.
  329. - The WIS Star Trek and PCI Voyager boards have no support yet for audio
  330. or the TV tuner.