1 //===-- AppleGetPendingItemsHandler.h ----------------------------*- C++
2 //-*-===//
3 //
4 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
5 // See https://llvm.org/LICENSE.txt for license information.
6 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //
8 //===----------------------------------------------------------------------===//
9 
10 #ifndef LLDB_SOURCE_PLUGINS_SYSTEMRUNTIME_MACOSX_APPLEGETPENDINGITEMSHANDLER_H
11 #define LLDB_SOURCE_PLUGINS_SYSTEMRUNTIME_MACOSX_APPLEGETPENDINGITEMSHANDLER_H
12 
13 #include <map>
14 #include <mutex>
15 #include <vector>
16 
17 #include "lldb/Symbol/CompilerType.h"
18 #include "lldb/Utility/Status.h"
19 #include "lldb/lldb-public.h"
20 
21 // This class will insert a UtilityFunction into the inferior process for
22 // calling libBacktraceRecording's
23 // __introspection_dispatch_queue_get_pending_items()
24 // function.  The function in the inferior will return a struct by value
25 // with these members:
26 //
27 //     struct get_pending_items_return_values
28 //     {
29 //         introspection_dispatch_item_info_ref *items_buffer;
30 //         uint64_t items_buffer_size;
31 //         uint64_t count;
32 //     };
33 //
34 // The items_buffer pointer is an address in the inferior program's address
35 // space (items_buffer_size in size) which must be mach_vm_deallocate'd by
36 // lldb.  count is the number of items that were stored in the buffer.
37 //
38 // The AppleGetPendingItemsHandler object should persist so that the
39 // UtilityFunction
40 // can be reused multiple times.
41 
42 namespace lldb_private {
43 
44 class AppleGetPendingItemsHandler {
45 public:
46   AppleGetPendingItemsHandler(lldb_private::Process *process);
47 
48   ~AppleGetPendingItemsHandler();
49 
50   struct GetPendingItemsReturnInfo {
51     lldb::addr_t items_buffer_ptr =
52         LLDB_INVALID_ADDRESS; /* the address of the pending items buffer
53           from libBacktraceRecording */
54     lldb::addr_t items_buffer_size = 0; /* the size of the pending items buffer
55                                        from libBacktraceRecording */
56     uint64_t count = 0; /* the number of pending items included in the buffer */
57 
58     GetPendingItemsReturnInfo() = default;
59   };
60 
61   /// Get the list of pending items for a given queue via a call to
62   /// __introspection_dispatch_queue_get_pending_items.  If there's a page of
63   /// memory that needs to be freed, pass in the address and size and it will
64   /// be freed before getting the list of queues.
65   ///
66   /// \param [in] thread
67   ///     The thread to run this plan on.
68   ///
69   /// \param [in] queue
70   ///     The dispatch_queue_t value for the queue of interest.
71   ///
72   /// \param [in] page_to_free
73   ///     An address of an inferior process vm page that needs to be
74   ///     deallocated,
75   ///     LLDB_INVALID_ADDRESS if this is not needed.
76   ///
77   /// \param [in] page_to_free_size
78   ///     The size of the vm page that needs to be deallocated if an address was
79   ///     passed in to page_to_free.
80   ///
81   /// \param [out] error
82   ///     This object will be updated with the error status / error string from
83   ///     any failures encountered.
84   ///
85   /// \returns
86   ///     The result of the inferior function call execution.  If there was a
87   ///     failure of any kind while getting
88   ///     the information, the items_buffer_ptr value will be
89   ///     LLDB_INVALID_ADDRESS.
90   GetPendingItemsReturnInfo GetPendingItems(Thread &thread, lldb::addr_t queue,
91                                             lldb::addr_t page_to_free,
92                                             uint64_t page_to_free_size,
93                                             lldb_private::Status &error);
94 
95   void Detach();
96 
97 private:
98   lldb::addr_t
99   SetupGetPendingItemsFunction(Thread &thread,
100                                ValueList &get_pending_items_arglist);
101 
102   static const char *g_get_pending_items_function_name;
103   static const char *g_get_pending_items_function_code;
104 
105   lldb_private::Process *m_process;
106   std::unique_ptr<UtilityFunction> m_get_pending_items_impl_code;
107   std::mutex m_get_pending_items_function_mutex;
108 
109   lldb::addr_t m_get_pending_items_return_buffer_addr;
110   std::mutex m_get_pending_items_retbuffer_mutex;
111 };
112 
113 } // using namespace lldb_private
114 
115 #endif // LLDB_SOURCE_PLUGINS_SYSTEMRUNTIME_MACOSX_APPLEGETPENDINGITEMSHANDLER_H
116