1 /**
2  * Copyright © 2020 IBM Corporation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #pragma once
17 
18 #include "file_descriptor.hpp"
19 #include "temporary_file.hpp"
20 #include "xyz/openbmc_project/Logging/Create/server.hpp"
21 
22 #include <cstdint>
23 #include <filesystem>
24 
25 namespace phosphor::power::regulators
26 {
27 
28 namespace fs = std::filesystem;
29 using FFDCFormat =
30     sdbusplus::xyz::openbmc_project::Logging::server::Create::FFDCFormat;
31 using FileDescriptor = phosphor::power::util::FileDescriptor;
32 using TemporaryFile = phosphor::power::util::TemporaryFile;
33 
34 /**
35  * @class FFDCFile
36  *
37  * File that contains FFDC (first failure data capture) data.
38  *
39  * This class is used to store FFDC data in an error log.  The FFDC data is
40  * passed to the error logging system using a file descriptor.
41  *
42  * The constructor creates the file and opens it for both reading and writing.
43  *
44  * Use getFileDescriptor() to obtain the file descriptor needed to read or write
45  * data to the file.
46  *
47  * Use remove() to delete the file.  Otherwise the file will be deleted by the
48  * destructor.
49  *
50  * FFDCFile objects cannot be copied, but they can be moved.  This enables them
51  * to be stored in containers like std::vector.
52  */
53 class FFDCFile
54 {
55   public:
56     // Specify which compiler-generated methods we want
57     FFDCFile() = delete;
58     FFDCFile(const FFDCFile&) = delete;
59     FFDCFile(FFDCFile&&) = default;
60     FFDCFile& operator=(const FFDCFile&) = delete;
61     FFDCFile& operator=(FFDCFile&&) = default;
62     ~FFDCFile() = default;
63 
64     /**
65      * Constructor.
66      *
67      * Creates the file and opens it for both reading and writing.
68      *
69      * Throws an exception if an error occurs.
70      *
71      * @param format format type of the contained data
72      * @param subType format subtype; used for the 'Custom' type
73      * @param version version of the data format; used for the 'Custom' type
74      */
75     explicit FFDCFile(FFDCFormat format, uint8_t subType = 0,
76                       uint8_t version = 0);
77 
78     /**
79      * Returns the file descriptor for the file.
80      *
81      * The file is open for both reading and writing.
82      *
83      * @return file descriptor
84      */
85     int getFileDescriptor()
86     {
87         // Return the integer file descriptor within the FileDescriptor object
88         return descriptor();
89     }
90 
91     /**
92      * Returns the format type of the contained data.
93      *
94      * @return format type
95      */
96     FFDCFormat getFormat() const
97     {
98         return format;
99     }
100 
101     /**
102      * Returns the absolute path to the file.
103      *
104      * @return absolute path
105      */
106     const fs::path& getPath() const
107     {
108         return tempFile.getPath();
109     }
110 
111     /**
112      * Returns the format subtype.
113      *
114      * @return subtype
115      */
116     uint8_t getSubType() const
117     {
118         return subType;
119     }
120 
121     /**
122      * Returns the version of the data format.
123      *
124      * @return version
125      */
126     uint8_t getVersion() const
127     {
128         return version;
129     }
130 
131     /**
132      * Closes and deletes the file.
133      *
134      * Does nothing if the file has already been removed.
135      *
136      * Throws an exception if an error occurs.
137      */
138     void remove();
139 
140   private:
141     /**
142      * Format type of the contained data.
143      */
144     FFDCFormat format{FFDCFormat::Text};
145 
146     /**
147      * Format subtype; used for the 'Custom' type.
148      */
149     uint8_t subType{0};
150 
151     /**
152      * Version of the data format; used for the 'Custom' type.
153      */
154     uint8_t version{0};
155 
156     /**
157      * Temporary file where FFDC data is stored.
158      *
159      * The TemporaryFile destructor will automatically delete the file if it was
160      * not explicitly deleted using remove().
161      */
162     TemporaryFile tempFile{};
163 
164     /**
165      * File descriptor for reading from/writing to the file.
166      *
167      * The FileDescriptor destructor will automatically close the file if it was
168      * not explicitly closed using remove().
169      */
170     FileDescriptor descriptor{};
171 };
172 
173 } // namespace phosphor::power::regulators
174