Kernel operations

What a program can ask the kernel: 29 operations. The parameters and the result of each are the words of the comment of the contract: "(parameters) -> result", then its text; the contract has no other form of them.

Number	Operation	Parameters	Result	What the contract says
0	`None`
1	`Log`	log, address, count, level, channel 0, channel 1		write one text on the log. The channel is 16 bytes in two values.
2	`Memory_Create`	budget, page_count, Memory_Flags	memory handle	The memory is zero. The budget pays now for each page. A page gets its page frame at its first use (a page on first use), or now with Frames_Now. An access to the memory never fails for lack of memory.
3	`Memory_Map`	memory, program or 0 for self, address or 0, Map_Flags, first page, page_count or 0 for all	address
4	`Memory_Unmap`	program or 0, address
5	`Memory_Size`	memory	page_count
6	`Program_Create`	budget, name address, name count	program handle	The program has no memory and no handle. The budget pays for the program, for its page tables and for its first thread.
7	`Program_Start`	program, entry address, stack address, context address		the first thread of the program.
8	`Program_Stop`	program or 0 for self, code
9	`Program_State`	program, address of a Stop_Report or 0	Program_State, code, kernel entries of the program	With an address, the kernel writes the Stop_Report of the program there.
10	`Handle_Give`	target: program handle, memory handle, or 0 for this program; handle; Rights	the handle in the target program	The new handle has the rights of the handle that are also in Rights: a grant never adds a right. With a memory handle, the target is the other program that maps this memory: the other side of a ring. If no other program maps it, the target is the one other program that holds a handle to it. The kernel keeps, with the new handle, the memory object that it came through (Handle_State).
11	`Handle_Close`	handle		The kernel stops a program when its last handle closes.
12	`Interrupt_Read`	interrupt	the number of interrupts since the last read
13	`Device_Create`	machine, Device_Kind, a, b	handle	Ports: a = first port, b = count. Interrupt: a = line. Memory: a = physical address, b = page count: the registers of a device, as a memory object that a program maps with no cache. The kernel refuses addresses of the memory that it manages. Message: an interrupt that a device sends as a write to the interrupt controller (MSI-X). The results are the handle, then the address and the value that the device must write.
14	`Inspect`	machine, Inspect_Kind, index, address, size	bytes written
15	`Machine_Stop`	machine, code
16	`Thread_Create`	budget, entry address, stack address, parameter, weight, request	thread handle	A new thread of this program. The thread starts at the entry with the parameter in the first register. The weight (1 to WEIGHT_FULL; 0 is WEIGHT_FULL) and the request (microseconds, 1 to REQUEST_LIMIT; 0 is REQUEST_DEFAULT) are for the strategies that use them (Strategy). A weight can only be lower than the weight of a thread with 0.
17	`Thread_Stop`	thread or 0 for self		A program with no thread stops.
18	`Thread_State`	thread	Program_State: Ready, Waiting or Stopped	The word wait: the one way to wait for something else than a time. A thread waits while each word of a list holds its value. The kernel names a word by its page frame, so two programs that map one memory object can use one word.
19	`Word_Wait`	address of Word records, count		the wait of this entry ends when a Word_Wake names one of these words, or at its deadline. If a word does not hold its value, the wait ends at once. One entry can wait on WORD_WAIT_CAPACITY words.
20	`Word_Wake`	address, count	threads woken: wake at most count threads that wait on this word
21	`Budget_Create`	budget, pages, programs, threads, processor, log_records	budget handle	See Budget_Amounts.
22	`Budget_Read`	budget	pages, programs, threads: what the budget can still pay; processor, log_records: its limits; the microseconds of processor time that it used since it was made; the log records that the kernel refused
23	`Handle_State`	handle, memory or 0	Object_Kind, Rights, 1 if the handle came through this memory object, the count of the holdings that came from this handle	A program that receives the number of a handle from another program, in a ring, proves with this operation that the other program gave the handle through that ring. Without the proof, the other program can name a handle that the receiver holds for itself.
24	`Handle_Revoke`	handle, program or 0	the count of holdings that ended	A holding is a handle or a mapping. The origin of a handle that Handle_Give made is the handle that was given. The origin of a mapping is the memory handle that was mapped. When a handle closes, what came from it comes from its origin. Handle_Revoke ends each holding that came from the handle, in one program (a handle with the right Control) or in each program, and what came from those holdings in any program. The handle stays, and the mappings of the program that revokes stay. A program that lost a holding gets an event. A thread that uses memory that its program lost stops its program on a page fault.
25	`Memory_Physical`	machine, memory	the physical address of the first page of a memory object that was created Contiguous, or of device memory: its pages follow each other in physical memory and do not move	Another memory object gives Bad_Operation. A device service gives these addresses to its device: the device reads and writes the memory with no processor (direct memory access). Needs the right Physical on the machine.
26	`Program_Module`	program or 0 for self, address of a Module_Record		the module record of a module that a loader put in the program. A record with the base of a record that exists replaces it; with the size 0 it removes it. The kernel does not read the module: the record is what the loader asserts. The kernel names the module of the address of a fault with it, and Inspect gives the records (Module_Report).
27	`Strategy_Set`	machine, Strategy	the strategy before	The scheduling strategy of the machine changes while it runs: no thread stops, none is lost. The state of the strategy of each thread starts from zero (docs/SCHEDULING.md). Needs the right Schedule on the machine. The virtual memory of a program (docs/ARCHITECTURE.md, "The virtual memory of a program").
28	`Memory_Commit`	memory, budget or 0, address of a table of Page_Range, count, Commit_Flags	pages changed	The pages of the ranges of an object made with Uncommitted become committed: the budget pays one page for each, and each gets a frame at its first use. The budget handle must name the budget of the object, with the right Commit or Spend (the right Write on the object does not spend the budget of its maker; to let another program commit, give it the object and a budget handle with Commit only). With Decommit, the committed pages of the ranges are no longer paid: their frames and their pages return at once to the budget of the object, and a page committed again is zero; the budget argument is not read. The ranges are in increasing order and do not overlap; at most RANGE_TABLE_CAPACITY, and RANGE_TABLE_PAGE_LIMIT pages. Needs the right Write on the object. Decommit needs an object that only this program names, with one mapping at most. A table that the budget cannot pay changes nothing.
29	`Memory_Protect`	address of a table of Address_Range, count, Map_Flags	pages changed	The protection of the pages of mappings of this program: Read only (no flag), Write, Execute, or No_Access. It can only take away what the mapping was made with (Bad_Operation); Write and Execute together are refused. A range inside a mapping, not its whole, takes away from the protection of the mapping now (it cannot get more: Bad_Operation), and needs an object with a frame list that only this program names, with one mapping; while a part has its own protection, the object is not mapped again and not given (Bad_State). At most RANGE_TABLE_PAGE_LIMIT pages. Each processor that runs a thread of the program forgets the old translations before the operation returns (one shoot-down).

Read from contract/operation/operation.odin.

The status of a completion

Number	Status	What the contract says
0	`Ok`
1	`Bad_Operation`
2	`Bad_Handle`
3	`Bad_Address`
4	`No_Memory`
5	`No_Slot`
6	`Bad_State`
7	`No_Right`	The handle names the object, but it does not have the right for this operation.
8	`No_Budget`	The budget cannot pay for the operation.

Read from contract/operation/operation.odin.