--- Gnu-Mach/doc/mach.info-1 2020/09/02 04:46:44 1.1 +++ Gnu-Mach/doc/mach.info-1 2020/09/02 04:55:32 1.1.1.5 @@ -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 6.3 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 14 December 2016, of 'The GNU +Mach Reference Manual', for version 1.8. 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 14 December 2016, of 'The GNU +Mach Reference Manual', for version 1.8. 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 @@ -1459,10 +1475,10 @@ File: mach.info, Node: Exchanging Port ---------------------------- Each task has its own space of port rights. Port rights are named with -positive integers. Except for the reserved values 'MACH_PORT_NULL (0)'(1) -and 'MACH_PORT_DEAD (~0)', this is a full 32-bit name space. When the -kernel chooses a name for a new right, it is free to pick any unused -name (one which denotes no right) in the space. +positive integers. Except for the reserved values +'MACH_PORT_NULL (0)'(1) and 'MACH_PORT_DEAD (~0)', this is a full 32-bit +name space. When the kernel chooses a name for a new right, it is free +to pick any unused name (one which denotes no right) in the space. There are five basic kinds of rights: receive rights, send rights, send-once rights, port-set rights, and dead names. Dead names are not @@ -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 @@ -3077,16 +3216,16 @@ File: mach.info, Node: Memory Attribute successfully set and 'KERN_INVALID_ADDRESS' if an invalid or non-allocated address was specified. - -- Function: kern_return_t vm_wire (host_priv_t HOST_PRIV, - vm_task_t TARGET_TASK, vm_address_t ADDRESS, vm_size_t SIZE, - vm_prot_t ACCESS) - The function 'vm_wire' allows privileged applications to control - memory pageability. HOST_PRIV is the privileged host port for the - host on which TARGET_TASK resides. ADDRESS is the starting - address, which will be rounded down to a page boundary. SIZE is - the size in bytes of the region for which protection is to change, - and will be rounded up to give a page boundary. ACCESS specifies - the types of accesses that must not cause page faults. + -- Function: kern_return_t vm_wire (host_t HOST, vm_task_t TARGET_TASK, + vm_address_t ADDRESS, vm_size_t SIZE, vm_prot_t ACCESS) + The function 'vm_wire' allows applications to control memory + pageability. HOST is the host port for the host on which + TARGET_TASK resides. ADDRESS is the starting address, which will + be rounded down to a page boundary. SIZE is the size in bytes of + the region for which protection is to change, and will be rounded + up to give a page boundary. ACCESS specifies the types of accesses + that must not cause page faults. If the host port is not + privileged, the amount of memory is limited per task. The semantics of a successful 'vm_wire' operation are that memory in the specified range will not cause page faults for any accesses @@ -3095,15 +3234,13 @@ File: mach.info, Node: Memory Attribute special case is that 'VM_PROT_NONE' makes the memory pageable. The function returns 'KERN_SUCCESS' if the call succeeded, - 'KERN_INVALID_HOST' if HOST_PRIV was not the privileged host port, + 'KERN_INVALID_HOST' if HOST was not a valid host port, 'KERN_INVALID_TASK' if TASK was not a valid task, 'KERN_INVALID_VALUE' if ACCESS specified an invalid access mode, - 'KERN_FAILURE' if some memory in the specified range is not present - or has an inappropriate protection value, and - 'KERN_INVALID_ARGUMENT' if unwiring (ACCESS is 'VM_PROT_NONE') and - the memory is not already wired. + and 'KERN_NO_SPACE' if some memory in the specified range is not + present or has an inappropriate protection value. - The 'vm_wire' call is actually an RPC to HOST_PRIV, normally a send + The 'vm_wire' call is actually an RPC to HOST, normally a send right for a privileged host 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 @@ -3328,14 +3465,14 @@ File: mach.info, Node: Memory Object Se procedure, 'memory_object_server', to handle a received message. This function does all necessary argument handling, and actually calls one of the following functions: 'memory_object_init', - 'memory_object_data_write', 'memory_object_data_return', - 'memory_object_data_request', 'memory_object_data_unlock', - 'memory_object_lock_completed', 'memory_object_copy', - 'memory_object_terminate'. The *default memory manager* may get - two additional requests from the kernel: 'memory_object_create' and - 'memory_object_data_initialize'. The remote procedure call - generator produces a procedure 'memory_object_default_server' to - handle those functions specific to the default memory manager. + 'memory_object_data_return', 'memory_object_data_request', + 'memory_object_data_unlock', 'memory_object_lock_completed', + 'memory_object_copy', 'memory_object_terminate'. The *default + memory manager* may get two additional requests from the kernel: + 'memory_object_create' and 'memory_object_data_initialize'. The + remote procedure call generator produces a procedure + 'memory_object_default_server' to handle those functions specific + to the default memory manager. The 'seqnos_memory_object_server' and 'seqnos_memory_object_default_server' differ from @@ -3385,9 +3522,9 @@ File: mach.info, Node: Memory Object Cr the calling kernel is included for planning purposes. When the memory manager is prepared to accept requests for data for - this object, it must call 'memory_object_ready' with the attribute. - Otherwise the kernel will not process requests on this object. To - reject all mappings of this object, the memory manager may use + this object, it must call 'memory_object_ready'. Otherwise the + kernel will not process requests on this object. To reject all + mappings of this object, the memory manager may use 'memory_object_destroy'. The argument MEMORY_OBJECT is the port that represents the memory @@ -3672,8 +3809,8 @@ File: mach.info, Node: Memory Objects a 1. The object was created by 'memory_object_create' and the kernel has not yet provided data for this range (either via a - 'memory_object_data_initialize', 'memory_object_data_write' or - a 'memory_object_data_return' for the object. + 'memory_object_data_initialize', or a + 'memory_object_data_return' for the object. 2. The object was created by an 'memory_object_data_copy' and the kernel should copy this region from the original memory @@ -3742,63 +3879,6 @@ File: mach.info, Node: Memory Objects a is called by the kernel, which does not wait for a reply message, this value is ignored. - The remaining interfaces in this section are obsolete. - - -- Function: kern_return_t memory_object_data_write - (memory_object_t MEMORY_OBJECT, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t DATA, vm_size_t DATA_COUNT) - -- Function: kern_return_t seqnos_memory_object_data_write - (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t DATA, vm_size_t DATA_COUNT) - The function 'memory_object_data_write' provides the memory manager - with data that has been modified while cached in physical memory. - It is the old form of 'memory_object_data_return'. Once the memory - manager no longer needs this data (e.g., it has been written to - another storage medium), it should be deallocated using - 'vm_deallocate'. - - The argument MEMORY_OBJECT is the port that represents the memory - object data, as supplied to the kernel in a 'vm_map' call. - MEMORY_CONTROL is the request port to which a response is - requested. (In the event that a memory object has been supplied to - more than one the kernel that has made the request.) OFFSET is the - offset within a memory object to which this call refers. This will - be page aligned. DATA is the data which has been modified while - cached in physical memory. DATA_COUNT is the amount of data to be - written, in bytes. This will be an integral number of memory - object pages. - - The function should return 'KERN_SUCCESS', but since this routine - is called by the kernel, which does not wait for a reply message, - this value is ignored. - - -- Function: kern_return_t memory_object_data_provided - (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t DATA, vm_size_t DATA_COUNT, vm_prot_t LOCK_VALUE) - The function 'memory_object_data_provided' supplies the kernel with - data for the specified memory object. It is the old form of - 'memory_object_data_supply'. Ordinarily, memory managers should - only provide data in response to 'memory_object_data_request' calls - from the kernel. The LOCK_VALUE specifies what type of access will - not be allowed to the data range. The lock values must be one or - more of the set: 'VM_PROT_NONE', 'VM_PROT_READ', 'VM_PROT_WRITE', - 'VM_PROT_EXECUTE' and 'VM_PROT_ALL' as defined in 'mach/vm_prot.h'. - - The argument MEMORY_CONTROL is the port, provided by the kernel in - a 'memory_object_init' call, to which cache management requests may - be issued. OFFSET is an offset within a memory object in bytes. - This must be page aligned. DATA is the data that is being provided - to the kernel. This is a pointer to the data. DATA_COUNT is the - amount of data to be provided. This must be an integral number of - memory object pages. LOCK_VALUE is a protection value indicating - those forms of access that should *not* be permitted to the - specified cached data. - - This routine does not receive a reply message (and consequently has - no return value), so only message transmission errors apply. -  File: mach.info, Node: Memory Object Locking, Next: Memory Object Attributes, Prev: Memory Objects and Data, Up: External Memory Management @@ -3813,9 +3893,9 @@ File: mach.info, Node: Memory Object Lo The function 'memory_object_lock_request' allows a memory manager to make cache management requests. As specified in arguments to the call, the kernel will: - * clean (i.e., write back using 'memory_object_data_supply' or - 'memory_object_data_write') any cached data which has been - modified since the last time it was written + * clean (i.e., write back using 'memory_object_data_supply' any + cached data which has been modified since the last time it was + written * flush (i.e., remove any uses of) that data from memory @@ -3940,11 +4020,13 @@ File: mach.info, Node: Memory Object At boolean_t MAY_CACHE_OBJECT, memory_object_copy_strategy_t COPY_STRATEGY, mach_port_t REPLY_TO) - The function 'memory_object_change_attribute' sets - performance-related attributes for the specified memory object. If - the caching attribute is asserted, the kernel is permitted (and - encouraged) to maintain cached data for this memory object even - after no virtual address space contains this data. + The function 'memory_object_change_attribute' informs the kernel + that the memory manager is ready to receive data or unlock requests + on behalf of the clients and sets performance-related attributes + for the specified memory object. If the caching attribute is + asserted, the kernel is permitted (and encouraged) to maintain + cached data for this memory object even after no virtual address + space contains this data. There are three possible caching strategies: 'MEMORY_OBJECT_COPY_NONE' which specifies that nothing special @@ -3980,46 +4062,6 @@ File: mach.info, Node: Memory Object At The function 'memory_object_change_completed' indicates the completion of an attribute change call. - The following interface is obsoleted by 'memory_object_ready' and -'memory_object_change_attributes'. If the old form -'memory_object_set_attributes' is used to make a memory object ready, -the kernel will write back data using the old 'memory_object_data_write' -interface rather than 'memory_object_data_return'.. - - -- Function: kern_return_t memory_object_set_attributes - (memory_object_control_t MEMORY_CONTROL, boolean OBJECT_READY, - boolean_t MAY_CACHE_OBJECT, - memory_object_copy_strategy_t COPY_STRATEGY) - The function 'memory_object_set_attribute' controls how the memory - object. The kernel will only make data or unlock requests when the - ready attribute is asserted. If the caching attribute is asserted, - the kernel is permitted (and encouraged) to maintain cached data - for this memory object even after no virtual address space contains - this data. - - There are three possible caching strategies: - 'MEMORY_OBJECT_COPY_NONE' which specifies that nothing special - should be done when data in the object is copied; - 'MEMORY_OBJECT_COPY_CALL' which specifies that the memory manager - should be notified via a 'memory_object_copy' call before any part - of the object is copied; and 'MEMORY_OBJECT_COPY_DELAY' which - guarantees that the memory manager does not externally modify the - data so that the kernel can use its normal copy-on-write - algorithms. 'MEMORY_OBJECT_COPY_DELAY' is the strategy most - commonly used. - - The argument MEMORY_CONTROL is the port, provided by the kernel in - a 'memory_object_init' call, to which cache management requests may - be issued. If OBJECT_READY is set, the kernel may issue new data - and unlock requests on the associated memory object. If - MAY_CACHE_OBJECT is set, the kernel may keep data associated with - this memory object, even after virtual memory references to it are - gone. COPY_STRATEGY tells how the kernel should copy regions of - the associated memory object. - - This routine does not receive a reply message (and consequently has - no return value), so only message transmission errors apply. -  File: mach.info, Node: Default Memory Manager, Prev: Memory Object Attributes, Up: External Memory Management @@ -4068,7 +4110,7 @@ File: mach.info, Node: Default Memory M No reply is expected after this call. Since this call is directed to the default memory manager, the kernel assumes that it will be ready to handle data requests to this object and does not need the - confirmation of a 'memory_object_set_attributes' call. + confirmation of a 'memory_object_ready' call. The argument OLD_MEMORY_OBJECT is a memory object provided by the default memory manager on which the kernel can make @@ -4100,13 +4142,12 @@ File: mach.info, Node: Default Memory M The function 'memory_object_data_initialize' provides the memory manager with initial data for a kernel-created memory object. If the memory manager already has been supplied data (by a previous - 'memory_object_data_initialize', 'memory_object_data_write' or - 'memory_object_data_return'), then this data should be ignored. - Otherwise, this call behaves exactly as does - 'memory_object_data_return' on memory objects created by the kernel - via 'memory_object_create' and thus will only be made to default - memory managers. This call will not be made on objects created via - 'memory_object_copy'. + 'memory_object_data_initialize', or 'memory_object_data_return'), + then this data should be ignored. Otherwise, this call behaves + exactly as does 'memory_object_data_return' on memory objects + created by the kernel via 'memory_object_create' and thus will only + be made to default memory managers. This call will not be made on + objects created via 'memory_object_copy'. The argument MEMORY_OBJECT the port that represents the memory object data, as supplied by the kernel in a 'memory_object_create' @@ -4557,7 +4598,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 +4609,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 +4623,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 +5066,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 @@ -6643,93 +6695,3 @@ File: mach.info, Node: Device Filter, 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 -