Re: Proposal for documentation patch - driver man pages, HWCursor, SWCursor
On Fri, 17 Oct 2003, Mark Vojkovich wrote: I checked driver man pages in xc/programs/Xserver/hw/xfree86/drivers/*/*.man Almost every driver implements the options: HWCursor, SWCursor however they are documented differently. Further, having two separate options is silly. It is a two-state switch: either the driver tries to use a HW cursor, or it always forces a SW cursor. What happens if you specify both, or neither? I'll bet different drivers come to different conclusions. That's why I only documented one of them. We could settle on one to document. The nv driver supports both because people seem to use either. This is more for the list than you Mark, as you know this of course. ;o) The X server has a plethora of ways of indicating the same boolean meaning: Option swcursor Option SWcursor Option swcursor yes Option sw cursor TRUE Option hwcursor false Option hwcursor no Option NoHwcursor Option sW___c___u__R S or Y eS all of the above options should do the exact same thing, and enable software cursor (or disable hardware cursor depending on your perspective). Likewise, similar options for hwcursor will enable it. The majority of drivers default to using the hardware cursor in all cases, however some of them default to using swcursor either due to hardware cursor limitations, or bugs in the hardware cursor code in the driver, sometimes just for one chip. The colour ARGB cursors add a new twist to this as well, as some hardware simply doesn't support using ARGB cursors in hardware cursor mode. Without specifying swcursor nor hwcursor you'll generally get hardware cursors if the driver supports it on your hardware and doesn't disable it due to hardware limitations or broken driver workaround hacks. If you're using the new colour mouse cursors, then wether you get hardware cursors or not depends on the driver and chip also. Since you might get hardware or software cursors by default depending on the variety of variables involved, both of the hwcursor and swcursor options make sense in a general X server sense. As a human, I think I want hardware cursors or I want software cursors rather than I want hardware cursors or I want no hardware cursors. Also, removing one of the two options from XFree86 would not really provide any benefit IMHO, and it would break config file compatibility and a lot of pre-existing usage. If it were deemed that this was the way to go anyway, and one of the two options were to be eliminated across the server and all drivers as a whole, I would only find that rational if all other options in the X server followed suit, and thus remove all redundant options at once. There is a lot of redundancy in the config file syntax. That was purported as a feature way back when I presume, and it's debateable wether or not it was a good thing or a bad thing I guess. ;o) Hopefully it doesn't change majorly between non-major X server generations, as that makes upgrades a PITA. ;o) -- Mike A. Harris ___ Devel mailing list [EMAIL PROTECTED] http://XFree86.Org/mailman/listinfo/devel
Re: Proposal for documentation patch - driver man pages, HWCursor, SWCursor
On Fri, Oct 17, 2003 at 10:32:28PM -0400, David Dawes wrote:
On Fri, Oct 17, 2003 at 02:15:20PM -0700, Tim Roberts wrote:
On Fri, 17 Oct 2003 23:44:57 +0300, Alexander Shopov wrote:
I checked driver man pages in xc/programs/Xserver/hw/xfree86/drivers/*/*.man
Almost every driver implements the options:
HWCursor, SWCursor however they are documented differently.
Further, having two separate options is silly. It is a two-state switch:
either the driver tries to use a HW cursor, or it always forces a SW
cursor. What happens if you specify both, or neither? I'll bet different
drivers come to different conclusions.
The presence of both is probably historical. Some drivers have one,
some both. The mga driver seems to define both, but only checks one.
If you specify neither, the driver should default to whatever works
best. That's the driver's call, but it should generally be HW cursor
when available.
Specifying both would be undefined in general, if both were specifying
contrary behaviour.
One way to handle the naming more uniformly might be to define the
concept of option aliases, with, say, SWCursor aliased to NoHWCursor.
That would make the specifying both behaviour well-defined too.
I've just committed a small change to the OptionInfoRec lookup code that
allows a simple form of aliasing for these types of options. Instead
of returning the first entry matching the token it now favours the first
matching entry that has been set (if one is). If two options with the
same token are both specified in the config file, the first in the
driver's list takes precedence.
If someone wants to generate a patch for various drivers that makes
these two options equivalent via this aliasing mechanism (and the same
for any other cases where two different option names are used to control
the same thing), it would be considered as a bug fix for 4.4.
Here is a sample patch for the radeon driver that I used for testing.
It also makes the declared but unused dac8bit option usable (another
example of two options names serving the same purpose).
Index: radeon_driver.c
===
RCS file: /home/x-cvs/xc/programs/Xserver/hw/xfree86/drivers/ati/radeon_driver.c,v
retrieving revision 1.109
diff -u -r1.109 radeon_driver.c
--- radeon_driver.c 11 Oct 2003 00:29:57 - 1.109
+++ radeon_driver.c 18 Oct 2003 12:19:23 -
@@ -112,7 +112,6 @@
OPTION_NOACCEL,
OPTION_SW_CURSOR,
OPTION_DAC_6BIT,
-OPTION_DAC_8BIT,
#ifdef XF86DRI
OPTION_IS_PCI,
OPTION_BUS_TYPE,
@@ -144,8 +143,9 @@
const OptionInfoRec RADEONOptions[] = {
{ OPTION_NOACCEL,NoAccel, OPTV_BOOLEAN, {0}, FALSE },
{ OPTION_SW_CURSOR, SWcursor, OPTV_BOOLEAN, {0}, FALSE },
+{ OPTION_SW_CURSOR, NoHWcursor, OPTV_BOOLEAN, {0}, FALSE },
{ OPTION_DAC_6BIT, Dac6Bit, OPTV_BOOLEAN, {0}, FALSE },
-{ OPTION_DAC_8BIT, Dac8Bit, OPTV_BOOLEAN, {0}, TRUE },
+{ OPTION_DAC_6BIT, NoDac8Bit,OPTV_BOOLEAN, {0}, FALSE },
#ifdef XF86DRI
{ OPTION_IS_PCI, ForcePCIMode, OPTV_BOOLEAN, {0}, FALSE },
{ OPTION_BUS_TYPE, BusType, OPTV_ANYSTR, {0}, FALSE },
David
--
David Dawes X-Oz Technologies
www.XFree86.org/~dawes www.x-oz.com
___
Devel mailing list
[EMAIL PROTECTED]
http://XFree86.Org/mailman/listinfo/devel
Re: Proposal for documentation patch - driver man pages, HWCursor, SWCursor
On Sat, Oct 18, 2003 at 08:30:05AM +0300, Alexander Shopov wrote: Back to the original point, the documentation of these options in the driver man pages should match how they are handled by the individual drivers. Specifically, the documented defaults may legitimately be different for different drivers. I am not talking about the defaults but what HWCursor and SWCursor mean. THe options are the same throughout X drivers but are explained differently. I will prepare a longer explanation of what I mean. I think I know what you mean, and changing the docs to use the same good description throughout is a good idea. You also brought to light some other useful points. David -- David Dawes X-Oz Technologies www.XFree86.org/~dawes www.x-oz.com ___ Devel mailing list [EMAIL PROTECTED] http://XFree86.Org/mailman/listinfo/devel
Re: Proposal for documentation patch - driver man pages, HWCursor, SWCursor
On Sat, 18 Oct 2003, David Dawes wrote: On Sat, Oct 18, 2003 at 08:30:05AM +0300, Alexander Shopov wrote: Back to the original point, the documentation of these options in the driver man pages should match how they are handled by the individual drivers. Specifically, the documented defaults may legitimately be different for different drivers. I am not talking about the defaults but what HWCursor and SWCursor mean. THe options are the same throughout X drivers but are explained differently. I will prepare a longer explanation of what I mean. I think I know what you mean, and changing the docs to use the same good description throughout is a good idea. You also brought to light some other useful points. Here's another (again historical): For adapters with separate DACs, there is a distinction to be made between DAC-provided and controller-provided cursors. Marc. +--+---+ | Marc Aurele La France | work: 1-780-492-9310 | | Computing and Network Services | fax:1-780-492-1729 | | 352 General Services Building | email: [EMAIL PROTECTED] | | University of Alberta +---+ | Edmonton, Alberta | | | T6G 2H1 | Standard disclaimers apply| | CANADA | | +--+---+ XFree86 Core Team member. ATI driver and X server internals. ___ Devel mailing list [EMAIL PROTECTED] http://XFree86.Org/mailman/listinfo/devel
Proposal for documentation patch - driver man pages, HWCursor, SWCursor
Hi guys, I checked driver man pages in xc/programs/Xserver/hw/xfree86/drivers/*/*.man Almost every driver implements the options: HWCursor, SWCursor however they are documented differently. From an end user perspective I would like: 1. Them being the same throughout docs 2. Them being as explicit as the best examples Should I prepare patches for this and enter them in Bugzilla? A patch per file? or a big patch containing all the changes? I will of course use MIT X11 license but are there any further intricate details I should know? (apart from http://www.xfree86.org/developer.html) Best regards: al_shopov ___ Devel mailing list [EMAIL PROTECTED] http://XFree86.Org/mailman/listinfo/devel
Re: Proposal for documentation patch - driver man pages, HWCursor, SWCursor
On Fri, Oct 17, 2003 at 02:15:20PM -0700, Tim Roberts wrote: On Fri, 17 Oct 2003 23:44:57 +0300, Alexander Shopov wrote: I checked driver man pages in xc/programs/Xserver/hw/xfree86/drivers/*/*.man Almost every driver implements the options: HWCursor, SWCursor however they are documented differently. Further, having two separate options is silly. It is a two-state switch: either the driver tries to use a HW cursor, or it always forces a SW cursor. What happens if you specify both, or neither? I'll bet different drivers come to different conclusions. The presence of both is probably historical. Some drivers have one, some both. The mga driver seems to define both, but only checks one. If you specify neither, the driver should default to whatever works best. That's the driver's call, but it should generally be HW cursor when available. Specifying both would be undefined in general, if both were specifying contrary behaviour. One way to handle the naming more uniformly might be to define the concept of option aliases, with, say, SWCursor aliased to NoHWCursor. That would make the specifying both behaviour well-defined too. It'd be nice to check driver options for consistency from time to time. It'd be even nicer if driver writers checked existing usage before making up new option names. A while ago we started documenting preferred option names and their behaviour in the xfree86/Registry file. There is also an xfree86/Options file that was added later. Back to the original point, the documentation of these options in the driver man pages should match how they are handled by the individual drivers. Specifically, the documented defaults may legitimately be different for different drivers. David -- David Dawes X-Oz Technologies www.XFree86.org/~dawes www.x-oz.com ___ Devel mailing list [EMAIL PROTECTED] http://XFree86.Org/mailman/listinfo/devel
