Where is the fglrx documentation?

[Melcar]

I think they just don't want people to mess with their (proprietary) driver. The official options that are used on the final releases of their drivers are on/off by default, like TexturedVideo for certain cards, and so on. They don't want people to be using beta features and then complain that they don't work. Remember that their beta programs are closed. This isn't any different from say the Windows driver. Again, this is the proprietary, closed driver we're talking about, so I wouldn't expect anything besides the must know configuration options to be disclosed (like setting overlays and initializing the driver).

[Porter]

So where are the docs?? Is "aticonfig --help" really the extent of ATI's efforts to document how one actually configures ATI hardware?? Another slap in the face from AMD/ATI.

A "slap in the face"?? You've got to be kidding. Melodramatic much?

[oblivious_maximus]

Again, this is the proprietary, closed driver we're talking about, so I wouldn't expect anything besides the must know configuration options to be disclosed (like setting overlays and initializing the driver).

that's all I'm looking for... I just want a definitive, official, current document that briefly explains what xorg.conf options for fglrx do and their proper syntax. Nvidia has an epic document detailing all that stuff for every driver release, and it's easy to find, where's the ATI equivalent?

A "slap in the face"?? You've got to be kidding. Melodramatic much?

More like totally fed up with having to keep plugging my Nvidia card back in because fglrx is so woefully inadequate. After you've bought 2 motherboards you didn't need to, and 2 ATI cards you can't make use of(the second after having never actually gotten to use the first), then you can talk to me about justifiable melodrama. I'm supposed to be enjoying >2x AA in Doom3 or some other game right now, not getting aggravated over the fact that I'm still stuck running my junky, feature-regressed, sucking-at-turning-off-my-damn-monitor 8600GT.

Is there a single Linux user stuck running fglrx who doesn't have at least one major issue to complain about? That's totally a slap in the face. And so is the apparent total lack of current, complete configuration info. Yeah OK, maybe I am overreacting a bit, but dammit I am totally aggravated with buying hardware that amounts to a glorified paperweight because the drivers are so bad. :mad

[SheeEttin]

Hmm... I don't have any major issues, and the only minor one I can think of right now is that I get corruption in certain types of icons. Totally unaffects me.

As for a big list of options, I don't know of one... You can scour the Phoronix forums if it's that important to you.

Actually, the options supplied by aticonfig look pretty exhaustive... I'm not sure what more you'd need!

Then again, you might be talking about options you can set manually in your xorg.conf. I've looked for one myself, but the one I found was way out of date.
Perhaps we should start one on the wiki...?

[mtippett]

There are a few people on this thread that have caught the essence of what we are trying to do. To answer the question posed in this thread.

There is no option documentation, but there is help and some documentation for the configuration tools.

To understand our approach consider the following.

• We support 2 fundamental modes of operation
  • Default configuration
  • Options enabled through the configuration tools (aticonfig and amdcccle)
• We don't generally use xorg.conf for configuration of the driver. Our model is that xorg.conf is used for configuration of X, not the driver. All configuration options are held in /etc/ati/amdpcsdb. This configuration file is growing very quickly. Tools to modify this configuration file can be found in aticonfig (see Persistent Configuration Store (PCS) Options). (We have some compatibility interfaces to read shadow entries from xorg.conf, but that is really for compatibility).
• The default configuration should just work (with 306 individual ASICs, 3 bus formats, distributions, etc). It isn't simple, but that is what our general aim is.
• I have a strong conviction that people shouldn't have to go playing around with configuration files to get things working. It should just work (a lofty aim).

