Linux 2.

6 Kernel 
Standard Serial driver description

Copyright (c)  H.J Boshoff. Permission is granted to copy, distribute and/or modify this document under the terms of 
the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; 
with no Invariant Sections,  with  the Front­Cover Texts being the title, the copyright notice and the document history 
list already sited in the section entitled DOCUMENT HISTORY, and the Back­Cover Texts being any reference already 
cited in the section entitled REFERENCE. A copy of the license is included in the section entitled "GNU Free 
Documentation License".

DOCUMENT HISTORY

By Rev Description Date

DOCUMENT DISTRIBUTION
This document may be downloaded from:
http://www.business­lounge.co.za/linux_kernel/SerialDriver.pdf
http://www.business­lounge.co.za/linux_kernel/SerialDriver.rtf
INTRODUCTION
It is advised that the serial driver and platform documentation shipped with the kernel source 
(linux2.6/Documentation/serial/driver.txt and linux2.6/Documentation/driver­model/platform.txt) be read either before 
or whilst reading this document. 
This document aims at giving a basic reference to kernel developers who need to update or add serial drivers to the 
Linux 2.6 kernel. It describes some of the serial_core support as  defined in drivers/serial.  (Basic installing and opening 
of the driver)

In stead of describing all the files from top to bottom, this description follows the program flow as it would usually be 
used in the kernel.

Fonts used are as follows

The description is in 10pt roman.
Console output is in itallic 10pt roman.
Source code is in 8pt courier.

CORE 8250 SERIAL DRIVER STRUCTURES USED IN THIS DOCUMENT
The structures shown here are often referred to further in this document. They are given for reference. 

struct irq_info 
This structure holds all the information required by the driver port spinlocks. It is set up for each IRQ in the system. 
struct irq_info {
spinlock_t lock;
struct list_head *head;
};
static struct irq_info irq_lists[NR_IRQS];

static struct uart_driver serial8250_reg 
This structure holds the basic uart information. The struct uart_driver is declared in serial core.h, but is defined as 
follows in 8250.c

static struct uart_driver serial8250_reg = {
.owner = THIS_MODULE,
.driver_name = "serial",
.devfs_name = "tts/",
.dev_name = "ttyS",
.major = TTY_MAJOR,
.minor = 64,
.nr = UART_NR,
.cons = SERIAL8250_CONSOLE,
};
8250 SERIAL DRIVER INITIALIZATION FUNCTIONS
These functions, are used when the core serial driver is initialized.  Three groups of structures are used by these 
functions to describe the driver. The first is a UART description structure (serial8250_reg) which defines the main 
UART variables. The second are the description for the tty drivers found in tty_io.c and the third is the platform device 
description defined in platform.c. If a console is required this will also be added. After the serial driver is active and all 
ports set up, the user defined structures may be used to add additional ports. 

Main functions in 8250.c

static int __init serial8250_init(void)
This function is the main entry point for the 8250 type device drivers. 
When the driver initializes the following will appear in the dmsg 

Serial: 8250/16550 driver $Revision: 1.90 $ 10 ports, IRQ sharing disabled
it gives you information on the amount of ports available as well as whether IRQ's will be enabled or disabled.

The first thing the function does is to initialize the spin_locks (See [1] page 117 for description of spin_locks) required 
by  the driver. This is done for each defined port. 
These spin_lock variables are stored in the irq_lists structure.  The NR_IRQS used by this for loop is defined in the 
platform specific files, and is the amount of interrupts available in the system.
for (i = 0; i < NR_IRQS; i++)
     spin_lock_init(&irq_lists[i].lock);

Once the spin_locks are set up, it will register the uart driver using the int uart_register_driver(struct uart_driver *drv)
function found in serial_core.c.  The driver structure passed to the function is set up with the normal values defined 
within the serial8250_reg struct.  This function will set up a tty struct associated with this device. 
      ret = uart_register_driver(&serial8250_reg);
if (ret)
  goto out;

If a serial console is required this device is set up by the function static int serial8250_console_setup(struct console *co, 
char *options) found in 8250.c. 
#if defined(CONFIG_X86) && defined(CONFIG_SERIAL_8250_CONSOLE)
serial8250_console_setup(&serial8250_console, NULL);
#endif

Once console set­up is finished,  it will register this device as a platform device using struct platform_device 
*platform_device_register_simple(char *name, unsigned int id,struct resource *res, unsigned int num) as found in 
base/platform.c. (See inux2.6/Documentation/driver­model/platform.txt for more information)
serial8250_isa_devs = platform_device_register_simple("serial8250",
      ­1, NULL, 0);
if (IS_ERR(serial8250_isa_devs)) {
ret = PTR_ERR(serial8250_isa_devs);
goto unreg;
}

