Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 1 | // Copyright (c) 2012 The Chromium OS Authors. All rights reserved. |
| 2 | // Use of this source code is governed by a BSD-style license that can be |
| 3 | // found in the LICENSE file. |
| 4 | |
| 5 | #ifndef CHROMEOS_PLATFORM_UPDATE_ENGINE_GPIO_HANDLER_H__ |
| 6 | #define CHROMEOS_PLATFORM_UPDATE_ENGINE_GPIO_HANDLER_H__ |
| 7 | |
| 8 | #include <libudev.h> |
| 9 | |
| 10 | #include <string> |
| 11 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 12 | #include <base/time.h> |
| 13 | |
| 14 | #include "update_engine/file_descriptor.h" |
| 15 | #include "update_engine/udev_interface.h" |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 16 | |
| 17 | namespace chromeos_update_engine { |
| 18 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 19 | // An abstract GPIO handler interface. Serves as basic for both concrete and |
| 20 | // mock implementations. |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 21 | class GpioHandler { |
| 22 | public: |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 23 | GpioHandler() {} |
| 24 | virtual ~GpioHandler() {}; // ensure virtual destruction |
| 25 | |
| 26 | // Returns true iff GPIOs have been used to signal an automated test case. |
| 27 | // This call may trigger a (deferred) GPIO discovery step prior to engaging in |
| 28 | // the signaling protocol; if discovery did not reveal GPIO devices, or the |
| 29 | // protocol has terminated prematurely, it will conservatively default to |
| 30 | // false. |
| 31 | virtual bool IsTestModeSignaled() = 0; |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 32 | |
| 33 | private: |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 34 | DISALLOW_COPY_AND_ASSIGN(GpioHandler); |
| 35 | }; |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 36 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 37 | |
| 38 | // Concrete implementation of GPIO signal handling. Currently, it only utilizes |
| 39 | // the two Chromebook-specific GPIOs (aka 'dut_flaga' and 'dut_flagb') in |
| 40 | // deciding whether a lab test mode has been signaled. Internal logic includes |
| 41 | // detection, setup and reading from / writing to GPIOs. Detection is done via |
| 42 | // libudev calls. This class should be instantiated at most once to avoid race |
| 43 | // conditions in communicating over GPIO signals; instantiating a second |
| 44 | // object will actually cause a runtime error. |
| 45 | class StandardGpioHandler : public GpioHandler { |
| 46 | public: |
Gilad Arnold | 6eccc53 | 2012-05-17 15:44:22 -0700 | [diff] [blame] | 47 | // This constructor accepts a udev interface |udev_iface| and a reusable file |
| 48 | // descriptor |fd|. The value of |is_defer_discovery| determines whether GPIO |
| 49 | // discovery should be attempted right away (false) or done lazily, when |
| 50 | // necessitated by other calls (true). If |is_cache_test_mode| is true, |
| 51 | // checking for test mode signal is done only once and further queries return |
| 52 | // the cached result. |
| 53 | StandardGpioHandler(UdevInterface* udev_iface, FileDescriptor* fd, |
| 54 | bool is_defer_discovery, bool is_cache_test_mode); |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 55 | |
| 56 | // Free all resources, allow to reinstantiate. |
| 57 | virtual ~StandardGpioHandler(); |
| 58 | |
| 59 | // Returns true iff GPIOs have been used to signal an automated test case. The |
| 60 | // check is performed at most once and the result is cached and returned on |
| 61 | // subsequent calls, unless |is_force| is true. This call may trigger a |
| 62 | // delayed GPIO discovery prior to engaging in the signaling protocol; if the |
| 63 | // delay period has not elapsed, it will conservatively default to false. |
| 64 | virtual bool IsTestModeSignaled(); |
| 65 | |
| 66 | private: |
| 67 | // GPIO identifiers, currently includes only the two dutflags. |
| 68 | enum GpioId { |
| 69 | kGpioIdDutflaga = 0, |
| 70 | kGpioIdDutflagb, |
| 71 | kGpioIdMax // marker, do not remove! |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 72 | }; |
| 73 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 74 | // GPIO direction specifier. |
| 75 | enum GpioDir { |
| 76 | kGpioDirIn = 0, |
| 77 | kGpioDirOut, |
| 78 | kGpioDirMax // marker, do not remove! |
| 79 | }; |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 80 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 81 | // GPIO value. |
| 82 | enum GpioVal { |
| 83 | kGpioValUp = 0, |
| 84 | kGpioValDown, |
| 85 | kGpioValMax // marker, do not remove! |
| 86 | }; |
| 87 | |
| 88 | // GPIO definition data. |
| 89 | struct GpioDef { |
| 90 | const char* name; // referential name of this GPIO |
| 91 | const char* udev_property; // udev property containing the device id |
| 92 | }; |
| 93 | |
| 94 | // GPIO runtime control structure. |
| 95 | struct Gpio { |
| 96 | std::string descriptor; // unique GPIO descriptor |
| 97 | std::string dev_path; // sysfs device name |
| 98 | }; |
| 99 | |
Gilad Arnold | 6eccc53 | 2012-05-17 15:44:22 -0700 | [diff] [blame] | 100 | // The number of seconds we wait before flipping the output signal (aka, |
| 101 | // producing the "challenge" signal). Assuming a 1 second sampling frequency |
| 102 | // on the servo side, a two second wait should be enough. |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 103 | static const int kServoOutputResponseWaitInSecs = 2; |
| 104 | |
Gilad Arnold | 6eccc53 | 2012-05-17 15:44:22 -0700 | [diff] [blame] | 105 | // The total number of seconds we wait for a servo response from the point we |
| 106 | // flip the output signal. Assuming a 1 second sampling frequency on the servo |
| 107 | // side, a two second wait should suffice. We add one more second for grace |
| 108 | // (servod / hardware processing delays, etc). |
| 109 | static const int kServoInputResponseTimeoutInSecs = 3; |
| 110 | |
| 111 | // The number of times per second we check for a servo response. Five seems |
| 112 | // like a reasonable value. |
| 113 | static const int kServoInputNumChecksPerSec = 5; |
| 114 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 115 | // GPIO value/direction conversion tables. |
| 116 | static const char* gpio_dirs_[kGpioDirMax]; |
| 117 | static const char* gpio_vals_[kGpioValMax]; |
| 118 | |
| 119 | // GPIO definitions. |
| 120 | static const GpioDef gpio_defs_[kGpioIdMax]; |
| 121 | |
| 122 | // Udev device enumeration helper classes. First here is an interface |
| 123 | // definition, which provides callbacks for enumeration setup and processing. |
| 124 | class UdevEnumHelper { |
| 125 | public: |
| 126 | UdevEnumHelper(StandardGpioHandler* gpio_handler) |
| 127 | : gpio_handler_(gpio_handler) {} |
| 128 | |
| 129 | // Setup the enumeration filters. |
| 130 | virtual bool SetupEnumFilters(udev_enumerate* udev_enum) = 0; |
| 131 | |
| 132 | // Processes an enumerated device. Returns true upon success, false |
| 133 | // otherwise. |
| 134 | virtual bool ProcessDev(udev_device* dev) = 0; |
| 135 | |
| 136 | // Finalize the enumeration. |
| 137 | virtual bool Finalize() = 0; |
| 138 | |
| 139 | protected: |
| 140 | StandardGpioHandler* gpio_handler_; |
| 141 | |
| 142 | private: |
| 143 | DISALLOW_COPY_AND_ASSIGN(UdevEnumHelper); |
| 144 | }; |
| 145 | |
| 146 | // Specialized udev enumerate helper for extracting GPIO descriptors from the |
| 147 | // GPIO chip device. |
| 148 | class GpioChipUdevEnumHelper : public UdevEnumHelper { |
| 149 | public: |
| 150 | GpioChipUdevEnumHelper(StandardGpioHandler* gpio_handler) |
| 151 | : UdevEnumHelper(gpio_handler), num_gpio_chips_(0) {} |
| 152 | virtual bool SetupEnumFilters(udev_enumerate* udev_enum); |
| 153 | virtual bool ProcessDev(udev_device* dev); |
| 154 | virtual bool Finalize(); |
| 155 | |
| 156 | private: |
| 157 | // Records the number of times a GPIO chip has been enumerated (should not |
| 158 | // exceed 1). |
| 159 | int num_gpio_chips_; |
| 160 | |
| 161 | DISALLOW_COPY_AND_ASSIGN(GpioChipUdevEnumHelper); |
| 162 | }; |
| 163 | |
| 164 | // Specialized udev enumerate helper for extracting a sysfs device path from a |
| 165 | // GPIO device. |
| 166 | class GpioUdevEnumHelper : public UdevEnumHelper { |
| 167 | public: |
| 168 | GpioUdevEnumHelper(StandardGpioHandler* gpio_handler, GpioId id) |
| 169 | : UdevEnumHelper(gpio_handler), num_gpios_(0), id_(id) {} |
| 170 | virtual bool SetupEnumFilters(udev_enumerate* udev_enum); |
| 171 | virtual bool ProcessDev(udev_device* dev); |
| 172 | virtual bool Finalize(); |
| 173 | |
| 174 | private: |
| 175 | // Records the number of times a GPIO has been enumerated with a given |
| 176 | // descriptor (should not exceed 1). |
| 177 | int num_gpios_; |
| 178 | |
| 179 | // The enumerated GPIO identifier. |
| 180 | GpioId id_; |
| 181 | |
| 182 | DISALLOW_COPY_AND_ASSIGN(GpioUdevEnumHelper); |
| 183 | }; |
| 184 | |
Gilad Arnold | 6eccc53 | 2012-05-17 15:44:22 -0700 | [diff] [blame] | 185 | // Helper class for resetting a GPIO direction. |
| 186 | class GpioDirResetter { |
| 187 | public: |
| 188 | GpioDirResetter(StandardGpioHandler* handler, GpioId id, GpioDir dir); |
| 189 | ~GpioDirResetter(); |
| 190 | |
| 191 | bool do_reset() const { |
| 192 | return do_reset_; |
| 193 | } |
| 194 | bool set_do_reset(bool do_reset) { |
| 195 | return (do_reset_ = do_reset); |
| 196 | } |
| 197 | |
| 198 | private: |
| 199 | // Determines whether or not the GPIO direction should be reset to the |
| 200 | // initial value. |
| 201 | bool do_reset_; |
| 202 | |
| 203 | // The GPIO handler to use for changing the GPIO direction. |
| 204 | StandardGpioHandler* handler_; |
| 205 | |
| 206 | // The GPIO identifier and initial direction. |
| 207 | GpioId id_; |
| 208 | GpioDir dir_; |
| 209 | }; |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 210 | |
| 211 | // An initialization helper performing udev enumeration. |enum_helper| |
| 212 | // implements an enumeration initialization and processing methods. Returns |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 213 | // true upon success, false otherwise. |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 214 | bool InitUdevEnum(struct udev* udev, UdevEnumHelper* enum_helper); |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 215 | |
Gilad Arnold | 6eccc53 | 2012-05-17 15:44:22 -0700 | [diff] [blame] | 216 | // Resets the object's flags which determine the status of test mode |
| 217 | // signaling. |
| 218 | void ResetTestModeSignalingFlags(); |
| 219 | |
| 220 | // Attempt GPIO discovery, at most once. Returns true if discovery process was |
| 221 | // successfully completed or already attempted, false otherwise. |
| 222 | bool DiscoverGpios(); |
| 223 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 224 | // Assigns a copy of the device name of GPIO |id| to |dev_path_p|. Assumes |
| 225 | // initialization. Returns true upon success, false otherwise. |
| 226 | bool GetGpioDevName(GpioId id, std::string* dev_path_p); |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 227 | |
Gilad Arnold | 6eccc53 | 2012-05-17 15:44:22 -0700 | [diff] [blame] | 228 | // Open a sysfs file device |dev_name| of GPIO |id|, for either reading or |
| 229 | // writing depending on |is_write|. Uses the internal file descriptor for |
| 230 | // this purpose, which can be reused as long as it is closed between |
| 231 | // successive opens. Returns true upon success, false otherwise (optionally, |
| 232 | // with errno set accordingly). |
| 233 | bool OpenGpioFd(GpioId id, const char* dev_name, bool is_write); |
| 234 | |
| 235 | // Writes a value to device |dev_name| of GPIO |id|. The index |output| is |
| 236 | // used to index the corresponding string to be written from the list |
| 237 | // |entries| of length |num_entries|. Returns true upon success, false |
| 238 | // otherwise. |
| 239 | bool SetGpio(GpioId id, const char* dev_name, const char* entries[], |
| 240 | const int num_entries, int output); |
| 241 | |
| 242 | // Reads a value from device |dev_name| of GPIO |id|. The list |entries| of |
| 243 | // length |num_entries| is used to convert the read string into an index, |
| 244 | // which is written to |input_p|. The call will fail if the value being read |
| 245 | // is not listed in |entries|. Returns true upon success, false otherwise. |
| 246 | bool GetGpio(GpioId id, const char* dev_name, const char* entries[], |
| 247 | const int num_entries, int* input_p); |
| 248 | |
| 249 | // Sets GPIO |id| to to operate in a given |direction|. Assumes |
| 250 | // initialization. Returns true on success, false otherwise. |
| 251 | bool SetGpioDirection(GpioId id, GpioDir direction); |
| 252 | |
| 253 | // Assigns the current direction of GPIO |id| into |direction_p|. Assumes |
| 254 | // initialization. Returns true on success, false otherwise. |
| 255 | bool GetGpioDirection(GpioId id, GpioDir* direction_p); |
| 256 | |
| 257 | // Sets the value of GPIO |id| to |value|. Assumues initialization. The GPIO |
| 258 | // direction should be set to 'out' prior to this call. If |
| 259 | // |is_check_direction| is true, it'll ensure that the direction is indeed |
| 260 | // 'out' prior to attempting the write. Returns true on success, false |
| 261 | // otherwise. |
| 262 | bool SetGpioValue(GpioId id, GpioVal value, bool is_check_direction); |
| 263 | |
| 264 | // Reads the value of a GPIO |id| and stores it in |value_p|. Assumes |
| 265 | // initialization. The GPIO direction should be set to 'in' prior to this |
| 266 | // call. If |is_check_direction| is true, it'll ensure that the direction is |
| 267 | // indeed 'in' prior to attempting the read. Returns true upon success, false |
| 268 | // otherwise. |
| 269 | bool GetGpioValue(GpioId id, GpioVal *value_p, bool is_check_direction); |
| 270 | |
| 271 | // Invokes the actual GPIO handshake protocol to determine whether test mode |
| 272 | // was signaled. Returns true iff the handshake has terminated gracefully |
| 273 | // without encountering any errors; note that a true value does *not* mean |
| 274 | // that a test mode signal has been detected. The spec for this protocol: |
| 275 | // https://docs.google.com/a/google.com/document/d/1DB-35ptck1wT1TYrgS5AC5Y3ALfHok-iPA7kLBw2XCI/edit |
| 276 | bool DoTestModeSignalingProtocol(); |
| 277 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 278 | // Dynamic counter for the number of instances this class has. Used to enforce |
| 279 | // that no more than one instance created. Thread-unsafe. |
| 280 | static unsigned num_instances_; |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 281 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 282 | // GPIO control structures. |
| 283 | Gpio gpios_[kGpioIdMax]; |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 284 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 285 | // Udev interface. |
| 286 | UdevInterface* const udev_iface_; |
| 287 | |
Gilad Arnold | 6eccc53 | 2012-05-17 15:44:22 -0700 | [diff] [blame] | 288 | // A file abstraction for handling GPIO devices. |
| 289 | FileDescriptor* const fd_; |
| 290 | |
| 291 | // Determines whether test mode signal should be checked at most once and |
| 292 | // cached, or reestablished on each query. |
| 293 | const bool is_cache_test_mode_; |
| 294 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 295 | // Indicates whether GPIO discovery was performed. |
| 296 | bool is_discovery_attempted_; |
| 297 | |
Gilad Arnold | 6eccc53 | 2012-05-17 15:44:22 -0700 | [diff] [blame] | 298 | // Persistent state of the test mode check. |
| 299 | bool is_first_check_; |
| 300 | bool is_handshake_completed_; |
| 301 | bool is_test_mode_; |
| 302 | |
Gilad Arnold | 4d740eb | 2012-05-15 08:48:13 -0700 | [diff] [blame] | 303 | DISALLOW_COPY_AND_ASSIGN(StandardGpioHandler); |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 304 | }; |
| 305 | |
Gilad Arnold | bf7919b | 2013-01-08 13:07:37 -0800 | [diff] [blame^] | 306 | |
| 307 | // A "no-op" GPIO handler, initialized to return either test or normal mode |
| 308 | // signal. This is useful for disabling the GPIO functionality in production |
| 309 | // code. |
| 310 | class NoopGpioHandler : public GpioHandler { |
| 311 | public: |
| 312 | // This constructor accepts a single argument, which is the value to be |
| 313 | // returned by repeated calls to IsTestModeSignaled(). |
| 314 | NoopGpioHandler(bool is_test_mode) : is_test_mode_(is_test_mode) {} |
| 315 | |
| 316 | // Returns the constant Boolean value handed to the constructor. |
| 317 | virtual bool IsTestModeSignaled(); |
| 318 | |
| 319 | private: |
| 320 | // Stores the constant value to return on subsequent test mode checks. |
| 321 | bool is_test_mode_; |
| 322 | |
| 323 | DISALLOW_COPY_AND_ASSIGN(NoopGpioHandler); |
| 324 | }; |
| 325 | |
Gilad Arnold | 1ebd813 | 2012-03-05 10:19:29 -0800 | [diff] [blame] | 326 | } // namespace chromeos_update_engine |
| 327 | |
| 328 | #endif // CHROMEOS_PLATFORM_UPDATE_ENGINE_GPIO_HANDLER_H__ |