If you go outside the configuration tools and manually modify the configuration files, you move outside of what is supported, and consequently any defects you come across are not considered part of the driver. (For example: undocumented, experimental features like TexturedXRender are prone to breakage and hence shouldn't be used).

I know that this approach is not going to be popular with everybody, but that is our approach. There are aspects of what we are doing with amdpcsdb that will become clearer in the future as we roll out more features that require far more that xorg.conf can provide.

There are many nuances in the use of the term support. In this context, support means that there is a high likelihood that we have tested a reasonable subset of the possible configurations, and that we will in general attempt to avoid breaking those configurations in the future.

If people want to start documenting amdpcsdb options, then there may be some nuggets of features that people may be interested in using, but if aticonfig/amdcccle doesn't configure that option, then there is no guarantee that it will stay working.

Look at how aticonfig initializes an xorg.conf config file. There are no options. Users who use cut and pasted configuration options from 3 or 4 years ago may trigger unknown and unstable paths in the driver.

Regards,

Matthew

[adurbin]

I was just wondering the same thing, so I probed fglrx_drv.so (the driver binary) (Catalyst 8.3) for options. After a little filtering, I got this list. Unfortunately, that's only options, no explanation.

(For the curious, here's the command I used:

strings /usr/lib/xorg/modules/drivers/fglrx_drv.so | grep -nE "[a-zA-Z]{3,}"

The options, for me, started on line 11534.)

...line 76 "EnableMultiCard"...Could this be crossfire? So would I just add this under the device section in my xorg.conf as something like

Option "EnableMultiCard"

and then run the command to have it reread into the database? What was that command?

[voltaic]

I have to agree with oblivious_maximus here. Even though the drivers are getting better with each release, fglrx has such basic features lacking/broken that I can't help but feel aggravated.

For instance, according to aticonfig, PowerPlay features will not work with a dual screen configuration. Great. It says it's a hardware limitation. So I can deal with that. When I go to turn off the laptop display (LVDS) and only use CRT1 fglrx cannot figure out what the proper resolution of the external display is. And of course, like a reasonable person, I want to do this dynamically. I don't want to change my xorg.conf every time I want to switch between two displays. Well, last night I spent two hours trying to figure our how to get fglrx to just, simply, output to CRT1 at the correct resolution, while keeping LVDS off. And for the life of me I could not get such a basic feature to work.

The worst part is, after I started messing with aticonfig's dynamic options, the driver would no longer output anything above 1024x768. When I noticed this, I said, well OK I will revert to having both monitors enabled. Logical, right? This only made things worse, as now both monitors would run at incorrect resolutions! In fact, I noticed that at this point the driver would insist that the 22" external monitor was only capable of outputting 1024x768 (EDID from Xorg log). Restarting X or switching to a backed up xorg.conf would do absolutely nothing to change that. This is astounding to me. When I change a "dynamic" option, I expect the driver to make an on-the-fly change, not a permanent one. It turns out aticonfig --enable-monitor=CRT1, somehow, writes to a file that is not xorg.conf. I know this because I don't have write permission to xorg.conf as a user. This took me a long time to figure out. I had to go and remove everything in /etc/ati and reinstall the driver just to get my external monitor to display at the correct resolution. By the way, nowhere have I found this "workaround" documented.

On another note, I disagree with the point that a proprietary driver does not need as much documentation as an open one. If the driver is incapable of figuring out the correct resolution of the display(s) it's driving then it better be documented well enough that I can configure it properly without pulling my hair out for two hours. Case in point, even searching for hours on Phoronix forums would not tell me that in order to get video playback on my external display, I would need the following three options:

Option      "OverlayOnCRTC2" "1"
Option      "VideoOverlay" "on"
Option      "Mode2" "1680x1050"

I don't know what OverlayOnCRTC2 is supposed to mean. Do they mean CRT1? Because that's how the external display is referenced as in aticonfig (0 is LVDS, 1 is CRT1). Why do I need to specify Mode2? Doesn't xorg.conf have a section, aptly labeled "Screen", for settings such as resolution? I can't answer those questions, but I know from experimentation that no matter how many modelines or Modes I specify under the "Screen" section of xorg.conf fglrx will not respect my configuration. And why do we need aticonfig to do the modesetting and dynamic changes when there is already a perfectly good alternative such as XRandr? I would be understanding if AMD did not want to interface their proprietary drivers with open source extensions in fear of divulging the inner workings of their drivers. But they should at least provide something that is equivalent to or better in basic funtionality and ease of use (see XRandr).

I'm sorry if my rant sounds antagonizing/bitter. I'm not trying to blame anyone in particular, and I appreciate AMD's efforts in improving fglrx, but I do also want to make it clear that I'm frustrated and disappointed with the driver support. With each release I read about all the great work that's going into fglrx, but on some level I really think the effort is misdirected. Maybe a lot of people do, but I really don't care if fglrx supports CrossFire, or can run Crysis at 100fps, while it simply cannot do the basics such as dynamic frequency scaling or automatic resolution detection and display switching. Compared to how easily and seamlessly the Intel drivers work on my other laptop, I kind of regret purchasing my ThinkPad T43 which came with a Mobility X300.

I sincerely hope that someone from AMD gets to read this, because I think this is how a lot of GNU/Linux users are feeling about AMD/ATI. Just my two cents.

EDIT: I just saw Matthew's comment, which sort of clarifies some of the questions I was asking. I just wish this sort of a design statement was accessible outside of the forums. If the driver team is going for a "just works" configuration, then as a user I should have a way of knowing that. I now realize that I've been wasting all my time configuring xorg.conf. In fact, I just configured everything properly using amdcccle; frequency scaling seems to work fine. Perhaps my frustration was not due to the deficiencies of the drivers, but rather a result of a lack of communication and official documentation. This I guess brings us back on topic.

[SheeEttin]

EDIT: I just saw Matthew's comment, which sort of clarifies some of the questions I was asking. I just wish this sort of a design statement was accessible outside of the forums. If the driver team is going for a "just works" configuration, then as a user I should have a way of knowing that. I now realize that I've been wasting all my time configuring xorg.conf. In fact, I just configured everything properly using amdcccle; frequency scaling seems to work fine. Perhaps my frustration was not due to the deficiencies of the drivers, but rather a result of a lack of communication and official documentation. This I guess brings us back on topic.

After reading it myself, I took a look at /etc/ati/amdpcsdb, and it's even more cryptic than a bad xorg.conf.

Any chance we could get some documentation for this? It might help those of us with partially- or non-working setups (and supporting more customers is better for everyone, right?).

[oblivious_maximus]

voltaic, I don't think you need to worry about coming off as antagonizing or bitter, if anyone in this thread has to worry about that, it's me. Your post was quite polite I thought.

Matthew: thank you for your informative reply. I'm afraid it just increased my utter disappointment however.

So xorg.conf is for configuring X, but not for configuring ATI's driver for X?? How does that make any sense? Maybe this would be acceptable if the alternative tools ATI is providing weren't as woefully inadequate as fglrx itself. At one point, starting CCCLE with my svideo plugged in resulted in my system locking up. Attempting to use what I could glean from "aticonfig --help" was totally useless. For example:

sudo aticonfig --initial=dual-head --screen-layout=right --tv-standard-type=VIDEO --tv-format-type=NTSC-M

Should this have setup my TV as half my desktop? If it should have, it didn't. And because there's basically zero documentation on anything, I have no idea why, or what I need to add to that to make it actually work. If I run another aticonfig command with other options, will it add them to the ones I already set, or start over? I JUST DON'T KNOW because there's no docs.

sudo aticonfig --enable-monitor=tv

That actually did something, and would probably be a nice option to use, only it did't output a useful display on my TV, only garbage maladjusted-vertical-hold-type distortion. And when I enabled my CRT again(through the distortion using bash history), it was running at 640x480 and not 1600x1200. Again, no documentation, so no idea why it didn't quite work or what I need to do about it. I also tried to use CCCLE (it only locked up my computer the one time thankfully) to set this up, even though it doesn't even support the way I want to use my TV. I tried to setup a clone mode with the TV at 640x480 and my monitor at 1600x1200. Guess what? With CCCLE, they both have to use the same resolution for some bonkers reason. Guess what else? xorg.conf does this just fine without issue.

I'm all for things just working, but the fact of the matter is that it fglrx (and CCCLE for that matter) don't "just work", and for ATI to take it upon themselves to totall eschew the established standard in favour of some other, totally undocumented (apparently...) ATI-only solution that can't even offer what X.org does (like for example, a second Xserver on a second display that isn't connected to the main display in any way), well, all I can say is I'm really really glad AMD is releasing specifications and fostering the free driver (it's the only reason I didn't just buy an older Nvidia card that hopefully would not be suffering from the same feature regressions and defects that mine is)

