Start GDB session with API

CHANGELOG.md

@@ -14,6 +14,10 @@ and this project adheres to
   `VIRTIO_NET_F_RX_MRGBUF` support to the `virtio-net` device. When this feature
   is negotiated, guest `virtio-net` driver can perform more efficient memory
   management which in turn improves RX and TX performance.
+- [#4797](https://github.com/firecracker-microvm/firecracker/pull/4797),
+  [#4854](https://github.com/firecracker-microvm/firecracker/pull/4854): Added
+  GDB debugging support for a microVM guest kernel. Please see our
+  [GDB debugging documentation](docs/gdb-debugging.md) for more information.
 
 ### Changed
 

docs/gdb-debugging.md

@@ -6,8 +6,6 @@ Firecracker supports debugging the guest kernel via GDB remote serial protocol.
 This allows us to connect GDB to the firecracker process and step through debug
 the guest kernel.
 
-The GDB feature requires Firecracker to be booted with a config file.
-
 ## Prerequisites
 
 Firstly, to enable GDB debugging we need to compile Firecracker with the `gdb`
@@ -25,22 +23,35 @@ debugging to work. The key config options to enable are:
 
 ```
 CONFIG_FRAME_POINTER=y
-CONFIG_KGDB=y
-CONFIG_KGDB_SERIAL_CONSOLE=y
 CONFIG_DEBUG_INFO=y
 ```
 
-For GDB debugging the `gdb-socket` option should be set in your config file. In
-this example we set it to `/tmp/gdb.socket`
+For GDB debugging the `gdb_socket_path` option under `machine-config` should be
+set. When using the API the socket address must be set before instance start.
+
+In this example we set the address to `/tmp/gdb.socket` in the config file:
 
 ```
 {
   ...
-  "gdb-socket": "/tmp/gdb.socket"
+  "machine-config": {
+    ...
+    "gdb_socket_path": "/tmp/gdb.socket"
+    ...
+  }
   ...
 }
 ```
 
+Using the API the socket address can be configured before boot like so:
+
+```
+sudo curl -X PATCH --unix-socket "${API_SOCKET}" \
+  --data "{
+    \"gdb_socket_path\": \"/tmp/gdb.socket\"
+  }" "http://localhost/machine-config"
+```
+
 ## Starting Firecracker with GDB
 
 With all the prerequisites in place you can now start firecracker ready to

src/firecracker/swagger/firecracker.yaml

@@ -1028,6 +1028,9 @@ definitions:
     properties:
       cpu_template:
         $ref: "#/definitions/CpuTemplate"
+      gdb_socket_path:
+        type: string
+        description: Path to the GDB socket. Requires the gdb feature to be enabled.
       smt:
         type: boolean
         description: Flag for enabling/disabling simultaneous multithreading. Can be enabled only on x86.

src/vmm/src/builder.rs

@@ -346,8 +346,8 @@ pub fn build_microvm_for_boot(
     let vmm = Arc::new(Mutex::new(vmm));
 
     #[cfg(feature = "gdb")]
-    if let Some(gdb_socket_addr) = &vm_resources.gdb_socket_addr {
-        gdb::gdb_thread(vmm.clone(), vcpu_fds, gdb_rx, entry_addr, gdb_socket_addr)
+    if let Some(gdb_socket_path) = &vm_resources.vm_config.gdb_socket_path {
+        gdb::gdb_thread(vmm.clone(), vcpu_fds, gdb_rx, entry_addr, gdb_socket_path)
             .map_err(GdbServer)?;
     } else {
         debug!("No GDB socket provided not starting gdb server.");

src/vmm/src/persist.rs

@@ -433,6 +433,8 @@ pub fn restore_from_snapshot(
             cpu_template: Some(microvm_state.vm_info.cpu_template),
             track_dirty_pages: Some(track_dirty_pages),
             huge_pages: Some(microvm_state.vm_info.huge_pages),
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: None,
         })
         .map_err(BuildMicrovmFromSnapshotError::VmUpdateConfig)?;
 

src/vmm/src/resources.rs

@@ -86,9 +86,6 @@ pub struct VmmConfig {
     vsock_device: Option<VsockDeviceConfig>,
     #[serde(rename = "entropy")]
     entropy_device: Option<EntropyDeviceConfig>,
-    #[cfg(feature = "gdb")]
-    #[serde(rename = "gdb-socket")]
-    gdb_socket_addr: Option<String>,
 }
 
 /// A data structure that encapsulates the device configurations
@@ -117,9 +114,6 @@ pub struct VmResources {
     pub mmds_size_limit: usize,
     /// Whether or not to load boot timer device.
     pub boot_timer: bool,
-    #[cfg(feature = "gdb")]
-    /// Configures the location of the GDB socket
-    pub gdb_socket_addr: Option<String>,
 }
 
 impl VmResources {
@@ -142,8 +136,6 @@ impl VmResources {
 
         let mut resources: Self = Self {
             mmds_size_limit,
-            #[cfg(feature = "gdb")]
-            gdb_socket_addr: vmm_config.gdb_socket_addr,
             ..Default::default()
         };
         if let Some(machine_config) = vmm_config.machine_config {
@@ -529,8 +521,6 @@ impl From<&VmResources> for VmmConfig {
             net_devices: resources.net_builder.configs(),
             vsock_device: resources.vsock.config(),
             entropy_device: resources.entropy.config(),
-            #[cfg(feature = "gdb")]
-            gdb_socket_addr: resources.gdb_socket_addr.clone(),
         }
     }
 }
@@ -640,8 +630,6 @@ mod tests {
             boot_timer: false,
             mmds_size_limit: HTTP_MAX_PAYLOAD_SIZE,
             entropy: Default::default(),
-            #[cfg(feature = "gdb")]
-            gdb_socket_addr: None,
         }
     }
 

src/vmm/src/vmm_config/machine_config.rs

@@ -111,6 +111,10 @@ pub struct MachineConfig {
     /// Configures what page size Firecracker should use to back guest memory.
     #[serde(default)]
     pub huge_pages: HugePageConfig,
+    /// GDB socket address.
+    #[cfg(feature = "gdb")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gdb_socket_path: Option<String>,
 }
 
 impl Default for MachineConfig {
@@ -146,6 +150,10 @@ pub struct MachineConfigUpdate {
     /// Configures what page size Firecracker should use to back guest memory.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub huge_pages: Option<HugePageConfig>,
+    /// GDB socket address.
+    #[cfg(feature = "gdb")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gdb_socket_path: Option<String>,
 }
 
 impl MachineConfigUpdate {
@@ -166,6 +174,8 @@ impl From<MachineConfig> for MachineConfigUpdate {
             cpu_template: cfg.cpu_template,
             track_dirty_pages: Some(cfg.track_dirty_pages),
             huge_pages: Some(cfg.huge_pages),
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: cfg.gdb_socket_path,
         }
     }
 }
@@ -185,6 +195,9 @@ pub struct VmConfig {
     pub track_dirty_pages: bool,
     /// Configures what page size Firecracker should use to back guest memory.
     pub huge_pages: HugePageConfig,
+    /// GDB socket address.
+    #[cfg(feature = "gdb")]
+    pub gdb_socket_path: Option<String>,
 }
 
 impl VmConfig {
@@ -238,6 +251,8 @@ impl VmConfig {
             cpu_template,
             track_dirty_pages: update.track_dirty_pages.unwrap_or(self.track_dirty_pages),
             huge_pages: page_config,
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: update.gdb_socket_path.clone(),
         })
     }
 }
@@ -251,6 +266,8 @@ impl Default for VmConfig {
             cpu_template: None,
             track_dirty_pages: false,
             huge_pages: HugePageConfig::None,
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: None,
         }
     }
 }
@@ -264,6 +281,8 @@ impl From<&VmConfig> for MachineConfig {
             cpu_template: value.cpu_template.as_ref().map(|template| template.into()),
             track_dirty_pages: value.track_dirty_pages,
             huge_pages: value.huge_pages,
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: value.gdb_socket_path.clone(),
         }
     }
 }