Book review: FreeB­SD Device Dri­vers

In mid-April a woman from the mar­ket­ing depart­ment of No Starch Press con­tact­ed me and asked if I am inter­est­ed to do a pub­lic review of the FreeB­SD Device Dri­vers book by Joseph Kong (no link to a book shop, go and have a look in your pre­ferred one). Just this sim­ple ques­tion, no strings attached.

I had my nose in some device dri­vers in the past, but I nev­er wrote one, and nev­er had a look at the big pic­ture. I was inter­est­ed to know how every­thing fits togeth­er, so this made me a good vic­tim for a review (novice enough to learn some­thing new and to have a look if enough is explained, and expe­ri­enced enough to under­stand what is going on in the FreeB­SD ker­nel).

Some min­utes after I agreed to review it (but with a lit­tle notice that I do not know how long I need to review it), I had the PDF ver­sion of the book. That was faster than I expect­ed (maybe I am too old-school and used to have paper ver­sions of books in my hands).

Let the review begin… but bear with me, this is the first time I do a real pub­lic review of a book (instead of a tech­ni­cal review for an author). And as this is my very own per­son­al opin­ion, I will not allow com­ments here. This page is all about my opin­ion while read­ing the book, ques­tions I have while read­ing the book shall serve as a hint about the qual­i­ty of the book and they should be answered in the book, not here.

In short, the book is not per­fect, but it is a good book. There is room for improve­ment, but on a very high lev­el. If you want to write a device dri­ver for FreeB­SD, this book is a must. I sug­gest to read it com­plete­ly, even chap­ters which do not belong to the type of dri­ver you want to write (spe­cial­ly the case stud­ies of real dri­vers). The rea­son is that each chap­ter has some notes which may not only apply to the chap­ter in ques­tion, but to all kinds of device dri­vers. The long review fol­lows now.

The first chap­ter is titled “Build­ing and run­ning mod­ules”. The author begins with descrip­tion of the usu­al device dri­ver types (NIC dri­ver, pseudo-device, …) and how they can be added to the ker­nel (sta­t­i­cal­ly linked in or as a mod­ule). The first code exam­ple is a small and easy ker­nel mod­ule, so that we do not have to reboot the sys­tem we use to devel­op a dri­ver (except we make a fault dur­ing dri­ver devel­op­ment which caus­es the machine to pan­ic or hang). Every part of the exam­ple is well explained. This is fol­lowed by an overview about char­ac­ter devices (e.g. disks) and a sim­ple character-device dri­ver (so far a pseudo-device, as we do not have real hard­ware we access) which is not only as-well explained as the module-example, but there is also a note where the code was sim­pli­fied and what should be done instead.

After read­ing this chap­ter you should be able to write your own ker­nel mod­ule in 5 min­utes (well, after 5 min­utes it will not be able to do a lot – just a “hel­lo world” – but at least you can already load/unload/execute some code into/from/in the ker­nel).

I have not tried any exam­ple myself, but I com­piled a lot of mod­ules and dri­vers I mod­i­fied in the past and remem­ber to have seen the described parts.

The sec­ond chap­ter explains how to allo­cate and free mem­o­ry in the ker­nel. There is the pos­si­bil­i­ty to allo­cate maybe-contiguous mem­o­ry (the nor­mal case, when your hard­ware does not do DMA or does not have the require­ment that the mem­o­ry region it makes DMA from/too needs to be con­tigu­ous), and real­ly con­tigu­ous. For the size argu­ment of the free­ing of the the con­tigu­ous mem­o­ry there is the sen­tence “Gen­er­al­ly, size should be equal the amount allo­cat­ed.”. Imme­di­ate­ly I want­ed to know what hap­pens if you spec­i­fy a dif­fer­ent size (as a non-native eng­lish speak­er I under­stand this sen­tence in a way that I am allowed to spec­i­fy a dif­fer­ent size and as such are able to free only parts of the allo­cat­ed mem­o­ry). Unfor­tu­nate­ly this is not answered. I had a look into the source, the ker­nel frees mem­o­ry pages, so the size argu­ment (and addr argu­ment) will be round­ed to include a full page. This means the­o­ret­i­cal­ly I am able to free parts of the allo­cat­ed mem­o­ry, but this is a source-maintenance night­mare (needs knowl­edge about the machine spe­cif­ic page bound­aries and you need to make sure that you do the absolute­ly cor­rect size cal­cu­la­tions).  To me this looks more like as long as nobody is point­ing a gun at my head and tells me to use a dif­fer­ent size, spec­i­fy­ing the same size as made dur­ing the allo­ca­tion of this mem­o­ry region is the way to go.