"If people want to start documenting amdpcsdb options" ?? Are you serious?? If "people" want to? Why doesn't ATI document the options??

Utter disappointment is an understatment at this point. ATI has sucked the will to tinker right out of me. I want to keep going but ATI has also just about sucked the will to seek assistance and explanation out of me also. I must appologize if I have been overly harsh or antagonizing or insulting, I try really hard to remain detatched when discussing this stuff, but I've got all sorts of frustration bombarding me from the back of my mind whenever I even think about the ATI cards that I desperately want to be using, but which are sitting on a shelf gathering dust. So yeah, if I'm harsh, it's only out of love ... and a lot of frustration


OT:
And PowerPlay doesn't work if you have more than one display connected?? WTF??? Seriously, what's up with that? Where's the doc explaining how that works and in what (ridiculous)circumstances it does not work? So if someone wants to actually use all the outputs on the back of their video card, they can expect the much lauded power saving features to simply not function? How is that acceptable?

edit: hit post instead of preview with edits left to do

[mtippett]

....

On another note, I disagree with the point that a proprietary driver does not need as much documentation as an open one. If the driver is incapable of figuring out the correct resolution of the display(s) it's driving then it better be documented well enough that I can configure it properly without pulling my hair out for two hours.

The configuration options will not be documented, the configuration tools will be documented - see below.

