release/src/router/apcupsd/include/drivers.h

   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., 59 Temple Place - Suite 330, Boston,
  23  * MA 02111-1307, 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  * ups_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 typedef struct upsdriver {
  94    /* Data side of the driver structure. */
  95    const char *driver_name;
  96
  97    /* Functions side of the driver structure. */
  98    int (*open) (UPSINFO *ups);
  99    int (*setup) (UPSINFO *ups);
 100    int (*close) (UPSINFO *ups);
 101    int (*kill_power) (UPSINFO *ups);
 102    int (*shutdown) (UPSINFO *ups);
 103    int (*read_ups_static_data) (UPSINFO *ups);
 104    int (*read_ups_volatile_data) (UPSINFO *ups);
 105    int (*get_ups_capabilities) (UPSINFO *ups);
 106    int (*check_ups_state) (UPSINFO *ups);
 107    int (*ups_program_eeprom) (UPSINFO *ups, int command, const char *data);
 108    int (*ups_entry_point) (UPSINFO *ups, int command, void *data);
 109 } UPSDRIVER;
 110
 111 /* Some defines that helps code readability. */
 112 #define device_open(ups) \
 113    do { \
 114       if (ups->driver) ups->driver->open(ups); \
 115    } while(0)
 116 #define device_setup(ups) \
 117    do { \
 118       if (ups->driver) ups->driver->setup(ups); \
 119    } while(0)
 120 #define device_close(ups) \
 121    do { \
 122       if (ups->driver) ups->driver->close(ups); \
 123    } while(0)
 124 #define device_kill_power(ups) \
 125    do { \
 126       if (ups->driver) ups->driver->kill_power(ups); \
 127    } while(0)
 128 #define device_shutdown(ups) \
 129    do { \
 130       if (ups->driver) { \
 131          if (ups->driver->shutdown) { \
 132             ups->driver->shutdown(ups); \
 133          } else { \
 134             Dmsg1(000, "Power off not supported for %s driver\n", \
 135                        ups->driver->driver_name); \
 136          } \
 137       } \
 138    } while(0)
 139 #define device_read_static_data(ups) \
 140    do { \
 141       if (ups->driver) ups->driver->read_ups_static_data(ups); \
 142    } while(0)
 143 #define device_read_volatile_data(ups) \
 144    do { \
 145       if (ups->driver) ups->driver->read_ups_volatile_data(ups); \
 146    } while(0)
 147 #define device_get_capabilities(ups) \
 148    do { \
 149       if (ups->driver) ups->driver->get_ups_capabilities(ups); \
 150    } while(0)
 151 #define device_check_state(ups) \
 152    do { \
 153       if (ups->driver) ups->driver->check_ups_state(ups); \
 154    } while(0)
 155 #define device_program_eeprom(ups, command, data) \
 156    do { \
 157       if (ups->driver) ups->driver->ups_program_eeprom(ups, command, data); \
 158    } while(0)
 159 #define device_entry_point(ups, command, data) \
 160    do { \
 161       if (ups->driver) ups->driver->ups_entry_point(ups, command, data); \
 162    } while(0)
 163
 164 /* Now some defines for device_entry_point commands. */
 165
 166 /* Dumb entry points. */
 167 #define DEVICE_CMD_DTR_ENABLE       0x00
 168 #define DEVICE_CMD_DTR_ST_DISABLE   0x01
 169
 170 /* Smart entry points. */
 171 #define DEVICE_CMD_GET_SELFTEST_MSG 0x02
 172 #define DEVICE_CMD_CHECK_SELFTEST   0x03
 173 #define DEVICE_CMD_SET_DUMB_MODE    0x04
 174
 175 /* Support routines. */
 176 const UPSDRIVER *attach_driver(UPSINFO *ups);
 177
 178 #endif /*_DRIVERS_H */