After read­ing this chap­ter you should know how to kill the sys­tem by allo­cat­ing all the RAM in the ker­nel.

Again, I did not try to com­pile the exam­ples in this chap­ter, but the dif­fer­ence of the mem­o­ry allo­ca­tion in the ker­nel com­pared with mem­o­ry allo­ca­tion in the user­land is not that big.

The third chap­ter explains the device com­mu­ni­ca­tion and con­trol inter­faces (ioctl/sysctl) of a dri­ver. The ioctl part teached me some parts I always want­ed to know when I touched some ioctls, but nev­er both­ered to find out before. Unfor­tu­nate­ly this makes me a lit­tle bit ner­vous about the way ioctls are han­dled in the FreeB­SD lin­ux­u­la­tor, but this is not urgent ATM (and can prob­a­bly be han­dled by a com­mend in the right place). The sysctl part takes a lit­tle bit longer to fol­low through, but there is also more to learn about it. If you just mod­i­fy an exist­ing dri­ver with an exist­ing sysctl inter­face, it prob­a­bly just comes down to copy&paste with lit­tle mod­i­fi­ca­tions, but if you need to make more com­plex changes or want to add a sysctl inter­face to a dri­ver, this part of the book is a good way to under­stand what is pos­si­ble and how every­thing fits togeth­er. Per­son­al­ly I would have wished for a more detailed guide when to pick the ioctl inter­face and when the sysctl inter­face than what was writ­ten in the con­clu­sion of the chap­ter, but it is prob­a­bly not that easy to come up with a good list which fits most dri­vers.

After read­ing this chap­ter you should be able to get data in and out of the ker­nel in 10 min­utes.

As before, I did not com­pile the exam­ples in this chap­ter. I already added ioctls and sysctls in var­i­ous places in the FreeB­SD ker­nel.

Chap­ter 4 is about thread syn­chro­niza­tion – mutex­es, shared/exclusive locks, reader/writer locks and con­di­tion vari­ables. For me this chap­ter is not as good as the pre­vi­ous ones. While I got a good expla­na­tion of every­thing, I missed a nice overview table which com­pares the var­i­ous meth­ods of thread syn­chro­niza­tion. Bren­dan Gregg did a nice table to give an overview of DTrace vari­able types and when to use them. Some­thing like this would have been nice in this chap­ter too. Apart from this I got all the info I need (but hey, I already wrote a NFS client for an exper­i­men­tal com­put­er with more than 200000 CPUs in 1998, so I’m famil­iar with such syn­chro­niza­tion prim­i­tives).

Delayed exe­cu­tion is explained in chap­ter 5. Most of the infor­ma­tion pre­sent­ed there was new to me. While there where not much exam­ples pre­sent­ed (there will be some in a lat­er chap­ter), I got a good overview about what exists. This time there was even an overview when to use which type of delayed exe­cu­tion infra­struc­ture. I would have pre­ferred to have this overview in the begin­ning of the chap­ter, but that is maybe some kind of per­son­al pref­er­ence.

In chap­ter 6 a com­plete device dri­ver is dis­sect­ed. It is the vir­tu­al null modem ter­mi­nal dri­ver. The chap­ter pro­vides real-world exam­ples of event-handlers, call­outs and taskqueues which where not demon­strat­ed in chap­ter five. At the same time the chap­ter serves as a descrip­tion of the func­tions a TTY dri­ver needs to have.

