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_pid_version
 144  *
 145  * @abstract
 146  * Returns the pid version for that client.
 147  *
 148  * @param client
 149  * The specified client.
 150  */
 151 OS_NOTHROW OS_NONNULL1
 152 int
 153 firehose_client_get_pid_version(firehose_client_t client);
 154
 155 /*!
 156  * @function firehose_client_get_euid
 157  *
 158  * @abstract
 159  * Returns the EUID for that client as discovered at connect time.
 160  *
 161  * @param client
 162  * The specified client.
 163  */
 164 OS_NOTHROW OS_NONNULL1
 165 uid_t
 166 firehose_client_get_euid(firehose_client_t client);
 167
 168 /*!
 169  * @function firehose_client_get_metadata_buffer
 170  *
 171  * @abstract
 172  * Returns the metadata buffer for the specified firehose client
 173  *
 174  * @param client
 175  * The specified client.
 176  *
 177  * @param size
 178  * The size of the metadata buffer.
 179  *
 180  * @returns
 181  * The pointer to the buffer.
 182  */
 183 OS_NOTHROW OS_NONNULL_ALL
 184 void *
 185 firehose_client_get_metadata_buffer(firehose_client_t client, size_t *size);
 186
 187 /*!
 188  * @function firehose_client_get_context
 189  *
 190  * @abstract
 191  * Gets the context for the specified client.
 192  *
 193  * @param client
 194  * The specified client.
 195  *
 196  * @returns
 197  * The context set for the client with firehose_client_set_context
 198  */
 199 OS_NOTHROW OS_NONNULL1
 200 void *
 201 firehose_client_get_context(firehose_client_t client);
 202
 203 /*!
 204  * @function firehose_client_set_context
 205  *
 206  * @abstract
 207  * Sets the context for the specified client.
 208  *
 209  * @discussion
 210  * Setting the context exchanges the context pointer, but the client must
 211  * ensure proper synchronization with possible getters.
 212  *
 213  * The lifetime of the context is under the control of the API user,
 214  * it is suggested to destroy the context when the CLIENT_DIED event is
 215  * received.
 216  *
 217  * @param client
 218  * The specified client.
 219  *
 220  * @param ctxt
 221  * The new context to set.
 222  *
 223  * @returns
 224  * The previous context set for the client.
 225  */
 226 OS_NOTHROW OS_NONNULL1
 227 void *
 228 firehose_client_set_context(firehose_client_t client, void *ctxt);
 229
 230 /*!
 231  * @function firehose_client_metadata_stream_peek
 232  *
 233  * @abstract
 234  * Peek at the metadata stream in flight buffers for a given client
 235  *
 236  * @discussion
 237  * This function should never be called from the context of a snapshot
 238  * handler.
 239  *
 240  * @param client
 241  * The specified client
 242  *
 243  * @param context
 244  * If this function is called synchronously from the handler passed to
 245  * firehose_server_init, then `context` should be the event being processed.
 246  * Else pass FIREHOSE_EVENT_NONE.
 247  *
 248  * @param peek_should_start
 249  * Handler that is called prior to peeking to solve the race of metadata
 250  * buffers not beeing processed yet at first lookup time, and being processed
 251  * before the peek enumeration starts.
 252  *
 253  * If the handler returns false, then the enumeration doesn't start.
 254  * If the race cannot happen, pass NULL.
 255  *
 256  * @param peek
 257  * Handler that will receive all the live metadata buffers for this process.
 258  * If the handler returns false, the enumeration is interrupted.
 259  */
 260 OS_NOTHROW OS_NONNULL1 OS_NONNULL4
 261 void
 262 firehose_client_metadata_stream_peek(firehose_client_t client,
 263                 firehose_event_t context, OS_NOESCAPE bool (^peek_should_start)(void),
 264                 OS_NOESCAPE bool (^peek)(firehose_chunk_t fbc));
 265
 266 #pragma mark - Firehose Server
 267
 268 /*!
 269  * @typedef firehose_handler_t
 270  *
 271  * @abstract
 272  * Type of the handler block for firehose_server_init()
 273  */
 274 typedef void (^firehose_handler_t)(firehose_client_t client,
 275                 firehose_event_t event, firehose_chunk_t page);
 276
 277 /*!
 278  * @function firehose_server_init
 279  *
 280  * @abstract
 281  * Initializes the firehose MiG server
 282  *
 283  * @discussion
 284  * Initializes the firehose MiG server by boostrap registering the services
 285  * and creating dispatch_sources for the same.
 286  */
 287 OS_NOTHROW
 288 void
 289 firehose_server_init(mach_port_t firehose_comm_port,
 290                 firehose_handler_t handler);
 291
 292 /*!
 293  * @function firehose_server_assert_spi_version
 294  *
 295  * @abstract
 296  * Checks that libdispatch and firehose components all match
 297  *
 298  * @discussion
 299  * Will assert that all the components have the same SPI versions
 300  */
 301 OS_NOTHROW
 302 void
 303 firehose_server_assert_spi_version(uint32_t spi_version);
 304
 305 /*!
 306  * @function firehose_server_has_ever_flushed_pages
 307  *
 308  * @abstract
 309  * Checks whether the firehose server has ever flushed any pages this boot.
 310  *
 311  * @discussion
 312  * Must be called after firehose_server_init() and before calling
 313  * firehose_server_resume().
 314  */
 315 OS_NOTHROW
 316 bool
 317 firehose_server_has_ever_flushed_pages(void);
 318
 319 /*!
 320  * @function firehose_server_resume
 321  *
 322  * @abstract
 323  * Allows firehose events to flow
 324  *
 325  * @discussion
 326  * Must be called after firehose_server_init()
 327  */
 328 OS_NOTHROW
 329 void
 330 firehose_server_resume(void);
 331
 332 /*!
 333  * @function firehose_server_cancel
 334  *
 335  * @abstract
 336  * Cancels the server, disconnects all clients, and prevents new connections.
 337  */
 338 OS_NOTHROW
 339 void
 340 firehose_server_cancel(void);
 341
 342 /*!
 343  * @typedef firehose_server_queue_t
 344  *
 345  * @abstract
 346  * Values to pass to firehose_server_get_queue()
 347  */
 348 OS_ENUM(firehose_server_queue, unsigned long,
 349         FIREHOSE_SERVER_QUEUE_UNKNOWN,
 350         FIREHOSE_SERVER_QUEUE_IO,
 351         FIREHOSE_SERVER_QUEUE_MEMORY,
 352 );
 353
 354 /*!
 355  * @function firehose_server_copy_queue
 356  *
 357  * @abstract
 358  * Returns internal queues to the firehose server subsystem.
 359  */
 360 OS_NOTHROW OS_OBJECT_RETURNS_RETAINED
 361 dispatch_queue_t
 362 firehose_server_copy_queue(firehose_server_queue_t which);
 363
 364 #pragma mark - Firehose Snapshot
 365
 366 /*!
 367  * @typedef firehose_snapshot_event
 368  */
 369 OS_ENUM(firehose_snapshot_event, unsigned long,
 370         FIREHOSE_SNAPSHOT_EVENT_IO_START = 1,
 371         FIREHOSE_SNAPSHOT_EVENT_MEM_START,
 372         FIREHOSE_SNAPSHOT_EVENT_IO_BUFFER,
 373         FIREHOSE_SNAPSHOT_EVENT_MEM_BUFFER,
 374         FIREHOSE_SNAPSHOT_EVENT_COMPLETE,
 375 );
 376
 377 /*!
 378  * @typedef firehose_snapshot_handler_t
 379  *
 380  * @abstract
 381  * Type of the handler block for firehose_snapshot
 382  */
 383 typedef void (^firehose_snapshot_handler_t)(firehose_client_t client,
 384                 firehose_snapshot_event_t event, firehose_chunk_t page);
 385
 386 /*!
 387  * @function firehose_snapshot
 388  *
 389  * @abstract
 390  * Gather a snapshot for the current firehose state.
 391  *
 392  * @discussion
 393  * This function can be called several times, in which case snapshots are taken
 394  * one after the other. If coalescing is desired, it has to be built around this
 395  * call.
 396  */
 397 OS_NOTHROW
 398 void
 399 firehose_snapshot(firehose_snapshot_handler_t handler);
 400
 401 #endif // OS_FIREHOSE_SPI
 402
 403 #endif // __FIREHOSE_SERVER_PRIVATE__