August 2001 - Wine-Devel - list.winehq.org

Re: Documenting functions

by Bill Medland

Alexandre Julliard <julliard(a)winehq.com> wrote in article <878zh3y8e0.fsf(a)mail.wine.dyndns.org>... > Francois Gouget <fgouget(a)free.fr> writes: > > > So I think the functions implemented in Wine should be fully > > documented. And the only place to do that is in the code source because > > this is the only place where they have a remote chance of staying up to > > date (and also where it's most practical to have it). > > I have to disagree here. Yes it would be nice to have a free Win API > documentation, but it definitely doesn't belong inside the Wine > source. First it would be a huge bloat in the source; and more > importantly the Wine source doesn't define the Windows API, it is > defined by Microsoft. I agree that bloat is a serious danger. To me the issue is that the full documentation is just too big and actually belongs in a decent documentation management environment. To be honest since Wine is a re-engineering of an existing product I actually expect that the full documentation is many times larger than the source, once we start considering the scraps of paper on which we jot down the results of random experiments and the programs written for them. All Microsoft need are the change requests, specs and design docs. We need more. > > > Of course developpers are very well-known for hating to document > > stuff so it's going to be pretty hard to get proper documentation. But > > we should encourage all Wine developpers to write good documentation for > > the functions they implement/fix, not dissuade them to do so. > > I'd much rather have developers spend their time writing code. Making > them duplicate the whole MSDN documentation would be a huge waste of > their time. Our resources are not infinite, and it's much more useful > to have 100% API coverage with no docs at all than 50% coverage and > tons of docs. Yes I am happy with that view. However when I spend four days writing test code and experimenting to find out how 24 different flags interact and proving that the weird code IS wrong. I would like to know where I should put that information. > > > Also I agree with you that the strict minimum is to at least document > > all the undocumented/weird behaviors. Especially since without some sort > > of documentation the next developper may be tempted to remove what looks > > like unnecessarily convoluted/obviously wrong code. > > That should be done with comments inside the code itself. And in many > cases it would actually be better to comment the places where the > behavior is not right. What I mean is, instead of adding a comment on > every line stating "yes this is what Windows does", I'd prefer adding > a comment/FIXME to mark the lines that have been written without > checking whether Windows really does it this way. > Bill

Aug. 2, 2001

Switching threads in winedbg

by Francois Gouget

Is it possible to switch threads in winedbg? I can use 'walk thread' to see a list of the threads of my application but I could not find how to get a backtrace of one of these other threads. It's not in the Wine Developper's Guide and I could not find it from the source. -- Francois Gouget fgouget(a)free.fr http://fgouget.free.fr/ In a world without fences who needs Gates?

Aug. 1, 2001

Re: Documenting functions

by Alexandre Julliard

Francois Gouget <fgouget(a)free.fr> writes: > So I think the functions implemented in Wine should be fully > documented. And the only place to do that is in the code source because > this is the only place where they have a remote chance of staying up to > date (and also where it's most practical to have it). I have to disagree here. Yes it would be nice to have a free Win API documentation, but it definitely doesn't belong inside the Wine source. First it would be a huge bloat in the source; and more importantly the Wine source doesn't define the Windows API, it is defined by Microsoft. > Of course developpers are very well-known for hating to document > stuff so it's going to be pretty hard to get proper documentation. But > we should encourage all Wine developpers to write good documentation for > the functions they implement/fix, not dissuade them to do so. I'd much rather have developers spend their time writing code. Making them duplicate the whole MSDN documentation would be a huge waste of their time. Our resources are not infinite, and it's much more useful to have 100% API coverage with no docs at all than 50% coverage and tons of docs. > Also I agree with you that the strict minimum is to at least document > all the undocumented/weird behaviors. Especially since without some sort > of documentation the next developper may be tempted to remove what looks > like unnecessarily convoluted/obviously wrong code. That should be done with comments inside the code itself. And in many cases it would actually be better to comment the places where the behavior is not right. What I mean is, instead of adding a comment on every line stating "yes this is what Windows does", I'd prefer adding a comment/FIXME to mark the lines that have been written without checking whether Windows really does it this way. -- Alexandre Julliard julliard(a)winehq.com

Aug. 1, 2001

Re: Dont allow SetSelectorBase to change into an kernel region

by Uwe Bonnes

>>>>> "Uwe" == Uwe Bonnes <bon(a)elektron.ikp.physik.tu-darmstadt.de> writes: Uwe> Hallo, galep3 crashes with following sequence: 096c7b38:Call Uwe> KERNEL.189: SETSELECTORLIMIT(0x0d87,0x0000045f) ret=02e7:6fb5 Uwe> ds=099f 096c7b38:Ret KERNEL.189: SETSELECTORLIMIT() retval=0x0d87 Uwe> ret=02e7:6fb5 ds=099f 096c7b38:Call KERNEL.187: Uwe> SETSELECTORBASE(0x0d87,0xc02924e0) ret=02e7:6fc1 ds=099f Uwe> 096c7b38:Ret KERNEL.187: SETSELECTORBASE() retval=0x0d87 Uwe> ret=02e7:6fc1 ds=099f ... Unhandled exception: page fault on read Uwe> access to 0xc0292545 Uwe> Obviously the application trys to reach some kernel memory. Uwe> If I only allow to set the selector base when (selector base + Uwe> selector limit) is smaller than 0x8000000, the application goes on Uwe> and lets me read an eprom plugged into the Galep3 Programmer. Is Uwe> the appended fix a right acceptable? Obviously not modifying the base in that case lets me save and exit too Index: wine/memory/selector.c =================================================================== RCS file: /home/wine/wine/memory/selector.c,v retrieving revision 1.39 diff -u -r1.39 selector.c --- wine/memory/selector.c 19 Jul 2001 00:39:10 -0000 1.39 +++ wine/memory/selector.c 1 Aug 2001 17:42:53 -0000 @@ -326,8 +326,15 @@ { LDT_ENTRY entry; wine_ldt_get_entry( sel, &entry ); - wine_ldt_set_base( &entry, DOSMEM_MapDosToLinear(base) ); - wine_ldt_set_entry( sel, &entry ); + if ((base + wine_ldt_copy.limit[sel >> __AHSHIFT]) > 0x8000000) + { + FIXME("Illegal region base %lx limit %lx\n", base,wine_ldt_copy.limit[sel >> __AHSHIFT]); + } + else + { + wine_ldt_set_base( &entry, DOSMEM_MapDosToLinear(base) ); + wine_ldt_set_entry( sel, &entry ); + } return sel; } -- Uwe Bonnes bon(a)elektron.ikp.physik.tu-darmstadt.de Institut fuer Kernphysik Schlossgartenstrasse 9 64289 Darmstadt --------- Tel. 06151 162516 -------- Fax. 06151 164321 ----------

Aug. 1, 2001

Dont allow SetSelectorBase to change into an kernel region

by Uwe Bonnes

Hallo, galep3 crashes with following sequence: 096c7b38:Call KERNEL.189: SETSELECTORLIMIT(0x0d87,0x0000045f) ret=02e7:6fb5 ds=099f 096c7b38:Ret KERNEL.189: SETSELECTORLIMIT() retval=0x0d87 ret=02e7:6fb5 ds=099f 096c7b38:Call KERNEL.187: SETSELECTORBASE(0x0d87,0xc02924e0) ret=02e7:6fc1 ds=099f 096c7b38:Ret KERNEL.187: SETSELECTORBASE() retval=0x0d87 ret=02e7:6fc1 ds=099f ... Unhandled exception: page fault on read access to 0xc0292545 Obviously the application trys to reach some kernel memory. If I only allow to set the selector base when (selector base + selector limit) is smaller than 0x8000000, the application goes on and lets me read an eprom plugged into the Galep3 Programmer. Is the appended fix a right acceptable? Index: wine/memory/selector.c =================================================================== RCS file: /home/wine/wine/memory/selector.c,v retrieving revision 1.39 diff -u -r1.39 selector.c --- wine/memory/selector.c 19 Jul 2001 00:39:10 -0000 1.39 +++ wine/memory/selector.c 1 Aug 2001 17:30:48 -0000 @@ -327,7 +327,12 @@ LDT_ENTRY entry; wine_ldt_get_entry( sel, &entry ); wine_ldt_set_base( &entry, DOSMEM_MapDosToLinear(base) ); - wine_ldt_set_entry( sel, &entry ); + if ((base + wine_ldt_copy.limit[sel >> __AHSHIFT]) > 0x8000000) + { + FIXME("Illegal region base %lx limit %lx\n", base,wine_ldt_copy.limit[sel >> __AHSHIFT]); + } + else + wine_ldt_set_entry( sel, &entry ); return sel; } Bye -- Uwe Bonnes bon(a)elektron.ikp.physik.tu-darmstadt.de Institut fuer Kernphysik Schlossgartenstrasse 9 64289 Darmstadt --------- Tel. 06151 162516 -------- Fax. 06151 164321 ----------

Aug. 1, 2001

Strange window handle in the trace

by Marco Bizzarri <m.bizzarri＠icube.it>

Hi all. I'm working on a no-windows installation. The system is a RH 6.2 system, upgraded to the latest patches. I've installed XFree4 and KDE 2.1 I'm experiencing an unhandled exception when I try to a VC application. The application works (almost) fine until it opens a selection dialog, with a list on it. As you can see from the trace, it is trying to do an RDW_UpdateRgns with a wndPtr of 0xffff Unhandled exception: page fault on read access to 0x08fd506b in 32-bit code (0x406d1771). In 32-bit mode. Symbol h_errno is invalid Symbol hack_digit is invalid 0x406d1771 (RDW_UpdateRgns+0x3c9 [painting.c:720] in libuser32.so): testb $ 0x10,0x6b(%esi) 720 if( wnd->dwStyle & WS_VISIBLE ) Wine-dbg>bt Backtrace: =>0 0x406d1771 (RDW_UpdateRgns+0x3c9(wndPtr=0xffff, hRgn=0x0, flags=0x180, firstRecursLevel=0x0) [painting.c:720] in libuser32.so) (ebp=405b1bc4) 1 0x406d1787 (RDW_UpdateRgns+0x3df(wndPtr=0x40377824, hRgn=0x0, flags=0x180, firstRecursLevel=0x0) [painting.c:721] in libuser32.so) (ebp=405b1c20) 2 0x406d1787 (RDW_UpdateRgns+0x3df(wndPtr=0x40377538, hRgn=0x0, flags=0x180, firstRecursLevel=0x1) [painting.c:721] in libuser32.so) (ebp=405b1c7c) 3 0x406d1e08 (RedrawWindow+0x38c(hwnd=0x43f0, rectUpdate=0x0, hrgnUpdate=0x0, flags=0x180) [painting.c:982] in libuser32.so) (ebp=405b1cd4) 4 0x406d1f1d (UpdateWindow+0x21(hwnd=0x43f0) [painting.c:1015] in libuser32.so) (ebp=405b1cf0) 5 0x0043df7a (<Debugged process>.EntryPoint+0x13625 in <Debugged process>) (ebp=0046e660) 6 0x00000623 (ebp=000044e4) Just for "fun", I've tryied to add checks for 0xffff, but it crashes when it enters non Wine DLL (actually they are Spread dlls from Farpoint) Any clue? Thanks you all in advance Bye Marco -- Marco Bizzarri - Responsabile Tecnico - Icube S.r.l. Sede: Via Ridolfi 15 - 56124 Pisa (PI), Italia E-mail: m.bizzarri(a)icube.it WWW: www.icube.it Tel: (+39) 050 97 02 07 Fax: (+39) 050 31 36 588

Aug. 1, 2001

CloseHandle with 0xffffffff parameter

by Marco Bizzarri

Hi All. While trying to make an application working under wine, I've stumped into the following trace fragment, obtained with --debugmsg +relay: 081612c8:Call kernel32.CreateFileA(405f6454 "c:\\rs\\project\\apitest\\vc\\32\\apitestvc60\\debug\\ret_dll.pdb",80000000,00000001,00000000,00000003,00000080,00000000) ret=404aa001 081612c8:Ret kernel32.CreateFileA() retval=ffffffff ret=404aa001 081612c8:Call kernel32.CloseHandle(ffffffff) ret=404aa0bd 081612c8:Ret kernel32.CloseHandle() retval=00000000 ret=404aa0bd As you can see, the program is trying to open a file, which is not found. An invalid handle (ffffffff) is returned. The program however closes the handle. My question is: is this correct? Should the CloseHandle check to see if it is a correct handle? Thank you all in advance Marco Bizzarri -- Marco Bizzarri - Responsabile Tecnico - Icube S.r.l. Sede: Via Ridolfi 15 - 56124 Pisa (PI), Italia E-mail: m.bizzarri(a)icube.it WWW: www.icube.it Tel: (+39) 050 97 02 07 Fax: (+39) 050 31 36 588

Aug. 1, 2001

Re: Documenting functions

by Uwe Bonnes

>>>>> "Francois" == Francois Gouget <fgouget(a)free.fr> writes: Francois> Well, let me offer a different opinion. Francois> Wine is an open-source reimplementation of the Win32 Francois> API. You can use it to run existing Windows applications and Francois> to recompile or develop Win32 applications using Winelib. Francois> Now, for me an open-source project that implements an API for Francois> which there is no open-source documentation is not Francois> complete. Especially for Winelib where the API is part of what Francois> we provide to the user, i.e. to programmers using Winelib. Francois> And currently the only documentation of the Win32 API is Francois> available from Microsoft as part of the MSDN. I see many Hallo, while this doesn't answer many question, I think it is worth knowing: Javob Navia has achieved the explicit right to distribute the win32 help files with his lcc-win32. You can download lcc-win32 and win32help for free at http://www.cs.virginia.edu/~lcc-win32/ Bye -- Uwe Bonnes bon(a)elektron.ikp.physik.tu-darmstadt.de Institut fuer Kernphysik Schlossgartenstrasse 9 64289 Darmstadt --------- Tel. 06151 162516 -------- Fax. 06151 164321 ----------

Aug. 1, 2001

Re: Documenting functions

by Francois Gouget

On Tue, 31 Jul 2001, Andreas Mohr wrote: > On Tue, Jul 31, 2001 at 04:33:06PM +0000, Bill Medland wrote: > > Getting back to what we are and are not allowed to do.. > > > > Suppose I am looking at a low-level function that I believe is only > > 75%-complete (the most important 75% of course and no disrespect meant to > > those who have got it that far). > > > > One of the problems with it is it is not totally clear EXACTLY what the > > function should do in some of its more esoteric modes. > > > > To me the first task is to define what it should do and that should be part > > of the documentation of the function. > IMNSHO full documentation should *not* be included in the Wine tree. > Instead, we should rely on MSDN documented stuff wherever possible > and only explain quirks/undocumented behaviour/whatever isn't documented. > > Having full docu inside the source tree simply bloats it too much IMHO. Well, let me offer a different opinion. Wine is an open-source reimplementation of the Win32 API. You can use it to run existing Windows applications and to recompile or develop Win32 applications using Winelib. Now, for me an open-source project that implements an API for which there is no open-source documentation is not complete. Especially for Winelib where the API is part of what we provide to the user, i.e. to programmers using Winelib. And currently the only documentation of the Win32 API is available from Microsoft as part of the MSDN. I see many problems with that: * it's not open-source (of course). This means we cannot distribute it with Winelib, we cannot generate man pages from it, you cannot generate a winelib-doc package that would contain the man pages of all the Winelib API. * MSDN documentation comes... and goes. Find me the documentation of 16bit functions. The current MSDN versions have eradicated the documentation of all 16 bit APIs. There are tons of aspects of the Win16 environment for which we no longer have any documentation. Then when someone comes to modify some piece of code which is shared between Win16 and Win32 you have no idea if the fix you made for Win32 is not going to break Win16. If Wine had had good independent documentation of the API from the start developpers could refer to this documentation to know whether a change is going to break Win16 or not. * MSDN documentation is often incomplete / slightly incorrect (though people working on Wine should maybe look at it a bit more). So what you propose is that this be *the* documentation for the Win32 API. I think Wine developpers and Winelib users deserve better. And no one using Winelib as a development platform would want to have to go to two places to find documentation. * The MSDN documentation is currently freely available on the Web. Tomorrow it could very well not be the case anymore. Or Microsoft could come up with some sort of click-through license agreement that would make it unsuitable for us. Then Wine and Winelib will be left without any usable documentation. So I think the functions implemented in Wine should be fully documented. And the only place to do that is in the code source because this is the only place where they have a remote chance of staying up to date (and also where it's most practical to have it). Of course developpers are very well-known for hating to document stuff so it's going to be pretty hard to get proper documentation. But we should encourage all Wine developpers to write good documentation for the functions they implement/fix, not dissuade them to do so. Also I agree with you that the strict minimum is to at least document all the undocumented/weird behaviors. Especially since without some sort of documentation the next developper may be tempted to remove what looks like unnecessarily convoluted/obviously wrong code. Then come the open questions: * How do we get people motivated to write documentation? Maybe people writing tests (as in using programs/winetest) should/could write documentation. After all to write proper tests you have to understand the API well enough to know what are the corner cases. So you might as well document the functions you test while you're at it. Then people doing the first non-stub implementation of an API would be in a good position to document it. After all if you implement an API aren't you supposed to know how it works? I certainly don't think we should bar code (implementation or tests) that comes with no documentation from getting into CVS. But maybe we could gently ask as a reminder if the submitter could write some doc too. * Is the current format the most appropriate one? Well, it's just that I'm a fan of JavaDoc-like formats and that I've always been a bit skeptical of the current system (c2man). Does it still work btw? Is http://www.winehq.com/WineAPI/ up to date? Also it seems we should have documentation on what messages do, especially for things like LVM_XXX. Maybe these could be documented with ListView_XXX macros so that searching for either will return the right page. Similarly there should be a policy wrt. documenting xxxA and/or xxxW. It seems like they should end up being documented on the same (man) page and that obviously we don't want to duplicate the documentation in the source. But there does not seem to be anything in place currently. It would probably be a good idea to also have a general way to group related functions together (e.g. all the MSVCRT execXXX variants). Did I say yet that I think a testing framework with many tests would be a great boon for Wine? No! Well, I'm going to stop there anyway. Lucky you :-) -- Francois Gouget fgouget(a)free.fr http://fgouget.free.fr/ Stolen from an Internet user: "f u cn rd ths, u cn gt a gd jb n cmptr prgrmmng !"

Aug. 1, 2001