--- Gnu-Mach/doc/mach.info-1 2020/09/02 04:46:44 1.1.1.1 +++ Gnu-Mach/doc/mach.info-1 2020/09/02 04:49:14 1.1.1.2 @@ -1,9 +1,9 @@ -This is mach.info, produced by makeinfo version 5.1 from mach.texi. +This is mach.info, produced by makeinfo version 5.2 from mach.texi. This file documents the GNU Mach microkernel. - This is edition 0.4, last updated on 27 September 2013, of 'The GNU -Mach Reference Manual', for version 1.4. + This is edition 0.4, last updated on 10 April 2015, of 'The GNU Mach +Reference Manual', for version 1.5. Copyright (C) 2001, 2002, 2006, 2007, 2008 Free Software Foundation, Inc. @@ -45,8 +45,8 @@ Main Menu This file documents the GNU Mach microkernel. - This is edition 0.4, last updated on 27 September 2013, of 'The GNU -Mach Reference Manual', for version 1.4. + This is edition 0.4, last updated on 10 April 2015, of 'The GNU Mach +Reference Manual', for version 1.5. Copyright (C) 2001, 2002, 2006, 2007, 2008 Free Software Foundation, Inc. @@ -150,6 +150,7 @@ Port Manipulation Interface * Receive Rights:: How to work with receive rights. * Port Sets:: How to work with port sets. * Request Notifications:: How to request notifications for events. +* Inherited Ports:: How to work with the inherited system ports. Virtual Memory Interface @@ -1291,6 +1292,15 @@ are typed. Each item has a type descrip of the message. The field must carry a send right, a send-once right, 'MACH_PORT_NULL', or 'MACH_PORT_DEAD'. + 'unsigned long msgh_protected_payload' + The 'msgh_protected_payload' field carries a payload that is + set by the kernel during message delivery. The payload is an + opaque identifier that can be used by the receiver to lookup + the associated data structure. + + It is only valid in received messages. See *note Message + Receive:: for further information. + 'mach_port_seqno_t msgh_seqno' The 'msgh_seqno' field provides a sequence number for the message. It is only valid in received messages; its value in @@ -1367,6 +1377,7 @@ bits. 'MACH_MSG_TYPE_STRING' 'MACH_MSG_TYPE_STRING_C' 'MACH_MSG_TYPE_PORT_NAME' + 'MACH_MSG_TYPE_PROTECTED_PAYLOAD' The following predefined types specify port rights, and receive special treatment. The next section discusses these @@ -1382,6 +1393,11 @@ bits. 'MACH_MSG_TYPE_MAKE_SEND' 'MACH_MSG_TYPE_MAKE_SEND_ONCE' + The type 'MACH_MSG_TYPE_PROTECTED_PAYLOAD' is used by the + kernel to indicate that a delivered message carries a payload + in the 'msgh_protected_payload' field. See *note Message + Receive:: for more information. + 'msgt_size : 8' The 'msgt_size' field specifies the size of each datum, in bits. For example, the msgt_size of @@ -1880,6 +1896,24 @@ then 'msgh_local_port' specifies 'MACH_P still exists, but isn't held by the caller, then 'msgh_local_port' specifies 'MACH_PORT_NULL'. + Servers usually associate some state with a receive right. To that +end, they might use a hash table to look up the state for the port a +message was sent to. To optimize this, a task may associate an opaque +PAYLOAD with a receive right using the 'mach_port_set_protected_payload' +function. Once this is done, the kernel will set the +'msgh_protected_payload' field to PAYLOAD when delivering a message to +this right and indicate this by setting the local part of 'msgh_bits' to +'MACH_MSG_TYPE_PROTECTED_PAYLOAD'. + + The support for protected payloads was added to GNU Mach. To +preserve binary compatibility, the 'msgh_local_port' and +'msgh_local_port' share the same location. This makes it possible to +add the payload information without increasing the size of +'mach_msg_header_t'. This is an implementation detail. Which field is +valid is determined by the local part of the 'msgh_bits'. Existing +software is not affected. When a receive right is transferred to +another task, its payload is cleared. + Received messages are stamped with a sequence number, taken from the port from which the message was received. (Messages received from a port set are stamped with a sequence number from the appropriate member @@ -2105,6 +2139,7 @@ ports, port rights and port sets. * Receive Rights:: How to work with receive rights. * Port Sets:: How to work with port sets. * Request Notifications:: How to request notifications for events. +* Inherited Ports:: How to work with the inherited system ports.  File: mach.info, Node: Port Creation, Next: Port Destruction, Up: Port Manipulation Interface @@ -2663,6 +2698,40 @@ File: mach.info, Node: Receive Rights, server (normally the kernel), the call may return 'mach_msg' return codes. + -- Function: kern_return_t mach_port_set_protected_payload + (ipc_space_t TASK, mach_port_t NAME, unsigned long PAYLOAD) + The function 'mach_port_set_protected_payload' sets the protected + payload associated with the right NAME to PAYLOAD. Section *note + Message Receive:: describes how setting a protected payload affects + the messages delivered to NAME. + + The function returns 'KERN_SUCCESS' if the call succeeded, + 'KERN_INVALID_TASK' if TASK was invalid, 'KERN_INVALID_NAME' if + NAME did not denote a right and 'KERN_INVALID_RIGHT' if NAME + denoted a right, but not a receive right. + + The 'mach_port_set_protected_payload' call is actually an RPC to + TASK, normally a send right for a task port, but potentially any + send right. In addition to the normal diagnostic return codes from + the call's server (normally the kernel), the call may return + 'mach_msg' return codes. + + -- Function: kern_return_t mach_port_clear_protected_payload + (ipc_space_t TASK, mach_port_t NAME, unsigned long PAYLOAD) + The function 'mach_port_clear_protected_payload' clears the + protected payload associated with the right NAME. + + The function returns 'KERN_SUCCESS' if the call succeeded, + 'KERN_INVALID_TASK' if TASK was invalid, 'KERN_INVALID_NAME' if + NAME did not denote a right and 'KERN_INVALID_RIGHT' if NAME + denoted a right, but not a receive right. + + The 'mach_port_clear_protected_payload' call is actually an RPC to + TASK, normally a send right for a task port, but potentially any + send right. In addition to the normal diagnostic return codes from + the call's server (normally the kernel), the call may return + 'mach_msg' return codes. +  File: mach.info, Node: Port Sets, Next: Request Notifications, Prev: Receive Rights, Up: Port Manipulation Interface @@ -2712,7 +2781,7 @@ File: mach.info, Node: Port Sets, Next return codes.  -File: mach.info, Node: Request Notifications, Prev: Port Sets, Up: Port Manipulation Interface +File: mach.info, Node: Request Notifications, Next: Inherited Ports, Prev: Port Sets, Up: Port Manipulation Interface 4.3.8 Request Notifications --------------------------- @@ -2803,6 +2872,76 @@ File: mach.info, Node: Request Notifica 'mach_msg' return codes.  +File: mach.info, Node: Inherited Ports, Prev: Request Notifications, Up: Port Manipulation Interface + +4.3.9 Inherited Ports +--------------------- + +The inherited ports concept is not used in the Hurd, and so the _SLOT +macros are not defined in GNU Mach. + + The following section documents how 'mach_ports_register' and +'mach_ports_lookup' were originally intended to be used. + + -- Function: kern_return_t mach_ports_register (task_t TARGET_TASK, + port_array_t INIT_PORT_SET, int INIT_PORT_ARRAY_COUNT) + -- Function: kern_return_t mach_ports_lookup (task_t TARGET_TASK, + port_array_t *INIT_PORT_SET, int *INIT_PORT_ARRAY_COUNT) + 'mach_ports_register' manipulates the inherited ports array, + 'mach_ports_lookup' is used to acquire specific parent ports. + TARGET_TASK is the task to be affected. INIT_PORT_SET is an array + of system ports to be registered, or returned. Although the array + size is given as variable, the kernel will only accept a limited + number of ports. INIT_PORT_ARRAY_COUNT is the number of ports + returned in INIT_PORT_SET. + + 'mach_ports_register' registers an array of well-known system ports + with the kernel on behalf of a specific task. Currently the ports + to be registered are: the port to the Network Name Server, the port + to the Environment Manager, and a port to the Service server. + These port values must be placed in specific slots in the + init_port_set. The slot numbers are given by the global constants + defined in 'mach_init.h': 'NAME_SERVER_SLOT', 'ENVIRONMENT_SLOT', + and 'SERVICE_SLOT'. These ports may later be retrieved with + 'mach_ports_lookup'. + + When a new task is created (see 'task_create'), the child task will + be given access to these ports. Only port send rights may be + registered. Furthermore, the number of ports which may be + registered is fixed and given by the global constant + 'MACH_PORT_SLOTS_USED' Attempts to register too many ports will + fail. + + It is intended that this mechanism be used only for task + initialization, and then only by runtime support modules. A parent + task has three choices in passing these system ports to a child + task. Most commonly it can do nothing and its child will inherit + access to the same INIT_PORT_SET that the parent has; or a parent + task may register a set of ports it wishes to have passed to all of + its children by calling 'mach_ports_register' using its task port; + or it may make necessary modifications to the set of ports it + wishes its child to see, and then register those ports using the + child's task port prior to starting the child's thread(s). The + 'mach_ports_lookup' call which is done by 'mach_init' in the child + task will acquire these initial ports for the child. + + Tasks other than the Network Name Server and the Environment + Manager should not need access to the Service port. The Network + Name Server port is the same for all tasks on a given machine. The + Environment port is the only port likely to have different values + for different tasks. + + Since the number of ports which may be registered is limited, ports + other than those used by the runtime system to initialize a task + should be passed to children either through an initial message, or + through the Network Name Server for public ports, or the + Environment Manager for private ports. + + The function returns 'KERN_SUCCESS' if the memory was allocated, + and 'KERN_INVALID_ARGUMENT' if an attempt was made to register more + ports than the current kernel implementation allows. + + File: mach.info, Node: Virtual Memory Interface, Next: External Memory Management, Prev: Inter Process Communication, Up: Top 5 Virtual Memory Interface @@ -3208,14 +3347,14 @@ File: mach.info, Node: Mapping Memory O memory exception. TARGET_TASK is the task to be affected. The starting address is - ADDRESS. If the ANYWHERE option is used, this address is ignored. - The address actually allocated will be returned in ADDRESS. SIZE - is the number of bytes to allocate (rounded by the system in a - machine dependent way). The alignment restriction is specified by - MASK. Bits asserted in this mask must not be asserted in the - address returned. If ANYWHERE is set, the kernel should find and - allocate any region of the specified size, and return the address - of the resulting region in ADDRESS. + ADDRESS. If the ANYWHERE option is used, this address is used as a + starting hint. The address actually allocated will be returned in + ADDRESS. SIZE is the number of bytes to allocate (rounded by the + system in a machine dependent way). The alignment restriction is + specified by MASK. Bits asserted in this mask must not be asserted + in the address returned. If ANYWHERE is set, the kernel should + find and allocate any region of the specified size, and return the + address of the resulting region in ADDRESS. MEMORY_OBJECT is the port that represents the memory object: used by user tasks in 'vm_map'; used by the make requests for data or @@ -4557,7 +4696,7 @@ their priority from their task and their -- Function: kern_return_t thread_priority (thread_t THREAD, int PRORITY, boolean_t SET_MAX) The function 'thread_priority' changes the priority and optionally - the maximum priority of THREAD. Priorities range from 0 to 31, + the maximum priority of THREAD. Priorities range from 0 to 49, where lower numbers denote higher priorities. If the new priority is higher than the priority of the current thread, preemption may occur as a result of this call. The maximum priority of the thread @@ -4568,7 +4707,7 @@ their priority from their task and their The functions returns 'KERN_SUCCESS' if the operation completed successfully, 'KERN_INVALID_ARGUMENT' if THREAD is not a thread or - PRIORITY is out of range (not in 0..31), and 'KERN_FAILURE' if the + PRIORITY is out of range (not in 0..49), and 'KERN_FAILURE' if the requested operation would violate the thread's maximum priority (thread_priority). @@ -4582,7 +4721,7 @@ their priority from their task and their The functions returns 'KERN_SUCCESS' if the operation completed successfully, 'KERN_INVALID_ARGUMENT' if THREAD is not a thread or PROCESSOR_SET is not a control port for a processor set or PRIORITY - is out of range (not in 0..31), and 'KERN_FAILURE' if the thread is + is out of range (not in 0..49), and 'KERN_FAILURE' if the thread is not assigned to the processor set whose control port was presented.  @@ -5025,6 +5164,17 @@ File: mach.info, Node: Task Information -- Data type: task_thread_times_info_t This is a pointer to a 'struct task_thread_times_info'. + -- Function: kern_return_t task_set_name (task_t TARGET_TASK, + kernel_debug_name_t NAME) + + The function 'task_set_name' sets the name of TARGET_TASK to NAME, + truncating it if necessary. + + This is a debugging aid. The name is used in diagnostic messages + printed by the kernel. + + The function returns 'KERN_SUCCESS' if the call succeeded. +  File: mach.info, Node: Task Execution, Next: Task Special Ports, Prev: Task Information, Up: Task Interface @@ -6482,254 +6632,3 @@ File: mach.info, Node: Device Status, written and 'D_NO_SUCH_DEVICE' if DEVICE does not denote a device port or the device is dead or not completely open. - -File: mach.info, Node: Device Filter, Prev: Device Status, Up: Device Interface - -10.8 Device Filter -================== - - -- Function: kern_return_t device_set_filter (device_t DEVICE, - mach_port_t RECEIVE_PORT, - mach_msg_type_name_t RECEIVE_PORT_TYPE, int PRIORITY, - filter_array_t FILTER, mach_msg_type_number_t FILTER_COUNT) - The function 'device_set_filter' makes it possible to filter out - selected data arriving at or leaving the device and forward it to a - port. FILTER is a list of filter commands, which are applied to - incoming data to determine if the data should be sent to - RECEIVE_PORT. The IPC type of the send right is specified by - RECEIVE_PORT_RIGHT, it is either 'MACH_MSG_TYPE_MAKE_SEND' or - 'MACH_MSG_TYPE_MOVE_SEND'. The PRIORITY value is used to order - multiple filters. - - There can be up to 'NET_MAX_FILTER' commands in FILTER. The actual - number of commands is passed in FILTER_COUNT. For the purpose of - the filter test, an internal stack is provided. After all commands - have been processed, the value on the top of the stack determines - if the data is forwarded or the next filter is tried. - - The first command is a header which contains two fields: one for - flags and the other for the type of interpreter used to run the - rest of the commands. - - Any combination of the following flags is allowed but at least one - of them must be specified. - - 'NETF_IN' - The filter will be applied to data received by the device. - - 'NETF_OUT' - The filter will be applied to data transmitted by the device. - - Unless the type is given explicitly the native NETF interpreter - will be used. To select an alternative implementation use one of - the following types: - - 'NETF_BPF' - Use Berkeley Packet Filter. - - For the listener to know what kind of packet is being received, - when the filter code accepts a packet the message sent to - RECEIVE_PORT is tagged with either NETF_IN or NETF_OUT. - - Each word of the command list specifies a data (push) operation - (high order NETF_NBPO bits) as well as a binary operator (low order - NETF_NBPA bits). The value to be pushed onto the stack is chosen - as follows. - - 'NETF_PUSHLIT' - Use the next short word of the filter as the value. - - 'NETF_PUSHZERO' - Use 0 as the value. - - 'NETF_PUSHWORD+N' - Use short word N of the "data" portion of the message as the - value. - - 'NETF_PUSHHDR+N' - Use short word N of the "header" portion of the message as the - value. - - 'NETF_PUSHIND+N' - Pops the top long word from the stack and then uses short word - N of the "data" portion of the message as the value. - - 'NETF_PUSHHDRIND+N' - Pops the top long word from the stack and then uses short word - N of the "header" portion of the message as the value. - - 'NETF_PUSHSTK+N' - Use long word N of the stack (where the top of stack is long - word 0) as the value. - - 'NETF_NOPUSH' - Don't push a value. - - The unsigned value so chosen is promoted to a long word before - being pushed. Once a value is pushed (except for the case of - 'NETF_NOPUSH'), the top two long words of the stack are popped and - a binary operator applied to them (with the old top of stack as the - second operand). The result of the operator is pushed on the - stack. These operators are: - - 'NETF_NOP' - Don't pop off any values and do no operation. - - 'NETF_EQ' - Perform an equal comparison. - - 'NETF_LT' - Perform a less than comparison. - - 'NETF_LE' - Perform a less than or equal comparison. - - 'NETF_GT' - Perform a greater than comparison. - - 'NETF_GE' - Perform a greater than or equal comparison. - - 'NETF_AND' - Perform a bitise boolean AND operation. - - 'NETF_OR' - Perform a bitise boolean inclusive OR operation. - - 'NETF_XOR' - Perform a bitise boolean exclusive OR operation. - - 'NETF_NEQ' - Perform a not equal comparison. - - 'NETF_LSH' - Perform a left shift operation. - - 'NETF_RSH' - Perform a right shift operation. - - 'NETF_ADD' - Perform an addition. - - 'NETF_SUB' - Perform a subtraction. - - 'NETF_COR' - Perform an equal comparison. If the comparison is 'TRUE', - terminate the filter list. Otherwise, pop the result of the - comparison off the stack. - - 'NETF_CAND' - Perform an equal comparison. If the comparison is 'FALSE', - terminate the filter list. Otherwise, pop the result of the - comparison off the stack. - - 'NETF_CNOR' - Perform a not equal comparison. If the comparison is 'FALSE', - terminate the filter list. Otherwise, pop the result of the - comparison off the stack. - - 'NETF_CNAND' - Perform a not equal comparison. If the comparison is 'TRUE', - terminate the filter list. Otherwise, pop the result of the - comparison off the stack. The scan of the filter list - terminates when the filter list is emptied, or a 'NETF_C...' - operation terminates the list. At this time, if the final - value of the top of the stack is 'TRUE', then the message is - accepted for the filter. - - The function returns 'D_SUCCESS' if some data was successfully - written, 'D_INVALID_OPERATION' if RECEIVE_PORT is not a valid send - right, and 'D_NO_SUCH_DEVICE' if DEVICE does not denote a device - port or the device is dead or not completely open. - - -File: mach.info, Node: Kernel Debugger, Next: Copying, Prev: Device Interface, Up: Top - -11 Kernel Debugger -****************** - -The GNU Mach kernel debugger 'ddb' is a powerful built-in debugger with -a gdb like syntax. It is enabled at compile time using the -'--enable-kdb' option. Whenever you want to enter the debugger while -running the kernel, you can press the key combination . - -* Menu: - -* Operation:: Basic architecture of the kernel debugger. -* Commands:: Available commands in the kernel debugger. -* Variables:: Access of variables from the kernel debugger. -* Expressions:: Usage of expressions in the kernel debugger. - - -File: mach.info, Node: Operation, Next: Commands, Up: Kernel Debugger - -11.1 Operation -============== - -The current location is called "dot". The dot is displayed with a -hexadecimal format at a prompt. Examine and write commands update dot -to the address of the last line examined or the last location modified, -and set "next" to the address of the next location to be examined or -changed. Other commands don't change dot, and set next to be the same -as dot. - - The general command syntax is: - - COMMAND[/MODIFIER] ADDRESS [,COUNT] - - '!!' repeats the previous command, and a blank line repeats from the -address next with count 1 and no modifiers. Specifying ADDRESS sets dot -to the address. Omitting ADDRESS uses dot. A missing COUNT is taken to -be 1 for printing commands or infinity for stack traces. - - Current 'ddb' is enhanced to support multi-thread debugging. A break -point can be set only for a specific thread, and the address space or -registers of non current thread can be examined or modified if supported -by machine dependent routines. For example, - - break/t mach_msg_trap $task11.0 - - sets a break point at 'mach_msg_trap' for the first thread of task 11 -listed by a 'show all threads' command. - - In the above example, '$task11.0' is translated to the corresponding -thread structure's address by variable translation mechanism described -later. If a default target thread is set in a variable '$thread', the -'$task11.0' can be omitted. In general, if 't' is specified in a -modifier of a command line, a specified thread or a default target -thread is used as a target thread instead of the current one. The 't' -modifier in a command line is not valid in evaluating expressions in a -command line. If you want to get a value indirectly from a specific -thread's address space or access to its registers within an expression, -you have to specify a default target thread in advance, and to use ':t' -modifier immediately after the indirect access or the register reference -like as follows: - - set $thread $task11.0 - print $eax:t *(0x100):tuh - - No sign extension and indirection 'size(long, half word, byte)' can -be specified with 'u', 'l', 'h' and 'b' respectively for the indirect -access. - - Note: Support of non current space/register access and user space -break point depend on the machines. If not supported, attempts of such -operation may provide incorrect information or may cause strange -behavior. Even if supported, the user space access is limited to the -pages resident in the main memory at that time. If a target page is not -in the main memory, an error will be reported. - - 'ddb' has a feature like a command 'more' for the output. If an -output line exceeds the number set in the '$lines' variable, it displays -'--db_more--' and waits for a response. The valid responses for it are: - -'' - one more page - -'' - one more line - -'q' - abort the current command, and return to the command input mode -