Merge pull request #18 from tredontho/master

Spelling/Phrasing

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,114 +30,114 @@ 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).
  - Device SubType register (Read byte): At offset 2, there is a byte that gives 
    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