File KMOD_REBUILD_README.md of Package kernel-source

# Kernel Module Rebuild Guide for SUSE Kernels

## Overview

This document explains when you do and don't need to rebuild custom kernel modules when upgrading between SUSE kernel releases.

## SUSE Kernel Versioning Scheme

SUSE kernel versions follow this format:
```
kernel-flavor-{VERSION}-{RELEASE}.{SUFFIX}.{ARCH}.rpm
```

Example: `kernel-default-6.11.3-16.1.shift5.x86_64.rpm`

- **VERSION**: Upstream kernel version (6.11.3)
- **RELEASE**: SUSE package release number (16.1)
- **SUFFIX**: Build type identifier (.shift5)
- **ARCH**: Target architecture (x86_64)

## When Rebuilds Are NOT Required

You **do NOT need to rebuild** your custom kernel modules when:

### ✅ Same Kernel Version + Different Release Number

**Example**: Moving from `6.11.3-10.shift5` → `6.11.3-16.1.shift5`

This typically indicates:
- Packaging updates (spec file changes)
- Build system improvements
- Configuration tweaks (non-ABI affecting)
- Security/maintenance patches that preserve ABI
- Same underlying kernel source code

### ✅ Same Git Commit Hash

If both kernels use the same git commit, the core kernel code is identical:
```bash
# Check git commit in spec files
grep "git_commit" kernel-*.spec
```

### ✅ ABI-Compatible Updates

SUSE maintains kernel ABI stability within the same kernel version series for maintenance updates.

## When Rebuilds ARE Required

You **must rebuild** your custom kernel modules when:

### ❌ Different Kernel Version

**Example**: Moving from `6.11.3-X` → `6.11.4-Y` or `6.11.3-X` → `6.12.0-Y`

### ❌ Different Git Commit (Source Changes)

When the underlying kernel source code has changed.

### ❌ ABI-Breaking Changes

Rare, but sometimes unavoidable for security fixes. SUSE documents these.

### ❌ Different Kernel Flavor

**Example**: Moving from `kernel-default` → `kernel-kvmsmall`

## How SUSE Kernel Module Compatibility Works

### Modversions Mechanism

SUSE kernels use `CONFIG_MODVERSIONS` which:

1. **Attaches checksums** to each exported kernel symbol
2. **Validates symbol compatibility** when loading modules
3. **Allows modules built for different releases** to work if symbols haven't changed
4. **Prevents loading** if symbol interfaces have changed

From the SUSE documentation:
> "modversions attach a checksum to each symbol (function or variable) exported to modules by the kernel. This allows to use kernel modules that have been built for a kernel with a different version or release number in many cases, as long as none of the symbols the module uses have changed between the two kernel versions."

### ABI Stability Policy

> "When releasing maintenance or security update kernels for a specific product, we carefully try to keep the kernel ABI stable. Despite this, we sometimes have no choice but to break binary compatibility. In this case, those kernel modules must be rebuilt."

## Compatibility Verification Steps

### 1. Try Loading Your Existing Modules First

```bash
# Attempt to load your module
sudo modprobe your_module_name

# Or load directly
sudo insmod /path/to/your_module.ko
```

### 2. Check for Symbol Version Mismatches

```bash
# Check kernel messages for compatibility issues
dmesg | grep -i "disagrees about version of symbol"
dmesg | grep -i "unknown symbol"
dmesg | grep -i "version magic"
```

### 3. Compare Symbol Versions (Advanced)

```bash
# Check module's expected symbol versions
modprobe --dump-modversions your_module.ko

# Check kernel's actual symbol versions
cat /proc/kallsyms | grep your_symbol_name

# Compare Module.symvers between kernel versions
diff /boot/symvers-{old-version}.gz /boot/symvers-{new-version}.gz
```

### 4. Verify Module Information

```bash
# Check module info
modinfo your_module.ko

# Check what kernel version it was built for
modinfo your_module.ko | grep vermagic
```

## Troubleshooting Module Loading Issues

### Module Refuses to Load

**Error**: `insmod: ERROR: could not insert module: Invalid module format`

**Solution**: Check dmesg for specific error:
```bash
dmesg | tail -20
```

Common issues:
- **Version magic mismatch**: Different kernel version/config
- **Symbol version mismatch**: ABI incompatibility
- **Missing symbols**: Kernel config changed

### Symbol Version Disagreements

**Error**: `module disagrees about version of symbol X`

**Solution**: The kernel ABI changed for that symbol. You need to rebuild.

### Unknown Symbol Errors

**Error**: `unknown symbol in module`

**Solution**: 
1. Check if required kernel modules are loaded
2. Verify kernel configuration includes the needed symbols
3. May need to rebuild against new kernel

## Best Practices

### 1. Use Kernel Module Packages (KMP)

For production systems, create proper KMPs following the [SUSE KMP Manual](https://documentation.suse.com/sbp/all/html/SBP-KMP-Manual-SLE12SP2/index.html).

### 2. Test Before Deployment

Always test module loading on non-production systems first.

### 3. Keep Build Environment Ready

Maintain your module build environment to enable quick rebuilds when necessary:

```bash
# Install required packages
zypper install kernel-devel kernel-default-devel

# Verify build environment
ls /usr/src/linux-obj/$(uname -m)/default/
```

### 4. Version Your Modules

Include version information in your modules:
```c
MODULE_VERSION("1.0");
MODULE_DESCRIPTION("Your module description");
```

## Quick Decision Matrix

| Scenario | Rebuild Required? | Reason |
|----------|------------------|---------|
| 6.11.3-10 → 6.11.3-16.1 | ❌ No | Same kernel version |
| 6.11.3-X → 6.11.4-Y | ✅ Yes | Different kernel version |
| default → kvmsmall | ✅ Yes | Different kernel flavor/config |
| Same git commit | ❌ No | Identical source code |
| Different git commit | ⚠️ Maybe | Check ABI compatibility |

## Example: Real-World Scenario

**Your situation**:
- **Old**: `6.11.3-10.shift5-default` 
- **New**: `6.11.3-16.1.shift5-default`
- **Git commit**: Same (006a2b4f54ea8081d692c34fd38bd1c2b57d8bd1)

**Recommendation**: ❌ **No rebuild required**

**Reason**: Same kernel version, same source code, typical SUSE maintenance update.

## Getting Help

If you encounter issues:

1. **Check SUSE documentation**: [Kernel Module Packages Manual](https://documentation.suse.com/sbp/all/html/SBP-KMP-Manual-SLE12SP2/index.html)
2. **Review kernel changelogs**: Check for ABI-breaking changes
3. **SUSE Support**: For enterprise customers
4. **Community forums**: openSUSE forums and mailing lists

## References

- [SUSE Kernel Source README](README.SUSE)
- [SUSE Kernel Module Packages Manual](https://documentation.suse.com/sbp/all/html/SBP-KMP-Manual-SLE12SP2/index.html)
- [Linux Kernel Module Programming Guide](https://tldp.org/LDP/lkmpg/2.6/html/index.html)
- [Kernel Documentation on Module Versioning](https://www.kernel.org/doc/Documentation/kbuild/modules.txt)