It's that time again... The Gentoo/MIPS documentation is now at the stage it needs an overhaul. Things that have changed since the last overhaul: - Introduction of the `arcload` bootloader, for IP22, IP27, IP28, IP30, IP32 - I have some notes on how to do this... and so will be writing some docs on this soon. - Updates to the Cobalt netboot section - I plan to make new netboot images. Instead of distributing a raw kernel, I'll be packaging it with CoLo, and required boot scripts to rid the need of manual interaction with CoLo. - The mips64 profile -- for users running 64-bit kernels - This is important for 64-bit kernel users, as it emerges a 64-bit capable C compiler and binutils for building kernels. - The link for Octane port -- you'll find it at <http://www.linux-mips.org/~skylark/>. This needs to be changed in the Requirements page. If people have any other issues to be fixed... file them here. After my exams (my last exam is Next Friday, the 19th November), I'll start running through everything, cleaning up the grammar, tidying up everything, and fixing these problems that have slipped through the cracks. Then I'll pass the patches onto the docs-team (reassign the bug) to be committed.
Okay, the rewrite is mostly complete, there's just some minor things that need to be finalised, then the whole lot will be attached to this bug for inclusion into the official tree. Things that have changed... by section: - hb-mips-medium: Choosing the right installation medium... * Requirements has additional information added regarding MIPS32/64 CPUs. This is to answer the frequently asked question, "Why do the Cobalt stages b0rk on my mips32-based wireless router?" as well as to give people a clearer picture of the relationship between these CPU cores. * Cobalt Servers: Netboot instructions have been completely rewritten, with the advent of the newer netboot images. * A new LiveCD section has been added, for SGI users. - hb-mips-disk: Preparing the disks * Minor rewrites here... largely to cover the fact that only IP22/IP32 are able to use arcboot, and that arcload requires its kernels in the volume header (which needs to be sufficiently large enough to hold them) - hb-mips-stage: Installing the Gentoo Installation Files (NEW!!) This is a brand new section, based on the original generic section. Covered here, is information on which stages to use on which machines, and what CFLAGS are valid. - hb-mips-kernel: Configuring the Kernel * A note about ARCS64 machines gcc-mips64 and the mips64 profile has been added. * Machine-specific USE Flags (ip27, ip28, ip30, cobalt) are covered * Configuring the kernel; a number of avenues for gaining a .config file have been covered, including /proc/config.gz, the unofficial HCL, and the built-in default configs. (ip22_defconfig/ip32_defconfig/cobalt_defconfig) * Cross-compilation is now covered. * For O2 users: the vmlinux.32 makefile target is covered. - hb-mips-bootloader: Configuring the bootloader * arcload is now covered, as well as a note about which bootloaders support which machines. * CoLo section has been uploaded for CoLo 1.13 and above. * SGI PROM settings are now covered for each boot method. As I say, there's now just minor corrections to be made. (e.g. I just spotted one mistake with the LiveCD, which I will correct in just a moment)
Created attachment 74553 [details, diff] handbook-mips.xml update. 2 changes. Updates to handbook-mips.xml: + Updated my email address. + New MIPS-specific section on stages.
Created attachment 74554 [details, diff] hb-mips-bootloader.xml updates Bootloader updates, including a shiny new section on using arcload.
Created attachment 74555 [details, diff] hb-mips-disk.xml updates Partitioning update.
Created attachment 74556 [details, diff] hb-mips-kernel.xml updates Kernel section updates: + Now covers gcc-mips64, mips64 profile, and USE flags for kernels. + Other places to get .config settings.
Created attachment 74557 [details, diff] hb-mips-medium.xml updates Netboot updates: + Most notably, the Cobalt section has been rewritten.
Well... I haven't heard anything regarding things that need fixing. So I guess that means, docs-team... it's over to you. :-)
Could you fix your patches so that they do not undo changes, decrement version numbers or include non-existing parts? Thanks.
Woah there! This has definitely not been reviewed yet. How about giving us more than a day or two before you pull the trigger? I've been too busy the past week to really do anything except real life stuff, and I know hardave is in the same situation. I would prefer that these changes are not merged until we have all agreed they are correct.
Please assign to docs-team when you're all happy with the patches, and please do submit patches that can be used. Thanks.
Created attachment 74681 [details, diff] hb-mips-disk.xml updates Version number fix.
Created attachment 74682 [details, diff] hb-mips-kernel.xml updates Version number fix.
Created attachment 74683 [details, diff] hb-mips-medium.xml updates Version number fix.
Created attachment 74684 [details] New file: hb-install-mips-stage.xml This would be the "nonexistant" section I forgot to attach. :-) Take a look at the above patches, and let me know when things are ready to commit.
Created attachment 75905 [details, diff] handbook-mips.xml update + upstream changes
Created attachment 75906 [details, diff] hb-mips-bootloader.xml updates
Created attachment 75907 [details, diff] hb-mips-disk.xml updates
Created attachment 75908 [details, diff] hb-mips-kernel.xml updates
Created attachment 75909 [details, diff] hb-mips-medium.xml updates
Created attachment 77615 [details, diff] 000.handbook_handbook-mips.xml.diff - Upstream edits rolled in.
Created attachment 77617 [details, diff] 003.handbook_hb-install-mips-kernel.xml.diff - Further tweaks.
Created attachment 77618 [details, diff] 004.handbook_hb-install-mips-medium.xml.diff - Rearranged a few things... minor updates. Okay... further updates have been made. This should just about be all the issues nailed. A small note about these patches, seems I diffed a couple of them in the wrong directory, so they may need to be applied in en/handbook rather than en. Otherwise, everything should be set to commit. Can the MIPS team kindly review these updates (accessible via the URL above), and advise of any last-minute updates? I'd like to have this committed shortly, because maintaining my changes is becomming a hassle, not to mention directing confused newbies to the draft docs.
These are some suggestions I received in #gentoo-mips and thought might be worth mentioning in the docs. The following will probably be all Cobalt related. Chp 4: Promote the usage of ext3 (with index_dir which is already mentioned) over resier3 with respect to CPU usage. Chp 6: I had one heck of a time rsync'ing; always timed out. At least mention up'ing the RSYNC_TIMEOUT entry in make.conf or mention RSYNC_EXCLUDEFORM. I resorted to the latter to finally sync. Chp 5/6: Specifically for newbs coming from the x86/amd64 side, but perhaps a little mention of not using nptl and nptlonly would be helpful. Chp 7: A mention about Redhatter's kernel images would be nice: http://dev.gentoo.org/~redhatter/mips/cobalt/kernel-images Also, if there is documentation on distcc/crossdev, perhaps a comment about them would be helpful as well.
(In reply to comment #23) > These are some suggestions I received in #gentoo-mips and thought might be > worth mentioning in the docs. The following will probably be all Cobalt > related. > > Chp 4: Promote the usage of ext3 (with index_dir which is already mentioned) > over resier3 with respect to CPU usage. Bad idea. There are other filesystems which will be good for certain people in certain situations. > Chp 6: I had one heck of a time rsync'ing; always timed out. At least mention > up'ing the RSYNC_TIMEOUT entry in make.conf or mention RSYNC_EXCLUDEFORM. I > resorted to the latter to finally sync. This is probably only relevent on a per-user basis depending on the speed of their machine and link to the internet. Not really mips handbook worthy, in my opinion. Although, if there is a mention in the FAQ, it wouldn't bother me. Besides, if I recall, there should be a commented mention of this in the make.conf.example file which everyone has read thoroughly at least once...right? Right?? > Chp 5/6: Specifically for newbs coming from the x86/amd64 side, but perhaps a > little mention of not using nptl and nptlonly would be helpful. Irrelevent. The nptl USE flag is masked on mips, so you couldn't even attempt to build a nptl system if you tried. And then, if you unmasked said flag, and then tried to build glibc with NPTL and saw that the build failed, then that would be your own fault for unmasking something which was clearly masked for a reason. The use.mask file isn't there for our own amusement... > Chp 7: A mention about Redhatter's kernel images would be nice: > http://dev.gentoo.org/~redhatter/mips/cobalt/kernel-images No. These images will eventually make it to the correct spot on the mirrors. Links to netboot images on dev.gentoo.org do not belong in the manual. > Also, if there is documentation on distcc/crossdev, perhaps a comment about > them would be helpful as well. I'm pretty sure there is (new) documentation somewhere. A mention of this would be more suitable for a FAQ page.
>Bad idea. There are other filesystems which will be good for certain people in >certain situations. Indeed. However this was also tied in with the kernel images I mentioned below which lack reiser3 support. >This is probably only relevent on a per-user basis depending on the speed of >their machine and link to the internet. Exactly. I am coming from a Cobalt Qube2 install where speed is definately an issue. >No. These images will eventually make it to the correct spot on the mirrors. >Links to netboot images on dev.gentoo.org do not belong in the manual. That could be about the kernel images, I'm very new to mips. About the netboot images, since they are needed to boot the Qube, it would seem essential that they be at least mentioned seeing how booting the machine is the first step to an installation. Like I said, just some suggestions specifically for the Qube inserts. Some of them do seem more suitable to a FAQ however. Thanks.
I was thinking a bit more about Stephen Becker's comments regarding the make.conf.example. It is true that TIMEOUT and EXCLUDEFORM are both mentioned. However, the section for editing make.conf comes after the portage update section. Thus, I think my earlier suggestion is still reasonable.
There may be good reason for it, but the doc's lack any mention of hdparm. This section shows up in Chp2 of the x86 manual after Code Section 6.
(In reply to comment #27) > There may be good reason for it, but the doc's lack any mention of hdparm. This > section shows up in Chp2 of the x86 manual after Code Section 6. I've never needed to mess with hdparm on my Qube2, which is why it isn't covered. It's also known to not completely work with SCSI drives -- cobalt being the only machine we support which uses IDE disks.
(In reply to comment #28) > (In reply to comment #27) > > There may be good reason for it, but the doc's lack any mention of hdparm. This > > section shows up in Chp2 of the x86 manual after Code Section 6. > > I've never needed to mess with hdparm on my Qube2, which is why it isn't > covered. It's also known to not completely work with SCSI drives -- cobalt > being the only machine we support which uses IDE disks. > What about the sdparm utility? Works the exact same way as hdparm, but is specifically for SCSI/SATA drives. Any need to include sdparm in the MIPS docs, or is mucking with disk settings not recommended as it is in the other handbooks?
I can only speak for myself, but hdparm did boost my cached reads by twice. Unfortunately, I don't recall what I changed.
(In reply to comment #28) > (In reply to comment #27) > > I've never needed to mess with hdparm on my Qube2, which is why it isn't > covered. It's also known to not completely work with SCSI drives -- cobalt > being the only machine we support which uses IDE disks. hdparm is good really only for measuring transfer speeds on non-IDE disks via the -tT parameters. For cobalt, it can boost the drives from ~3-5MB/sec to 9-11mb/sec I've noticed once DMA and UltraDMA are both enabled (The controller can do UDMA4, but the utility maxes out at UDMA2 iirc). (In reply to comment #29) > > What about the sdparm utility? Works the exact same way as hdparm, but is > specifically for SCSI/SATA drives. Any need to include sdparm in the MIPS docs, > or is mucking with disk settings not recommended as it is in the other > handbooks? hdparm can enable/disable features, sdparm (from my limited usage) is more for tuning, as a scsi system generally is more dependnt on the hardware for speed (spindle speed, cabling, etc). There's probably things one can tune with it that makes it mimic some hdparm functionality, but I haven't played with it very in-depth to discover them all yet.
Blocking the 2006.0 tracker
Created attachment 79542 [details, diff] 002.handbook_hb-install-mips-bootloader.xml.diff - Changed in CVS -- upstream changes merged.
Created attachment 79543 [details, diff] 000.mips-requirements.xml.diff - Updated IP30 port page
Created attachment 79544 [details, diff] 000.mips-requirements.xml.diff - Updated IP30 port page (take #2) Ugh, and vim throws in a few tab chars... Okay, fixed.
Hi Shyam, I've just checked with the others ... the docs are all set to go live. :-) So it's over to you and the docs-team. (for real this time ;-) If there are any problems, let me know (either comment on this bug, or via IRC) and I'll fix it when I next have the chance. If one of the patches fails to apply, the full sources are available at: http://www.longlandclan.hopto.org/~stuartl/gentoo/docs/gentoo-doc/en/ Regards, Stuart Longland
Everything's in CVS. Big thank-you to Redhatter for the shiny new MIPS handbooks, good job. :)
Slight error on our part. Reopening to fix later.
Done. 2006.0 is out, handbook(s) are in CVS. Thanks guys!
