docs/designs/dump-manager.md

11 During a crash or a host failure, an event monitor mechanism generates an error
20 - **System Dump**: A dump of the Host's main memory and processor registers.
22 - **Memory Preserving Reboot(MPR)**: A method of reboot with preserving the
24 - **PLDM**: An interface and data model to access low-level platform inventory,
26   [ReadMore](https://github.com/openbmc/docs/blob/master/designs/pldm-stack.md)
27 - **Machine Check Exception**: A severe error inside a processor core that
29 - **BMCWeb**: An embedded webserver for OpenBMC.
52 A system dump is a collection of debugging information from the host, this may
53 include host memory and/or register data. This dump can be initiated by BMC and
55 host memory and offloaded through the BMC or get collected directly to BMC based
61 A special type of host dump is initiated and collected by the host based on the
64 what data to be collected. The content of the dump can be decided by the host.
65 This dump can be stored in host memory and offloaded through BMC or host can
71 A dump that can be collected during the boot failure of the host. This dump may
78 like the processor while the host is booted and running. The host may stop
84 …es - Users are examples, not a mandatory part of implementation](https://user-images.githubusercon…
88 - Create a dump: Initiate the creation of the dump, based on an error condition
90 - List the dumps: List all dumps present in the BMC.
91 - Get a dump: Offload the dump to an external entity.
92 - Notify: Notify the dump manager that a new dump is created.
93 - Delete the dump.
94 - Mark a dump as offloaded to an external entity.
95 - Set the dump policies like disabling a type of dump or dump overwriting
106 - Collected by BMC and stored on BMC.
107 - Collected and stored on an attached entity but offloaded through BMC.
109 This proposal focuses on re-using the existing
110 [phosphor-debug-collector](https://github.com/openbmc/phosphor-debug-collector),
113 ![phosphor-debug-collector](https://user-images.githubusercontent.com/16666879/72070844-7b56c980-33…
115 #### Brief design points of existing phosphor-debug-collector
117 - A create interface which assumes the type is BMC dump and returns an ID to the
118   caller for the user-initiated dumps.
119 - An external request of dump is considered as a user-initiated BMC dump and
121 - The dreport create dump file in the dump path provided by the dump manager
123 - A watch process is forked by the dump manager to catch the signal for the file
125 - The watch process calls an internal dbus interface to create the dump entry
127 - The path of dump is based on the predefined base path and the id of the dump.
128 - When the request comes for offload, the file is downloaded from the dump base
129   path +id, no update in the entry whether dump is offloaded
130 - Deleting a dump by deleting the entry and internal file also will be deleted.
131 - There are system generated dumps based on error log or core dump, which works
132   similar to user-initiated dumps with the following difference.
133 - No external create D-Bus interface is needed, but a monitor application will
136 - Once the event occurred, the monitor will call an internal D-Bus interface
138 - The dump manager calls dreport with a dump type got from the monitor and write
139   data to a path based on dump id.
141 #### Updates proposed to the existing phosphor-debug-collector.
143 - External D-Bus interface needs to specify the type of the dump since a user
145 - Create will be returning an id which can be mapped to the actual dump once it
147 - A Notify interface is provided for notifying the creation of a dump outside
149 - The InitiateOffload function will be implemented to download the dump.
150 - Status of the dump, whether offloaded or not, will be added to the dump entry.
154 - Dump Manager DBus object provides interfaces for creating and managing dump
156 - Interfaces
158   - **Create**: The interface to create a dump, called by clients to initiate
159     user-initiated dump.
161     - AdditionalData: The additional data, if any, for initiating the dump. The
164       either a string or a 64 bit number. The enum-format string is required to
171   - **Notify**: Notify the dump manager that a new dump is created.
172     - ID: ID of the dump, if not 0 this will be the external id of the dump
173     - Type: Type of dump that was created.
174     - Size: Size of the dump
178     -  **InitiateOffload**: Initiate the offload of the dump.
179         - OffloadUri: The URI where the dump should be offloaded.
185 - ID: Id of the dump
186 - Timestamp: Dump creation timestamp
187 - Size: Total size of the dump
188 - OffloadComplete: Set to true when offload is completed
189 - OffloadURI: The URI for offloading the dump, set while initiating the offload.
197 - No Additional properties
201 - External Source ID: ID provided by the Host, this id will be used for all
202   communication to the source of the dump, in this case, Host.
204 ### Flow of dumps collected and stored in the Host
207 Host and BMC.
209 - Create: Initiate methods to create the dump in Host.
210 - Generating the dump in Host
211 - Host notifies the creation of dump through PLDM to BMC.
212 - PLDM call Notify to create the dump entry
213 - InitiateOffload: Dump manager request Host to start offload
214 - The Host sends the dump through PLDM, and PLDM on BMC sends it out.
218 - Offloading Host dumps through Host instead of BMC, but considered BMC option
219   due to following reasons - The BMC is considered the "management path" of most
220   servers and often the Host is not connected to the desired network for the
221   offload location. - BMC provides one common point for all dumps generated in
226 - The existing BMC dump interface needs to be re-used. The current interface is
229 - Modifying the BMC dump infrastructure to support additional dumps.
230 - openpower-proc-control will be updated to call memory preserving chip-ops and
232 - Additional system state to indicate the system is collecting debug data While
237 - Unit tests to make sure the dump manager interfaces are working.
238 - Following integration tests will be executed to make sure the dump manager is
239   working as expected. - Test creating host dumps and offloading it. - Test
240   deleting host dumps - Create/List/Offload/Delete BMC dumps to make sure
242 - Automated tests for dump Create/List/Offload/Delete to avoid regression.