1 // Copyright 2016 The Fuchsia Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #pragma once
6 
7 // This file is a collection of utilities for writing tests.
8 // Typically they are wrappers on system calls and other routines
9 // and save the caller from having to test the return code (for cases
10 // where there's no point in continuing with the test if the call fails).
11 // Note that if these calls fail they cause the process to exit, and
12 // are not intended to be used for tests that have multiple "subtests"
13 // and it's reasonable to continue with the other subtests if a syscall
14 // in one fails.
15 
16 #include <stddef.h>
17 #include <threads.h>
18 #include <zircon/types.h>
19 #include <zircon/compiler.h>
20 #include <zircon/syscalls/object.h>
21 #include <launchpad/launchpad.h>
22 
23 __BEGIN_CDECLS
24 
25 // These malloc-using calls will terminate the process on ENOMEM.
26 void* tu_malloc(size_t size);
27 void* tu_calloc(size_t nmemb, size_t size);
28 char* tu_strdup(const char* s);
29 char* tu_asprintf(const char* fmt, ...);
30 
31 // Print a message saying a syscall (or similar) function failed,
32 // and terminate the process.
33 // |what| is typically the name of the function that had the syscall failure,
34 // but it can include more descriptive text as desired.
35 
36 void tu_fatal(const char *what, zx_status_t status) __NO_RETURN;
37 
38 // A wrapper on zx_handle_close.
39 
40 void tu_handle_close(zx_handle_t handle);
41 
42 // A wrapper on zx_handle_duplicate.
43 
44 zx_handle_t tu_handle_duplicate(zx_handle_t handle);
45 
46 // A wrapper on launchpad_launch.
47 
48 zx_handle_t tu_launch(zx_handle_t job, const char* name,
49                       int argc, const char* const* argv,
50                       const char* const* envp,
51                       size_t num_handles, zx_handle_t* handles,
52                       uint32_t* handle_ids);
53 
54 // The first part of launchpad_launch_fdio_etc that creates the
55 // launchpad and initializes the process.
56 
57 launchpad_t* tu_launch_fdio_init(zx_handle_t job, const char* name,
58                                  int argc, const char* const* argv,
59                                  const char* const* envp,
60                                  size_t num_handles, zx_handle_t* handles,
61                                  uint32_t* handle_ids);
62 
63 // The second part of launchpad_launch_fdio_etc that starts the process.
64 // Returns a handle of the started process.
65 
66 zx_handle_t tu_launch_fdio_fini(launchpad_t* lp);
67 
68 // A wrapper on C11 thrd_create.
69 
70 void tu_thread_create_c11(thrd_t* thread, thrd_start_t entry, void* arg,
71                           const char* name);
72 
73 // A wrapper on zx_object_wait_many that can be easier to call.
74 // |num_objects| is the number of elements in |handles,signals,pending|.
75 
76 zx_status_t tu_wait(uint32_t num_objects,
77                     const zx_handle_t* handles,
78                     const zx_signals_t* signals,
79                     zx_signals_t* pending);
80 
81 // A wrapper on zx_channel_create.
82 
83 void tu_channel_create(zx_handle_t* handle0, zx_handle_t* handle1);
84 
85 
86 // A wrapper on zx_channel_write.
87 
88 void tu_channel_write(zx_handle_t handle, uint32_t flags, const void* bytes, uint32_t num_bytes,
89                       const zx_handle_t* handles, uint32_t num_handles);
90 
91 // A wrapper on zx_channel_read.
92 
93 void tu_channel_read(zx_handle_t handle, uint32_t flags, void* bytes, uint32_t* num_bytes,
94                      zx_handle_t* handles, uint32_t* num_handles);
95 
96 // Wait for |channel| to be readable.
97 // Returns true if the channel is readable, and false if the peer has closed its end.
98 // Note: This waits "forever", and relies on the watchdog to catch hung tests.
99 bool tu_channel_wait_readable(zx_handle_t channel);
100 
101 // Wait for |process| to be signaled (ZX_PROCESS_TERMINATED).
102 // Note: This waits "forever", and relies on the watchdog to catch hung tests.
103 
104 void tu_process_wait_signaled(zx_handle_t process);
105 
106 // Return true if |process| has exited.
107 
108 bool tu_process_has_exited(zx_handle_t process);
109 
110 // Fetch the return code of |process|.
111 
112 int tu_process_get_return_code(zx_handle_t process);
113 
114 // Wait for |process| to exit and then fetch its return code.
115 
116 int tu_process_wait_exit(zx_handle_t process);
117 
118 // Return the handle of thread |tid| in |process|.
119 // Returns ZX_HANDLE_INVALID if the thread is not found (could have died).
120 
121 zx_handle_t tu_process_get_thread(zx_handle_t process, zx_koid_t tid);
122 
123 // Fetch the current threads of |process|.
124 // |max_threads| is the size of the |threads| buffer.
125 // Returns the actual number of threads at the point in time when the list
126 // of threads is obtained. It could be larger than |max_threads|.
127 // See discussion of ZX_INFO_PROCESS_THREADS in object_get_info.md.
128 
129 size_t tu_process_get_threads(zx_handle_t process, zx_koid_t* threads, size_t max_threads);
130 
131 // Create a child job of |job|.
132 
133 zx_handle_t tu_job_create(zx_handle_t job);
134 
135 // Create an io port.
136 
137 zx_handle_t tu_io_port_create(void);
138 
139 // Set the exception port for |handle| which is a process or thread.
140 
141 void tu_set_exception_port(zx_handle_t handle, zx_handle_t eport, uint64_t key, uint32_t options);
142 
143 // Add |handle| to the list of things |port| watches.
144 // When |handle| is signaled with a signal in |signals| a zx_packet_signal_t
145 // packet is sent to |port| with the key being the koid of |handle|.
146 void tu_object_wait_async(zx_handle_t handle, zx_handle_t port, zx_signals_t signals);
147 
148 // Get basic handle info for |handle|.
149 
150 void tu_handle_get_basic_info(zx_handle_t handle, zx_info_handle_basic_t* info);
151 
152 // Return the koid of the object of |handle|.
153 
154 zx_koid_t tu_get_koid(zx_handle_t handle);
155 
156 // Return the "related" koid of the object of |handle|.
157 
158 zx_koid_t tu_get_related_koid(zx_handle_t handle);
159 
160 // Return a handle of thread |tid|.
161 
162 zx_handle_t tu_get_thread(zx_handle_t proc, zx_koid_t tid);
163 
164 // Return zx_info_thread_t of |thread|.
165 
166 zx_info_thread_t tu_thread_get_info(zx_handle_t thread);
167 
168 // Return the state of |thread|, one of ZX_THREAD_STATE_*.
169 
170 uint32_t tu_thread_get_state(zx_handle_t thread);
171 
172 // Return true if |thread| is dying or dead.
173 
174 bool tu_thread_is_dying_or_dead(zx_handle_t thread);
175 
176 // Kill |task|.
177 
178 void tu_task_kill(zx_handle_t task);
179 
180 // Run a program and wait for it to exit.
181 // Any error in trying to run the program is fatal.
182 // The result is the return code of the child process.
183 
184 int tu_run_program(const char *progname, int argc, const char** argv);
185 
186 // A wrapper for /bin/sh -c <command>.
187 
188 int tu_run_command(const char* progname, const char* cmd);
189 
190 // Set the scaling factor for timeouts.
191 // The default is 1. A value of 2 waits twice as long, and so on.
192 // This is useful when running tests under a debugger or with a
193 // massive amount of tracing turned on.
194 // If 0 is passed no change is made.
195 // Returns the previous value.
196 
197 int tu_set_timeout_scale(int scale);
198 
199 __END_CDECLS
200