1 #pragma once
2 
3 #include <filesystem>
4 #include <string>
5 #include <vector>
6 
7 namespace witherspoon
8 {
9 namespace pmbus
10 {
11 
12 namespace fs = std::filesystem;
13 
14 // The file name Linux uses to capture the STATUS_WORD from pmbus.
15 constexpr auto STATUS_WORD = "status0";
16 
17 // The file name Linux uses to capture the STATUS_INPUT from pmbus.
18 constexpr auto STATUS_INPUT = "status0_input";
19 
20 // Voltage out status.
21 // Overvoltage fault or warning, Undervoltage fault or warning, maximum or
22 // minimum warning, ....
23 // Uses Page substitution
24 constexpr auto STATUS_VOUT = "statusP_vout";
25 
26 namespace status_vout
27 {
28 // Mask of bits that are only warnings
29 constexpr auto WARNING_MASK = 0x6A;
30 } // namespace status_vout
31 
32 // Current output status bits.
33 constexpr auto STATUS_IOUT = "status0_iout";
34 
35 // Manufacturing specific status bits
36 constexpr auto STATUS_MFR = "status0_mfr";
37 
38 // Reports on the status of any fans installed in position 1 and 2.
39 constexpr auto STATUS_FANS_1_2 = "status0_fans12";
40 
41 // Reports on temperature faults or warnings. Overtemperature fault,
42 // overtemperature warning, undertemperature warning, undertemperature fault.
43 constexpr auto STATUS_TEMPERATURE = "status0_temp";
44 
45 namespace status_word
46 {
47 constexpr auto VOUT_FAULT = 0x8000;
48 
49 // The IBM CFF power supply driver does map this bit to power1_alarm in the
50 // hwmon space, but since the other bits that need to be checked do not have
51 // a similar mapping, the code will just read STATUS_WORD and use bit masking
52 // to see if the INPUT FAULT OR WARNING bit is on.
53 constexpr auto INPUT_FAULT_WARN = 0x2000;
54 
55 // The bit mask representing the POWER_GOOD Negated bit of the STATUS_WORD.
56 constexpr auto POWER_GOOD_NEGATED = 0x0800;
57 
58 // The bit mask representing the FAN FAULT or WARNING bit of the STATUS_WORD.
59 // Bit 2 of the high byte of STATUS_WORD.
60 constexpr auto FAN_FAULT = 0x0400;
61 
62 // The bit mask representing the UNITI_IS_OFF bit of the STATUS_WORD.
63 constexpr auto UNIT_IS_OFF = 0x0040;
64 
65 // Bit 5 of the STATUS_BYTE, or lower byte of STATUS_WORD is used to indicate
66 // an output overvoltage fault.
67 constexpr auto VOUT_OV_FAULT = 0x0020;
68 
69 // The bit mask representing that an output overcurrent fault has occurred.
70 constexpr auto IOUT_OC_FAULT = 0x0010;
71 
72 // The IBM CFF power supply driver does map this bit to in1_alarm, however,
73 // since a number of the other bits are not mapped that way for STATUS_WORD,
74 // this code will just read the entire STATUS_WORD and use bit masking to find
75 // out if that fault is on.
76 constexpr auto VIN_UV_FAULT = 0x0008;
77 
78 // The bit mask representing the TEMPERATURE FAULT or WARNING bit of the
79 // STATUS_WORD. Bit 2 of the low byte (STATUS_BYTE).
80 constexpr auto TEMPERATURE_FAULT_WARN = 0x0004;
81 
82 } // namespace status_word
83 
84 namespace status_temperature
85 {
86 // Overtemperature Fault
87 constexpr auto OT_FAULT = 0x80;
88 } // namespace status_temperature
89 
90 /**
91  * Where the access should be done
92  */
93 enum class Type
94 {
95     Base,            // base device directory
96     Hwmon,           // hwmon directory
97     Debug,           // pmbus debug directory
98     DeviceDebug,     // device debug directory
99     HwmonDeviceDebug // hwmon device debug directory
100 };
101 
102 /**
103  * @class PMBus
104  *
105  * This class is an interface to communicating with PMBus devices
106  * by reading and writing sysfs files.
107  *
108  * Based on the Type parameter, the accesses can either be done
109  * in the base device directory (the one passed into the constructor),
110  * or in the hwmon directory for the device.
111  */
112 class PMBus
113 {
114   public:
115     PMBus() = delete;
116     ~PMBus() = default;
117     PMBus(const PMBus&) = default;
118     PMBus& operator=(const PMBus&) = default;
119     PMBus(PMBus&&) = default;
120     PMBus& operator=(PMBus&&) = default;
121 
122     /**
123      * Constructor
124      *
125      * @param[in] path - path to the sysfs directory
126      */
127     PMBus(const std::string& path) : basePath(path)
128     {
129         findHwmonDir();
130     }
131 
132     /**
133      * Constructor
134      *
135      * This version is required when DeviceDebug
136      * access will be used.
137      *
138      * @param[in] path - path to the sysfs directory
139      * @param[in] driverName - the device driver name
140      * @param[in] instance - chip instance number
141      */
142     PMBus(const std::string& path, const std::string& driverName,
143           size_t instance) :
144         basePath(path), driverName(driverName), instance(instance)
145     {
146         findHwmonDir();
147     }
148 
149     /**
150      * Reads a file in sysfs that represents a single bit,
151      * therefore doing a PMBus read.
152      *
153      * @param[in] name - path concatenated to
154      *                   basePath to read
155      * @param[in] type - Path type
156      *
157      * @return bool - false if result was 0, else true
158      */
159     bool readBit(const std::string& name, Type type);
160 
161     /**
162      * Reads a file in sysfs that represents a single bit,
163      * where the page number passed in is substituted
164      * into the name in place of the 'P' character in it.
165      *
166      * @param[in] name - path concatenated to
167      *                   basePath to read
168      * @param[in] page - page number
169      * @param[in] type - Path type
170      *
171      * @return bool - false if result was 0, else true
172      */
173     bool readBitInPage(const std::string& name, size_t page, Type type);
174     /**
175      * Checks if the file for the given name and type exists.
176      *
177      * @param[in] name   - path concatenated to basePath to read
178      * @param[in] type   - Path type
179      *
180      * @return bool - True if file exists, false if it does not.
181      */
182     bool exists(const std::string& name, Type type);
183 
184     /**
185      * Read byte(s) from file in sysfs.
186      *
187      * @param[in] name   - path concatenated to basePath to read
188      * @param[in] type   - Path type
189      *
190      * @return uint64_t - Up to 8 bytes of data read from file.
191      */
192     uint64_t read(const std::string& name, Type type);
193 
194     /**
195      * Read a string from file in sysfs.
196      *
197      * @param[in] name   - path concatenated to basePath to read
198      * @param[in] type   - Path type
199      *
200      * @return string - The data read from the file.
201      */
202     std::string readString(const std::string& name, Type type);
203 
204     /**
205      * Read data from a binary file in sysfs.
206      *
207      * @param[in] name   - path concatenated to basePath to read
208      * @param[in] type   - Path type
209      * @param[in] length - length of data to read, in bytes
210      *
211      * @return vector<uint8_t> - The data read from the file.
212      */
213     std::vector<uint8_t> readBinary(const std::string& name, Type type,
214                                     size_t length);
215 
216     /**
217      * Writes an integer value to the file, therefore doing
218      * a PMBus write.
219      *
220      * @param[in] name - path concatenated to
221      *                   basePath to write
222      * @param[in] value - the value to write
223      * @param[in] type - Path type
224      */
225     void write(const std::string& name, int value, Type type);
226 
227     /**
228      * Returns the sysfs base path of this device
229      */
230     inline const auto& path() const
231     {
232         return basePath;
233     }
234 
235     /**
236      * Replaces the 'P' in the string passed in with
237      * the page number passed in.
238      *
239      * For example:
240      *   insertPageNum("inP_enable", 42)
241      *   returns "in42_enable"
242      *
243      * @param[in] templateName - the name string, with a 'P' in it
244      * @param[in] page - the page number to insert where the P was
245      *
246      * @return string - the new string with the page number in it
247      */
248     static std::string insertPageNum(const std::string& templateName,
249                                      size_t page);
250 
251     /**
252      * Finds the path relative to basePath to the hwmon directory
253      * for the device and stores it in hwmonRelPath.
254      */
255     void findHwmonDir();
256 
257     /**
258      * Returns the path to use for the passed in type.
259      *
260      * @param[in] type - Path type
261      *
262      * @return fs::path - the full path
263      */
264     fs::path getPath(Type type);
265 
266   private:
267     /**
268      * Returns the device name
269      *
270      * This is found in the 'name' file in basePath.
271      *
272      * @return string - the device name
273      */
274     std::string getDeviceName();
275 
276     /**
277      * The sysfs device path
278      */
279     fs::path basePath;
280 
281     /**
282      * The directory name under the basePath hwmon directory
283      */
284     fs::path hwmonDir;
285 
286     /**
287      * The device driver name.  Used for finding the device
288      * debug directory.  Not required if that directory
289      * isn't used.
290      */
291     std::string driverName;
292 
293     /**
294      * The device instance number.
295      *
296      * Used in conjunction with the driver name for finding
297      * the debug directory.  Not required if that directory
298      * isn't used.
299      */
300     size_t instance = 0;
301 
302     /**
303      * The pmbus debug path with status files
304      */
305     const fs::path debugPath = "/sys/kernel/debug/";
306 };
307 
308 } // namespace pmbus
309 } // namespace witherspoon
310