This platform device is then registered to the serial driver using static void __init serial8250_register_ports(struct 
uart_driver *drv, struct device *dev) defined in 8250.c. 
serial8250_register_ports(&serial8250_reg, &serial8250_isa_devs­>dev);

After this, the driver is then registered in the kernel.
ret = driver_register(&serial8250_isa_driver);
if (ret == 0)
goto out;

static void __init serial8250_register_ports(struct uart_driver *drv, struct device *dev)
This function initializes a driver that was set up and passed using *drv. 

The first function called is static void __init serial8250_isa_init_ports(void) in 8250.c. No values are passed to the 
function, as it set's up all the 8250 ports, as defined by the serial8250_ports struct.
serial8250_isa_init_ports();

Once ISA init finished, it will step through all the ports,  and add the device to the uart core layer using int 
uart_add_one_port(struct uart_driver *drv, struct uart_port *port) found in serial_core.c. 
for (i = 0; i < UART_NR; i++) {
struct uart_8250_port *up = &serial8250_ports[i];

up­>port.dev = dev;
uart_add_one_port(drv, &up­>port);
}

static void __init serial8250_isa_init_ports(void)
This function set up the 8250 ports. 

Before it starts setup, It verifies that it is the first call to this function, and will return if called more than once. 
 
if (!first)
return;
first = 0;

After this check it will scan through all the serial8250_ports and set up relevant information, 
for (i = 0; i < UART_NR; i++) {
struct uart_8250_port *up = &serial8250_ports[i];

up­>port.line = i;
spin_lock_init(&up­>port.lock);

init_timer(&up­>timer);
up­>timer.function = serial8250_timeout;

/*
 * ALPHA_KLUDGE_MCR needs to be killed.
 */
up­>mcr_mask = ~ALPHA_KLUDGE_MCR;
up­>mcr_force = ALPHA_KLUDGE_MCR;

up­>port.ops = &serial8250_pops;
}

for (i = 0, up = serial8250_ports; i < ARRAY_SIZE(old_serial_port);
     i++, up++) {
up­>port.iobase   = old_serial_port[i].port;
up­>port.irq      = irq_canonicalize(old_serial_port[i].irq);
up­>port.uartclk  = old_serial_port[i].baud_base * 16;
up­>port.flags    = old_serial_port[i].flags;
up­>port.hub6     = old_serial_port[i].hub6;
up­>port.membase  = old_serial_port[i].iomem_base;
up­>port.iotype   = old_serial_port[i].io_type;
up­>port.regshift = old_serial_port[i].iomem_reg_shift;
if (share_irqs)
up­>port.flags |= UPF_SHARE_IRQ;
}

Main functions in Serial_core.c
int uart_register_driver(struct uart_driver *drv)
This function registers a new UART driver with the driver pointer passed.  The uart_driver structure is declared in 
serial_core.h

Initially it allocates memory for the uart_state structure.  If it fails, it will free memory and quit. 
drv­>state = kmalloc(sizeof(struct uart_state) * drv­>nr, GFP_KERNEL);
retval = ­ENOMEM;
if (!drv­>state)
goto out;
 memset(drv­>state, 0, sizeof(struct uart_state) * drv­>nr);

Once the memory are set up with zeroes, it will allocate the tty drivers with the function struct tty_driver 
*alloc_tty_driver(int lines), as declared in tty_io.c. 
normal  = alloc_tty_driver(drv­>nr);
if (!normal)
goto out;

The tty_driver associated with the driver is then set up and saved.  
drv­>tty_driver = normal;

normal­>owner = drv­>owner;
normal­>driver_name = drv­>driver_name;
normal­>devfs_name = drv­>devfs_name;
normal­>name = drv­>dev_name;
normal­>major = drv­>major;
normal­>minor_start = drv­>minor;
normal­>type = TTY_DRIVER_TYPE_SERIAL;
normal­>subtype = SERIAL_TYPE_NORMAL;
normal­>init_termios = tty_std_termios;
normal­>init_termios.c_cflag = B9600 | CS8 | CREAD | HUPCL | CLOCAL;
normal­>flags = TTY_DRIVER_REAL_RAW | TTY_DRIVER_NO_DEVFS;
normal­>driver_state    = drv;
tty_set_operations(normal, &uart_ops);

/*
 * Initialise the UART state(s).
 */
for (i = 0; i < drv­>nr; i++) {
struct uart_state *state = drv­>state + i;

state­>close_delay     = 500; /* .5 seconds */
state­>closing_wait    = 30000; /* 30 seconds */

init_MUTEX(&state­>sem);
}

retval = tty_register_driver(normal);

int uart_add_one_port(struct uart_driver *drv, struct uart_port *port)
This function register the device port to the core uart structure.

It starts with setting up a uart_state struct. 

state = drv­>state + port­>line;

down(&port_sem);
if (state­>port) {
ret = ­EINVAL;
goto out;
}

state­>port = port;

