Implement native plugin cycle hooks for real-time PLC synchronization

[devin-ai-integration]

Implement native plugin cycle hooks for real-time PLC synchronization

Summary

This PR implements the cycle_start() and cycle_end() hooks for native plugins, allowing them to synchronize with the PLC scan cycle in real-time. Previously, these hooks were loaded via dlsym but never actually invoked.

Key changes:

• Added plugin_driver_cycle_start() and plugin_driver_cycle_end() functions that iterate through all active native plugins and call their registered hooks
• Integrated these functions into the PLC scan cycle in plc_state_manager.c - cycle_start is called before PLC logic execution, cycle_end after
• Plugins opt-in by implementing the functions; opt-out by not implementing them (NULL pointer check)
• Only enabled and running native plugins are called
• Updated README.md documentation with comprehensive cycle hooks documentation

Updates since last revision

• Fixed section numbering in README.md: "Memory Management (Python)" is now correctly numbered as section 4 after adding the new "Native Plugin Cycle Hooks" section 3

Review & Testing Checklist for Human

• Test with a native plugin implementing cycle hooks: Load a native plugin (e.g., test_plugin.c in examples) that implements cycle_start() and cycle_end(), verify they are called each scan cycle
• Verify scan cycle timing: Confirm that adding these hook calls does not significantly impact PLC scan cycle time (the implementation is minimal but runs in the critical path)
• Verify mutex behavior: Confirm the buffer mutex is held during cycle hook execution as documented (hooks are called between plugin_mutex_take and plugin_mutex_give)

Recommended test plan:

1. Modify plugins/native/examples/test_plugin.c to add print statements or counters in cycle_start() and cycle_end()
2. Build and configure the plugin in plugins.conf with type=1
3. Run the PLC with a simple program and verify the hooks are called each cycle
4. Monitor scan cycle timing to ensure no significant degradation

Notes

• The cycle hooks are only supported for native plugins (not Python) since they need to run in real-time within the scan cycle
• Plugins that don't implement these functions are simply skipped (no error)
• The hooks are called while the buffer mutex is held, so plugins can safely access I/O buffers without additional locking

Link to Devin run: https://app.devin.ai/sessions/7bb7a40970384ea79ffea4adc955a73a
Requested by: Thiago Alves (@thiagoralves)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[Copilot]

Pull request overview

This PR implements real-time synchronization hooks for native plugins by integrating cycle_start() and cycle_end() functions into the PLC scan cycle. These hooks, which were previously loaded but never invoked, now allow native plugins to execute code in lockstep with the PLC's scan cycle while the buffer mutex is held.

Key changes:

• Added plugin_driver_cycle_start() and plugin_driver_cycle_end() functions that iterate through active native plugins and invoke their registered hooks
• Integrated cycle hooks into the PLC scan cycle with cycle_start called before PLC logic execution and cycle_end called after
• Enhanced documentation with comprehensive guidance on cycle hook usage, timing considerations, and the opt-in/opt-out pattern

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
core/src/plc_app/plc_state_manager.c	Integrated cycle hook calls into the PLC scan cycle thread between mutex lock/unlock operations
core/src/drivers/plugin_driver.h	Added function declarations for the new cycle hook driver functions
core/src/drivers/plugin_driver.c	Implemented the cycle hook iteration logic with NULL pointer checks and plugin state validation
core/src/drivers/README.md	Updated documentation to describe cycle hook usage patterns, real-time considerations, and provided implementation examples

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The section numbering is incorrect. This should be section 4, not 3, as section 3 is now 'Native Plugin Cycle Hooks (Real-Time Synchronization)' starting at line 653.

Suggested change

	3. **Memory Management (Python):**
	4. **Memory Management (Python):**

[thiagoralves]

Devin, can you check this please?

[devin-ai-integration]

Good catch! I've fixed the section numbering - "Memory Management (Python)" is now correctly numbered as section 4. The fix has been pushed in commit 0c0c9a6.