1 /* 2 * drivers.h 3 * 4 * Header file for exporting UPS drivers. 5 */ 6 7 /* 8 * Copyright (C) 1999-2001 Riccardo Facchetti <riccardo@master.oasi.gpa.it> 9 * Copyright (C) 1996-1999 Andre M. Hedrick <andre@suse.com> 10 * 11 * This program is free software; you can redistribute it and/or 12 * modify it under the terms of version 2 of the GNU General 13 * Public License as published by the Free Software Foundation. 14 * 15 * This program is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 18 * General Public License for more details. 19 * 20 * You should have received a copy of the GNU General Public 21 * License along with this program; if not, write to the Free 22 * Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 23 * MA 02110-1335, USA. 24 */ 25 26 #ifndef _DRIVERS_H 27 #define _DRIVERS_H 28 29 /* 30 * This is the generic drivers structure. It contain any routine needed for 31 * managing a device (or family of devices, like Smart UPSes). 32 * 33 * Routines defined: 34 * 35 * open() 36 * Opens the device and setup the file descriptor. Returns a working file 37 * descriptor. This function does not interact with hardware functionality. 38 * In case of error, this function does not return. It simply exit. 39 * 40 * setup() 41 * Setup the device for operations. This function interacts with hardware to 42 * make sure on the other end there is an UPS and that the link is working. 43 * In case of error, this function does not return. It simply exit. 44 * 45 * close() 46 * Closes the device returning it to the original status. 47 * This function always returns. 48 * 49 * kill_power() 50 * Put the UPS into hibernation mode, killing output power. 51 * This function always returns. 52 * 53 * shutdown() 54 * Turn off the UPS completely. 55 * This function always returns. 56 * 57 * read_ups_static_data() 58 * Gets the static data from UPS like the UPS name. 59 * This function always returns. 60 * 61 * read_ups_volatile_data() 62 * Fills UPSINFO with dynamic UPS data. 63 * This function always returns. 64 * This function must lock the UPSINFO structure. 65 * 66 * get_ups_capabilities() 67 * Try to understand what capabilities the UPS is able to perform. 68 * This function always returns. 69 * 70 * check_ups_state() 71 * Check if the UPS changed state. 72 * This function always returns. 73 * This function must lock the UPSINFO structure. 74 * 75 * program_eeprom(ups, command, data) 76 * Commit changes to the internal UPS eeprom. 77 * This function performs the eeprom change command (using data), 78 * then returns. 79 * 80 * ups_generic_entry_point() 81 * This is a generic entry point into the drivers for specific driver 82 * functions called from inside the apcupsd core. 83 * This function always return. 84 * This function must lock the UPSINFO structure. 85 * This function gets a void * that contain data. This pointer can be used 86 * to pass data to the function or to get return values from the function, 87 * depending on the value of "command" and the general design of the specific 88 * command to be executed. 89 * Each driver will have its specific functions and will ignore any 90 * function that does not understand. 91 */ 92 93 class UpsDriver 94 { 95 public: UpsDriver(UPSINFO * ups)96 UpsDriver(UPSINFO *ups) : _ups(ups) {} ~UpsDriver()97 virtual ~UpsDriver() {} 98 99 virtual bool Open() = 0; 100 virtual bool Close() = 0; 101 virtual bool read_static_data() = 0; 102 virtual bool read_volatile_data() = 0; 103 virtual bool get_capabilities() = 0; 104 virtual bool check_state() = 0; 105 setup()106 virtual bool setup() { return true; } kill_power()107 virtual bool kill_power() { return false; } shutdown()108 virtual bool shutdown() { return false; } 109 program_eeprom(int cmd,const char * data)110 virtual bool program_eeprom(int cmd, const char *data) { return false; } entry_point(int cmd,void * data)111 virtual bool entry_point(int cmd, void *data) { return false; } 112 113 protected: 114 UPSINFO *_ups; 115 }; 116 117 typedef struct upsdriver { 118 const char *driver_name; 119 UpsDriver *(* factory) (UPSINFO *ups); 120 } UPSDRIVER; 121 122 123 /* Some defines that helps code readability. */ 124 #define device_open(ups) ups->driver->Open() 125 #define device_setup(ups) ups->driver->setup() 126 #define device_close(ups) ups->driver->Close() 127 #define device_kill_power(ups) ups->driver->kill_power() 128 #define device_shutdown(ups) ups->driver->shutdown() 129 #define device_read_static_data(ups) ups->driver->read_static_data() 130 #define device_read_volatile_data(ups) ups->driver->read_volatile_data() 131 #define device_get_capabilities(ups) ups->driver->get_capabilities() 132 #define device_check_state(ups) ups->driver->check_state() 133 #define device_program_eeprom(ups, command, data) ups->driver->program_eeprom(command, data) 134 #define device_entry_point(ups, command, data) ups->driver->entry_point(command, data) 135 136 /* Now some defines for device_entry_point commands. */ 137 138 /* Dumb entry points. */ 139 #define DEVICE_CMD_DTR_ENABLE 0x00 140 #define DEVICE_CMD_DTR_ST_DISABLE 0x01 141 142 /* Smart entry points. */ 143 #define DEVICE_CMD_GET_SELFTEST_MSG 0x02 144 #define DEVICE_CMD_CHECK_SELFTEST 0x03 145 #define DEVICE_CMD_SET_DUMB_MODE 0x04 146 147 /* Support routines. */ 148 UpsDriver *attach_driver(UPSINFO *ups); 149 150 151 #endif /*_DRIVERS_H */ 152