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