Hardware control example program ver 0.5
Minimum system requirements: 80486 Intel CPU, RAM 2MB, VESA 1.2, PC-BIOS

INTRODUCTION
This program just provides a trace for writing your own software to control hardware.
It's not an "application" at all, but rather a "dumb assembly of snippets". Despite its name, it's not even a hardware test like Sandra: what is under test is not the hardware, but the program's ability to use it on an unknown machine. In fact you run the program only to see that it really controls the hardware - then you can take a working example for your mouse, pci etc. routines - or to (please) report a bug when behaviour is unexpected.
While each tutorial I found covers only few aspects of hardware control and I had to gather many of them, this is an all-in-one pure example. It has no additional code to implement any functionality (as you find in the various assembly OS out there, which are all-in-one examples as well); I see this as a valuable feature because when I had to search for the lines that did the low level job I was confused by those that implemented functionality. Each source file of mine, which is more or less self contained, is less than 10 Kbytes (ethernet card drivers are bigger since they are taken from MenuetOS).
My software does some things in a different way (for example, it doesn't use a second stage bootloader) and spans over rarely treated areas (Cardbus, USB, chipset programming, LFB emulation), while leaving apart some other important devices (disks, most noticeably). You best use it when you compare it with other sources.
Of course you need the docs for everything because the code covers very few aspects in each area (for USB, I would say 20%).

Needless to say, you can use parts of this source in your code with or without modification, provided you mention they come from me.

USAGE
See Assembling.txt for instructions on building the program.
Insert the floppy/CD/pendrive in you computer, or set up the PXE server (see NetBoot.txt). Then, set BIOS to boot from the media you chose, and reboot. With PXE or CD you may have to choose a disk image, first.
A list of available VESA video modes appears, in the form (X resolution).(Y resolution).(Bits per pixel).(Bits for the Green channel); the latter is used to distinguish between 15 and 16 bit modes because sometimes VESA says 16 bit in both cases).
Highlight the one you want using Q and W keys (other keys work randomly), then press Enter. You can also set MCGA (320x200, 8 colors, not listed) by pressing CANC, regardless of the mode selected.
While the program loads, the screen is trashed; it clears when loading completes (in version 0.2 it was cleared immediately).

Now the program shows a log of initialization steps:
- CheckSum failure: when present, it's the first line; in this case the program has been badly read from the media (generally floppy disk cause this problem) and you must re-write it or change media.
- Microcode update: present only with Intel processors, reports which update - if any - was applied.
- Video ROM patch: when needed, tells a patch was applied to those Intel graphics cards which have a bug in their VESA protected mode code.
- ROM tables: if APM is found prints its version; then prints 'VESA PM...' and checks for VESA protected mode entry point: if it's found and initialized prints 'found'. 
- A line of data for each PCI device scanned; after UHCI, OHCI and Cardbus lines, you'll see OK or KO: OK means device enabled (for Cardbus, a card must be inserted), KO means device disabled;
- HID module, which enables mouse and keys and tells you to hit RETURN key.

If you selected a VESA 8-bit mode and set PICTURE switch to 1, an image will appear on the screen under the data.

From now on, should any error occur, a processor registers dump appears at the bottom of the screen.
Keys enabled:
- Esc: cold reboot;
- F12: shut down the machine when APM 1.2 or better is present;
- R: if you have a defective PS/2 mouse, when it hangs, try leaving it still for 5 seconds, then press 'R';
- ALT + arrow keys: (slowly) move the cursor.

If a PS/2 mouse was present during BIOS startup, it's enabled, otherwise a serial one is enabled, if found. Cursor is a white dot leaving a trace as you move it around the screen; Trident video cards show a classic arrow in addition.
Screen should scroll when you reach its edges. After 'Scroll:' there is '4F0A' when scroll is performed with code given by VESA 4F0A call, 'Prot' when using VESA protected mode entry point, 'Real' when using virtual 8086 mode.

When you press the Return key, various info about the machine appear on the screen: I chose the data randomly, mainly from the info gathered in the bootloader, to see that my 512bytes routine did the job and correctly communicate with the main program. Note that ALL numbers are in hexadecimal, except for version numbers (generally starting with 'v', like 'PCI BIOS v2.10').

If you have a recognized ethernet card - can also be a CardBus one -, you see its data and you can test it (see Ethernet.txt on how to do it). Otherwise, program will show "No ethernet", even if you have an unrecognized Ethernet card.

********* VIA AC'97 SOUNDCARD ONLY (not a standard AC'97) *********
A sound is emitted; when it ends, an interrupt is generated and a message "Audio interrupt on IRQ 5 ..." should appear at the bottom of the screen.
*******************************************************************

******************* USB ONLY ************************************
As soon as a device is inserted in the root hub, host type (UHCI/OHCI/EHCI), number of controller/port/root hub ports are displayed. Program asks whether to stop search: if you answer N, it scans for next port with attached device - if any - and asks again.
When you press Y, it retrieves data from the selected device: device speed, ID and USB version are displayed together with packets status, which tells whether the ID is valid (to interpret it you need to know packet format, of course).
EHCI controller is used only if the device supports high speed; otherwise the program will try to switch to an USB 1.0 controller. Should it be absent (very rare) or unavailable (when using PS/2 emulation, see PS2_EMULATION switch), a message will inform you.
*****************************************************************


Send reports, bugs, suggestions, requests to: pfranz73 -A-T- tiscali -D-O-T- it, with HWTEST in the subject to pass spam filters.

Paolo Franchetti
