drivers/staging/media/atomisp/pci/atomisp2/css2400/ia_css_event_public.h

   1 /*
   2  * Support for Intel Camera Imaging ISP subsystem.
   3  * Copyright (c) 2015, Intel Corporation.
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms and conditions of the GNU General Public License,
   7  * version 2, as published by the Free Software Foundation.
   8  *
   9  * This program is distributed in the hope it will be useful, but WITHOUT
  10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  12  * more details.
  13  */
  14
  15 #ifndef __IA_CSS_EVENT_PUBLIC_H
  16 #define __IA_CSS_EVENT_PUBLIC_H
  17
  18 /* @file
  19  * This file contains CSS-API events functionality
  20  */
  21
  22 #include <type_support.h>       /* uint8_t */
  23 #include <ia_css_err.h>         /* ia_css_err */
  24 #include <ia_css_types.h>       /* ia_css_pipe */
  25 #include <ia_css_timer.h>       /* ia_css_timer */
  26
  27 /* The event type, distinguishes the kind of events that
  28  * can are generated by the CSS system.
  29  *
  30  * !!!IMPORTANT!!! KEEP THE FOLLOWING IN SYNC:
  31  * 1) "enum ia_css_event_type"                                  (ia_css_event_public.h)
  32  * 2) "enum sh_css_sp_event_type"                               (sh_css_internal.h)
  33  * 3) "enum ia_css_event_type event_id_2_event_mask"            (event_handler.sp.c)
  34  * 4) "enum ia_css_event_type convert_event_sp_to_host_domain"  (sh_css.c)
  35  */
  36 enum ia_css_event_type {
  37         IA_CSS_EVENT_TYPE_OUTPUT_FRAME_DONE             = 1 << 0,
  38         /** Output frame ready. */
  39         IA_CSS_EVENT_TYPE_SECOND_OUTPUT_FRAME_DONE      = 1 << 1,
  40         /** Second output frame ready. */
  41         IA_CSS_EVENT_TYPE_VF_OUTPUT_FRAME_DONE          = 1 << 2,
  42         /** Viewfinder Output frame ready. */
  43         IA_CSS_EVENT_TYPE_SECOND_VF_OUTPUT_FRAME_DONE   = 1 << 3,
  44         /** Second viewfinder Output frame ready. */
  45         IA_CSS_EVENT_TYPE_3A_STATISTICS_DONE            = 1 << 4,
  46         /** Indication that 3A statistics are available. */
  47         IA_CSS_EVENT_TYPE_DIS_STATISTICS_DONE           = 1 << 5,
  48         /** Indication that DIS statistics are available. */
  49         IA_CSS_EVENT_TYPE_PIPELINE_DONE                 = 1 << 6,
  50         /** Pipeline Done event, sent after last pipeline stage. */
  51         IA_CSS_EVENT_TYPE_FRAME_TAGGED                  = 1 << 7,
  52         /** Frame tagged. */
  53         IA_CSS_EVENT_TYPE_INPUT_FRAME_DONE              = 1 << 8,
  54         /** Input frame ready. */
  55         IA_CSS_EVENT_TYPE_METADATA_DONE                 = 1 << 9,
  56         /** Metadata ready. */
  57         IA_CSS_EVENT_TYPE_LACE_STATISTICS_DONE          = 1 << 10,
  58         /** Indication that LACE statistics are available. */
  59         IA_CSS_EVENT_TYPE_ACC_STAGE_COMPLETE            = 1 << 11,
  60         /** Extension stage complete. */
  61         IA_CSS_EVENT_TYPE_TIMER                         = 1 << 12,
  62         /** Timer event for measuring the SP side latencies. It contains the
  63              32-bit timer value from the SP */
  64         IA_CSS_EVENT_TYPE_PORT_EOF                      = 1 << 13,
  65         /** End Of Frame event, sent when in buffered sensor mode. */
  66         IA_CSS_EVENT_TYPE_FW_WARNING                    = 1 << 14,
  67         /** Performance warning encounter by FW */
  68         IA_CSS_EVENT_TYPE_FW_ASSERT                     = 1 << 15,
  69         /** Assertion hit by FW */
  70 };
  71
  72 #define IA_CSS_EVENT_TYPE_NONE 0
  73
  74 /* IA_CSS_EVENT_TYPE_ALL is a mask for all pipe related events.
  75  * The other events (such as PORT_EOF) cannot be enabled/disabled
  76  * and are hence excluded from this macro.
  77  */
  78 #define IA_CSS_EVENT_TYPE_ALL \
  79         (IA_CSS_EVENT_TYPE_OUTPUT_FRAME_DONE            | \
  80          IA_CSS_EVENT_TYPE_SECOND_OUTPUT_FRAME_DONE     | \
  81          IA_CSS_EVENT_TYPE_VF_OUTPUT_FRAME_DONE         | \
  82          IA_CSS_EVENT_TYPE_SECOND_VF_OUTPUT_FRAME_DONE  | \
  83          IA_CSS_EVENT_TYPE_3A_STATISTICS_DONE           | \
  84          IA_CSS_EVENT_TYPE_DIS_STATISTICS_DONE          | \
  85          IA_CSS_EVENT_TYPE_PIPELINE_DONE                | \
  86          IA_CSS_EVENT_TYPE_FRAME_TAGGED                 | \
  87          IA_CSS_EVENT_TYPE_INPUT_FRAME_DONE             | \
  88          IA_CSS_EVENT_TYPE_METADATA_DONE                | \
  89          IA_CSS_EVENT_TYPE_LACE_STATISTICS_DONE         | \
  90          IA_CSS_EVENT_TYPE_ACC_STAGE_COMPLETE)
  91
  92 /* The event struct, container for the event type and its related values.
  93  * Depending on the event type, either pipe or port will be filled.
  94  * Pipeline related events (like buffer/frame events) will return a valid and filled pipe handle.
  95  * For non pipeline related events (but i.e. stream specific, like EOF event), the port will be
  96  * filled.
  97  */
  98 struct ia_css_event {
  99         struct ia_css_pipe    *pipe;
 100         /** Pipe handle on which event happened, NULL for non pipe related
 101              events. */
 102         enum ia_css_event_type type;
 103         /** Type of Event, always valid/filled. */
 104         uint8_t                port;
 105         /** Port number for EOF event (not valid for other events). */
 106         uint8_t                exp_id;
 107         /** Exposure id for EOF/FRAME_TAGGED/FW_WARNING event (not valid for other events)
 108              The exposure ID is unique only within a logical stream and it is
 109              only generated on systems that have an input system (such as 2400
 110              and 2401).
 111              Most outputs produced by the CSS are tagged with an exposure ID.
 112              This allows users of the CSS API to keep track of which buffer
 113              was generated from which sensor output frame. This includes:
 114              EOF event, output frames, 3A statistics, DVS statistics and
 115              sensor metadata.
 116              Exposure IDs start at IA_CSS_MIN_EXPOSURE_ID, increment by one
 117              until IA_CSS_MAX_EXPOSURE_ID is reached, after that they wrap
 118              around to IA_CSS_MIN_EXPOSURE_ID again.
 119              Note that in case frames are dropped, this will not be reflected
 120              in the exposure IDs. Therefor applications should not use this
 121              to detect frame drops. */
 122         uint32_t               fw_handle;
 123         /** Firmware Handle for ACC_STAGE_COMPLETE event (not valid for other
 124              events). */
 125         enum ia_css_fw_warning fw_warning;
 126         /** Firmware warning code, only for WARNING events. */
 127         uint8_t                fw_assert_module_id;
 128         /** Firmware module id, only for ASSERT events, should be logged by driver. */
 129         uint16_t               fw_assert_line_no;
 130         /** Firmware line number, only for ASSERT events, should be logged by driver. */
 131         clock_value_t          timer_data;
 132         /** For storing the full 32-bit of the timer value. Valid only for TIMER
 133              event */
 134         uint8_t                timer_code;
 135         /** For storing the code of the TIMER event. Valid only for
 136              TIMER event */
 137         uint8_t                timer_subcode;
 138         /** For storing the subcode of the TIMER event. Valid only
 139              for TIMER event */
 140 };
 141
 142 /* @brief Dequeue a PSYS event from the CSS system.
 143  *
 144  * @param[out]  event   Pointer to the event struct which will be filled by
 145  *                      this function if an event is available.
 146  * @return              IA_CSS_ERR_QUEUE_IS_EMPTY if no events are
 147  *                      available or
 148  *                      IA_CSS_SUCCESS otherwise.
 149  *
 150  * This function dequeues an event from the PSYS event queue. The queue is
 151  * between the Host CPU and the CSS system. This function can be
 152  * called after an interrupt has been generated that signalled that a new event
 153  * was available and can be used in a polling-like situation where the NO_EVENT
 154  * return value is used to determine whether an event was available or not.
 155  */
 156 enum ia_css_err
 157 ia_css_dequeue_psys_event(struct ia_css_event *event);
 158
 159 /* @brief Dequeue an event from the CSS system.
 160  *
 161  * @param[out]  event   Pointer to the event struct which will be filled by
 162  *                      this function if an event is available.
 163  * @return              IA_CSS_ERR_QUEUE_IS_EMPTY if no events are
 164  *                      available or
 165  *                      IA_CSS_SUCCESS otherwise.
 166  *
 167  * deprecated{Use ia_css_dequeue_psys_event instead}.
 168  * Unless the isys event queue is explicitly enabled, this function will
 169  * dequeue both isys (EOF) and psys events (all others).
 170  */
 171 enum ia_css_err
 172 ia_css_dequeue_event(struct ia_css_event *event);
 173
 174 /* @brief Dequeue an ISYS event from the CSS system.
 175  *
 176  * @param[out]  event   Pointer to the event struct which will be filled by
 177  *                      this function if an event is available.
 178  * @return              IA_CSS_ERR_QUEUE_IS_EMPTY if no events are
 179  *                      available or
 180  *                      IA_CSS_SUCCESS otherwise.
 181  *
 182  * This function dequeues an event from the ISYS event queue. The queue is
 183  * between host and the CSS system.
 184  * Unlike the ia_css_dequeue_event() function, this function can be called
 185  * directly from an interrupt service routine (ISR) and it is safe to call
 186  * this function in parallel with other CSS API functions (but only one
 187  * call to this function should be in flight at any point in time).
 188  *
 189  * The reason for having the ISYS events separate is to prevent them from
 190  * incurring additional latency due to locks being held by other CSS API
 191  * functions.
 192  */
 193 enum ia_css_err
 194 ia_css_dequeue_isys_event(struct ia_css_event *event);
 195
 196 #endif /* __IA_CSS_EVENT_PUBLIC_H */