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