os/firehose_server_private.h

   1 /*
   2  * Copyright (c) 2015 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_APACHE_LICENSE_HEADER_START@
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * @APPLE_APACHE_LICENSE_HEADER_END@
  19  */
  20
  21 #ifndef __FIREHOSE_SERVER_PRIVATE__
  22 #define __FIREHOSE_SERVER_PRIVATE__
  23
  24 #include <os/base.h>
  25 #include <dispatch/dispatch.h>
  26 #include "firehose_buffer_private.h"
  27
  28 #if OS_FIREHOSE_SPI
  29 /*!
  30  * @group Firehose SPI
  31  * SPI intended for logd only
  32  */
  33
  34 #pragma mark - Firehose Client
  35
  36 /*!
  37  * @typedef firehose_client_t
  38  *
  39  * @abstract
  40  * Represents a firehose client.
  41  *
  42  * @discussion
  43  * Firehose client objects are os_object_t's, and it's legal to retain/release
  44  * them with os_retain / os_release.
  45  */
  46 OS_OBJECT_DECL_CLASS(firehose_client);
  47
  48 /*!
  49  * @typedef firehose_event_t
  50  *
  51  * @const FIREHOSE_EVENT_NONE
  52  * Never passed to callbacks, meaningful for
  53  * firehose_client_metadata_stream_peek.
  54  *
  55  * @const FIREHOSE_EVENT_CLIENT_CONNECTED
  56  * A new client has connected
  57  *
  58  * This is the first event delivered, and no event is delivered until
  59  * the handler of that event returns
  60  *
  61  * The `page` argument really is really a firehose_client_connected_info_t.
  62  *
  63  * @const FIREHOSE_EVENT_CLIENT_DIED
  64  * The specified client is gone and will not flush new buffers
  65  *
  66  * This is the last event delivered, it is never called before all other
  67  * event handlers have returned. This event is generated even when a
  68  * FIREHOSE_EVENT_CLIENT_CORRUPTED event has been generated.
  69  *
  70  * @const FIREHOSE_EVENT_IO_BUFFER_RECEIVED
  71  * A new buffer needs to be pushed, `page` is set to that buffer.
  72  *
  73  * This event can be sent concurrently wrt FIREHOSE_EVENT_MEM_BUFFER_RECEIVED
  74  * events.
  75  *
  76  * @const FIREHOSE_EVENT_MEM_BUFFER_RECEIVED
  77  * A new buffer needs to be pushed, `page` is set to that buffer.
  78  *
  79  * This event can be sent concurrently wrt FIREHOSE_EVENT_IO_BUFFER_RECEIVED
  80  * events.
  81  *
  82  * @const FIREHOSE_EVENT_CLIENT_CORRUPTED
  83  * This event is received when a client is found being corrupted.
  84  * `page` is set to the buffer header page. When this event is received,
  85  * logs have likely been lost for this client.
  86  *
  87  * This buffer isn't really a proper firehose buffer page, but its content may
  88  * be useful for debugging purposes.
  89  *
  90  * @const FIREHOSE_EVENT_CLIENT_FINALIZE
  91  * This event is received when a firehose client structure is about to be
  92  * destroyed. Only firehose_client_get_context() can ever be called with
  93  * the passed firehose client. The `page` argument is NULL for this event.
  94  *
  95  * The event is sent from the context that is dropping the last refcount
  96  * of the client.
  97  */
  98 OS_ENUM(firehose_event, unsigned long,
  99         FIREHOSE_EVENT_NONE = 0,
 100         FIREHOSE_EVENT_CLIENT_CONNECTED,
 101         FIREHOSE_EVENT_CLIENT_DIED,
 102         FIREHOSE_EVENT_IO_BUFFER_RECEIVED,
 103         FIREHOSE_EVENT_MEM_BUFFER_RECEIVED,
 104         FIREHOSE_EVENT_CLIENT_CORRUPTED,
 105         FIREHOSE_EVENT_CLIENT_FINALIZE,
 106 );
 107
 108 #define FIREHOSE_CLIENT_CONNECTED_INFO_VERSION  1
 109
 110 /*!
 111  * @typedef firehose_client_connected_info
 112  *
 113  * @abstract
 114  * Type of the data passed to CLIENT_CONNECTED events.
 115  */
 116 typedef struct firehose_client_connected_info_s {
 117         unsigned long fcci_version;
 118         // version 1
 119         const void *fcci_data;
 120         size_t fcci_size;
 121 } *firehose_client_connected_info_t;
 122
 123 /*!
 124  * @function firehose_client_get_unique_pid
 125  *
 126  * @abstract
 127  * Returns the unique pid of the specified firehose client
 128  *
 129  * @param client
 130  * The specified client.
 131  *
 132  * @param pid
 133  * The pid for this client.
 134  *
 135  * @returns
 136  * The unique pid of the specified client.
 137  */
 138 OS_NOTHROW OS_NONNULL1
 139 uint64_t
 140 firehose_client_get_unique_pid(firehose_client_t client, pid_t *pid);
 141
 142 /*!
 143  * @function firehose_client_get_metadata_buffer
 144  *
 145  * @abstract
 146  * Returns the metadata buffer for the specified firehose client
 147  *
 148  * @param client
 149  * The specified client.
 150  *
 151  * @param size
 152  * The size of the metadata buffer.
 153  *
 154  * @returns
 155  * The pointer to the buffer.
 156  */
 157 OS_NOTHROW OS_NONNULL_ALL
 158 void *
 159 firehose_client_get_metadata_buffer(firehose_client_t client, size_t *size);
 160
 161 /*!
 162  * @function firehose_client_get_context
 163  *
 164  * @abstract
 165  * Gets the context for the specified client.
 166  *
 167  * @param client
 168  * The specified client.
 169  *
 170  * @returns
 171  * The context set for the client with firehose_client_set_context
 172  */
 173 OS_NOTHROW OS_NONNULL1
 174 void *
 175 firehose_client_get_context(firehose_client_t client);
 176
 177 /*!
 178  * @function firehose_client_set_context
 179  *
 180  * @abstract
 181  * Sets the context for the specified client.
 182  *
 183  * @discussion
 184  * Setting the context exchanges the context pointer, but the client must
 185  * ensure proper synchronization with possible getters.
 186  *
 187  * The lifetime of the context is under the control of the API user,
 188  * it is suggested to destroy the context when the CLIENT_DIED event is
 189  * received.
 190  *
 191  * @param client
 192  * The specified client.
 193  *
 194  * @param ctxt
 195  * The new context to set.
 196  *
 197  * @returns
 198  * The previous context set for the client.
 199  */
 200 OS_NOTHROW OS_NONNULL1
 201 void *
 202 firehose_client_set_context(firehose_client_t client, void *ctxt);
 203
 204 /*!
 205  * @function firehose_client_metadata_stream_peek
 206  *
 207  * @abstract
 208  * Peek at the metadata stream in flight buffers for a given client
 209  *
 210  * @discussion
 211  * This function should never be called from the context of a snapshot
 212  * handler.
 213  *
 214  * @param client
 215  * The specified client
 216  *
 217  * @param context
 218  * If this function is called synchronously from the handler passed to
 219  * firehose_server_init, then `context` should be the event being processed.
 220  * Else pass FIREHOSE_EVENT_NONE.
 221  *
 222  * @param peek_should_start
 223  * Handler that is called prior to peeking to solve the race of metadata
 224  * buffers not beeing processed yet at first lookup time, and being processed
 225  * before the peek enumeration starts.
 226  *
 227  * If the handler returns false, then the enumeration doesn't start.
 228  * If the race cannot happen, pass NULL.
 229  *
 230  * @param peek
 231  * Handler that will receive all the live metadata buffers for this process.
 232  * If the handler returns false, the enumeration is interrupted.
 233  */
 234 OS_NOTHROW OS_NONNULL1 OS_NONNULL4
 235 void
 236 firehose_client_metadata_stream_peek(firehose_client_t client,
 237                 firehose_event_t context, OS_NOESCAPE bool (^peek_should_start)(void),
 238                 OS_NOESCAPE bool (^peek)(firehose_buffer_chunk_t fbc));
 239
 240 #pragma mark - Firehose Server
 241
 242 /*!
 243  * @typedef firehose_handler_t
 244  *
 245  * @abstract
 246  * Type of the handler block for firehose_server_init()
 247  */
 248 typedef void (^firehose_handler_t)(firehose_client_t client,
 249                 firehose_event_t event, firehose_buffer_chunk_t page);
 250
 251 /*!
 252  * @function firehose_server_init
 253  *
 254  * @abstract
 255  * Initializes the firehose MiG server
 256  *
 257  * @discussion
 258  * Initializes the firehose MiG server by boostrap registering the services
 259  * and creating dispatch_sources for the same.
 260  */
 261 OS_NOTHROW
 262 void
 263 firehose_server_init(mach_port_t firehose_comm_port,
 264                 firehose_handler_t handler);
 265
 266 /*!
 267  * @function firehose_server_assert_spi_version
 268  *
 269  * @abstract
 270  * Checks that libdispatch and firehose components all match
 271  *
 272  * @discussion
 273  * Will assert that all the components have the same SPI versions
 274  */
 275 OS_NOTHROW
 276 void
 277 firehose_server_assert_spi_version(uint32_t spi_version);
 278
 279 /*!
 280  * @function firehose_server_resume
 281  *
 282  * @abstract
 283  * Allows firehose events to flow
 284  *
 285  * @discussion
 286  * Must be called after firehose_server_init()
 287  */
 288 OS_NOTHROW
 289 void
 290 firehose_server_resume(void);
 291
 292 #pragma mark - Firehose Snapshot
 293
 294 /*!
 295  * @typedef firehose_snapshot_event
 296  *
 297  */
 298 OS_ENUM(firehose_snapshot_event, unsigned long,
 299         FIREHOSE_SNAPSHOT_EVENT_IO_START = 1,
 300         FIREHOSE_SNAPSHOT_EVENT_MEM_START,
 301         FIREHOSE_SNAPSHOT_EVENT_IO_BUFFER,
 302         FIREHOSE_SNAPSHOT_EVENT_MEM_BUFFER,
 303         FIREHOSE_SNAPSHOT_EVENT_COMPLETE,
 304 );
 305
 306 /*!
 307  * @typedef firehose_snapshot_handler_t
 308  *
 309  * @abstract
 310  * Type of the handler block for firehose_snapshot
 311  */
 312 typedef void (^firehose_snapshot_handler_t)(firehose_client_t client,
 313                 firehose_snapshot_event_t event, firehose_buffer_chunk_t page);
 314
 315 /*!
 316  * @function firehose_snapshot
 317  *
 318  * @abstract
 319  * Gather a snapshot for the current firehose state.
 320  *
 321  * @discussion
 322  * This function can be called several times, in which case snapshots are taken
 323  * one after the other. If coalescing is desired, it has to be built around this
 324  * call.
 325  */
 326 OS_NOTHROW
 327 void
 328 firehose_snapshot(firehose_snapshot_handler_t handler);
 329
 330 #endif // OS_FIREHOSE_SPI
 331
 332 #endif // __FIREHOSE_SERVER_PRIVATE__