Auto­mat­ed device detec­tion with New­bus and the cor­re­spond­ing resource allo­ca­tion (I/O ports, device mem­o­ry and inter­rupts) are explained in chap­ter 7. It is easy… if you have a real device to play with. Unfor­tu­nate­ly the chap­ter missed a para­graph or two about the sus­pend and resume meth­ods. If you think about it, it is not hard to come up with what they are sup­posed to do, but a lit­tle explic­it descrip­tion of what they shall do, in what state the hard­ware should be put and what to assume when being called would have been nice.

Chap­ter 8 is about inter­rupts. It is easy to add an inter­rupt han­dler (or to remove one), the hard part is to gen­er­ate an inter­rupt. The exam­ple code uses the par­al­lel port, and the chap­ter also con­tains a lit­tle expla­na­tion how to gen­er­ate an inter­rupt… if you are not afraid to touch real hard­ware (the par­al­lel port) with a resis­tor.

In chap­ter 9 the lpt(4) dri­ver is explained, as most of the top­ics dis­cussed so far are used inside. The expla­na­tion how every­thing is used is good, but what I miss some­times is why they are used. The most promi­nent (and only) exam­ple here for me is why are call­outs used to catch stray inter­rupts? That call­outs are a good way of han­dling this is clear to me, the big ques­tion is why can there be stray inter­rupts. Can this hap­pen only for the par­al­lel port (respec­tive­ly a lim­it­ed amount of devices), or does every dri­ver for real inter­rupt dri­ven hard­ware need to come with some­thing like this? I assume this is some­thing spe­cif­ic to the device, but a lit­tle expla­na­tion regard­ing this would have been nice.

Access­ing I/O ports and I/O mem­o­ry for devices are explained in chap­ter 10 based upon a dri­ver for a LED device (turn on and off 2 LEDs on an ISA bus). All the func­tions to read and write data are well explained, just the part about the mem­o­ry bar­ri­er is a lit­tle bit short. It is not clear why the CPU reorder­ing of mem­o­ry access­es mat­ter to what looks like func­tion calls. Those func­tion calls may be macros, but this is not explained in the text. Some lit­tle exam­ples when to use the bar­ri­ers instead of an abstract descrip­tion would also have been nice at this point.

Chap­ter 11 is sim­i­lar to chap­ter 10, just that a PCI bus dri­ver is dis­cussed instead of an ISA bus dri­ver. The dif­fer­ences are not that big, but impor­tant.

In chap­ter 12 it is explained how to do DMA in a dri­ver. This part is not easy to under­stand. I would have want­ed to have more exam­ples and expla­na­tions of the DMA tag and DMA map parts. I am also sur­prised to see dif­fer­ent sup­port­ed archi­tec­tures for the flags BUS_DMA_COHERENT and BUS_DMA_NOCACHE for dif­fer­ent func­tions. Either this means FreeB­SD is not coher­ent in those parts, or it is a bug in the book, or it is sup­posed to be like this and the rea­sons are not explained in the book. As there is no explic­it note about this, it prob­a­bly leads to con­fu­sion of read­ers which pay enough atten­tion here. It would also have been nice to have an expla­na­tion when to use those flags which are only imple­ment­ed on a sub­set of the archi­tec­tures FreeB­SD sup­ports. Any­way, the expla­na­tions give enough infor­ma­tion to under­stand what is going on and to be able to have a look at oth­er device dri­vers for real-live exam­ples and to get a deep­er under­stand­ing of this top­ic.

Disk dri­vers and block I/O (bio) requests are described in chap­ter 13. With this chap­ter I have a lit­tle prob­lem. The author used the word “unde­fined” in sev­er­al places where I as a non-native speak­er would have used “not set” or “set to 0”. The word “unde­fined” implies for me that there may be garbage inside, where­as from a tech­ni­cal point of view I can not imag­ine that some ran­dom val­ue in those places would have the desired result. In my opin­ion each such place is obvi­ous, so I do not expect that an expe­ri­enced pro­gram­mer would lose time/hairs/sanity over it, but inex­pe­ri­enced pro­gram­mers which try to assem­ble the cor­re­spond­ing struc­tures on the (unini­tial­ized) heap (for what­ev­er rea­son), may strug­gle with this.