What I am reading from your statements is that you are looking at some sort of use-case driven documentation. My understanding is that no driver has this sort of documentation model.

You seem to be saying,

1. Connect Laptop to TV
2. Dynamically switch on the TV to a resolution
3. Move the video to that screen

Using scenarios means piecing different options together. The number of fully described individual scenarios is ridiculously large. The Wiki or HOWTOs are a great place for people to collate their scenarios and the resultant options.

Case in point, even searching for hours on Phoronix forums would not tell me that in order to get video playback on my external display, I would need the following three options:

Option      "OverlayOnCRTC2" "1"
Option      "VideoOverlay" "on"
Option      "Mode2" "1680x1050"

From the aticonfig help

  --ovon, --overlay-on={0|1}
        Choose which head the hardware overlay should be visible on.  The
        hardware overlay can be used for either OpenGL, video, pseudo-color
        or stereo.
  --ovt, --overlay-type=STRING
        Change the overlay for the X server.  STRING can be one of:
            opengl
            Xv
            disable
  --mode2=W1xH1,W2XH2,W3xH3,...
        Change the modes for the second display.  You may specify several
        resolutions separated by commas.  Only valid for clone and big desktop
        settings.
Pair mode options: 
  Following options are used for query add and remove pair modes. 
  These options will be effective immediately. Other options on   
  the same command line will be ignored.
  --list-pairmode 
        list all the current existing pair modes the driver can use.
  --add-pairmode=width0xheight0+width1xheight1
        Add one pair mode to the list. width0 and height0 are the 
        size of primary display and width1 and height1 for the 
        secondary  display.
  --remove-pairmode=index 
        Remove one pair mode from the list. User can get index by 
        list-pairmode.
Dynamic Display Management Options:
  Following options will not change the config file. They are
  used for querying driver, controller and adaptor information.
  These options will be effective immediately. Other options on 
  the same command line will be ignored.
  --enable-monitor=STRING,STRING
        Setting current monitor to be enabled. Only 2 displays
        can be enabled at the same time. Any displays
        that are not on the list will be disabled.
        STRING can be one of the following set, separated 
        by commas:
            none
            crt1
            crt2
            lvds
            tv
            tmds1
            tmds2
            auto   -- use default policy to enable the displays.
  --query-monitor
        This will return connected and enabled monitor information
  --swap-monitor
        This only works for big desktop setup. This will swap the
        contents on the two monitors.
  --swap-screens={on|off}
        Enable/disable swap heads in dual-head mode.
        This option works only in dual-head mode.

I don't know what OverlayOnCRTC2 is supposed to mean. Do they mean CRT1? Because that's how the external display is referenced as in aticonfig (0 is LVDS, 1 is CRT1). Why do I need to specify Mode2?

As described above, don't look to understand the config options, look to understand the configuration tools. All the options are there.

Doesn't xorg.conf have a section, aptly labeled "Screen", for settings such as resolution? I can't answer those questions, but I know from experimentation that no matter how many modelines or Modes I specify under the "Screen" section of xorg.conf fglrx will not respect my configuration.
And why do we need aticonfig to do the modesetting and dynamic changes when there is already a perfectly good alternative such as XRandr? I would be understanding if AMD did not want to interface their proprietary drivers with open source extensions in fear of divulging the inner workings of their drivers. But they should at least provide something that is equivalent to or better in basic funtionality and ease of use (see XRandr).

Up until RANDR1.2 (released 9 months ago, and only now (last 3 months) appearing in distributions)), there was no consistent way of supporting multiple screens beyond dual-head configurations. The options above provide general capability as required.

The pair-mode support is compatible with Randr (using a pseudo-mode that provies pseudo-xinerama).

Regards,

Matthew