readme.realmagichwl

神龙卡开发原代码

Main module (realmagichwl_kernelland.o)
--------------------------------------- 
The main module enables MPEG decoding features on /dev/realmagichwl0

Its major number is 125, create device node:

mknod /dev/realmagichwl0 c 125 0
mknod /dev/realmagichwl1 c 125 1
mknod /dev/realmagichwl2 c 125 2...

Up to MAXPROBEDQUASARS=32 (see realmagichwl_kernelland/realmagichwl.h)
devices are supported. Irq sharing is supported. All Sigma chips
>=0x8400 will be probed. To know which card has which number, look in
the log files (/var/log/messages).

Allowed parameters:
enable_async= (1 or 0)

See section data transfer below to understand the meaning of this parameter.

OSD buffer (realmagichwl_kernelland_osdbuf.o)
---------------------------------------------
Be careful about the difference between OSD _buffer_ and OSD _framebuffer_. The
second is used on top of the first and has more features.

To enable a plain mmap()able OSD buffer, insmod realmagichwl_kernelland_osdbuf.o

For this to work, you must reserve some physical memory on the top of
your PC RAM. Run the script: 
sh cropram.sh 1000000
and follow the instructions.

This allows to use up to three framebuffers devices (each is 340KBytes approx).

Allowed parameters:
osdbuf_physicaladdress= (example shows usage)
osdbuf_size=            (example shows usage)

enable= : if your PC has 7 EM84xx devices #0 .. #6, enable=,,,1,,1 enables osdbuf on #3 and #5 only.
Default behaviour is to enable #0. Use enable=-1 to enable none.

Think of this notation as:
           , , ,1, ,1 (sixth not even specified)
	  ^ ^ ^ ^ ^ ^ 
device #: 0 1 2 3 4 5 6 

An enabled osdbuf shows circular patterns in alternating R, G, B colors
starting from the center alpha-blended on the video.

Usage of the OSD buffer is compatible with video and audio playback.

To unload realmagichwl_kernelland_osdbuf, use the 
realmagichwl_userland/osdbuf_fb_control utility to switch off one
by one all enabled osdbuf's.

An osdbuf cannot be switched off if a fb is running on top of it.	

realmagichwl_kernelland_osdbuf also supports various sizes, same parameter
syntax as realmagichwl_kernelland_yuvbuf. 
Default sizes are REALMAGICHWL_OSDBUFWIDTHxREALMAGICHWL_OSDBUFHEIGHT at
REALMAGICHWL_OSDBUFCOLORDEPTH (640x480@8bpp) for all.

osdbuf supports color depths 1,2,4 and 8.
by default the run length encoder is disable. You can enable it when inserting the module
parameter is rlc, or using the osd set dimension property.

the run length encoder is quite cpu consuming. Normally the result is shorter than the
decoded osd buffer. But in some cases it is not. A check of memory overflow inside the 
run length encoder can be enable or disable. (enable => more cpu usage but the driver will
never crash)
At compile time you can choose to enable or not the check:
REALMAGICHWL_FEATURES=-DWITH_CHECK_OSD_RLC=1 will enable it.

if REALMAGICHWL_FEATURES  is not defined the check is performed.

Linux frame buffer architecture compliant driver (realmagichwl_kernelland_fb.o)
-------------------------------------------------------------------------------
This module depends on realmagichwl_kernelland_osdbuf.o.
Your kernel must also have been compiled with frame buffer support (fb.o)

enable= : if your PC has 7 EM84xx devices #0 .. #6, enable=,,,1,,1 enables fb on #3 and #5 only.
Default behaviour is to enable #0. Use enable=-1 to enable none.

If your Linux box had no previous framebuffer device active, the new
one is /dev/fb0 and all consoles automatically jump on it. 

In this case you cannot unload realmagichwl_kernelland_fb unless you
enable another framebuffer device (maybe your graphic card can do
this) and send all consoles there.

__This is not a bug; this is a normal and expected behavior.__

To move consoles use:
realmagichwl_userland/sendconsoletoframebuffer	

realmagichwl_userland/fbswitch can also be used to enable/disable manually fb's.
	
The framebuffer device has a fixed size of REALMAGICHWL_OSDBUFWIDTHxREALMAGICHWL_OSDBUFHEIGHT
and color depth REALMAGICHWL_OSDBUFCOLORDEPTH. Its base osdbuf must be the same size.

YUV buffer (realmagichwl_kernelland_yuvbuf.o) 
--------------------------------------------- 
Now supported by both EM840x and EM847x.

