docs/designs/dump-manager.md

1 # Dump Manager Design
14 required for the debugging needs to be collected as a dump. The existing OpenBMC
15 dump interfaces support only the dumps generated on the BMC and dump manager
20 - **System Dump**: A dump of the Host's main memory and processor registers.
35 dump manager, which is orchestrating the collection and offload, needs to
36 provide methods to create, store the dump details, and offload it. Additionally,
37 some sources allow the dump to be extracted manually without a failure to
42 These are some of the dumps supported by dump manager.
44 #### BMC Dump
46 A dump collected when there is a failure in the BMC with various debug
47 information. This type of dump can be generated by user too to get the current
48 state of the BMC. This dump gets collected on BMC and stored on BMC
50 #### System Dump
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
54 there can be system reboots while collecting the dump. Dump gets stored in the
56 on the size of dump contents and the available space on the BMC to store the
57 dump.
59 #### Resource dump
61 A special type of host dump is initiated and collected by the host based on the
63 collection of this kind of a dump. A resource indicator may be used to indicate
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
66 send this dump down to BMC once the collection is completed based on the size of
67 the dump and the availability of space on the BMC.
69 #### Hostboot dump
71 A dump that can be collected during the boot failure of the host. This dump may
75 #### Hardware dump
77 This dump can be collected during a critical failure on the hardware components
79 during this dump and may collect various processor states and/or memory contents
84 ![Dump use cases - Users are examples, not a mandatory part of implementation](https://user-images.…
86 #### Dump manager needs to provide interfaces for
88 - Create a dump: Initiate the creation of the dump, based on an error condition
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
117 - A create interface which assumes the type is BMC dump and returns an ID to the
119 - An external request of dump is considered as a user-initiated BMC dump and
120   initiate BMC dump collection with a tool named dreport with type manual dump
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
124   close on that path and assume the dump collection is completed.
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
137   dump manager to create the dump with the type of dump.
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.
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.
152 ### Dump manager interfaces.
154 - Dump Manager DBus object provides interfaces for creating and managing dump
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
163       specific type of dump either in xyz or in a domain. The values can be
167       'domain.Dump.Create.CreateParameters.ParamName'. e.g.: { "key1": "value1",
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
176 ### Dump entry interfaces
178     -  **InitiateOffload**: Initiate the offload of the dump.
179         - OffloadUri: The URI where the dump should be offloaded.
183 There will be a base dump entry with properties common to all types of dumps
185 - ID: Id of the dump
186 - Timestamp: Dump creation timestamp
187 - Size: Total size of the dump
189 - OffloadURI: The URI for offloading the dump, set while initiating the offload.
190   Specific types need to inherit from this common dump entry class and add
193 #### Additional propertries based on dump types
195 ##### BMC Dump
199 ##### System Dump
202   communication to the source of the dump, in this case, Host.
206 PLDM is provided as an example dump transport and notification mechanism between
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.
226 - The existing BMC dump interface needs to be re-used. The current interface is
227   not accepting a dump type, so a new interface to create the dump with type
228   will be provided for BMC dump also without changing the existing interface.
229 - Modifying the BMC dump infrastructure to support additional dumps.
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
241   existing dump manager functions are not broken.
242 - Automated tests for dump Create/List/Offload/Delete to avoid regression.