Chap­ter 14 is about the CAM lay­er. While the pre­vi­ous chap­ter showed how to write a dri­ver for a disk device, chap­ter 14 gave an overview about how to an HBA to the CAM lay­er. It is just an overview, it looks like CAM needs a book on its own to be ful­ly described. The sim­ple (and most impor­tant) cas­es are described, with the hardware-specific parts being an exer­cise for the per­son writ­ing the device dri­ver. I have the impres­sion it gives enough details to let some­one with hard­ware (or pro­to­col), and more impor­tant­ly doc­u­men­ta­tion for this device, start writ­ing a dri­ver.

It would have been nice if chap­ter 13 and 14 would have had a lit­tle schemat­ic which describes at which lev­el of the kernel-subsystems the cor­re­spond­ing dri­ver sits. And while I am at it, a schemat­ic with all the dri­ver com­po­nents dis­cussed in this book at the begin­ning as an overview, or in the end as an annex, would be great too.

An overview of USB dri­vers is giv­en in chap­ter 15 with the USB print­er dri­ver as an exam­ple for the expla­na­tion of the USB dri­ver inter­faces. If USB would not be as com­plex as it is, it would be a nice chap­ter to start driver-writing exper­i­ments (due to the avail­abil­i­ty of var­i­ous USB devices). Well… bad luck for curi­ous peo­ple. BTW, the author gives point­ers to the offi­cial USB docs, so if you are real­ly curi­ous, feel free to go ahead. 🙂

Chap­ter 16 is the first part about net­work dri­vers. It deals with ifnet (e.g. stuff need­ed for ifcon­fig), ifme­dia (sim­pli­fied: which kind of cable and speed is sup­port­ed), mbufs and MSI(-X). As in oth­er chap­ters before, a lit­tle overview and a lit­tle pic­ture in the begin­ning would have been nice.

Final­ly, in chap­ter 17, the pack­et recep­tion and trans­mis­sion of net­work dri­vers is described. Large exam­ple code is bro­ken up into sev­er­al pieces here, for more easy dis­cus­sion of relat­ed infor­ma­tion.

One thing I miss after reach­ing the end of the book is a dis­cus­sion of sound dri­vers. And this is sure­ly not the only type of dri­vers which is not dis­cussed, I can come up with cryp­to, firewire, gpio, watch­dog, smb and iic devices with­in a few sec­onds. While I think that it is much more easy to under­stand all those dri­vers now after read­ing the book, it would have been nice to have at least a lit­tle overview of oth­er dri­ver types and maybe even a short descrip­tion of their dri­ver meth­ods.

Con­clu­sion: As I wrote already in the begin­ning, the book is not per­fect, but it is good. While I have not writ­ten a device dri­ver for FreeB­SD, the book pro­vid­ed enough insight to be able to write one and to under­stand exist­ing dri­vers. I real­ly hope there will be a sec­ond edi­tion which address­es the minor issues I had while read­ing it to make it a per­fect book.

Send to Kin­dle

More dri­vers avail­able in the FreeBSD-kernel doxy­gen docs

Yes­ter­day I com­mit­ted some more con­figs to gen­er­ate doxy­gen doc­u­men­ta­tion of FreeBSD-kernel dri­vers. I mechan­i­cal­ly gen­er­at­ed miss­ing con­figs for sub­di­rec­to­ries of src/sys/dev/. This means there is no depen­den­cy infor­ma­tion includ­ed in the con­figs, and as such you will not get links e.g. to the PCI doc­u­men­ta­tion, if a dri­ver calls func­tions in the PCI dri­ver (feel free to tell me about such depen­den­cies).

If  you want to gen­er­ate the HTML or PDF ver­sion of some sub­sys­tem, just go to src/tools/kerneldoc/subsys/ an run “make” to get a list of tar­gets to build. As an exam­ple, “make dev_sound” will gen­er­ate the HTML ver­sion for the sound sys­tem, “make pdf-dev_sound” gen­er­ates the PDF ver­sion. The sound sys­tem is prob­a­bly the most “nice” exam­ple, as it includes a page with TODO items, and has even some real API docs instead of just the call-graphs and such auto­mat­i­cal­ly gen­er­at­ed infor­ma­tion.