To enable a plain mmap()able YUV buffer (either 4:2:0 or 4:2:2 data format), 
insmod realmagichwl_kernelland_yuvbuf.o
Same parameters as realmagichwl_kernelland_osdbuf.o (replace `osd' with `yuv').

Default sizes are REALMAGICHWL_YUVBUFWIDTHxREALMAGICHWL_YUVBUFHEIGHT (720x480) for all.
Default YUV data format is REALMAGICHWL_YUVBUFDATAFORMAT (YUV 4:2:0).

To specify alternate sizes and YUV data format use the following parameters:
enable=,,,1,,1 width=,,,,,400 height=,,,1000,,450 yuv_format=,,,,1,
enables yuvbuf #3 of size 1000x480/4:2:0, #5 of size 400x450/4:2:2.
		**The maximum YUV buffer size is 1632x918**
Use enable=-1 to enable none. yuvbuf_control allows to do this afterwards
(ex: yuvbuf_control 3 -y11000,480,0 for size 1000x480 and YUV 4:2:0 data format, 
note the `1' twice)

An enabled yuvbuf shows colored level lines with a saddle point.

OSD buffer and YUV buffer can be used simultaneously but you must
ensure their memory zones do not overlap.

Usage of the YUV buffer _excludes_ video playback.

Linux sound architecture compliant driver (realmagichwl_kernelland_snd.o)
-------------------------------------------------------------------------
Your kernel must have been compiled with sound support (soundcore.o)
	
The realmagic sound driver is an OSS sound driver. To work it needs the
kernel OSS support (soundcore.o).

Before trying to use the sound driver make sure you have the following
file devices, with read/write attributes:

/dev/realmagichwl (125,0)
/dev/dsp          (14, 3)
/dev/mixer        (14, 0)

(NB: example mknod -m 666 /dev/dsp c 14 3)

To enable the driver there are 2 steps:
1) install the loadable modules realmagichwl_kernelland and realmagichwl_kernelland_snd
/sbin/insmod realmagichwl_kernelland.o (should be done already)
/sbin/insmod realmagichwl_kernelland_snd.o (sound specific module)

2) switch on the audio driver
sndmixerswitch <device number> <0/1>
the device number is the index of the /dev/realmagichwl you want to
use. If only one board :0.
the second argument is 1 to enable the sound driver
                       0 to disable it
(example: sndmixerswitch 0 1)

Now you can use whatever application compatible with the OSS API.
common linux applications are:
	mpg123 for mp3 files;
	play   for wav files.
	aumix  to control the volume.
	realaudio plugin for netscape

Before removing the module realmagichwl_kernelland you need to disable the
sound driver with the command in our example: 
sndmixerswitch 0 0

Note:
if you have multiple realmagic cards or sound cards, the realmagic
audio devices (/dev/dsp and /dev/mixer) may have different minor number.
They are logged as: 

Mar 26 10:41:29 ulysse kernel: (hwl1) realmagic sound driver
(/dev/mixer0,/dev/dsp3) registered.  

Here the /dev/realmagichwl1 audio driver uses: 
/dev/dsp (14, 3) and /dev/mixer (14, 0)

But in this case 

Mar 27 19:51:41 ulysse kernel: (hwl0) realmagic sound driver
(/dev/mixer16, /dev/dsp19) registered.

Here the /dev/realmagichwl0 audio driver uses:
/dev/dsp1 (14,19) and /dev/mixer1 (14, 16)

In most applications you can specify the device you want to use. This may
be useful in case of muliple boards.

Settings
---------------
* as much as possible a running decoder (resp. osdbuf, encoder) is
reset in the same state.

* realmagichwl_userland/encode2file.c shows some code to use encoder settings

* realmagichwl_userland/playm2v.c shows some code to use decoder settings

Algorithmic details, latency concerns, multiple access
------------------------------------------------------
* two ore more different user application may open the driver at the
same time. ioctl() completion consistency is ensured. As a counterpart, 
what the user tries to do may be inconsistent. [Typical use would be: writing
monitors, handling analog overlay, activate/deactivate osdbuf]

* Queueing user OSD payload cannot be done when osdbuf is active.

Incompatible hardware
---------------------
* EM84xx PCI chips support IRQ sharing and IRQ sharing scenarios
have been tested with sucess.

If you observe a freeze when running insmod realmagichwl_kernelland.o,
chances are a device not supporting IRQ sharing exists on the same IRQ