Contributing to OGP

T. Miller Jun 06:since we're working on OGD1 right now, the discussions have a distinct bias towards the hardware-design aspects of the project(...)Lots of people with varied levels of hardware knowledge on this list have been invaluable in helping to collect information and ideas together and put it into a form that is digestible to the general population, as well as helping us hardware engineers keep organised and focused on our jobs. Other things we can use help with include web development. Experts have contributed some great stuff, but you could assist them. There's research that can be done on all sorts of things (legal, marketing, technical, etc.). We have a software model of the 3D graphics engine; some more work needs to be done to make the ideas in it transparent to other people, particularly those who will write drivers.

Documentation and Website

T. Miller (jun 06):We can use help with include web development. Experts have contributed some great stuff, but you could assist them.

Wiki

Lots of people with varied levels of hardware knowledge on this list have been invaluable in helping to collect information and ideas together and put it into a form that is digestible to the general population, as well as helping us hardware engineers keep organised and focused on our jobs.

Documentation for OGP will also include the condition that Traversal is permitted to copy and re-use at their discretion any of the Documentation for OGP. This is to assist Traversal producing Official Documentation so that they can concentrate more of their energies on Graphic Card Development.

Documenting the Mailing List
JB (Jun 06): The wiki needs constant updating. This is full of small jobs where someone with attention to detail is valuable. Quite a few pages need small things eg:The OGP in the news page probably would benefit from adding more recent links in the newsletters.

A Volunteer could also document in the wiki topics that were covered in the newsgroups - This can make a difference for open source projects and improve documentation. The developers don't always have time to work out how to write it down, but a wiki entry is easy to review and correct. With some mailing lists, occasionally you see a post onto the end of a discussion with a note that the info was added to their wiki and includes a link. The Open Graphics project can also be helped by someone watching the lists and adding bits to the wiki - you could put their name, the date and add a link to the mailing list if possible. This is not a huge job, or a highly technical one but will really help. The wiki guys can keep an eye out for you.

To obtain a login account, our Wiki requires new users to provide a working email address so we can send a link to activate your account. We find this small hurdle helps greatly in preventing spam or Vandals. We want to commend and encourage volunteers helping with the Open Graphics Project Wiki. For those wanting to lean how to use Tiki wiki markup, Tikiwiki documentation can be found at http://doc.tikiwiki.org. The sandbox is here

Hints for Editing the Wiki

• If you use Firefox, there is an extension called View Source With, which allows you to open form field with an external editor. This works with our wiki, too. Any editor which opens a new window and don't "fork" itself, should work.
• For the newsletters. Assuming you use and editor which supports regex search-and-replace, you can add the colour coding of the quotes in one command. E.g. the vim-command is ":%s/^;:\(.*\)/;:__\~\~#880000:__\~\~/c".

Wiki Formatting Examples
When preparing a newsletter, quotes from the mailing list are colored and block-indented.

• Prepending a line with ";:" will apply a block indentation, valid for a single line (until the next line break).
• The color is applied using "~~#880000:" which specifies the color of the text, until terminated with another "~~".
• Enclosing the text with leading and trailing "__" will indicate a bold font, making the colored text easier to read.

Thus, a colored quote would be:

";:~~#880000: __ This is the quote. __~~ "

As can be expected, there are caveats: the formatting does not carry nicely across line breaks. Because of this, it is necessary to apply the formatting for each paragraph individually, as paragraphs are indicated using a line break. Because of the block indent, this results in large spaces between paragraphs. Unfortunately, we haven't yet found a way to deal with this.

In some cases, it is possible to format lines as a list. The list cannot be block indented, but the indentation of the text due to the bullets lines up with the block indentation, so that it is passable. In this case, the coloring is applied to the whole list, and the bold to each item.

The result is:

~~#880000:
* __This example of using color quotes __
* __when dealing with a list __
* __provides a bold dark red group of numbers or bullets __
~~

Further Reading: http://doc.tikiwiki.org/tiki-index.php?page=Wiki+Syntax

Verilog Tutorials
Already we have some helping by adding the Verilog Tutorials. You could assist with wiki formatting and adding further comments from the Mailing list and even some links for further reading.

OGD1 Documentation

Jb (Jun 06): Pin outs: Timothy has provided the latest revG schematic and started the pin out list. The hardware programmers would appreciate a list of what goes where for when they stop with the simulations and assign the pins for real.

As soon as the new Bill of Materials is listed with the new Xilinx chip, we want some list references and details in the wiki, and this will help with the pin out list.

• OGD1

Artwork

We will be needing artwork for Manuals, packaging and our website.

• OGP Artwork

Research

There's research that can be done on all sorts of things (legal, marketing, technical, etc.). Post to the list if you have an interest in these.

