diff -Nru /sys/man/9nix/adr /sys/man/9nix/adr --- /sys/man/9nix/adr Thu Jan 1 00:00:00 1970 +++ /sys/man/9nix/adr Sat Dec 29 00:00:00 2012 @@ -0,0 +1,133 @@ +.TH ADR 9 +.SH NAME +adr \- physical address map +.SH SYNOPSIS +.B cat '#P/adr' +.br +.de PB +.PP +.ft L +.nf +.. +.PB +#include "adr.h" +enum { + Anone, + Amemory, + Areserved, + Aacpireclaim, + Aacpinvs, + Aunusable, + Adisable, + + Aapic, + Apcibar, + Ammio, + Alast = Ammio, +}; +.PB +enum { + Mfree, + Mktext, + Mkpage, + Mupage, + Mvmap, + Mlast = Mvmap, +}; +.PB +.PD 0 +.ta +\w'\fL 'u +\w'\fL 'u +6n +4n +uintmem adralloc(uintmem base, uintmem len, int align, + int type, int use, uint flags) +.PB +void adrdump(void) +.PB +void adrinit(void) +.PB +void adrmapck(uintmem base, uintmem len, + int type, int use) +.PB +int adrmapenc(uintmem *base, uintmem *len, + int type, int use) +.PB +void adrmapinit(uintmem base, uintmem len, + int type, int use) +.PB +uint adrmemflags(uintmem pa) +.PB +void adrfree(uintmem base, uintmem len) +.PB +uintmem adrmemtype(uintmem pa, uintmem *len, + int *type, int *use) +.SH DESCRIPTION +The physical address map is managed by +.IR adr . +Map entries consist of a base, length address type +(e.g. memory, mmio, etc.), current use and +caching flags. The map is initlialized from the +.B *e820 +configuration variable (see +.IR plan9.ini (8)), +PCI mappings, ACPI and other memory-mapped +devices such as I/O APICs and LAPICs. Address ranges may +be allocated by address type; +.I adr +splits address ranges as necessary. Allocated maps +are indicated by a non- +.B Mfree +value of +.BR use . +When maps are freed, they are merged with adjacent +maps of the same address type. +.PP +The functions for accessing maps are as follows +.PP +.TP +.BI adralloc( base\fP,\fP\ len\fP,\fP\ align\fP,\fP\ type\fP,\fP\ use\fP,\fP\ flags ) +Allocate from existing memory maps with the given alignment. +A matching map must exist and be free, but will be split to fit +the allocation. The memory type for the range is set to +.IR type . +.TP +.B adrdump() +Dump all maps to the console for debugging. (See +.BR #P/adr .) +.TP +.B adrinit() +Set up the address map. This is called early in +.BR main . +.TP +.BI adrmapinit( base\fP,\fP\ len\fP,\fP\ type\fP,\fP\ use ) +Enter a new physical mapping to be entered into +the +.I adr +map. The map must not overlap existing maps. +.TP +.BI adrmapck( base\fP,\fP\ len\fP,\fP\ type\fP,\fP\ use ) +Ensure that the given map exists and is the correct type. +Correct the map if necessary. This is useful to work +around machines that do not reserve memory for I/O +APICs and such. +.TP +.BI adrfree( base\fP,\fP\ len ) +Delete the given mapping. +.TP +.BI adrmapenc( *base\fP,\fP\ *len\fP,\fP\ type\fP,\fP\ use ) +Find the enclosing map, and convert it to the type and use. +Return 0 if successful, and -1 otherwise. +.TP +.BI adrmemtype( pa\fP,\fP\ *len\fP,\fP\ *type\fP,\fP\ *use ) +Find the enclosing map, and return the base address. Also +return the size, type, and use, if the corresponding pointers +are not nil. +.TP +.BI adrmemflags( pa ) +Return the memory flags for the enclosing region. This +is used by +.IR vmap (9nix) +to maintain consistent caching flags. +.SH SOURCE +.B /sys/src/nix/k10/adr.c +.SH "SEE ALSO" +.IR plan9.ini (8), +.IR vmap (9nix). diff -Nru /sys/man/9nix/physalloc /sys/man/9nix/physalloc --- /sys/man/9nix/physalloc Thu Jan 1 00:00:00 1970 +++ /sys/man/9nix/physalloc Sat Dec 29 00:00:00 2012 @@ -0,0 +1,45 @@ +.TH PHYSALLOC 9 +.SH NAME +physalloc, physfree, phystag, physinit, physallocdump \- kernel buddy allocator for physical addresses +.SH SYNOPSIS +.ta \w'\fLuintmem 'u +.de PB +.PP +.ft L +.nf +.. +.PB +void physinit(uintmem pa, u64int size) +.PB +uintmem physalloc(u64int size, int *colorp, void *tag) +.PB +void* phystag(uintmem pa) +.PB +void physfree(uintmem pa, u64int size) +.PB +char* seprintphysstats(char *s, char *e) +.SH DESCRIPTION +The kernel contains a buddy allocator to hand out large chunks of +memory outside the kernel heap. The buddy allocator does not +assign virtual addresses. The map is populated by one or more calls to +.IR physinit . +.I Physalloc +allocates a region of the given color with the given tag. If the color +is -1, then any memory color may be used, otherwise only memory +of the given color will be allocated. The +.B tag +is user-defined. Calls to +.I phystag +map addresses in the allocation back to +.BR tag . +Allocated regions are freed with +.IR physfree . +Stats may be put in a buffer with +.IR seprintstats , +which takes a pointer to a buffer and its end as +.IR seprint . +.SH SOURCE +.B /sys/src/nix/k10/physalloc.c +.SH "SEE ALSO" +.IR adr (9nix), +.IR qmalloc (9nix), diff -Nru /sys/man/9nix/qmalloc /sys/man/9nix/qmalloc --- /sys/man/9nix/qmalloc Thu Jan 1 00:00:00 1970 +++ /sys/man/9nix/qmalloc Sat Dec 29 00:00:00 2012 @@ -0,0 +1,184 @@ +.TH QMALLOC 9 +.SH NAME +qmalloc \- quickfit malloc +malloc, mallocz, smalloc, realloc, calloc, free, msize, setmalloctag, setrealloctag, getmalloctag, getrealloctag, mallocinit, mallocsummary \- quickfit kernel memory allocator +.SH SYNOPSIS +.ta \w'\fLvoid* 'u +.B +void* malloc(usize size) +.PP +.B +void* mallocalign(usize size, usize align, long offset, usize span) +.PP +.B +void* mallocz(usize size, int clr) +.PP +.B +void* smalloc(usize size) +.PP +.B +void* realloc(void *p, usize size) +.PP +.B +void* calloc(ulong n, usize szelem) +.PP +.B +void free(void *ptr) +.PP +.B +ulong msize(void *ptr) +.PP +.B +void setmalloctag(void *ptr, ulong tag) +.PP +.B +ulong getmalloctag(void *ptr) +.PP +.B +void setrealloctag(void *ptr, ulong tag) +.PP +.B +ulong getrealloctag(void *ptr) +.PP +.B +void mallocinit(void) +.B +void mallocsummary(void) +.PP +.SH DESCRIPTION +These are kernel versions of the functions in +.IR malloc (2). +They allocate memory with Quickfit with an allocator +from Kernighan & Ritchie. +The allocation is currently fixed, but could call +.IR physalloc (9nix) +in the future. +All but +.I smalloc +(which calls +.IR sleep (9)) +may safely be called by interrupt handlers. +.PP +.I Malloc +returns a pointer to a block of at least +.I size +bytes, initialised to zero. +The block is suitably aligned for storage of any type of object. +The call +.B malloc(0) +returns a valid pointer rather than null. +.I Mallocz +is similar, but only clears the memory if +.I clr +is non-zero. +.PP +.I Smalloc +returns a pointer to a block of +.I size +bytes, initialised to zero. +If the memory is not immediately available, +.I smalloc +retries every 100 milliseconds until the memory is acquired. +.PP +.I Mallocalign +allocates a block of at least +.I n +bytes of memory respecting alignment contraints. +If +.I align +is non-zero, +the returned pointer is aligned to be equal to +.I offset +modulo +.IR align . +If +.I span +is non-zero, +the +.I n +byte block allocated will not span a +.IR span -byte +boundary. +.PP +.I Realloc +changes the size of the block pointed to by +.I p +to +.I size +bytes, +if possible without moving the data, +and returns a pointer to the block. +The contents are unchanged up to the lesser of old and new sizes, +and any new space allocated is initialised to zero. +.I Realloc +takes on special meanings when one or both arguments are zero: +.TP +.B "realloc(0,\ size) +means +.LR malloc(size) ; +returns a pointer to the newly-allocated memory +.TP +.B "realloc(ptr,\ 0) +means +.LR free(ptr) ; +returns null +.TP +.B "realloc(0,\ 0) +no-op; returns null +.PD +.PP +.I Calloc +returns a pointer to a block of memory of at least +.I "n*szelem" +bytes, initialised to zero. +New code should use +.I mallocz +instead. +.PP +The argument to +.I free +is a pointer to a block of memory allocated by one of the routines above, which +is returned to the allocation pool, or a null pointer, which is ignored. +.PP +When a block is allocated, sometimes there is some extra unused space at the end. +.I Msize +grows the block to encompass this unused space and returns the new number +of bytes that may be used. +.PP +The memory allocator does not maintain ``malloc tag'' and the ``realloc tag'', +but the functions +.IR setmalloctag , +.IR getmalloctag , +.IR setrealloctag , +and +.IR getrealloctag +are provided for compaibility with the +.IR pool (2) +library. +.PP +.I Mallocinit +must be called before +.I malloc +is used. +.I Mallocsummary +prints a short summary of the allocator's state on the console. +.SH SOURCE +.B /sys/src/9/port/qmalloc.c +.br +.B /sys/src/nix/port/qmalloc.c +.SH DIAGNOSTICS +All functions except +.I smalloc +return a null pointer if space is unavailable. +.SH SEE ALSO +.IR "The C Programming Language" , +2ed, Brian Kernighan and Dennis Ritchie, +chapter 8 §7: Example—Storage Allocator. +.br +.I "Quickfit: An efficient algorithm" +.I for heap storage allocation" , +Charles B. Weinstock and William A. Wulf. +ACM SIGPLAN Notices, 23(10):141—144, October 1988. +.br +.IR pool (2), +.IR physalloc (9nix) diff -Nru /sys/man/9nix/vmap /sys/man/9nix/vmap --- /sys/man/9nix/vmap Thu Jan 1 00:00:00 1970 +++ /sys/man/9nix/vmap Sat Dec 29 00:00:00 2012 @@ -0,0 +1,72 @@ +.TH VMAP 9 +.SH NAME +vmap. vmappat \- physical to virtual mapping +.SH SYNOPSIS +.de PB +.PP +.ft L +.nf +.. +#include "fns.h" +.PB +enum { + PATUC = 0, /* uncachable */ + PATWC = 1, /* use write-combining buffers */ + PATWT = 4, /* write-through */ + PATWP = 5, /* write protect */ + PATWB = 6, /* write back */ + PATUCMINUS = 7, /* UC-; strongly uncacheable */ +}; +.PB +.PD 0 +.ta +\w'\fL 'u +\w'\fL 'u +6n +4n +void* vmap(uintmem base, usize size) +.PB +void* vmappat(uintmem base, usize size, uint pattype) +.PB +void vunmap(void*) +.PB +int vmapsync(uintmem addr) +.SH DESCRIPTION +.I Vmap +creates and returns a virtual address for the physical +address +.I base +on the local processor. +The most common use for this is to map PCI BARs. +.PP +The actual map may be larger than the requested size +if the base is not smallest page-aligned or the size is +not a multiple of the smallest page size. It is an error +to map the same region of memory twice, but overlap +is calculated before rounding to smallest page size. +It is also an error to map an unknown region. +The default +memory type is uncachable memory, or +.BR PATUC . +But +.I vmappat +allows the memory type to be user-selected. +.PP +If the new map is accessed on another processor +it will fault. +.I Fault +can restore the mapping with +.IR vmapsync , +which returns 0 if a matching map is found and +restored, and -1 otherwise. +.SH SOURCE +.B /sys/src/nix/*/mmu.c +.SH "SEE ALSO" +.IR adr (9nix) +.SH DIAGNOSTICS +.I Vmap +and +.I Vmappat +return +.B nil +on failure. +.I Vmapsync +returns -1 if no map is found. +.SH BUGS +PAT is x86- and x86-64-specific. --- /sys/man/2/types Sat Jan 5 18:19:09 2013 +++ /sys/man/2/types Sat Jan 5 00:00:00 2013 @@ -0,0 +1,147 @@ +.TH TYPES 2 +.SH NAME +types \- c type system +.SH SYNOPSIS +.BR char , +.BR short , +.BR int , +.BR vlong +.PP +.BR uchar , +.BR ushort , +.BR uint , +.BR uvlong +.PP +.BR u8int , +.BR u16int , +.BR u32int , +.BR u64int +.PP +.B Rune +.PP +.BR usize , +.BR uintptr +.PP +.B uintmem +.PP +.B schar +.SH DESCRIPTION +The Plan 9 C compilers and system use a specialization of the C99 type system, +which has evolved over time. +The compilers are unsigned preserving, and +.B char +can be assumed to be a signed value. +Although the system currently makes heavy use of +.BR ulong +to represent exactly-32-bit integers and pointers as unsigned +integers, this practice is no longer supportable with the advent of +true 64-bit compilers. Having a more explicit type set permits us to +be more specific about intent and is helpful to maintain portability +to other systems, especially Plan 9 from User Space. +.PP +The basic 8, 16, 32 and 64-bit types are +.BR char , +.BR short , +.BR int , +and +.BR vlong. +Conventionally, unsigned types simply prepend a "u" to the basic type name rather +than using the +.B unsigned +prefix. +.PP +Most programs will need no more integer types than this. Exceptions +come in two forms: the need to be specific about use to aid in +porting, and type widths fixed by hardware or protcols. +The system call interface does not fit the second case since the compiler +itself will pick the same sizes for both kernel and user space. +.PP +To specify an integer of a particular width, the form +.BI u bits int +is used. Types for 8, 16, 32, and 64 bit-width specific unsigned +integers are available. There are no signed variants of these as they +are not useful where size-specific types are appropriate. As a +special case, +.B uchar +is assumed to be equivalent to +.BR u8int . +Beware of using size-specific integers in a structure as a marshalling +technique. The compiler is free to pad the structure and endian +conversion can easily be forgotten. Consider using a structure +of basic types (typically uchar) marshalled with functions as in +.IR getbe (2). +.PP +The +.B Rune +type stands alone. It holds a single unicode codepoint as +described in +.IR rune (2) +and +.IR utf (6). +.PP +The use-specific types are +.B usize +and +.BR uintptr . +.B Usize +represents the type returned by the C +.B sizeof +operator. It is typically the same width as a virtual address. +In order to ease the transition to 64-bits, the AMD64 compiler +currently uses a 32-bit +.BR usize . +An integer representation of a virtual-address pointer is represented by the type +.BR uintptr . +.PP +The kernel additionally needs to specify a type to represent a +physical address. Since physical addresses may be the same size, +larger (PAE) or smaller than virtual addresses, +.B uintmem +as a physical address may be the same size, larger (PAE), or smaller than a virtual address. +.B Uintmem +also stores the sizes of things that +.B uintmem +might address. +.PP +Finally, +.B schar +is used when porting to other systems where it may matter. It should not generally be used. +.SH EXAMPLES +The C library has a number of functions which are in need +of conversion. For example, +.IP +.EX +void* malloc(usize nbytes); +int segfree(void *va, usize len); +uintptr getcallerpc(void*); +.EE +.PP +A device driver might access a 32-bit register with +.IP +.EX +u32int regval; + +regval = regbase[regoff/4]; +.EE +.PP +In the kernel we could convert between physical and virtual addresses +this way: +.IP +.EX +uintmem upaddr(uintptr kva); +uintptr upaddr(uintmem pa); +.EE +.PP +The actual functions use +.B void* +for kernel addresses. +.SH "SEE ALSO" +.IR 8c (1), +.IR getbe (2), +.IR rune (2), +.IR utf (6), +.br +Plan 9 from User Space, +.B http://swtch.com/plan9port +.SH BUGS +The spirit of the original type system has faded with time. --- /sys/man/2/atom Sat Jan 5 19:44:03 2013 +++ /sys/man/2/atom Wed Oct 7 00:00:00 2009 @@ -0,0 +1,113 @@ +.TH ATOM 2 +.SH NAME +ainc, adec, cas, cas32, cas64, casp, casl, loadlink, storecond, _tas \- atomic RMW operations +.SH SYNOPSIS +.B #include +.br +.B #include +.PP +.B +long ainc(long *addr); +.PP +.B +long adec(long *addr); +.PP +.B +int cas32(u32int *addr, u32int ov, u32int nv); +.PP +.B +int cas64(u64int *addr, u64int ov, u64int nv); +.PP +.B +int cas(int *addr, int ov, int nv); +.PP +.B +int casp(void **addr, void *ov, void *nv); +.PP +.B +int casl(ulong *addr, ulong ov, ulong nv); +.PP +.B +int _tas(ulong *addr); +.PP +.B +ulong loadlink(ulong*); +.PP +.B +int storecond(ulong*, ulong); +.SH DESCRIPTION +.I Ainc +atomically increments the value pointed to by +.I addr +and returns the new value. +.PP +.I Adec +atomically decrements the value pointed to by +.I addr +and returns the new value. +.PP +.IR Cas , +.IR cas32 , +.IR cas64 , +.IR casp , +and +.I casl +implement +.I Compare-and-Swap +on, respectively, +.IR int , +.IR u32int , +.IR u64int , +.IR void* , +and +.IR ulong +values. The availability of these functions depends on the +\s-2CPU\s0 architecture: Pentium III and later, as well as AMD64 +have 64-bit CAS instructions. Other architectures don't. +ARM-5 processors and earlier do not have CAS (nor have they +.I Load-Linked +or +.I Store-Conditional ). +These instructions are, however, emulated by the Plan 9 kernel. +All other architectures have 32-bit CAS. +.PP +.I _tas +implements +.IR Test-and-Set , +which is available on all architectures and used for the implementation +of kernel locks +(see +.IR lock (2) +and +.IR thread (2)). +.PP +.I Loadlink +and +.I Storecond +access the +.I load-linked +and +.I store-conditional +instructions present on MIPS (LL/SC), ARM (Strex/Ldrex), PowerPC (LWAR/STWCCC), Alpha (MOVLL, MOVLC). +These are not present on Pentium or AMD64. +.PP +On the architectures that have +.I load-linked +and +.IR store-conditional , +these are used to implement +.IR compare-and-swap . +.SH SOURCE +.B /sys/src/libc/*/atom.s +.br +.B /sys/src/libc/*/tas.s +.SH SEE ALSO +.IR semacquire (2), +.IR lock (2), +.IR thread (2) +.SH DIAGNOSTICS +The CAS functions, +.IR _tas , +and +.I storecond +return 0 for failure and 1 for success.