Greg Troxel wrote: > "Kamil Rytarowski" <[email protected]> writes: > > >> Also, "happy" doesn't seem like a useful name; examples should have > >> names that suggest the kinds of things they do with respect to the > >> module system, to guide people choosing which ones to read. > > > > Well, I like /dev/happy for Happy Number generator. What would be the > > better name? > > random_generator? The point is that someone looking at examples does > not care what particular generator you are using; the point is about the > glue code. It would be fair, arguably better, to have a "random > generator" that emits sequential numbers. Anything other than module > glue is a distraction. >
For this reason, I took one of the simplest integral sequences and for the joy of math I would like to stick to it. It's common to use existing algorithms in basic examples. like Fibonacci numbers, primes etc. http://www.home.unix-ag.org/bmeurer/NetBSD/howto-lkm.html uses Fibonacci. Personally I have a reason to not use it in my patch, I will eventually unveil why after a month or so. Thanks! > >> > I like it. Maybe place them in `share/examples/kmodules'? > >> > >> share/examples/sys/modules would be better; kmodules is not the name of > >> a program in base and would be confusing to someone expecting examples > >> to be about programs in base. > > > > kmodule was inspired by (/usr/share/mk/)bsd.kmodule.mk and it was so > > natural for me to pick up this name. Maybe share/examples/sys/kmodule? > > I am ok with sys/kmuodules (if this is mis-installed in share/examples). > Therefore share/examples/sys/kmodules (plural form)? > > I'm improving this single example adding to it 4 additional modules and > > README. There is no revolution, except moving the original example to a > > new location. > > So why not just example-foo, example-bar, etc. > Modules named 'example' in a directory 'examples' aren't verbose to me (is it a pleonasm?). I'm listing them in README this way: * hello - the simplest `hello world' module * properties - handle incoming properties during the module load * happy - basic implementation of read(9) with happy numbers * ping - basic ioctl(9) * hellolua - the simplest `hello world' Lua module The description of what they do is in the README file, not embedded in their names. I designed it minimal and funny (doing something quasi-functional) for each case :) It's a matter of taste, but a module dots with device /dev/dots printing ".\n" would be enough too, but (to me) boring. With happy numbers people can play a bit with it, easily change the algorithm to something else (like redefining happy (1) and sad number (4)) and checking results just for the fun of experimenting with read(4). > > I'm trying to improve the documentation and add more enlightening examples > > for newcomers (like myself!). > > > I'm aware of the fact that experienced kernel programmers familiar with > > NetBSD internals know how to handle all kinds of things, dependencies and > > for them following 'ab uno disces omnis' (single example just parsing the > > parameters) is sufficient. > > > Please let it be easier for people starting to hack in the kernel from > > the modules (people like me) and not assuming they mastered the kernel > > internals. > > That's great that you are spiffin gup docs and I didn't mean to be > critical of it. I just meant that 1) examples belong in the source tree > 2) example name should be about the kind of function and 3) examples > should have minimal semantic distraction besides their glue functions. > So for example a fs transformation module could be gzip or just > rot13, with just barely enough code to see that it is doing something, > and a generator could just return 0, 1, 2, 3, 4, etc. enough that you > can tell it is working. > I understood your argument. I plan to rediff and send my new patch tomorrow.