Open Hardware Foundation

We founded a non-profit foundation that handled, among other things, donations used to buy OGD1 boards for developers who will help us with the graphics engine work. This role has been taken over by the Linux Fund who are helping us build 10 developer boards.

http://www.linuxfund.org/projects/ogd1/
Open Hardware Foundation (historical information)

Software

Subversion Commit Policy
Documentation
We have a software model of the 3D graphics engine; some more work needs to be done to make the ideas in it transparent to other people, particularly those who will write drivers.

Drivers

Are you a programmer? We need drivers for ODG1
Timothy has put out a call for 4 or 5 driver writers who would be willing to help with the following pieces of software for OGD1, OGC1, etc We will soon be having the programming interfaces soon, and are looking for those who are interested.

* VGA BIOS
* Linux kernel driver
* Linux fbconsole driver
* Linux DRI driver
* X11 DDX module
* Mesa driver (later than the others)

Those that volunteer will be lent OGD1 cards. Most likely, those who check in (significant) working code will get their loans made permanent. Those willing to volunteer should post to the list. This is a serious card so this may be an opportunity to get ahold of some excellent hardware. Source OGPN12
Timothy: State in the code that it is multi licensed. Joshua: The kernel driver, the fbconsole driver, and the dri driver should all be GPL (in hopes of being made part of the mainline kernel tree someday), but that doesn't stop the code from being dual licensed, which is what some people do when they want their code to be kept in both Linux and NetBSD.Source OGPN12

The current plan is for these to be using a license which freely allows commercial and non commercial use such as a BSD license. We want to encourage developers to freely share tips, methods and concepts for volunteers writing a driver for their favourite operating system. Timothy (Jun 06): I am going to recommend that drivers and such be licensed under MIT and BSD licenses. (...) If it needs to be converted to GPL for the purposes of inclusion in like the Linux kernel, I have no problem with that.


Dieter (Jun 06): Device drivers will be needed for *BSD, OS-X, Plan9, Linux, ...Preferably with most of the code being common across all OSes.

T. Miller (Jun 06): (regarding writing drivers) Andy's version of the simulator does a better job of assigning numbers to registers.


some random comments: It is important that the code used as a reference is functionally correct. It will be easier to debug the logic in the simulator, and there's also potential for making an actual driver out of it and using various other cards as a dumb frame buffer. We could also use a shared memory space and start up a second X server on this virtual device and have the results displayed in a window on the main X session.

Wine

We use Xilinx and Lattice software for our design. There are programs used for our project that are available free of cost, but for Windows only. Some of these do install on Wine but there are a number of problems with using Wine. If you can code in C, improving Wine is an advanced task that can help our project developers who prefer to use Linux. Post to the list if you are interested in helping as our developers may already have some suggestions for you. Yes there is a version for Xilinx for Linux, but it has a bit of development to go yet and because it is not open source we cant improve it. However, we can improve Wine which helps those using the version released for Windows.

• ispLEVER Starter under Wine
• www.winehq.org

Test Software
Howard (Jun 06) (...We will need...) test code that will be run on a PC and run a suite of tests that check memory, video, prom, etc. Traditionally, these are tests written in C and run under DOS, but this will probably change for OGD1. (...) The tests that are written would have to be general in nature, maybe using the COTS graphics card already in the developers machine.

Hardware Programming

hardware programming is in some ways inside-out compared to software programming. For instance, with software, brevity in source code often translates into small machine code. But with chips, you have to be elaborate and detailed. Oh, and going from thinking serially to thinking in parallel can be tough. (You might want to get good at pthreads as a stepping stone.) We have some tutorials at present to help those who would want to learn. We are using Verilog at present and code is accepted through the Mailing list.

Hardware Software for OGP is under a dual license. This allows Traversal to use the software for OGP so as to make money, which is hoped to help us with developing more boards. For License Details Please check the source code.

RTL started for ODG1 in May/June 2006. If you want to help out you are welcome.

Contributing Code
Development_Tools
Introduction to Verilog - tutorial.
Naming Conventions - Coding Guideline

Verilog Documentation:
JB (Jun 06):If you wanted to document for new ones how to use the open source option of Icarus Verilog and GTKWave for writing and testing Verilog - there is a really good start. (we can help with editing the wiki if needed). You certainly would help those coming from windows , or ones wanting to abandon windows.

Development_Tools
Contributing Code


OGP and Traversal Number Log Generation
J. Carroll (jun 06): I'm not looking for a piece of software _at this time_. I think jb is probably right that a suitable piece of software can help maintain consistency and reduce duplication when we need to assign document numbers and stock numbers, but the amount of that kind of work facing us right now is easy to handle manually.

• OGP Number Log

(This has been listed as it could be a future task.)