============================================================================= 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