Signed-off-by: Andrew Leech <[email protected]>

Signed-off-by: Andrew Leech <[email protected]>

This adds documentation for a proposed enhancement to allow native
modules to use the same static module definition pattern as user C
modules, reducing boilerplate and improving consistency.

- natmod-static-modules.md: Overview and analysis of current state
- natmod-implementation-plan.md: Detailed implementation strategy

The proposal includes a parser tool to auto-generate init functions,
build system integration, and maintains backward compatibility.

This commit introduces improvements to reduce boilerplate in native
module definitions while maintaining compatibility:

1. Parser tool (py/make_natmod_init.py) - Generates init functions
   for modules using MP_REGISTER_MODULE pattern (experimental).

2. Build system integration - dynruntime.mk can auto-detect static
   module definitions and extract module names from source.

3. Helper macros in dynruntime.h:
   - MP_OBJ_QSTR_VALUE: Extract QSTR from object
   - MP_DYNRUNTIME_REGISTER_GLOBALS_TABLE: Register module globals
   - MP_DYNRUNTIME_INIT_STATIC_MODULE: Simplified registration

4. Working example (static_module_hybrid) demonstrates a practical
   macro-based approach that reduces boilerplate.

The implementation recognizes native module constraints where QSTRs
are runtime values, not compile-time constants. The hybrid approach
provides a cleaner way to define module attributes while working
within these constraints.

This commit adds infrastructure to support a cleaner way of defining
native modules using static patterns similar to user C modules:

1. Added make_natmod_init.py parser tool to extract MP_REGISTER_MODULE
   declarations and generate mpy_init functions automatically.

2. Enhanced dynruntime.mk to auto-detect static module patterns and
   invoke the parser tool when needed.

3. Added helper macros to dynruntime.h:
   - MP_OBJ_QSTR_VALUE: Extract QSTR value from object at runtime
   - MP_DYNRUNTIME_REGISTER_GLOBALS_TABLE: Register globals from table
   - MP_DYNRUNTIME_INIT_STATIC_MODULE: Initialize module from definition

4. Created static_module_hybrid example demonstrating macro-based
   approach that reduces boilerplate while maintaining zero overhead.

5. Updated documentation in docs/develop/natmod.rst with new patterns
   and helper macros.

6. Added dual-mode module examples showing how the same C source can
   be compiled as either a user C module or native module.

The traditional mpy_init approach remains fully supported. The new
infrastructure is optional and provides a migration path for cleaner
module definitions.

Signed-off-by: Assistant <[email protected]>