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 
33 /**
34  * @class FFDCFile
35  *
36  * File that contains FFDC (first failure data capture) data.
37  *
38  * This class is used to store FFDC data in an error log.  The FFDC data is
39  * passed to the error logging system using a file descriptor.
40  *
41  * The constructor creates the file and opens it for both reading and writing.
42  *
43  * Use getFileDescriptor() to obtain the file descriptor needed to read or write
44  * data to the file.
45  *
46  * Use remove() to delete the file.  Otherwise the file will be deleted by the
47  * destructor.
48  *
49  * FFDCFile objects cannot be copied, but they can be moved.  This enables them
50  * to be stored in containers like std::vector.
51  */
52 class FFDCFile
53 {
54   public:
55     // Specify which compiler-generated methods we want
56     FFDCFile() = delete;
57     FFDCFile(const FFDCFile&) = delete;
58     FFDCFile(FFDCFile&&) = default;
59     FFDCFile& operator=(const FFDCFile&) = delete;
60     FFDCFile& operator=(FFDCFile&&) = default;
61     ~FFDCFile() = default;
62 
63     /**
64      * Constructor.
65      *
66      * Creates the file and opens it for both reading and writing.
67      *
68      * Throws an exception if an error occurs.
69      *
70      * @param format format type of the contained data
71      * @param subType format subtype; used for the 'Custom' type
72      * @param version version of the data format; used for the 'Custom' type
73      */
74     explicit FFDCFile(FFDCFormat format, uint8_t subType = 0,
75                       uint8_t version = 0);
76 
77     /**
78      * Returns the file descriptor for the file.
79      *
80      * The file is open for both reading and writing.
81      *
82      * @return file descriptor
83      */
84     int getFileDescriptor()
85     {
86         // Return the integer file descriptor within the FileDescriptor object
87         return descriptor();
88     }
89 
90     /**
91      * Returns the format type of the contained data.
92      *
93      * @return format type
94      */
95     FFDCFormat getFormat() const
96     {
97         return format;
98     }
99 
100     /**
101      * Returns the absolute path to the file.
102      *
103      * @return absolute path
104      */
105     const fs::path& getPath() const
106     {
107         return tempFile.getPath();
108     }
109 
110     /**
111      * Returns the format subtype.
112      *
113      * @return subtype
114      */
115     uint8_t getSubType() const
116     {
117         return subType;
118     }
119 
120     /**
121      * Returns the version of the data format.
122      *
123      * @return version
124      */
125     uint8_t getVersion() const
126     {
127         return version;
128     }
129 
130     /**
131      * Closes and deletes the file.
132      *
133      * Does nothing if the file has already been removed.
134      *
135      * Throws an exception if an error occurs.
136      */
137     void remove();
138 
139   private:
140     /**
141      * Format type of the contained data.
142      */
143     FFDCFormat format{FFDCFormat::Text};
144 
145     /**
146      * Format subtype; used for the 'Custom' type.
147      */
148     uint8_t subType{0};
149 
150     /**
151      * Version of the data format; used for the 'Custom' type.
152      */
153     uint8_t version{0};
154 
155     /**
156      * Temporary file where FFDC data is stored.
157      *
158      * The TemporaryFile destructor will automatically delete the file if it was
159      * not explicitly deleted using remove().
160      */
161     TemporaryFile tempFile{};
162 
163     /**
164      * File descriptor for reading from/writing to the file.
165      *
166      * The FileDescriptor destructor will automatically close the file if it was
167      * not explicitly closed using remove().
168      */
169     FileDescriptor descriptor{};
170 };
171 
172 } // namespace phosphor::power::regulators
173