--- Gnu-Mach/doc/mach.info-2 2020/09/02 04:46:44 1.1.1.1 +++ Gnu-Mach/doc/mach.info-2 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. @@ -38,6 +38,96 @@ START-INFO-DIR-ENTRY END-INFO-DIR-ENTRY  +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 + + File: mach.info, Node: Commands, Next: Variables, Prev: Operation, Up: Kernel Debugger 11.2 Commands @@ -313,11 +403,12 @@ File: mach.info, Node: Commands, Next: numbers may change. The current thread can be distinguished from others by a '#' after the thread id instead of ':'. Without 'l' option, it only shows thread id, thread structure address and the - status for each thread. The status consists of 5 letters, R(run), - W(wait), S(suspended), O(swapped out) and N(interruptible), and if - corresponding status bit is off, '.' is printed instead. If 'l' - option is specified, more detail information is printed for each - thread. + status for each thread. The status consists of 6 letters, R(run), + W(wait), S(suspended), O(swapped out), N(interruptible), and + F(loating) point arithmetic used (if supported by the platform). + If the corresponding status bit is off, '.' is printed instead. If + 'l' option is specified, more detail information is printed for + each thread. 'show task [ ADDR ]' Display the information of a task specified by ADDR. If ADDR is @@ -1400,25 +1491,25 @@ Function and Data Index * device_open: Device Open. (line 6) * device_open_request: Device Open. (line 33) * device_read: Device Read. (line 6) -* device_read_inband: Device Read. (line 24) -* device_read_request: Device Read. (line 31) -* device_read_request_inband: Device Read. (line 48) +* device_read_inband: Device Read. (line 25) +* device_read_request: Device Read. (line 32) +* device_read_request_inband: Device Read. (line 50) * device_reply_server: Device Reply Server. (line 10) * device_set_filter: Device Filter. (line 6) * device_set_status: Device Status. (line 6) * device_t: Device Interface. (line 13) * device_write: Device Write. (line 6) -* device_write_inband: Device Write. (line 21) -* device_write_request: Device Write. (line 28) -* device_write_request_inband: Device Write. (line 45) -* ds_device_open_reply: Device Open. (line 36) -* ds_device_read_reply: Device Read. (line 34) -* ds_device_read_reply_inband: Device Read. (line 52) -* ds_device_write_reply: Device Write. (line 31) -* ds_device_write_reply_inband: Device Write. (line 49) -* evc_wait: Exceptions. (line 17) -* exception_raise: Exceptions. (line 11) -* host_adjust_time: Host Time. (line 40) +* device_write_inband: Device Write. (line 22) +* device_write_request: Device Write. (line 29) +* device_write_request_inband: Device Write. (line 48) +* ds_device_open_reply: Device Open. (line 37) +* ds_device_read_reply: Device Read. (line 36) +* ds_device_read_reply_inband: Device Read. (line 55) +* ds_device_write_reply: Device Write. (line 32) +* ds_device_write_reply_inband: Device Write. (line 53) +* evc_wait: Exceptions. (line 18) +* exception_raise: Exceptions. (line 12) +* host_adjust_time: Host Time. (line 41) * host_basic_info_t: Host Information. (line 74) * host_get_boot_info: Host Information. (line 112) * host_get_time: Host Time. (line 31) @@ -1432,42 +1523,45 @@ Function and Data Index (line 21) * host_reboot: Host Reboot. (line 6) * host_sched_info_t: Host Information. (line 91) -* host_set_time: Host Time. (line 36) +* host_set_time: Host Time. (line 37) * host_t: Host Ports. (line 6) * ipc_space_t: Port Manipulation Interface. (line 9) * mach_host_self: Host Ports. (line 13) * mach_msg: Mach Message Call. (line 9) -* MACH_MSGH_BITS: Message Format. (line 94) -* MACH_MSGH_BITS_LOCAL: Message Format. (line 106) -* MACH_MSGH_BITS_OTHER: Message Format. (line 116) -* MACH_MSGH_BITS_PORTS: Message Format. (line 111) -* MACH_MSGH_BITS_REMOTE: Message Format. (line 101) +* MACH_MSGH_BITS: Message Format. (line 103) +* MACH_MSGH_BITS_LOCAL: Message Format. (line 116) +* MACH_MSGH_BITS_OTHER: Message Format. (line 127) +* MACH_MSGH_BITS_PORTS: Message Format. (line 122) +* MACH_MSGH_BITS_REMOTE: Message Format. (line 110) * mach_msg_bits_t: Message Format. (line 20) * mach_msg_header_t: Message Format. (line 32) * mach_msg_id_t: Message Format. (line 28) * mach_msg_size_t: Message Format. (line 24) * mach_msg_timeout_t: Mach Message Call. (line 60) -* mach_msg_type_long_t: Message Format. (line 231) -* mach_msg_type_name_t: Message Format. (line 127) -* mach_msg_type_number_t: Message Format. (line 137) -* MACH_MSG_TYPE_PORT_ANY: Message Format. (line 217) -* MACH_MSG_TYPE_PORT_ANY_RIGHT: Message Format. (line 226) -* MACH_MSG_TYPE_PORT_ANY_SEND: Message Format. (line 221) -* mach_msg_type_size_t: Message Format. (line 132) -* mach_msg_type_t: Message Format. (line 142) +* mach_msg_type_long_t: Message Format. (line 248) +* mach_msg_type_name_t: Message Format. (line 138) +* mach_msg_type_number_t: Message Format. (line 148) +* MACH_MSG_TYPE_PORT_ANY: Message Format. (line 234) +* MACH_MSG_TYPE_PORT_ANY_RIGHT: Message Format. (line 243) +* MACH_MSG_TYPE_PORT_ANY_SEND: Message Format. (line 238) +* mach_msg_type_size_t: Message Format. (line 143) +* mach_msg_type_t: Message Format. (line 153) +* mach_ports_lookup: Inherited Ports. (line 14) +* mach_ports_register: Inherited Ports. (line 12) * mach_port_allocate: Port Creation. (line 6) * mach_port_allocate_name: Port Creation. (line 64) +* mach_port_clear_protected_payload: Receive Rights. (line 144) * mach_port_deallocate: Port Destruction. (line 6) * mach_port_destroy: Port Destruction. (line 28) * mach_port_extract_right: Ports and other Tasks. - (line 57) + (line 58) * mach_port_get_receive_status: Receive Rights. (line 54) * mach_port_get_refs: Port Rights. (line 6) * mach_port_get_set_status: Port Sets. (line 6) * mach_port_insert_right: Ports and other Tasks. (line 6) -* mach_port_mod_refs: Port Rights. (line 35) +* mach_port_mod_refs: Port Rights. (line 36) * mach_port_move_member: Port Sets. (line 26) * mach_port_mscount_t: Receive Rights. (line 10) * mach_port_msgcount_t: Receive Rights. (line 14) @@ -1477,75 +1571,70 @@ Function and Data Index (line 6) * mach_port_rights_t: Receive Rights. (line 18) * mach_port_seqno_t: Receive Rights. (line 6) -* mach_port_set_mscount: Receive Rights. (line 71) -* mach_port_set_qlimit: Receive Rights. (line 88) -* mach_port_set_seqno: Receive Rights. (line 106) +* mach_port_set_mscount: Receive Rights. (line 73) +* mach_port_set_protected_payload: Receive Rights. (line 126) +* mach_port_set_qlimit: Receive Rights. (line 90) +* mach_port_set_seqno: Receive Rights. (line 108) * mach_port_status_t: Receive Rights. (line 22) * mach_port_t: Message Format. (line 13) * mach_port_type: Port Names. (line 33) * mach_reply_port: Port Creation. (line 47) * mach_task_self: Task Information. (line 6) * mach_thread_self: Thread Information. (line 6) -* mapped_time_value_t: Host Time. (line 49) +* mapped_time_value_t: Host Time. (line 50) * memory_object_change_attributes: Memory Object Attributes. - (line 25) + (line 26) * memory_object_change_completed: Memory Object Attributes. - (line 60) + (line 66) * memory_object_copy: Memory Objects and Data. - (line 202) + (line 209) * memory_object_create: Default Memory Manager. (line 25) * memory_object_data_error: Memory Objects and Data. - (line 152) + (line 159) * memory_object_data_initialize: Default Memory Manager. - (line 69) -* memory_object_data_provided: Memory Objects and Data. - (line 284) + (line 73) * memory_object_data_request: Memory Objects and Data. - (line 45) + (line 47) * memory_object_data_return: Memory Objects and Data. (line 6) * memory_object_data_supply: Memory Objects and Data. - (line 80) + (line 84) * memory_object_data_unavailable: Memory Objects and Data. - (line 172) + (line 179) * memory_object_data_unlock: Memory Object Locking. - (line 81) -* memory_object_data_write: Memory Objects and Data. - (line 254) + (line 83) * memory_object_default_server: Memory Object Server. (line 8) * memory_object_destroy: Memory Object Termination. - (line 35) + (line 39) * memory_object_get_attributes: Memory Object Attributes. (line 6) * memory_object_init: Memory Object Creation. (line 6) * memory_object_lock_completed: Memory Object Locking. - (line 55) + (line 56) * memory_object_lock_request: Memory Object Locking. (line 6) * memory_object_ready: Memory Object Creation. - (line 48) + (line 55) * memory_object_server: Memory Object Server. (line 6) -* memory_object_set_attributes: Memory Object Attributes. - (line 76) * memory_object_supply_completed: Memory Objects and Data. - (line 121) + (line 125) * memory_object_terminate: Memory Object Termination. (line 6) * processor_assign: Processors and Sets. (line 6) -* processor_basic_info_t: Processor Info. (line 66) +* processor_basic_info_t: Processor Info. (line 67) * processor_control: Processor Control. (line 8) * processor_exit: Processor Control. (line 7) * processor_get_assignment: Processors and Sets. (line 30) * processor_info: Processor Info. (line 6) -* processor_set_basic_info_t: Processor Set Info. (line 74) +* processor_set_basic_info_t: Processor Set Info. (line 75) * processor_set_create: Processor Set Creation. (line 6) * processor_set_default: Processor Set Access. - (line 33) + (line 34) * processor_set_destroy: Processor Set Destruction. (line 6) * processor_set_info: Processor Set Info. (line 6) @@ -1556,121 +1645,120 @@ Function and Data Index (line 8) * processor_set_policy_enable: Processor Set Policy. (line 6) -* processor_set_sched_info_t: Processor Set Info. (line 92) +* processor_set_sched_info_t: Processor Set Info. (line 93) * processor_set_t: Processor Set Ports. (line 12) * processor_set_tasks: Tasks and Threads on Sets. (line 6) * processor_set_threads: Tasks and Threads on Sets. - (line 20) + (line 21) * processor_start: Processor Control. (line 6) * processor_t: Processor Interface. (line 6) -* sampled_pc_flavor_t: Profiling. (line 67) -* sampled_pc_t: Profiling. (line 52) +* sampled_pc_flavor_t: Profiling. (line 69) +* sampled_pc_t: Profiling. (line 54) * seqnos_memory_object_change_completed: Memory Object Attributes. - (line 63) + (line 69) * seqnos_memory_object_copy: Memory Objects and Data. - (line 207) + (line 217) * seqnos_memory_object_create: Default Memory Manager. - (line 30) + (line 33) * seqnos_memory_object_data_initialize: Default Memory Manager. - (line 73) + (line 78) * seqnos_memory_object_data_request: Memory Objects and Data. - (line 49) + (line 53) * seqnos_memory_object_data_return: Memory Objects and Data. - (line 11) + (line 13) * seqnos_memory_object_data_unlock: Memory Object Locking. - (line 85) -* seqnos_memory_object_data_write: Memory Objects and Data. - (line 258) + (line 89) * seqnos_memory_object_default_server: Memory Object Server. - (line 12) + (line 14) * seqnos_memory_object_init: Memory Object Creation. - (line 11) + (line 15) * seqnos_memory_object_lock_completed: Memory Object Locking. - (line 59) + (line 61) * seqnos_memory_object_server: Memory Object Server. - (line 10) + (line 11) * seqnos_memory_object_supply_completed: Memory Objects and Data. - (line 126) + (line 132) * seqnos_memory_object_terminate: Memory Object Termination. - (line 10) + (line 13) * struct host_basic_info: Host Information. (line 47) * struct host_sched_info: Host Information. (line 77) -* struct processor_basic_info: Processor Info. (line 43) -* struct processor_set_basic_info: Processor Set Info. (line 50) -* struct processor_set_sched_info: Processor Set Info. (line 77) -* struct task_basic_info: Task Information. (line 81) -* struct task_events_info: Task Information. (line 112) -* struct task_thread_times_info: Task Information. (line 143) -* struct thread_basic_info: Thread Information. (line 65) -* struct thread_sched_info: Thread Information. (line 126) -* swtch: Hand-Off Scheduling. (line 81) -* swtch_pri: Hand-Off Scheduling. (line 93) +* struct processor_basic_info: Processor Info. (line 44) +* struct processor_set_basic_info: Processor Set Info. (line 51) +* struct processor_set_sched_info: Processor Set Info. (line 78) +* struct task_basic_info: Task Information. (line 82) +* struct task_events_info: Task Information. (line 113) +* struct task_thread_times_info: Task Information. (line 144) +* struct thread_basic_info: Thread Information. (line 66) +* struct thread_sched_info: Thread Information. (line 127) +* swtch: Hand-Off Scheduling. (line 82) +* swtch_pri: Hand-Off Scheduling. (line 94) * task_assign: Tasks and Threads on Sets. - (line 34) + (line 36) * task_assign_default: Tasks and Threads on Sets. - (line 47) -* task_basic_info_t: Task Information. (line 109) + (line 50) +* task_basic_info_t: Task Information. (line 110) * task_create: Task Creation. (line 6) -* task_disable_pc_sampling: Profiling. (line 20) +* task_disable_pc_sampling: Profiling. (line 21) * task_enable_pc_sampling: Profiling. (line 6) -* task_events_info_t: Task Information. (line 140) +* task_events_info_t: Task Information. (line 141) * task_get_assignment: Tasks and Threads on Sets. - (line 57) -* task_get_bootstrap_port: Task Special Ports. (line 40) + (line 61) +* task_get_bootstrap_port: Task Special Ports. (line 41) * task_get_emulation_vector: Syscall Emulation. (line 6) -* task_get_exception_port: Task Special Ports. (line 34) -* task_get_kernel_port: Task Special Ports. (line 28) -* task_get_sampled_pcs: Profiling. (line 34) +* task_get_exception_port: Task Special Ports. (line 35) +* task_get_kernel_port: Task Special Ports. (line 29) +* task_get_sampled_pcs: Profiling. (line 36) * task_get_special_port: Task Special Ports. (line 6) -* task_info: Task Information. (line 41) +* task_info: Task Information. (line 42) * task_priority: Task Execution. (line 27) * task_ras_control: Task Execution. (line 45) * task_resume: Task Execution. (line 18) -* task_set_bootstrap_port: Task Special Ports. (line 76) -* task_set_emulation: Syscall Emulation. (line 20) +* task_set_bootstrap_port: Task Special Ports. (line 78) +* task_set_emulation: Syscall Emulation. (line 21) * task_set_emulation_vector: Syscall Emulation. (line 12) -* task_set_exception_port: Task Special Ports. (line 70) -* task_set_kernel_port: Task Special Ports. (line 64) -* task_set_special_port: Task Special Ports. (line 46) +* task_set_exception_port: Task Special Ports. (line 72) +* task_set_kernel_port: Task Special Ports. (line 66) +* task_set_name: Task Information. (line 161) +* task_set_special_port: Task Special Ports. (line 47) * task_suspend: Task Execution. (line 6) * task_t: Task Interface. (line 6) * task_terminate: Task Termination. (line 6) * task_threads: Task Information. (line 30) -* task_thread_times_info_t: Task Information. (line 157) +* task_thread_times_info_t: Task Information. (line 158) * thread_abort: Thread Execution. (line 36) * thread_assign: Tasks and Threads on Sets. - (line 69) + (line 73) * thread_assign_default: Tasks and Threads on Sets. - (line 83) -* thread_basic_info_t: Thread Information. (line 123) + (line 87) +* thread_basic_info_t: Thread Information. (line 124) * thread_create: Thread Creation. (line 6) -* thread_depress_abort: Hand-Off Scheduling. (line 74) -* thread_disable_pc_sampling: Profiling. (line 22) -* thread_enable_pc_sampling: Profiling. (line 8) +* thread_depress_abort: Hand-Off Scheduling. (line 75) +* thread_disable_pc_sampling: Profiling. (line 24) +* thread_enable_pc_sampling: Profiling. (line 9) * thread_get_assignment: Tasks and Threads on Sets. - (line 93) + (line 97) * thread_get_exception_port: Thread Special Ports. (line 25) * thread_get_kernel_port: Thread Special Ports. (line 19) -* thread_get_sampled_pcs: Profiling. (line 37) +* thread_get_sampled_pcs: Profiling. (line 39) * thread_get_special_port: Thread Special Ports. (line 6) * thread_get_state: Thread Execution. (line 98) * thread_info: Thread Information. (line 30) -* thread_max_priority: Thread Priority. (line 36) +* thread_max_priority: Thread Priority. (line 37) * thread_policy: Scheduling Policy. (line 6) * thread_priority: Thread Priority. (line 18) * thread_resume: Thread Execution. (line 27) -* thread_sched_info_t: Thread Information. (line 157) +* thread_sched_info_t: Thread Information. (line 158) * thread_set_exception_port: Thread Special Ports. (line 50) * thread_set_kernel_port: Thread Special Ports. (line 44) * thread_set_special_port: Thread Special Ports. (line 31) -* thread_set_state: Thread Execution. (line 122) +* thread_set_state: Thread Execution. (line 123) * thread_suspend: Thread Execution. (line 6) * thread_switch: Hand-Off Scheduling. (line 6) * thread_t: Thread Interface. (line 6) @@ -1695,6 +1783,6 @@ Function and Data Index * vm_statistics_data_t: Memory Statistics. (line 6) * vm_task_t: Virtual Memory Interface. (line 6) -* vm_wire: Memory Attributes. (line 98) +* vm_wire: Memory Attributes. (line 99) * vm_write: Data Transfer. (line 31)