Next: Introduction, Up: (dir) [Contents]
This is the user manual for version 0.2.0 of CHIP-8 software package. To check for updates, please visit http://github.com/danirod/chip8.
| • Introduction: | An introduction to CHIP-8 | |
| • Emulator usage: | How to use the emulator | |
| • Emulated systems: | Platforms that can be executed | |
| • Compatible ROM formats: | ROM formats supported by the emulator. | |
| • Hacking the emulator: | How to modify the source code. | |
| • GNU Free Documentation License: |
Next: Emulator usage, Previous: Top, Up: Top [Contents]
Welcome to chip8, my implementation of an emulator compatible with the CHIP-8 virtual machine. This software manual will bring you information about the emulator, how to run programs on the CHIP-8, how to use the emulator and some information for those interested on the insides of the CHIP-8 virtual machine and the format used by the ROMs that can be run from CHIP-8.
| • Main features: | Some of the features of this emulator | |
| • Reporting bugs: | How to report bugs that you might find | |
| • Some history: | Some history on the CHIP-8 machine |
Next: Reporting bugs, Up: Introduction [Contents]
This implementation for the CHIP-8 virtual machine has, at this moment, the following features:
At this stage the emulator has not been finished. There are a few features that have not been implemented yet. There is a particular interest in adding the following features:
Next: Some history, Previous: Main features, Up: Introduction [Contents]
This tool has not been finished yet, and therefore there might be issues that haven’t been reported or addressed yet. If during the execution of a program you find some bug that would like to report for having it fixed, you can report bugs to our issue tracker, at the canonical repository for our project. The URL is https://www.github.com/danirod/chip8.
Please, provide as much information as you can, including the operating system you are using, the version of the emulation software and if you can tell us which ROM were you playing, it would be better.
Previous: Reporting bugs, Up: Introduction [Contents]
CHIP-8 is an interpreted programming language and the specification for a virtual machine. As is, CHIP-8 is not a cmoputer, and there are no computers in the wild using this architecture, because it has limited resources. Instead there are computers with their own hardware, that have a virtual machine that allows the computer to decode and execute CHIP-8 programs.
One of the first computers in add support for CHIP-8 as the COSMAC VIP, sold by RCA in the late 70s. This computer had a processor made too by RCA, with a speed of about 1.77 MHz and 2 kB of RAM memory. Inside the ROM, the operating system had the CHIP-8 interpreter that allowed the system to run games using the CHIP-8 language.
However, there are more machines that have added support for CHIP-8, specially during the late 80s and early 90s, with the expansion of small computers such as graphical calculators. In fact, during this period and thanks to the first Internet communities that came around that time, many hobbyists could extend the original CHIP-8 specification, by making some changes that would make them run better on their machines, and sometimes even improving the original CHIP-8 system, with features such as a bigger screen, more memory and even color.
Thanks to being easy to understand, CHIP-8 is one of the greatest platforms for those people who want to start working in the world of emulators development, learning an easy architecture before starting bigger projects.
Next: Emulated systems, Previous: Introduction, Up: Top [Contents]
| • Installing the emulator: | How to install the emulator | |
| • Running the emulator: | How to run the emulator | |
| • Using the emulator: | How to use the emulator | |
| • Stopping the emulation: | How to stop the emulator |
Next: Running the emulator, Up: Emulator usage [Contents]
The main procedure for installing the emulator is to download the source code distribution, compiling it and installing it. Of course, there are aditional ways for obtaining the emulator, such as getting it from a binary distribution, for example, a .deb file for Debian based systems or an .exe application for Microsoft® Windows®.
This emulator only depends on SDL2, because it is the multimedia library used
for displaying the emulator output, reading keys from the keyboard and making
the speaker buzz. After the dependencies are met, this CHIP-8 emulator can be
installed by downloading the software release, extracting it somewhere, and
then running ./configure && make to compile it.
Once compiled, it can be installed using make install. By default
on a standard GNU/Linux system they would be installed into
/usr/local/bin, /usr/local/share/doc/chip8, etc. On
Apple® MacOS® X systems, these locations
will be used as well. On Microsoft®
Windows®, the location might actually change depending on
how you build the software.
If you are interested in checking that the software actually works as intended
you can use the test suite provided with the source distribution. In order to
run the tests you’ll need to have check installed on your computer.
Install the dependencies, and then after running ./configure && make
on the emulator package, run make check to run the test suite.
After the execution, you will get a report on the test status.
Next: Using the emulator, Previous: Installing the emulator, Up: Emulator usage [Contents]
After the emulator has been downloaded it can be executed using the command
chip8 file, where file is the path to a binary file
that has the encoded data for a program that can run on the CHIP-8 virtual
machine.
As an example, to run the ROM WIPEOFF.BIN using the emulator, the following command can be used:
$ chip8 WIPEOFF.BIN
assuming the game is on the current working directory. Some games can make use
of the buzzer that the CHIP-8 computer has. The buzzer will sound through the
speakers. If you want to avoid this behaviour you can run the game muted using
the --mute option:
$ chip8 --mute WIPEOFF.BIN
There are actually two kinds of ROMs: binary ROMs and hexadecimal ROMs. A binary ROM only has binary data and it is the most lightweight and fast way for running a ROM because the data can be placed in memory and executed instantaneously. This data can come from a dump for an actual CHIP-8 game or a game made for the CHIP-8 platform in any other way
However, to make easier to people to create their own ROMs, there is an
aditional way for running these ROMs and is using hexadecimal files. These
files are plain text files only having the characters 0-9, A-F
and a-f encoded as either US-ASCII, UTF-8, Windows-1252 or a similar
human readable text-enconding and can be modified using any kind of text
editor that supports plain text. This format is slower to load since the
file has to be converted to binary but it makes playing around faster.
Next: Stopping the emulation, Previous: Running the emulator, Up: Emulator usage [Contents]
Once the emulator opens, it automatically starts executing the ROM contents. It is possible to control the emulator using the emulated keyboard. The CHIP-8 specification sets a 16 keys keyboard using a 4x4 table having the following layout:
[1] [2] [3] [C] [4] [5] [6] [D] [7] [8] [9] [E] [A] [0] [B] [F]
Using the current settings, that aren’t modifiable by the user yet –although that is hoped for future releases, the assigned keys for the keyboard are mapped to the following keys on a traditional keyboard:
[1] [2] [3] [4] [Q] [W] [E] [R] [A] [S] [D] [F] [Z] [X] [C] [V]
Which means that if you want to send the 5 key to your game you should press the W key in the emulator. Pressing F will trigger E key and similar.
During the execution of a CHIP-8 ROM, some games may play sounds on the buzzer. As explained in Running the emulator, this behaviour can be changed by using the option --mute when running the game.
Previous: Using the emulator, Up: Emulator usage [Contents]
At this moment there is no way for pausing, resuming, resetting or stopping the emulation in this CHIP-8 emulator. The only way for stopping it is by exiting the emulator, something that you can do by pressing the Close button on the emulator window. This depends on your window manager or operating system.
Next: Compatible ROM formats, Previous: Emulator usage, Up: Top [Contents]
This CHIP-8 emulator is compatible with other kinds of systems. CHIP-8 is based in the origina lspecification written for the first computers using CHIP-8 virtual machines inside, such as the COSMAC VIP. However, through the years, hobbyists interested in CHIP-8 emulation have developed emulators for other kinds of machines such as calculators or PCs, and they have extended the original specification for adding support to new features if the host hardware allowed so.
In particular, this emulator is at the moment compatible with CHIP-8 and SUPERCHIP ROMs.
| • CHIP-8 platform: | About the original CHIP-8 specification. | |
| • SUPERCHIP platform: | The SUPERCHIP extended specification. | |
| • MEGACHIP platform: | The MEGACHIP extended specification. |
Next: SUPERCHIP platform, Up: Emulated systems [Contents]
This is the original platform for the CHIP-8 virtual machine. It is a simple architecture that has the following hardware resources.
V0, V1, ..., V9,
VA, VB, VC, VD, VE and VF.
The CHIP-8 screen is a rasterized 64 x 32 pixels display. It is monochrome and up to 2048 pixels can be represented. Usually these pixels will be black and white, but there is no official statement on this, which means that is possible for some systems to use different colors, such as green over black.
CHIP-8 also has a 16 keys keyboard, as indicated in Using the emulator. It also has a buzzer that can play sounds on a particular and single frequency.
Talking about the interpreter, the CHIP-8 specification sets 34 instructions that can manipulate the data in memory, registers and stack, and interact with other IO devices such as sending images to the screen, reading keys from the keyboard or making the speaker buzz.
Next: MEGACHIP platform, Previous: CHIP-8 platform, Up: Emulated systems [Contents]
SUPERCHIP is an extension over the original CHIP-8 specification that appeared in the early 90s in order to run CHIP-8 games in some graphical calculators. Thanks to the new hardware capabilities of the machine, this specification adds the following features to CHIP-8:
There are 10 new instructions that cna be used in the programs. SUPERCHIP is still compatible with the original instruction set because these new opcodes are mapped to opcodes that would trigger on a crash on regular CHIP-8 emulators. A classic ROM can still work because the original instruction set is, of course, provided.
Previous: SUPERCHIP platform, Up: Emulated systems [Contents]
This mode is not implemented yet in this emulator, although their features makes this platform very appealing.
MEGACHIP is a new format born after the improvement of personal computers. Old limitations have no place on regular devices we have today, and therefore we can have better multimedia capabilities for running games.
MEGACHIP adds support for the following features, that should be designed to be backwards compatible with CHIP-8 and SUPERCHIP formats:
There are 11 new instructions that are of course mapped to opcodes that neither CHIP-8 nor SUPERCHIP uses. Therefore, it is possible to run old CHIP-8 and SUPERCHIP games without side effects.
Next: Hacking the emulator, Previous: Emulated systems, Up: Top [Contents]
In order to run the programs, it is required to have a ROM containing the instructions for the program. These instructions are executed by the virtual machine when the emulator starts.
This CHIP-8 distribution comes with a set of public domain ROMs that can be executed in order to test the features of the emulator. These ROMs are in the examples/ directory for the software distribution package, and once installed they are placed in /usr/local/share/doc/chip8/roms, although the exact location may change depending on where is the package installed in.
The user can also create new ROMs using software tools or manually writing machine code into a binary file or an hexadecimal file. These files have to be provided as parameters when starting the emulator, as explained in Running the emulator.
However, there are two ways of storing the program instructions inside CHIP-8 ROMs.
| • Binary ROM files: | Binary files having only instructions. | |
| • Hexadecimal ROM files: | Text files having hexadecimal characters. | |
| • Corrupt ROM files: | What happens when a broken ROM is loaded. |
Next: Hexadecimal ROM files, Up: Compatible ROM formats [Contents]
A binary ROM file is a file where every byte is a byte that must be placed in the RAM memory for the emulator when the game starts. In other words, the actual opcodes are encoded. Every 2 bytes in the ROM file can be translated to an actual instruction that the machine must run. (Or to some data such as an sprite).
This is the fastest way for starting ROMs because no transformation is needed. As the emulator starts, the contents of the file are loaded in RAM memory if they fit, and the game is started. However, they need special software, such as hexadecimal editors, in order to see the contents, because they are binary and cannot be opened with regular text editors.
As an example, let’s suppose that we have a binary ROM with the following
contents, that we might have got using an hexadecimal file tool such as
hexdump:
$ hexdump examples/PONG 0000 6a 02 6b 0c 6c 3f 6d 0c a2 ea da b6 dc d6 6e 00 0010 22 d4 66 03 68 02 60 60 f0 15 f0 07 30 00 12 1a
(more lines have been omitted for brevity)
When this ROM is loaded into memory, the first instruction that will be
executed will be 6A02, as these are the first two bytes in the file.
Next, the instruction 6B0C will be executed, and then 6C3F,
and so.
Binary format is the most preferred way when working with dumps coming from external sources such as actual chips containing programs for old computers using the CHIP-8 format, because they represent the program as it was.
Next: Corrupt ROM files, Previous: Binary ROM files, Up: Compatible ROM formats [Contents]
An hexadecimal ROM file has the hexadecimal characters that are required for running a ROM file, organized in a text file that can be edited by the user in order to build their own programs and games.
It is a file that makes use of a human readable character encoding such as
US-ASCII, UTF-8 or Windows-1252 and that contains only characters in the ranges
"0" to "9", "A" to "F" and "a" to "f.
These ranges would equal to the US-ASCII codes 0x30-0x39,
0x41-0x46 and 0x61-0x66.
The contents for an hexadecimal ROM file can be inspected using regular text editors, as an example:
$ cat pong.hex 6A026B0C6C3F6D0CA2EADAB6DCD66E0022D46603 68026060F015F0073000121AC717770869FFA2F0 D671A2EADAB6DCD66001E0A17BFE6004E0A17B02 601F8B02DAB6600CE0A17DFE600DE0A17D02601F 8D02DCD6A2F0D67186848794603F8602611F8712 46021278463F1282471F69FF47006901D671122A
When an hexadecimal ROM file is given to the emulator, it must be processed. The hexadecimal ROM is converted to binary using the following method:
([0-9A-Fa-f]{2}), the following operation is made:
(L, R) -> (L << 4) | R, where L is the left hexadecimal character
once converted to binary and R is the right hexadecimal character once
converted to binary. This conversion is made by transforming every
character to the 4-bit digit they represent (0x0 to 0xF).
Although it has not been implemented yet, the following operations are planned:
Previous: Hexadecimal ROM files, Up: Compatible ROM formats [Contents]
This emulator has not been tested against fuzz testing, which means that it is not possible to know at this moment what should happen and how should the emulator behave when ROMs having corrupt instructions are execute.
Fuzz testing is made by giving a random input to a program. As an example, randomly generating about 100 to 200 bytes of instructions, either in binary or hexadecimal way, and loading the contents in order to check what happens.
Even though it has not been tested, the expected behaviour should be:
Anyway, it is not expected that a corrupt ROM could harm the host machine in anyway, becuase none of the operations execcuted by the program interact with the underlying operating system in a way that could have side effects. On the other side, all the operations that work with memory buffers make enough tests to minimize the risk of a buffer overflow error.
Despite all of that, this is something that hasn’t been further tested. As stated by the license terms of this sfotware, available in the COPYING file, the emulator is provided AS IS, with no extra warranties.
Next: GNU Free Documentation License, Previous: Compatible ROM formats, Up: Top [Contents]
By downloading the software package including source code, any user can change how the emulator works to make it behave in a different way for their personal interest, as stated in the license terms for the software package.
Some hints are given on the source code to make it easier to advanced people to modify the program. They should be specially useful for people that wants to contribute to the project by making their contributions public by patching the upstream source code via a Pull Request.
| • Basic source code guidelines: | The most easy rules to follow. | |
| • Style guides: | Style guides when writing code for this project. | |
| • Opcodes table: | Clarification on how the opcodes table is made. |
Next: Style guides, Up: Hacking the emulator [Contents]
This program is made using the C programming language. Although any port to a different programming language is good to have as a side project, this is the official language for this project. Therefore, any patch that attempts to change that is not welcome. The project is good using C; I don’t want to change to C++, Python or whatever funky language is the trendiest at this moment.
This program uses GNU Autotools for the build tool. Although GNU Autotools is not loved by everyone, this is the official tool for this project. So, any attempt to change the build tool to CMake, Gradle or regular Makefiles is not welcome.
Next: Opcodes table, Previous: Basic source code guidelines, Up: Hacking the emulator [Contents]
Although this is not an official GNU project, I make use of most of their style guidelines. Any contributor that wants to make public changes to the project must keep the following rules in mind.
P,
X, Y or K for variables related to an opcode, because
these are the names given to the opcode structures. Long names when they
are not required is not pretty.
Previous: Style guides, Up: Hacking the emulator [Contents]
In order to implement the opcodes, the following structure has been made.
There is a common definition for every opcode function in the code, declared
as a type named opcode_table_t, located as a private typedef
in the file cpu.c at the lib8 subproject.
After that, 16 functions are declared, every one compatible with that typedef.
Their names are nibble_0, nibble_1, nibble_2... These
functions have been declared as private functions using the same parameters:
static void nibble_0(struct machine_t* cpu, word opcode); static void nibble_1(struct machine_t* cpu, word opcode); static void nibble_2(struct machine_t* cpu, word opcode);
Every one of these functions executes opcodes with a P value matching the one
in the function name. As an example, the opcode 6104 would be executed
by nibble_6, since P(6104) = 6.
Then, there is an array pointing to every opcode function named
nibbles[]. These functions are sorted by P value, so that
nibbles[6] will return a pointer to the function nibble_6,
and nibbles[0xB] will return a pointer to the function
nibble_B.
Thanks to this indirection, the processing logic for an opcode is easier
since no big switch is required on code. Using this indirection, it is
more straightforward to know which function should process each opcode.
Although, some functions such as nibble_6 will make use of switch
anyway since there are multiple opcodes sharing the same P value.
Previous: Hacking the emulator, Up: Top [Contents]
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. http://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.