Some dri­vers already have (some) doxy­gen markup (I did just a quick grep for ‘/*[*!]’ to detect doxy­gen markup indi­ca­tors, no idea about the cov­er­age or qual­i­ty), name­ly:

There is more doc­u­men­ta­tion than only for those dri­vers, I just list­ed those as there are at least parts of doxy­gen doc­u­men­ta­tion inside.

Send to Kin­dle

The FreeBSD-linuxulator explained (for users)

After anoth­er mail where I explained a lit­tle bit of the lin­ux­u­la­tor behav­ior, it is time to try to make an easy text which I can ref­er­ence in future answers. If some­one wants to add parts of this expla­na­tion to the FreeB­SD hand­book, go ahead.

Lin­ux emu­la­tion? No, “native” exe­cu­tion (sort of)!

First, the lin­ux­u­la­tor is not an emu­la­tion. It is “just” a bina­ry inter­face which is a lit­tle bit dif­fer­ent from the FreeBSD-“native”-one. This means that the bina­ry files in FreeB­SD and Lin­ux are both files which com­ply to the ELF spec­i­fi­ca­tion.

When the FreeB­SD ker­nel loads an ELF file, it looks if it is a FreeB­SD ELF file or a Lin­ux ELF file (or some oth­er fla­vor it knows about). Based upon this it looks up appro­pri­ate actions in a table for this bina­ry (it can also dif­fer­en­ti­ate between 64-bit and 32-bit, and prob­a­bly oth­er things too).

The FreeBSD-table is always com­piled in (for a bet­ter big pic­ture: at least on an AMD/Intel 64-bit plat­form there is also the pos­si­bil­i­ty to include a 32-bit ver­sion of this table addi­tion­al­ly, to be able to exe­cute 32-bit pro­grams on 64-bit sys­tems), and oth­er ones like the Lin­ux one can be loaded addi­tion­al­ly into the ker­nel (or build sta­t­i­cal­ly in the ker­nel, if desired).

Those tables con­tain some para­me­ters and point­ers which allow to exe­cute the bina­ry. If a pro­gram is mak­ing a sys­tem call, the ker­nel will look up the cor­rect func­tion inside this table. It will do this for FreeB­SD bina­ries, and for Lin­ux bina­ries. This means that there is no emulation/simulation (over­head) going on… at least ide­al­ly. Some behav­ior is a lit­tle bit dif­fer­ent­ly between Lin­ux and FreeB­SD, so that a lit­tle bit of translation/house-keeping has to go on for some Lin­ux sys­tem calls for the under­ly­ing FreeB­SD ker­nel func­tions.

This means that a lot of Lin­ux stuff in FreeB­SD is han­dled at the same speed as if this Lin­ux pro­gram would be a FreeB­SD pro­gram.

Lin­ux file/directory tricks

When the ker­nel detects a Lin­ux pro­gram, it is also play­ing some tricks with files and direc­to­ries (also a prop­er­ty of the above men­tioned table in the ker­nel, so the­o­ret­i­cal­ly the ker­nel could play tricks for FreeB­SD pro­grams too).

If you look up for a file or direc­to­ry /A, the ker­nel will first look for /compat/linux/A, and if it does not find it, it will look for /A. This is impor­tant! For exam­ple if you have an emp­ty /compat/linux/home, any appli­ca­tion which wants to dis­play the con­tents of /home will show /compat/linux/home. As it is emp­ty, you see noth­ing. If this appli­ca­tion does not allow you to enter a direc­to­ry man­u­al­ly via the key­board, you have lost (ok, you can remove /compat/linux/home or fill it with what you want to have). If you can enter a direc­to­ry via the key­board, you could enter /home/yourlogin, this would first let the ker­nel look for /compat/linux/home/yourlogin, and as it can not find it then have a look for /home/yourlogin (which we assume is there), and as such would dis­play the con­tents of your home direc­to­ry.

This implies sev­er­al things:

  • you can hide FreeB­SD direc­to­ry con­tents from Lin­ux pro­grams while still being able to access the con­tent
  • bad­ly” pro­grammed Lin­ux appli­ca­tions (more cor­rect­ly: Lin­ux pro­grams which make assump­tions which do not hold in FreeB­SD) can pre­vent you from access­ing FreeB­SD files, or files which are the same in Lin­ux and FreeB­SD (like /etc/group which is not avail­able in /compat/linux in the linux_base ports, so that the FreeB­SD one is read)
  • you can have dif­fer­ent files for Lin­ux than for FreeB­SD

The Lin­ux user­land

The linux_base port in FreeB­SD is com­ing from a plain instal­la­tion of Lin­ux pack­ages. The dif­fer­ence is that some files are delet­ed, either because we can not use them in the lin­ux­u­la­tor, or because they exist already in the FreeB­SD tree at the same place and we want that the Lin­ux pro­grams use the FreeB­SD file (/etc/group and /etc/passwd come to mind). The instal­la­tion also marks bina­ry pro­grams as Lin­ux pro­grams, so that the ker­nel knows which kernel-table to con­sult for sys­tem calls and such (this is not real­ly nec­es­sary for all bina­ry pro­grams, but it is hard­er to script the cor­rect detec­tion log­ic, than to just “brand” all bina­ry pro­grams).

Addi­tion­al­ly some con­fig­u­ra­tions are made to (hope­ful­ly) make it do the right thing out of the box. The com­plete set­up of the linux_base ports is done to let Lin­ux pro­grams inte­grate into FreeB­SD. This means if you start acrore­ad or skype, you do not want to have to have to con­fig­ure some things in /compat/linux/etc/ first to have your fonts look the same and your user IDs resolved to names (this does not work if you use LDAP or ker­beros or oth­er direc­to­ry ser­vices for the user/group ID man­age­ment, you need to con­fig­ure this your­self). All this should just work and the appli­ca­tion win­dows shall just pop up on your screen so that you can do what you want to do. Some linux_base ports also do not work on all FreeB­SD releas­es. This can be because some ker­nel fea­tures which this linux_base ports depends upon is not avail­able (yet) in FreeB­SD. Because of this you should not choice a linux_base port your­self. Just go and install the pro­gram from the Ports Col­lec­tion and let it install the cor­rect linux_base port auto­mat­i­cal­ly (a dif­fer­ent FreeB­SD release may have a dif­fer­ent default linux_base port).

A note of cau­tion, there are instruc­tions out there which tell how to install more recent linux_base ports into FreeB­SD releas­es which do not have them as default. You do this on your own risk, it may or may not work. It depends upon which pro­grams you use and at which ver­sion those pro­grams are (or more tech­ni­cal­ly, which ker­nel fea­tures they depend upon). If it does not work for you, you just have two pos­si­bil­i­ties: revert back and for­get about it, or update your FreeB­SD ver­sion to a more recent one (but it could be the case, that even the most recent devel­op­ment ver­sion of FreeB­SD does not have sup­port for what you need).

Lin­ux libraries and “ELF file OS ABI invalid”-error mes­sages

Due to the above explained fact about file/directory tricks by the ker­nel, you have to be care­ful with (addi­tion­al) Lin­ux libraries. When a Lin­ux pro­gram needs some libraries, sev­er­al direc­to­ries (spec­i­fied in /compat/linux/etc/ are searched. Let us assume that the /compat/linux/etc/ spec­i­fies to search in /A, /B and /C. This means the FreeB­SD ker­nel first gets a request to open /A/libXYZ. Because of this he first tries /compat/linux/A/libXYZ, and if it does not exist he tries /A/libXYZ. When this fails too, the Lin­ux run­time link­er tries the next direc­to­ry in the con­fig, so that the ker­nel looks now for /compat/linux/B/libXYZ and if it does not exist for /B/libXYZ.

Now assume that libXYZ is in /compat/linux/C/ as a Lin­ux library, and in /B as a FreeB­SD library. This means that the ker­nel will first find the FreeB­SD library /B/libXYZ. The Lin­ux bina­ry which needs it can not do any­thing with this FreeB­SD library (which depends upon the FreeB­SD syscall table and FreeB­SD sym­bols from e.g. libc), and the Lin­ux run­time link­er will bail out because of this (actu­al­ly he sees that the lin is not of the required type by read­ing the ELF head­er of it). Unfor­tu­nate­ly the Lin­ux run­time link­er will not con­tin­ue to search for anoth­er library with the same name in anoth­er direc­to­ry (at least this was the case last time I checked and mod­i­fied the order in which the Lin­ux run­time link­er search­es for libraries… this has been a while, so he may be smarter now) and you will see the above error mes­sage (if you start­ed the lin­ux pro­gram in a ter­mi­nal).

The bot­tom line of all this is: the error mes­sage about ELF file OS ABI invalid just means that the Lin­ux pro­gram was not able to find the cor­rect Lin­ux library and got a FreeB­SD library instead. Go, install the cor­re­spond­ing Lin­ux library, and make sure the Lin­ux pro­gram can find it instead of the FreeB­SD library (do not for­get to run “/compat/linux/sbin/ldconfig ‑r /compat/linux” if you make changes by hand instead of using a port, else your changes may not be tak­en into account).

Con­straints regard­ing chroot into /compat/linux

The linux_base ports are designed to have a nice install-and-start expe­ri­ence. The draw­back of this is, that there is not a full Lin­ux sys­tem in /compat/linux, so doing a chroot into /compat/linux will cause trou­ble (depend­ing on what you want to do). If you want to chroot into the lin­ux sys­tem on your FreeB­SD machine, you bet­ter install a linux_dist port. A linux_dist port can be installed in par­al­lel to a linux_base port. Both of them are inde­pen­dent and as such you need to redo/copy con­fig­u­ra­tion changes you want to have in both envi­ron­ments.

Send to Kin­dle

Doxy­gen stuff updat­ed in 9‑current

I com­mit­ted my patch for tools/kerneldoc/subsys. Except for not gen­er­at­ing the PDF part, this is now the same con­fig which I use to gen­er­ate the online ver­sion. While writ­ing the com­mit log I noticed that I did more changes than I thought…

So any­one who wants to gen­er­ate the Doxy­gen docs of some FreeB­SD ker­nel sub­sys­tems on his own, can do it now. Adding more sub­sys­tems is easy, just make a copy of one the the exist­ing Doxyfile-* files – keep the same nam­ing scheme – and change the con­tents. Every­thing else is han­dled auto­mat­i­cal­ly.

I also added a link to the FreeB­SD wiki. It is not at a promi­nent place (near the end of the main page), but at least some­one can find the link to the my FreeB­SD-doxy­gen page there.

Send to Kin­dle

Dai­ly doxy­gen gen­er­at­ed docs of the FreeB­SD ker­nel (head)

I man­aged to get some time to set­up an auto­mat­ed gen­er­a­tion of the doxy­gen docs for ker­nel sub­sys­tems of FreeB­SD on my web­serv­er.

Every night/morning (Ger­man time­zone) the sources will be updat­ed, and the docs get regen­er­at­ed (this takes some time). Cur­rent­ly this depends upon some patch­es to the make­file and doxy­gen con­fig files in tools/kerneldoc/subsys. Every­thing is gen­er­at­ed direct­ly in the place where the web­serv­er will look for to deliv­er the pages, so if you browse this in the mid­dle of the gen­er­a­tion, the con­tent may not be con­sis­tent (yet).

Please be nice to the web­serv­er and do not mir­ror this. You can gen­er­ate this your­self very easy. Assum­ing you have the FreeB­SD source on a local hard disk, you just need to down­load the patch from (if you do not find dox.diff, update your FreeB­SD sources and every­thing will be OK), apply the patch, cd into tools/kerneldoc/subsys and run “make all” (or “make vm” or what­ev­er you are inter­est­ed in). You need doxy­gen installed, off course.

If you want to set­up some­thing like this your­self, just down­load the script which is doing all the work, change some vari­ables in the begin­ning, and cre­ate your own local ver­sion of the com­plete docs.

In case this is using sig­nif­i­cant traf­fic, I will ask core/admins if there is the pos­si­bil­i­ty to host it on resources.

Send to Kin­dle