Date: Mon, 27 Nov 1995 13:38:02 -0700 (MST) From: Terry Lambert <terry@lambert.org> To: grog@lemis.de Cc: terry@lambert.org, hackers@FreeBSD.ORG Subject: Re: Where is the documentation for ibcs2? Message-ID: <199511272038.NAA19427@phaeton.artisoft.com> In-Reply-To: <199511270855.JAA04164@allegro.lemis.de> from "Greg Lehey" at Nov 27, 95 09:55:23 am
next in thread | previous in thread | raw e-mail | index | archive | help
> > BSDI needs one because they have to enable it explicitly. > > Wrong. That's the case for FreeBSD, as you say: Option it in and rebuild a kernel instead of "flicking a switch" is what I meant by "explicitly". > >> How do I know how to enable the emulation? > > > > At install time, when it asks you about it. > > I didn't want it then. I want it now. How do I know how to enable > the emulation? Rewrite the installation/configuration tool so it is reentrant to allow you to dynamically reconfigure the system at runtime. > >> How do I run the program? Just start it by name? > > > > Yes. > > Aha. Where can I read that? In the documentation that came with the program that tell you how to start it. 8-). Why are you assuming that there would be a gratuitous change in the way you start programs? Your assumptions are bad -- and you want written documentation to correct them? > >> Do I need to say "ibcs2 vi", or will it be enough just to write "vi"? > > > > Do I need to type "run foo" or just "foo"? > > I don't know. What's foo? The generic class of executable programs of which a FreeBSD native binary, a Linux binary, and an IBCS2 binary are all members. Like I said, it's a problem in the infrastructure documentation, not the instance documentation. You are confused about the instance (IBCS2) because you don't understand the infrastructure (and because you insist on understanding it instead of just using it). > > It apparently won't run. > > Why not? Probably because IBCS2 emulation is not totally complete and you didn't supply the missing pieces from your SCO system (the share libraries) when you took the shared vi binary (which implies a certain level of understanding above and beyond that implied by your "how do I..." questions). You are generating a situation that could not have occurred without sufficient knowledge to get you out of the situation in the first place. Then you are feigning ignorance. Bad syllogism, bad logical progression in support of your argument. 8-(. > >> === root@freebie (/dev/ttyp0) /allegro/usr/sco/usr/bin 17 -> ibcs2 vi > >> modload: error initializing module: File exists > > > > You are now typing things at random. > > People tend to do that if they can't find the documentation. I should have said "pseudo random". A typical user would not understand IBCS2 was necessary. They would have typed: % sco vi sco: Command not found. Or something similar, if it were really random. > > A bad idea for root (you must have > > been root to get that particular error message). > > Give me a better suggestion. How about: Don't login as root, login as yourself an use the 'su' command 8-). Or: Don't try to use SCO binary compatability until it's finished unless you are willing to look at the source code and understand what is going on. > >> Well, it appears that I need to run it as "ibcs2 vi". But what's this > >> modload problem? I have enabled Or have I done it wrong after all? > > > > Tell me: what must you do to enamle running of FreeBSD binaries? You > > must install. > > Must I? I thought it was sufficient to copy the data. If I run them > across the net, I don't even need to do that? Where did the binaries environment come from? It came from an install. > >> I'm an experienced computer person, and quite honestly the lack of > >> documentation (coupled, admittedly, with a lack of interest in SCO > >> software) is enough that I'm prepared to give up. Who is going to use > >> this stuff if they run into trouble and can't even be certain they've > >> started it properly. How does it work? > > > > I agree that there is a lot of missing "theory of operation" documentation > > for lots of the kernel. Execution classes are one such beastie. The > > VM is another. > > > > But if you expect Joe Schmoe to be able to make it work without asking > > questions on -questions at this point if Joe Schmoe didn't have things > > handled for him in the install, then you are barking up the wrong tree. > > Assuming that this abort trap is not typical, yes, I do expect Joe > Schmoe to be able to make it work without asking questions on > -questions at this point. Joe and his brother Bill are working for > one of my customers, who are doing just this with a System V > application running on BSD/OS in Munich. It would be nice if they > could use them on FreeBSD as well. They have FreeBSD, but for various > minor, silly reasons they don't use it. I think you will need to write (or steal) SCO shared libraries for this to be practical. Once you have them, it would be reasonable to write a man page: maybe. More likely, it would be reasonable to build ABI compliant install tools so that they can install the binaries in the normal fashion so that they can use them. If your customer is installing Lotus 1-2-3, the machine licensing uses the uname command and a binary file concatentatin that requires either reverse engineering their copy protection or the ability to run their install script to get it installed. Or you could rename a System V/SCO box, install it there, and move the files over to your FreeBSD box. That's how I installed Lotus and Word the first few times, until I got fed up and simply reverse engineered the copy protection. If you can "turn it on" with a tool AND all the pieces are there (some must come from SCO licensed materials right now) AND you can install IBCS2 binaries without detailed knowledge of the install process, there's really very little point to explaining what is happening *underneath* the install tool that does the work of "turning it on". And no reason for the question to be asked, since it "just works". > > Perhaps the right tree is http://www.freebsd.org. > > It should be the FM. Anyway, I've looked through the handbook. I > can't find anything there, either. http://www.freebsd.org *is* the FM. > > Or the source code, which is provided free of charge. > > I looked there too. The program is called /usr/bin/ibcs2, but there's > no source directory /usr/src/usr.sbin/ibcs2. There's a directory > /usr/src/sys/i386/ibcs2, but it doesn't have a Makefile. There's a > directory /usr/src/lkm/ibcs2, but the program there does nothing more > than load an lkm. Anyway, what do you think Joe would say? Well, I think that it's a mistake to put the module loading code in /usr/bin. And I think Joe would say "What's IBCS2?". > > Or the installation software that should have created the missing > > devices for you. > > No it shouldn't. I didn't want one then. But that's > interesting--this is the first I have heard of missing devices. Maybe > that's why it doesn't work. Where's this documented? In the null device alias handling in the source code in /sys/i386/ibcs2, since the devices are controlled via ioctl(), and /dev/null is as convenient a mechanism for implementing an open descriptor as any other. And in the iABI documentation from UNIPress, in section 8. > > Or the fact that to > > use an SCO shared binary, you must first own a copy of SCO to get the > > shared libraries. And you must know enough about how SCO uses shared > > libraries to get them moved over. And you must know general theory of > > operation of execution classes. > > Indeed. Where's the man page? There isn't one. Remember what I said before: 'I agree that there is a lot of missing "theory of operation" documentation'. This is still a hell of a lot different from an IBCS2 man page. > > And let me tell you, a simple (or even a complex) man page will sure > > as hell not cover it, especially without doing what Linux did and > > supplying our own IBCS2 shared libraries, etc. > > Why not? Because of a dislike of man pages on the part of the person > who should be writing them? Well, because: o that person is busy writing code o the code isn't done o you are asking them to document what the code will look like when it is done, and they don't know any more than you do because volunteer efforts code to code, not to spec, since it's not like you have the ability to fire them to bludgeon them into limiting themselves to a spec o once the code is done, the documentation you want would be about as useful to the average user as documentation for the "tbhresdecode" routine (a static routine in the kernel in tty_tb.c which is also not well documented) > > So who will use it? People who have this information already, people > > willing to dig it out of the sources, or people willing to ask questions > > of people who already know these things. > > > >> How do I go about finding out what's wrong here? > > > > Ask. > > RTFM. "Read The Fine Manual" is a great blow-off aphorism for not answering questions. If you ask, the annoyancy counter is incremented, and the documentation gets written to combat the annoyance. > >>> Typically, you don't document things that don't have parameters, options, > >>> or other controls. > >> > >> Speak for yourself. From my point of view, this is completely wrong. > > > > Are we talking "typically" (like I thought) or "ideally"? If "typically", > > then feel free to write man pages to make yourself right. "Typically" > > means in the common case, and if we pick a case at random (oh, say, IBCS2?) > > and examine it, we find the documentation unwritten except as source code. > > As I said, speak for yourself. If I release software, I document it. Even incomplete software? Full IBCS2 emulation is a hell of a lot more than simply supporting the execution class in the kernel. It's a full environment, including install tools, compatability shared libraries so that you don't have to have a licensed system whose libraries you can use by taking the licensed system offline, etc.. > > One problem is that the install > > configuration is not very reentrant. So fix it, you have the sources. > > First I need to know what the problem is. If I run into problems, the > first thing I do is read the man page. That's what I've been trying > to do, but I've come across this claim "There isn't one. There > doesn't need to be one." Look. If you want to work on the (incomplete) IBCS2 emulation, then you should know as much about it as the author -- or close to as much. If you aren't interested in doing that, then you aren't really interested in working on it. An that information is not something that can be contained in a man page, unless it's a 200+ page man page. Like the Intel document. Like all the related documents. > > Tell me, how is your hypothetical IBCS2 user, who will be using IBCS2 based > > apps, not system components like "vi" going to *load* his software without > > IBCS2 install tools? I know the answer to this one: they will do it by > > playing computer and running the install script by hand. Try Lotus 1-2-3 > > this way some day: I have. > > I don't know. I don't have the documentation. But I would guess that > he will run his install tools in the same environment that he would > use to run them. BZZZZT. This assumes that IBCS2 is completely functional. What's there right now is the ability to load the binaries, which is a far cry from an IBCS2 environment. An IBCS2 man page would document something that was only 10-20% there: an IBCS2 environment. You don't document what you don't have. > > The software is incomplete. You are incorrectly equating the kernel > > components (which are to be optioned at install time, if done correctly) > > with a full IBCS2 environment. > > Now here's the first statement with which I can agree. Fine, except > that I didn't know that (it didn't say that in the man page). Still, > a minimum of documentation would help even at this stage. So, what > remains to be done? o Shared libraries. o Install tools for IBCS2. o Install tools for SCO's package install system. o User documentation. o VM86() support; Lotus 1-2-3 already needs a kludged piece of VM86() code to make it not fail when it tries to determine the existance of a math coprocessor o Kernel compatability environment for drivers. o Streams for drivers (some packages include Streams components). o Implementation of install/packaging for FreeBSD based tools to get the environment in and out of the machine cleanly. o Demand loading of LKM's (and a new LKM system to do it with) so that when you attempt to run a binary, it loads the apropriate execution class module and any required support modules. o Modifications on VM layout based on object persistance to keep demand loading/unloading from fragmenting the kernel memory space. Specifically, a distinction between short (probe), medium (loadable module for non-system-critical components), and long (system critical and long service duration) persistance object code/data objects. The first four of these are bare minimum before an existing IBCS2 system would not be needed, along with explicit knowledge, to be able to use the emulation environment. The user doc is last intentionally: that's the order I would choose. The remaining five items are long term projects. I'm sure Soren and Sean, et al, could add to this list considerably, since I'm not even directly involved in the IBCS2 project (I'm more interested in revamping the execution class infrastructure to allow the use non-native instruction sets -- a big project itself). At some point, someone needs to beg/buy the Intel IBCS2 validation suite and run it agains the thing and pronounce it golden. Regards, Terry Lambert terry@lambert.org --- Any opinions in this posting are my own and not those of my present or previous employers.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199511272038.NAA19427>