spin_lock_init(&port­>lock);
port­>cons = drv­>cons;
port­>info = state­>info;

After this it will add the port to the core uart structure using  uart_configure_port(struct uart_driver *drv, struct 
uart_state *state, struct uart_port *port), as found in serial_core.c. This typically would give an initial Dmesg printout, 
indicating what ports have been set up. 
ttyS0 at MMIO 0xc8000000 (irq = 15) is a XScale
ttyS1 at MMIO 0xc8001000 (irq = 13) is a XScale

uart_configure_port(drv, state, port);

After this initial setup, it will register the device using void tty_register_device(struct tty_driver *driver, unsigned index, 
struct device *device) as found in tty_io.c as well as the console.

tty_register_device(drv­>tty_driver, port­>line, port­>dev);

if (port­>type != PORT_UNKNOWN &&
    port­>cons && !(port­>cons­>flags & CON_ENABLED))
register_console(port­>cons);
ADDITIONAL SERIAL DRIVER INIT FUNCTIONS
These functions, are used when additional serial drivers are initialized, using the serial_core system.  

Initially a structure need to be set up and filled in that describes the port to be registered. 

struct serial_struct serial_req;

serial_req.type        = PORT_16550;
serial_req.flags       = ASYNC_SKIP_TEST; 
serial_req.baud_base   = BASE_BAUD;
serial_req.irq         = irq;
serial_req.io_type     = UPIO_MEM;

#define UPIO_PORT (0)
#define UPIO_HUB6 (1)
#define UPIO_MEM (2)
#define UPIO_MEM32 (3)

serial_req.iomap_base = port;
serial_req.iomem_base  = port;
serial_req.iomem_reg_shift  = 0;

This structure us then passed to the function int register_serial(struct serial_struct *req) found in 8250.c.

Functions in 8250.c
int register_serial(struct serial_struct *req)
This function sets up a uart_port structure from the serial_struct that is used as an argument in the int 
serial8250_register_port(struct uart_port *port) function. 

return serial8250_register_port(&port);

int serial8250_register_port(struct uart_port *port)

This function first finds a port that is not used, and make it the next active port. 
uart = serial8250_find_match_or_unused(port);

It then sets up the port and register it using int uart_add_one_port(struct uart_driver *drv, struct uart_port *port)

if (uart) {
uart_remove_one_port(&serial8250_reg, &uart­>port);

uart­>port.iobase   = port­>iobase;
uart­>port.membase  = port­>membase;
uart­>port.irq      = port­>irq;
uart­>port.uartclk  = port­>uartclk;
uart­>port.fifosize = port­>fifosize;
uart­>port.regshift = port­>regshift;
uart­>port.iotype   = port­>iotype;
uart­>port.flags    = port­>flags | UPF_BOOT_AUTOCONF;
uart­>port.mapbase  = port­>mapbase;
if (port­>dev)
uart­>port.dev = port­>dev;

ret = uart_add_one_port(&serial8250_reg, &uart­>port);
if (ret == 0)
ret = uart­>port.line;
}

int uart_add_one_port(struct uart_driver *drv, struct uart_port *port)
This function first configures the port, as with the core serial ports. It will also display the port settings in Dmesg.
uart_configure_port(drv, state, port);

Then it register a tty device to this port.  

tty_register_device(drv­>tty_driver, port­>line, port­>dev);

Then if required it registers a console. 
/*
 * If this driver supports console, and it hasn't been
 * successfully registered yet, try to re­register it.
 * It may be that the port was not available.
 */
if (port­>type != PORT_UNKNOWN &&
    port­>cons && !(port­>cons­>flags & CON_ENABLED))
register_console(port­>cons);
FUNCTIONS ASOCIATED WITH THE OPENING OF A PORT
When transmitting a char the first thing that happens is the opening of the device. This is done with static int 
uart_open(struct tty_struct *tty, struct file *filp) defined in serial_core.c. 

Functions in serial_core.c

uart_open(struct tty_struct *tty, struct file *filp)
This function does a few tests to determine whether the port is not used. Once it is determined that it is free, it calls the 
static int uart_startup(struct uart_state *state, int init_hw) function in serial core.c Which sets up the UART registers, 
and interrupts. 

retval = uart_startup(state, 0);

After the UART us set up, it calls static int uart_block_til_ready(struct file *filp, struct uart_state *state)
which blocks until the UART is ready. 

retval = uart_block_til_ready(filp, state);

 When ready, it will set up the termios and return.

static int uart_startup(struct uart_state *state, int init_hw)
This function does a few tests to verify that the port can be opened. Once this is determined it a allocates transmit and 
tempory buffers. 

if (!info­>xmit.buf) {
page = get_zeroed_page(GFP_KERNEL);
if (!page)
return ­ENOMEM;
    
info­>xmit.buf = (unsigned char *) page;
uart_circ_clear(&info­>xmit);
}

