From 11aa28496aaca35b17c75b1dfce7258f62e9aac2 Mon Sep 17 00:00:00 2001 From: Trevor Thompson Date: Fri, 9 May 2014 00:27:38 -0500 Subject: [PATCH] Spelling corrections, clear up some of the phrasing. --- README.md | 150 +++++++++++++++++++++++++++--------------------------- 1 file changed, 75 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index ab06408..d14a80a 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,12 @@ Trillek Virtual Computer Specifications ===================================== Version 0.4h -**ADVICE** : In this documents there some technical stuff that could looks hard -or complex to understand for not hardware guys. -Some of these stuff there is only to give natural limitations of what can do -and can't do the computer. If your only interest is programing the computer, +**ADVICE** : In this document there is some technical stuff that could look +complex or hard to understand for non-hardware folks. +Some of these things exist only to give natural limitations of what the computer +can and can't do. If your only interest is programing the computer, you should check the instruction set of a CPU and the specs of the devices to -understand how program the computer and use the devices at assembly or C +understand how to program the computer and use the devices at assembly or C programing level. **NOTATION** : Byte is a 8 bit value. Word is a 16 bit value and DWord is a 32 @@ -30,82 +30,82 @@ SUMMARY (0x000000-0x0FFFFF) - CPUs are connected by a CPU board (actually TR3200 and DCPU-16N) to the mother board. Only one CPU can be connected to the computer at same time - (not multi-processor setups) + (no multi-processor setups) - CPU Clock speed could be 1Mhz , 500 Khz, 200 Khz and 100Khz (actually we work with 100Khz, but we expect to allow higher speeds). CPU clock speed in KHz can be read at address 0x11E050 (I/O port 0xE050 on DCPU-16N) - - Devices uses a fixed clock of 100Khz (thinking to change it to 50 KHz) if - they need to do periodic or sync stuff. + - Devices use a fixed clock of 100Khz (thinking to change it to 50 KHz) if + they need to do something periodically or sync stuff. - Devices are [memory mapped](http://en.wikipedia.org/wiki/Memory-mapped_I/O). So dcpu's **HWI** is replaced by writing/reading to addresses where the - device is listening. **HWN** and **HWQ** is replaced by reading addresses. + device is listening. **HWN** and **HWQ** are replaced by reading addresses. - Addresses used by devices are over 0x110000 to avoid address clashes with the RAM/ROM. - Addresses 0x110000 to 0x112000 are reserved to Devices Enumeration and Communication. - - At address 0x11XX00, were **XX** is the device slot number (to a total + - At address 0x11XX00, where **XX** is the device slot number (to a total of 32 -> 0x20), there is mapped the **Enumeration And Control registers** of - device **XX**, that consists : + device **XX**, that consists of: Device Type, Device SubType, Device ID, Device Vendor ID, CMD, A, B, C, D, E hardware registers. - Devices could do **DMA** operations at will, but ONLY one device could do - that at same time, and can only transfer 4 bytes every Device Clock (like + that at a time, and can only transfer 4 bytes every Device Clock (i.e. if the DMA operates in the falling clock flank and the CPU operated in the rising clock flank.) - - Usually the devices exposes his own ram and&or uses commands. The only + - Usually the devices expose their own ram and&or uses commands. The only exception is the most basic graphics device that uses computer RAM as buffer. - The computer can be expanded to a total 32 devices, not counting integrated - devices on motherboard. This can be archived by plugin the device boards in - the expansion bus. Some devices will require a external module attached to + devices on motherboard. This can be achieved by plugging the device boards in + the expansion bus. Some devices will require an external module attached to the computer, like floppy drives, graphics cards, joysticks, weapons, etc... - Integrated devices on motherboard: - Programmable Interval Timer (**PIT**) aka *Clock* device. - Real Time Clock (**RTC**), that gives the date and time in game world - when is polled (not have alarm). + when it's polled (does not have alarm). - Random Number Generator (**RNG**), that generates a 32 bit random number - every time that is polled (at implementation level, a simple call to + every time that it's polled (at implementation level, a simple call to rand_r) - Beeper or *buzzer* device (**Beeper**). Simply generates a squared wave sound at desired frequency. - - 256 bytes of NVRAM (Not Volatile RAM). Usefull to store basic configration - used in boot time. + - 256 bytes of NVRAM (Not Volatile RAM). Useful to store basic configration + used at boot time. - 256 bytes reserved for CPU board HW registers from 0x11FF00 to 0x11FFFF -HOW WORKS ---------- +HOW IT WORKS +------------ [![Computer Architecture Diagram](img/dia/computer_tn.png "Diagram")](img/dia/computer.png) As can you see, the computer uses a 24 bit Address Bus and 32 bit Data bus. RAM -and ROM are directly attached to these buses, as any device in the computer -that is controllable by software. Also there is the integrated devices. +and ROM are directly attached to these buses, as are any device in the computer +that is controllable by software. Also there are the integrated devices. ### Interrupts To avoid clashes with interrupt petitions, we daisy chain the interrupt signals -*INT* and *IACQ* . So when two devices try to generate a interrupt at same time -, the device more near to the CPU (with lowest slot number), have preference. +*INT* and *IACQ* . So when two devices try to generate an interrupt at the same +time, the device nearer to the CPU (with lowest slot number), has preference. The **PIT** and **Keyboard controller** devices can generate interrupts, so we -put it between the expandable devices and the CPU having more preference that -any expansion device. Plus the **PIT** have more preference as is more near to -the CPU that the Keyboard Controller. +put it between the expandable devices and the CPU having more preference than +any expansion device. Plus the **PIT** has more preference as it's nearer to +the CPU than the Keyboard Controller. **NOTE FOR USERS**: In other words, you only need to worry about the interrupt message in your **Interrupt Service Routine** (ISR). This stuff is to put some limitations to the computer and add some details at implementation of it. -**NOTE FOR IMPLEMENTATION**: This means that when you need to "executes" the +**NOTE FOR IMPLEMENTATION**: This means that when you need to "execute" the hardware devices, you only need to loop the device array in order and check if -device **x** send a Interrupt. If it happens, allow it to send the message to +device **x** sends an Interrupt. If it does, allow it to send the message to the CPU, and just ignore the Interrupt petitions for the rest of the loop. ### Hardware Enumeration -Devices maps 0x11XX00 address block, were XX is the slot were is plugged. -In these address block that we call **Enumeration And Control registers**, there - is a few registers : +Devices map 0x11XX00 address block, where XX is the slot in which it is plugged. +In this address block that we call **Enumeration And Control registers**, there + are a few registers : - - Present flag (Read byte): At offset 0,there is a byte that always read 0xFF + - Present flag (Read byte): At offset 0,there is a byte that always reads 0xFF if a device is plugged in these slot. - Device Type register (Read byte): At offset 1, there is a byte that gives information about the device type (see Device Type list section). @@ -113,31 +113,31 @@ In these address block that we call **Enumeration And Control registers**, there information about the device subtype (see Device Type list section). - Device ID register (Read byte) : At offset 3, there is a byte that gives the Device ID. - - Device Vendor ID register (Read dword) : At offset 4, there is dword that - gives the Vendor/Builder ID of the device (see know Device Vendor list section). - - CMD register (Write word) : At offset 8, there is a d that writing to it, - sends a command to the device. The command list is dependent of the device, - and is showed in the device specs. - - A, B, C, D, E registers (Read/Write word every one) : Begin at offset 10, - there is five word registers that are used to send values with the commands - and receive status/error or other stuff from the devices. + - Device Vendor ID register (Read dword) : At offset 4, there is a dword that + gives the Vendor/Builder ID of the device (see Known Device Vendor list section). + - CMD register (Write word) : At offset 8, there is a dword that, when writing + to it, sends a command to the device. The command list is dependent on the + device, and is shown in the device specs. + - A, B, C, D, E registers (Read/Write, one word each) : Beginning at offset 10, + there are five one-word registers that are used to send values with the + commands and receive status/error or other stuff from the devices. [![Device Enumeration And Control Header](img/dia/DevConfigHeader.png "DevHeader")](img/dia/DevConfigHeader.png) -To know how many devices are plugged to the computer, you only need to read the -first byte of the 32 addresses and count one more for every byte being 0xFF. +To know how many devices are plugged in to the computer, you only need to read the +first byte of each of the 32 addresses and count one for every byte being 0xFF. The tuple {Device Vendor ID, Device ID} defines a unique device. This information -can be used to allow the software know what device is plugged and how should +can be used to allow the software to know what device is plugged in and how to use it. -Devices that have the same {Device Type ID, Device SubType ID} are expect that -share some minimal compatibility. To archive this, should share a minimal list +Devices that have the same {Device Type ID, Device SubType ID} are expected to +share some minimal compatibility. To achieve this, they yshould share a minimal list of commands with the same expected behavior. -**NOTE FOR USERS**: This is nearly the same stuff that does the original -Notch's DCPU-16, but being memory mapped instead of being special magic -instructions. Each device have his own set registers. The device at slot 0 have -this registers at 0x110000, and his A register is at 0x11000A; device 8 have this -registers at 0x110800, and his BuildID register is at 0x110804; etc... +**NOTE FOR USERS**: This is nearly the same stuff that Notch's original DCPU-16 +does, but being memory mapped instead of being special magic +instructions. Each device has its own set of registers. The device at slot 0 has +these registers at 0x110000, and its A register is at 0x11000A; device 8 has these +registers at 0x110800, and its BuildID register is at 0x110804; etc... #### Device Types and SubTypes values @@ -197,7 +197,7 @@ Here is a list of Device Types. Each entry could contain a sublist of actually k - 0x1D : FTL Navigational Systems (control of warp engines) - 0xFF : Unassigned class -#### Know Vendor values +#### Known Vendor values - 0x00000000 -> Unknown builder (reserved value) - 0x048BAD15 -> RocoCorp. @@ -209,56 +209,56 @@ Here is a list of Device Types. Each entry could contain a sublist of actually k ### PIT (PROGRAMMABLE INTERVAL TIMER) -The PIT consists in two 32 bit timers as can you find in any modern -micro-controller. Allow to do time measurements and generate periodic -interrupts for system clock and tasks switchers. Have the highest priority when +The PIT consists of two 32 bit timers as you can find in any modern +micro-controller. They allow one to do time measurements and generate periodic +interrupts for system clock and task switchers. Has the highest priority when needs to signal a interrupt. -**NOTE FOR USERS**: Could look a bit more hard that the Noth's DCPU-16 Timer -device, but gives more freedom and control. Plus is more easy to -understand and use that the IBM PC timer. Using the highest interrupt priority -means that will be the first Interrupt to be attended by the CPU when -simultaneous interrupts happens. +**NOTE FOR USERS**: Could look a bit harder than Notch's DCPU-16 Timer +device, but gives more freedom and control. Plus it's easier to +understand and use than the IBM PC timer. Using the highest interrupt priority +means that it will be the first Interrupt to be attended by the CPU when +simultaneous interrupts happen. **NOTE FOR VM IMPLEMENTATION**: Uses two vars per timer. One stores the Reload -value and the other count downs every timer clock tick. The times generated are +value and the other counts down every timer clock tick. The times generated are in Virtual Computer time, so if you run the Virtual Computer at 200% speed, the measured times should be the half. ### RTC (Real Time Clock) -Is a basic device that gives the actual game time and date. Not have alarm, so -is necessary doing a polling every 12 or 24 hours to keep a software clock in +Is a basic device that gives the actual game time and date. Doesn't have alarm, so +it's necessary to poll every 12 or 24 hours to keep a software clock in sync with game time. Gives time information in dd-mm-yyyy hh:mm:ss format (see specs) ### RNG (Random Number Generator) Is a basic device that writing to it, sets the RNG seed, and reading from it, gets a 32 bit random number. Simply reading a dword from 0x11E040 gets a 32 bit -random number. Writing to the same address, setups the random seed. (see specs) +random number. Writing to the same address, sets up the random seed. (see specs) ### Beeper Simple basic Beeper with similar functionality to the IBM PC speaker or -ZX Spectrum beeper. It have less power as can't allow do PWM to generate basic -crude PCM sound, but it makes a lot more simple to use and understand. +ZX Spectrum beeper. It has less power as can't allow do PWM to generate basic +crude PCM sound, but it makes it a lot simpler to use and understand. **NOTE FOR VM IMPLEMENTATION**: Try to use a Band-Limited Sound Synthesis lib to generate square wave sound, but a crude Fourier synthesis could do the trick. ### NVRAM -The computer motherboard includes a small 256 bytes NVRAM powered by a litium battery. -This small not volatile RAM are mapped in 0x11F000 to 0x11F0FF, and can be used +The computer motherboard includes a small 256 bytes NVRAM powered by a lithium battery. +This small non-volatile RAM is mapped in 0x11F000 to 0x11F0FF, and can be used for boot configuration stuff. ### Devices with DMA (Direct Memory Access) DMA operations by the hardware devices are allowed, but only one DMA operation -could be happening at same time at a rate of 4 byte for each device clock. To -avoid that two or more devices try to do a DMA operation, there is a BUSY BUS -signal. DMA operations happens in the opposite flank that the CPU clock, so -don't interfere and not need contention hardware. +could happen at a time at a rate of 4 byte for each device clock. To +avoid two or more devices trying to do a DMA operation, there is a BUSY BUS +signal. DMA operations happen in the opposite flank from the CPU clock, so +don't interfere and don't need contention hardware. -**NOTE FOR VM IMPLEMENTATION**: By practical reasons, this will translated in a +**NOTE FOR VM IMPLEMENTATION**: For practical reasons, this will translated in a flag in the Virtual Computer to indicate if a device will being doing DMA, as -can't be two devices doing a DMA at same time. +two devices can't do a DMA at the same time. ADVICE