file_id.diz
=============================================================================
h u g i s i z e c o d i n g c o m p e t i t i o n
g e n e r a l i n f o
=============================================================================
---------------------------------- [RULES] ----------------------------------
Unless stated otherwise in the competition specific rules, your entry must
... follow the competition specific rules.
... have the filename "entry.com".
... work in a Windows95 DOS box.
... work on Adok's PC, an Intel Pentium 4, 2.50 GHz, 256 MByte RAM,
running Windows XP Home Edition Version 2002 Service Pack 1.
... use only instructions up to i586 (Pentium).
Unless stated otherwise, your entry must NOT
... depend on its file name, i.e. it still has to work after renaming
it to, say, FOOBAR.EXE, or any other valid DOS executable file name.
... depend on its drive or path.
... crash unless where explicitly stated by the rules.
... use MMX instructions or other non-Pentium instructions like CMOVcc;
look at the "x86.txt" file for further information.
... use the special registers CR0..4 (this includes the MSW), DR0..7, or
RDMSR/WRMSR instructions.
... use any external files or create new files on the disk.
... rely on any previously loaded code or data in memory, excluding
DOS itself.
... disable interrupts for longer than 1/50 second in a row on
a 200MHz Pentium.
... have been modified by means of an executable-packer (i.e., entry.com
must be the product of assembling entry.asm).
You may assume that
... the registers have these values (all in hex):
(xx - means an unknown value which MUST NOT be assumed)
EAX = xxxx****
AL = 00 if first FCB has valid drive letter, FF if not
AH = 00 if second FCB has valid drive letter, FF if not
EBX = xxxx****
BL = 00 if first FCB has valid drive letter, FF if not
BH = 00 if second FCB has valid drive letter, FF if not
ECX = xxxx00FF
EDX = xxxxxxxx
DX = CS = DS = ES = SS = xxxx, 0080 <= DX <=9000.
ESI = xxxx0100
EDI = xxxxFFFE
EBP = xxxx09xx
ESP = xxxxFFFE
EIP = xxxx0100
EFLAGS (binary) = xxxxxxxx xxxxxxxx xxxxx01x xx0x0x1x
i.e.
DF = 0
IF = 1
other flags = x
WORD [FFFE] = 0000
Layout of PSP: see [Memory Layout]
... that the program is not loaded high.
... that DPMI services are available.
... FCB functions can be used to access files whose name is given in 8.3
format.
You must NOT assume that
... the FPU state is defined; you have to use FINIT to initialize it
before using it.
If you use other's people code (from previous compos or the like), please
add a comment about this to your code, including a reference to the original
program. Oh yes, and please comment your code.
------------------------------ [MEMORY LAYOUT] ------------------------------
The PSP is a copy of a buffer containing the history of command line
arguments. You can assume that all preceding command line arguments were
smaller than 100 bytes. That is:
PSP:[E5h] = 0Dh or 0
PSP:[E6h]...[FFh] = 0
Format of Program Segment Prefix (PSP) (located at initial DS:0000):
[according to Ralf Brown's Interrupt List]
Offset Size Description (Table 01378)
00h 2 BYTEs INT 20 instruction for CP/M CALL 0 program termination
the CDh 20h here is often used as a signature for a valid PSP
02h WORD segment of first byte beyond memory allocated to program
note: do not assume that this word contains 0A000h
04h BYTE (DOS) unused filler
05h BYTE CP/M CALL 5 service request (FAR CALL to absolute 000C0h)
06h WORD CP/M compatibility--size of first segment for .COM files
08h 2 BYTEs remainder of FAR JMP at 05h
0Ah DWORD stored INT 22 termination address
0Eh DWORD stored INT 23 control-Break handler address
12h DWORD DOS 1.1+ stored INT 24 critical error handler address
16h WORD segment of parent PSP
18h 20 BYTEs DOS 2+ Job File Table, one byte per file handle, FFh = closed
2Ch WORD DOS 2+ segment of environment for process (see #01379)
2Eh DWORD DOS 2+ process's SS:SP on entry to last INT 21 call
32h WORD DOS 3+ number of entries in JFT (default 20)
34h DWORD DOS 3+ pointer to JFT (default PSP:0018h)
38h DWORD DOS 3+ pointer to previous PSP (default FFFFFFFFh in 3.x)
3Ch BYTE DOS 4+ (DBCS) interim console flag (see AX=6301h)
3Dh BYTE (APPEND) TrueName flag (see INT 2F/AX=B711h)
3Eh 2 BYTE ?
40h 2 BYTEs DOS 5+ version to return on INT 21/AH=30h
42h 7 BYTE ?
49h BYTE unused by DOS versions <= 6.00
4Ch WORD ?
4Eh 2 BYTEs unused by DOS versions <= 6.00
50h 3 BYTEs DOS 2+ service request (INT 21/RETF instructions)
53h 2 BYTEs unused in DOS versions <= 6.00
55h 7 BYTEs unused in DOS versions <= 6.00; can be used to make first FCB
into an extended FCB
5Ch 16 BYTEs first default FCB, filled in from first commandline argument
overwrites second FCB if opened
6Ch 16 BYTEs second default FCB, filled in from second commandline argument
overwrites beginning of commandline if opened
7Ch 4 BYTEs unused
80h 128 BYTEs commandline / default DTA
command tail is BYTE for length of tail, N BYTEs for the tail,
followed by a BYTE containing 0Dh
-------------------------------- [CHECKING] ---------------------------------
Usually, there is a test suite provided with the competition rules, which is
irregularily updated; new versions can be found at
http://www.hugi.scene.org/compo/
However, the test suites usually only serve as a GUIDE, so please check your
program against the rules before submitting. Also be aware that the test
suite itself may contain bugs; if you find one, please send an e-mail about
it to Adok (cdvolko@gmx.net) or (preferred) to the compo mailinglist (see
below).
------------------------------- [SUBMISSION] --------------------------------
You have to send
- the sourcecode of your entry
- the executable of your entry ("entry.com")
to Adok so that he can analyse and evaluate your entry.
Send your entries to:
cdvolko@gmx.net
It would be best if you could submit your entry as early as possible. Then
Adok can inform you about bugs, if he finds any, and you have enough time to
fix them. Attention: if he finds no bugs, this doesn't automatically mean
that your entry is bug-free; see also CHECKING (above).
You can submit updates to your entries all the time till the deadline.
Entries that do not agree with these rules will be disqualified. Their coders
will be informed about the mistake, and they can re-submit a bugfixed version
unless the compo is over.
Only one entry per coder can qualify; if two or more coders work together on
a single entry, it will count as a joint entry for those coders; no other
entries of these coders can qualify. Note that the entry will count as a
entry of this group of coders for the world league table.
----------------------------- [PUBLIC JUDGEMENT] ----------------------------
After the deadline for entry submission, as soon as the entries and the beta
results are released, the public judgement starts. During this week you can
discuss and object to the entries that seem to break some rule. Please send
your objections to the compo-mailinglist (see below). Adok and/or a jury
formed by him will check if your objections are according to the rules.
If a hidden flaw is found in one of the originally accepted entries during
the public judgement period, public judgement will decide what to do with the
entry. Possible consequences include disqualification and penalties.
------------------------------- [PRE-RESULTS] -------------------------------
Preliminary results of this compo will be released on the compo-web-site and
always updated after receiving a new entry. In this way the compo will
hopefully be exciting.
Compo-web-site URL:
http://www.hugi.scene.org/compo/
---------------------------------- [PRIZES] ---------------------------------
I'm sorry if I disappoint you, but there are no material prizes. Everything
is just a matter of fun, honor and fame. Moreover, the 30 best competitors
will get points and be listed in the 'World League Table of Assembly'
situated at the compo-web-site. Reaching a good place at a compo and even
more in the World League Table of Assembly is a good visiting-card and
recommendation for every competitor!
------------------------------ [MAILING LIST] -------------------------------
The purpose of the Hugi Compo mailing list is to inform about new compos and
provide a discussion forum for the competitors. At the moment there are about
350 subscribers.
To subscribe send a mail to hugi-compo-subscribe@yahoogroups.com. You'll get
an automatically generated mail which confirms your subscription within a few
hours. Then you start getting the mails the others have posted to this
mailinglist. You will have to subscribe to write mails to the mailinglist.
Mails for the list have to be sent to:
hugi-compo@yahoogroups.com
If you want to subscribe, send a mail to:
hugi-compo-subscribe@yahoogroups.com
If you want to unsubscribe, send a mail to:
hugi-compo-unsubscribe@yahoogroups.com
The mailing list archive can be found at
http://groups.yahoo.com/groups/hugi-compo/
-------------------------------- [ADDRESSES] --------------------------------
Send your entries to:
cdvolko@gmx.net [Adok/Hugi]
Compo-homepage (pre-results, world league table, test suites etc.):
http://www.hugi.scene.org/compo/
Subscribe to the mailing list:
hugi-compo-subscribe@yahoogroups.com
Unsubscribe from mailing list:
hugi-compo-unsubscribe@yahoogroups.com
Mailing list archive:
http://www.yahoogroups.com/groups/hugi-compo/
-----------------------------------------------------------------------------
Thanks for reading this file!
Original rules by Adok
Extended and revised by INT-E
Ë Ë ÉÍÍ» ÉÍÍ»
º º o º º º
ÌÍ͹ Ë Ë ÉÍ» Ë ÉÍͼ ̼ɹ
º º º º º º º º º º
Ê Ê Èͼ È͹ Ê ÈÍͼ ÈÍͼ
º compo
Èͼ
_
/\ ______/ \
///\\\ // \_/
//H \\ // _
/// Usb\\\----------------------/ \
\\\ G ///----------------------\_/
\\ I// \\ _
\\\/// \\_____/ \
\/ \_/
Last updated: 25 June 2009 (v4.3.5)
Greetings Hugi Coders!
It's been awhile.
This time your task is to retrieve the device descriptor from an attached
USB device. Yep, you must detect the controller, find its I/O base,
and control the USB controller, polling for a device connection, then
display the attached device's descriptor.
For those who know the USB hardware, this sounds simple. For those who
don't know the USB hardware, this may sound too difficult, but don't
despair. It really isn't.
You can find the UHCI specs at
http://www.frontiernet.net/~fys/incoming/uhci11d.pdf
and the USB specs at
http://www.usb.org
Before you get discouraged about the complexity of the task, don't worry
too much. The example program will contain many comments and explain
what it does, and why it does it that way.
First a glossary of terms:
- USB Universal Serial Bus
- UHCI Universal Host Controller Interface
- LS Low Speed
- FS Full Speed
- PCI Peripheral Component Interconnect
- IOC Interrupt On Completion
- TD Transfer Descriptor
- GRESET Global Reset bit in the Command register
Please see the UHCI specs above for more on these registers and
their respective bits.
- CRLF Carriage Return Line Feed (ASCII characters 13 10)
The task:
1) Enumerate the PCI bus until you find the first UHCI controller.
Class = 0xC, sub class = 0x3, proto = 0x0
a) You must assume there are 2 buses, 32 devices per bus,
and 8 functions per device.
b) You can not assume that the revision number will be 1
2) Find the I/O base (base 4 in the PCI configuration space).
a) You may use the BIOS's PCI interrupt service, or
b) You may use ports 0xCF8 and 0xCFC
to read the PCI configuration space.
c) write 0x0005 to the command register, without modifying
the status register.
3) Reset the UHCI controller
a) You must reset the controller by setting bit 2 (GRESET) in
the Command register.
b) Wait a minimum of 10ms and no more than 100ms
There is no rule stating how you must delay. However, it must
be at least 10ms and no more than 100ms on *any*
machine. i.e: You cannot simply set ecx to a large number
and loop until it's zero. A slow machine will be more than 100ms
while a fast machine may be less than 10ms.
c) Reset (clear) bit 2
4) Create a UHCI stack
a) Create an empty UHCI stack frame. i.e: you need a buffer
no less than 1024 dwords, and set bit 0 on all dwords.
Remember that this buffer must be 4K aligned.
b) Point the "Frame List Base Address" register to this buffer.
5) Start the UHCI controller.
a) Set the IOC bit in the Interrupt Enable Register.
b) Set bit 0 in the Command Register
6) Reset the port, enable it, retrieve the device descriptor.
* (Please see the note on resetting the port below)
1) You must use an 8-byte control packet.
2) You must only read 8 bytes at a time.
i.e: each packet must not read more than 8 bytes
3) You must send the status packet afterward.
Packet:
SETUP (8 bytes)
IN (8 bytes)
IN (8 bytes)
IN (2 or more, but not more than 8)
OUT (0 bytes)
4) The buffer you use for the 18 or more bytes transferred,
and the setup packet's 8 bytes, must be within your program.
Either you allocate the space with DOS's allocation services,
or you point to a buffer in the current memory block your program
occupies. See general.txt for more on how much space your
program occupies.
i.e: You must not assume any memory space is available outside
your program.
5) You must wait for the interrupt to occur.
You don't have to have a valid ISR, you can simply wait for
bit 0 in the STATUS register to become 1. However, please
note, for Bochs to work this way, you *must* set all four
bits in the low nibble of the INTERRUPT_ENABLE register.
Therefore, it is a rule. You must set all four bits.
6) Stop the Controller
7) Display the device descriptor bytes in the following format:
CRLFxx xx xx xx xx xx xx xx-xx xx xx xx xx xx xx xx
CRLFxx xx
a) You must place a CRLF at the start of each line, not the end
b) No other characters may be displayed.
c) The blanks must be spaces (ASCII 20h)
d) If a value is less than 10h, you must use a prefix of 0.
i.e: 01 02 03...
* e) No space should be printed after the 18th digit pair
8) Do nothing else to the device. Do not retrieve anything else.
The order of the steps above may be changed.
Assumptions:
You *may* assume:
1) There will only be one root hub. i.e: only one PCI UHCI controller.
2) There will only be one device attached and it will always be attached
to the first port of the root hub.
3) Once you retrieve the base I/O address from the PCI, you may assume
that I/O address for the rest of the task. Same for the Int number.
4) You do not have to handle stall's or error codes as long as you
code your stack correctly.
5) That the device is a low speed (LS) device
You *may not* assume:
1) Anything about the UHCI controller. You must follow all rules of
the UHCI and any reserved bits.
You *must*:
1) Find the I/O address of the UHCI controller from the PCI.
2) Setup all 1024 stack frames, even if you only use one of them.
i.e: all dwords must have bit 0 set on frame creation even if
you will only use one of the dwords for your frame.
3) Not modify the SOF register (base + 0x0C).
4) Not crash the computer or UHCI in any way.
7) Allow your program to exit and restart in the same DOS session
(no reboot) and detect the same device.
8) Use the default address of zero (0) for the device
9) Use a UHCI queue with your TD's inside the queue.
10) Clear the breadth-first bit (i.e: use breadth first, not depth first)
You *must not*:
1) Assume anything about any memory that is not allocated to you,
either by int 21h func 48h or at program startup (the 64K+ you are
allocated for the .com program), unless it is well documented.
2) Have or use any other USB drivers or assume any other USB code
is loaded in memory.
3) Modify any bits in any register other than the ones mentioned above.
i.e: do not:
- write to the status register.
- modify any bit in the INT Enable register except for the low nibble.
- read or write to/from the frame number register.
- read or write to/from the SOF register.
- must only write to the frame list address register once as a
dword value, or twice as two consecutive word values.
4) Set the address of the device
5) Simply delay after the packets are sent. You must wait for the
interrupt to occur before you assume the data in the return buffer
is valid.
* Note on reseting the port:
When you reset the port, you can simply set bit 9. However, due to the
nature of the UHCI, when you clear bit 9, you must read in the port
first, clear the bit, then write it back. This isn't so important when
clearing the reset bit, as it is when enabling the port. For example,
have a look at the following code:
mov dx,io_base
add dx,10h
mov ax,(1<<9)
out dx,ax
call delay ; wait for the reset to occur
and ax,(~(1<<9))
out dx,ax
call delay ; wait for the enable to occur
or ax,(1<<2)
out dx,ax
The above code looks like it may work just fine. However, due to the
nature of the UHCI (and most I/O hardware), the port value will change
during the delay. Therefore, you can not simply write the value that
you read before the delay, back to the port expecting the correct values
to be set/cleared.
Therefore, you must read in the port value, set the enable bit, and
write it back to be a legal enable.
For the sake of this compo, you *must* read in the value from the
port, change a bit, then write the value back when you are clearing
the port reset and enabling the port.
To help clarify these rules an example program (appropriately called
example.asm) is provided. The example program still does all of the
older rules, i.e: still uses DOS to allocate the frame list. However,
I will leave it up to you to delete from the example code the items
that are no longer needed. That is the fun part anyway, right?
You must call your program "entry.com".
Send your entry.com along with its source code to Sniper at:
------->> fys@frontiernet.net <<-------
The compo deadline is 31st of August 2009 at the stroke of midnight MST.
You may submit entries as often as you like up until the deadline. In
fact you're encouraged to do so to add excitement to the compo.
Besides these rules, you must follow the general rules that apply to all
compos, which are described in the accompanying file, general.txt.
If you do not have a test computer with a UHCI controller and/or do not
have a USB device to test with, you may use the Bochs emulator at
bochs.sourceforge.net
It will emulate the UHCI and a mouse, hub, or thumbdrive. If you use
this technique for your tests, and it works on Bochs, this doesn't mean
that your entry will pass my test on real hardware.
TEST SUITE: There will be no test suite. You can send your entry to
me and I will see if it returns the expected results. I will let you
know either way with details about it not passing if that is the case.
Please Note: Even if it passes my tests as expected, this doesn't mean
you have a valid entry. It is up to you to make sure that your entry
passes all the rules above. At the end of the compo, each entry
will be released to the group to verify its validity.
If a violation is found, 5 bytes will be added for each instance
plus the number of bytes required to fix it.
If you have any questions or comments, please feel free to post them at:
hugi-compo@yahoogroups.com
Thanks to Boreal for helping with these rules.
-Sniper