After this it opens the function pointer to the startup function. The standard function being called by the function 
pointer is static int serial8250_startup(struct uart_port *port) defined in 8250.c 
retval = port­>ops­>startup(port);

It is then verified that the uart us up and active. If it is active, the hardware speed, and control signals are set up.  
if (retval == 0) {
if (init_hw) {
/*
 * Initialise the hardware port settings.
 */
uart_change_speed(state, NULL);

/*
 * Setup the RTS and DTR signals once the
 * port is open and ready to respond.
 */
if (info­>tty­>termios­>c_cflag & CBAUD)
uart_set_mctrl(port, TIOCM_RTS | TIOCM_DTR);
}
info­>flags |= UIF_INITIALIZED;
clear_bit(TTY_IO_ERROR, &info­>tty­>flags);
}

Once finished, the function returns.

Functions in 8250.c
 
static int serial8250_startup(struct uart_port *port)
This function does the physical low level setup of the UART registers. It writes values to these registers, verify it, clears 
the interrupts and check for validity. If it uses a real interrupt, it calls static int serial_link_irq_chain(struct 
uart_8250_port *up) defined in 8250.c

retval = serial_link_irq_chain(up);

Once it finishes the irq setup, it calls static void serial8250_set_mctrl(struct uart_port *port, unsigned int mctrl) defined 
in 8250.c, which sets up the MCR register.

Once everything is set up the interrupts are enabled.  

static int serial_link_irq_chain(struct uart_8250_port *up)
This function sets up the interrupts and call request_irq as specified in [1] chapter 3. 

Before setting up the lists, it sets up an irq_info pointer i, which points to the specific IRQ stored in he irq_lists 
structure. 
struct irq_info *i = irq_lists + up­>port.irq;

It then verifies whether this is a shared IRQ, and sets the flags accordingly. 
int ret, irq_flags = up­>port.flags & UPF_SHARE_IRQ ? SA_SHIRQ : 0;

If another IRQ are stored against this irq_info pointer, it will add the IRQ to this list. 
if (i­>head) {
list_add(&up­>list, i­>head);
spin_unlock_irq(&i­>lock);

ret = 0;
       }
     
Else it will add this IRQ to the irq_info registre, and request the IRQ from the kernel.  If it fails it will unlink the IRQ 
using static void serial_do_unlink(struct irq_info *i, struct uart_8250_port *up)
} else {
INIT_LIST_HEAD(&up­>list);
i­>head = &up­>list;
spin_unlock_irq(&i­>lock);

ret = request_irq(up­>port.irq, serial8250_interrupt,
  irq_flags, "serial", i);
if (ret < 0)
serial_do_unlink(i, up);
}

static void serial_do_unlink(struct irq_info *i, struct uart_8250_port *up)
This function unlink the IRQ from the IRQ list.
if (!list_empty(i­>head)) {
if (i­>head == &up­>list)
i­>head = i­>head­>next;
list_del(&up­>list);
} else {
BUG_ON(i­>head != &up­>list);
i­>head = NULL;
}
REFERENCE
[1] J.C. Alessandro, et.al. “Linux device drivers”, Third Ed. ISBN 0­596­00590­3
GNU Free Documentation License
Version 1.2, November 2002

Copyright (C) 2000,2001,2002  Free Software Foundation, Inc.
     51 Franklin St, Fifth Floor, Boston, MA  02110­1301  USA
 Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

0. PREAMBLE

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.

1. APPLICABILITY AND DEFINITIONS

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.

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.

2. VERBATIM COPYING

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.

3. COPYING IN QUANTITY
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.

4. MODIFICATIONS

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: 

A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions 
(which should, if there were any, be listed in the History section of the Document).  You may use the same title as a previous 
version if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the 
Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer 
than five), unless they release you from this requirement.
C. State on the Title page the name of the publisher of the Modified Version, as the publisher. 
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under 
the terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license 
notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, 
and publisher of the Modified Version as given on the Title Page.  If there is no section Entitled "History" in the Document, create 
one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the 
Modified Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise 
the network locations given in the Document for previous versions it was based on.  These may be placed in the "History" section.
You may omit a network location for a work that was published at least four years before the Document itself, or if the original
publisher of the version it refers to gives permission. 
K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,unaltered in their text and in their titles.  Section numbers or the 
equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements".  Such a sectionmay not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.

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.

5. COMBINING DOCUMENTS

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".

6. COLLECTIONS OF DOCUMENTS

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.

7. AGGREGATION WITH INDEPENDENT WORKS

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.

8. TRANSLATION

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.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License.  Any other 
attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this 
License.  However, parties who have received copies, or rights, from you under this License will not have their licenses terminated 
so long as such parties remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE

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.

ADDENDUM: How to use this License for your documents

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.2
    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.