HACKING - vx32 - Local 9vx git repository for patches.
 (HTM) git clone git://r-36.net/vx32
 (DIR) Log
 (DIR) Files
 (DIR) Refs
       ---
       HACKING (2286B)
       ---
            1 Plan 9 VX Hacking Guide
            2 
            3 * Make
            4 
            5 For now, 9vx lives in the vx32 distribution, so it uses a somewhat
            6 involved build setup comprising multiple makefile fragments
            7 called Makefrags.  You shouldn't need to concern yourself with
            8 these except to remember to open "Makefrag" instead of "Makefile"
            9 and to run "make 9vx/9vx" in the src/ directory to build 9vx.
           10 The primary benefit of this arrangement is that if you edit
           11 a file anywhere in the tree (even in libvx32), make will know that
           12 9vx/9vx is out of date.
           13 
           14 
           15 * Source layout
           16 
           17 The files in the 9vx and 9vx/x11 directories are maintained by hand.
           18 The files in the other 9vx subdirectories (9vx/a, 9vx/libsec, etc.)
           19 are automatically generated from Plan 9 sources by applying simple
           20 ed scripts (named *.ed).  This simplifies incorporating new code from
           21 Plan 9, and also documents what the local changes are, so that
           22 there's some hope of pushing them back.  If someone would like to
           23 take these scripts and do the same to drawterm, I'd gladly accept 
           24 the result.  (If you don't know what drawterm is, don't worry about it.)
           25 The 1,000 lines of ed scripts substitute for maintaining 40,000 lines
           26 of imported code.  (If someone would like to convert drawterm to
           27 do this, please feel free.)
           28 
           29 Unless you're fiddling with x11 or Plan 9 itself, you should be able
           30 to restrict yourself to just editing files in this top directory.  
           31 The core of 9vx is the six files:
           32 
           33         main.c
           34         mmu.c
           35         sched.c
           36         time.c
           37         trap.c
           38         vx32.c
           39 
           40 These files total about 2500 lines.  I've tried to comment them pretty
           41 well, and you should try to understand them all before hacking on 9vx.
           42 If anything isn't clear, feel free to ask, so that I can update the comments.
           43 
           44 The *dev*.c files implement access to host resources.
           45 
           46 
           47 * Kernel changes
           48 
           49 The most pervasive change to the Plan 9 kernel in creating Plan 9 VX
           50 is that valid user addresses cannot simply be dereferenced in kernel mode.
           51 Instead they must be translated to sit relative to uzero, the base of the
           52 user address space.  (Early versions of 9vx used uzero=0, but too many
           53 operating systems had problems with mapping data at address 0.)
           54 Any code that casts a user address to a pointer or vice versa is wrong.
           55 I think I've caught them all, but I might have missed some in obscure
           56 code paths.
           57 
           58 
           59 Russ Cox
           60 rsc@swtch.com
           61 June 2008