c_dsp: body-only snippets + user C oscillators (install_c_osc / c_osc)

install_c_process/install_c_osc now accept just the function body -- the
signature and standard includes are wrapped on automatically, with #line
so tcc errors keep the user's own line numbers. Full programs still work
(detected by a process(/render( mention).

New oscillator kind: install_c_osc(name, src) compiles
void render(int16_t *buf, int frames, int osc, int phase_inc_q16, int amp_q15)
and c_osc(name, osc) makes that AMY osc play it -- dispatched from
amy_external_render_hook (registered on desktop run_amy), which derives the
Q16 phase step and Q15 envelope level from msynth so pitch bend and ADSR
just work; AMY still applies pan and mixing. State between calls = statics
in the body; per-osc state (polyphony) = static arrays indexed by the osc
param.

Ships tulip/fs/tulip/ex/c_dsp_demo.py: a body-form bitcrusher and a
CZ-101-style phase distortion oscillator, on osc 200 (low oscs belong to
midi.py's default synths, which silence raw events -- now documented).

Verified headless: a muting user osc zeroes the bus during a held note
(override proven on the live path), hot-swapping to the CZ body restores
full-scale audio, and the effect path still passes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: bwhitman

docs/user_c_dsp_design.md

@@ -168,12 +168,25 @@ v2; don't block on wire-protocol design.
   out of that build).
 
   ```python
-  tulip.install_c_process("crush", src)   # -> slot; ValueError on bad C
+  tulip.install_c_process("crush", src)   # effect -> slot; ValueError on bad C
   tulip.c_process("crush", True, 0)       # enable on bus 0 (on, bus=0)
+  tulip.install_c_osc("cz", osc_src)      # oscillator kind
+  tulip.c_osc("cz", 20)                   # AMY osc 20 now plays your C code
   tulip.c_process_calls("crush")          # blocks processed so far
   tulip.uninstall_c_process("crush")
   ```
 
+  `src` can be a **full program or just the function body** — bodies are
+  wrapped in the signature + standard includes automatically (with `#line`
+  so tcc errors keep the user's line numbers). Effect body sees
+  `buf/frames/chans`; osc body sees `buf/frames/osc/phase_inc_q16/amp_q15`
+  (mono buf; the dispatcher derives phase step + envelope from `msynth` so
+  pitch bend and ADSR just work, and AMY still applies pan). **State between
+  calls** = `static` variables in the body; polyphonic per-osc state =
+  static arrays indexed by `osc`. See the shipped example
+  `tulip/fs/tulip/ex/c_dsp_demo.py` (bitcrusher + CZ-101-style phase
+  distortion osc).
+
 ### Failure modes, honestly
 
 This is native code in the audio task. A wild pointer = panic + reboot, same as

tulip/fs/tulip/ex/c_dsp_demo.py

@@ -0,0 +1,84 @@
+# c_dsp_demo.py
+# User C DSP demo: write audio effects and oscillators in C, from Python.
+# (Tulip Desktop only for now -- AMYboard/web support is coming.)
+#
+# You give tulip just the *body* of a C function. Samples are plain 16-bit
+# PCM, -32767..32767, like a WAV file. No fixed point math needed.
+#
+# Effect body variables:  int16_t *buf, int frames, int chans
+#   buf is chans sequential channel blocks of frames samples; edit in place.
+# Osc body variables:     int16_t *buf, int frames, int osc,
+#                         int phase_inc_q16, int amp_q15
+#   Fill buf (mono) with frames samples. phase_inc_q16 is the per-sample
+#   phase step for the note's current pitch (65536 = one full cycle) and
+#   amp_q15 is the envelope level right now (0..32767) -- multiply by it so
+#   your osc follows AMY's ADSR.
+#
+# KEEPING STATE BETWEEN CALLS: declare variables `static`. They live as long
+# as the install. For oscillators, many AMY oscs can play your code at once
+# (polyphony!), so keep per-osc state in a static array indexed by `osc`,
+# like the phase[] array below.
+
+import tulip, amy, time
+
+# --- An effect: 10-bit bitcrusher ------------------------------------------
+
+CRUSH = """
+    int i = 0;
+    while (i < frames * chans) {
+        buf[i] = (buf[i] >> 10) << 10;
+        i = i + 1;
+    }
+"""
+
+# --- An oscillator: CZ-101-style phase distortion "saw" --------------------
+# Casio's CZ series makes bright waves without a filter: read a plain cosine
+# with a *bent* phase. The first `dcw` fraction of the cycle sweeps the
+# cosine's whole first half, the rest sweeps the second half. Small dcw =
+# buzzy and bright (like an open filter); dcw = 32768 = pure cosine.
+
+CZ = """
+    static int phase[256];               // per-osc phase, Q16: state between calls
+    int dcw = 6554;                      // bend point (0.1 of a cycle). edit me live!
+    int i = 0;
+    while (i < frames) {
+        int p = phase[osc];
+        int wp;                          // warped phase
+        if (p < dcw) wp = (int)(((long long)p * 32768) / dcw);
+        else wp = 32768 + (int)(((long long)(p - dcw) * 32768) / (65536 - dcw));
+        float angle = (float)wp * (6.2831853f / 65536.0f);
+        buf[i] = (int16_t)(cosf(angle) * (float)amp_q15);
+        p = p + phase_inc_q16;
+        if (p >= 65536) p = p - 65536;
+        phase[osc] = p;
+        i = i + 1;
+    }
+"""
+
+def run():
+    tulip.install_c_process('crush', CRUSH)
+    tulip.install_c_osc('cz', CZ)
+
+    # Point AMY osc 200 at our oscillator and set up its envelope. Use a HIGH
+    # osc number: low ones belong to midi.py's default synths, which fight
+    # you for control of them (raw events to an owned osc go silent).
+    tulip.c_osc('cz', 200)
+    amy.send(osc=200, wave=amy.SINE, bp0='10,1,500,0.2,250,0', vel=0)
+
+    print("CZ phase distortion osc...")
+    for note in (48, 52, 55, 60):
+        amy.send(osc=200, note=note, vel=1)
+        time.sleep(0.4)
+    time.sleep(1)
+
+    print("same notes through the bitcrusher...")
+    tulip.c_process('crush', True)
+    for note in (48, 52, 55, 60):
+        amy.send(osc=200, note=note, vel=1)
+        time.sleep(0.4)
+    time.sleep(1)
+    tulip.c_process('crush', False)
+    tulip.c_osc('cz', 200, False)
+    print("done. try editing CZ's dcw and re-running -- reinstalls hot-swap.")
+
+run()

tulip/shared/amy_connector.c

@@ -507,6 +507,8 @@ void run_amy(uint8_t capture_device_id, uint8_t playback_device_id) {
 #ifdef TULIP_USER_C_DSP
     extern void tulip_bus_postprocess_hook(uint8_t bus, SAMPLE *buf, uint16_t len);
     amy_config.amy_external_bus_postprocess_hook = tulip_bus_postprocess_hook;
+    extern uint8_t tulip_user_render_hook(uint16_t osc, SAMPLE *buf, uint16_t len);
+    amy_config.amy_external_render_hook = tulip_user_render_hook;
 #endif
     amy_config.features.default_synths = 0; // midi.py does this for us
     amy_config.capture_device_id = capture_device_id;

tulip/shared/modtulip.c

@@ -423,23 +423,48 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(tulip_pcm_load_file_obj, 0, 1, tulip_pcm_loa
 #ifdef TULIP_USER_C_DSP
 #include "user_c_dsp.h"
 
-// install_c_process(name, src): compile a C string defining
+// install_c_process(name, src): compile a C effect —
 // void process(int16_t *buf, int frames, int chans) — plain 16-bit PCM,
-// -32767..32767 — and install it under name.
+// -32767..32767 — and install it under name. src may be a full program or
+// just the function body (the wrapper and includes are added for you).
 STATIC mp_obj_t tulip_install_c_process(mp_obj_t name_obj, mp_obj_t src_obj) {
     char err[512];
-    int slot = user_c_dsp_install(mp_obj_str_get_str(name_obj), mp_obj_str_get_str(src_obj), err, sizeof(err));
+    int slot = user_c_dsp_install(mp_obj_str_get_str(name_obj), mp_obj_str_get_str(src_obj), USER_C_DSP_KIND_EFFECT, err, sizeof(err));
     if (slot < 0) mp_raise_msg_varg(&mp_type_ValueError, MP_ERROR_TEXT("install_c_process: %s"), err);
     return mp_obj_new_int(slot);
 }
 MP_DEFINE_CONST_FUN_OBJ_2(tulip_install_c_process_obj, tulip_install_c_process);
 
+// install_c_osc(name, src): compile a C oscillator —
+// void render(int16_t *buf, int frames, int osc, int phase_inc_q16, int amp_q15)
+// — and install it under name. src may be a full program or just the body.
+STATIC mp_obj_t tulip_install_c_osc(mp_obj_t name_obj, mp_obj_t src_obj) {
+    char err[512];
+    int slot = user_c_dsp_install(mp_obj_str_get_str(name_obj), mp_obj_str_get_str(src_obj), USER_C_DSP_KIND_OSC, err, sizeof(err));
+    if (slot < 0) mp_raise_msg_varg(&mp_type_ValueError, MP_ERROR_TEXT("install_c_osc: %s"), err);
+    return mp_obj_new_int(slot);
+}
+MP_DEFINE_CONST_FUN_OBJ_2(tulip_install_c_osc_obj, tulip_install_c_osc);
+
+// c_osc(name, osc, on=True): replace AMY osc number osc's waveform with the
+// named user oscillator (or restore it with on=False).
+STATIC mp_obj_t tulip_c_osc(size_t n_args, const mp_obj_t *args) {
+    int on = (n_args > 2) ? mp_obj_is_true(args[2]) : 1;
+    int r = user_c_dsp_bind_osc(mp_obj_str_get_str(args[0]), mp_obj_get_int(args[1]), on);
+    if (r == -1) mp_raise_ValueError(MP_ERROR_TEXT("no such c_osc"));
+    if (r == -2) mp_raise_ValueError(MP_ERROR_TEXT("bad osc number"));
+    if (r == -3) mp_raise_ValueError(MP_ERROR_TEXT("not an osc (installed with install_c_process?)"));
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(tulip_c_osc_obj, 2, 3, tulip_c_osc);
+
 // c_process(name, on, bus=0): enable/disable a named process on a bus.
 STATIC mp_obj_t tulip_c_process(size_t n_args, const mp_obj_t *args) {
     int bus = (n_args > 2) ? mp_obj_get_int(args[2]) : 0;
     int r = user_c_dsp_set(mp_obj_str_get_str(args[0]), bus, mp_obj_is_true(args[1]));
     if (r == -1) mp_raise_ValueError(MP_ERROR_TEXT("no such c_process"));
     if (r == -2) mp_raise_ValueError(MP_ERROR_TEXT("bad bus"));
+    if (r == -3) mp_raise_ValueError(MP_ERROR_TEXT("not an effect (installed with install_c_osc?)"));
     return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(tulip_c_process_obj, 2, 3, tulip_c_process);
@@ -1773,7 +1798,9 @@ STATIC const mp_rom_map_elem_t tulip_module_globals_table[] = {
 
 #ifdef TULIP_USER_C_DSP
     { MP_ROM_QSTR(MP_QSTR_install_c_process), MP_ROM_PTR(&tulip_install_c_process_obj) },
+    { MP_ROM_QSTR(MP_QSTR_install_c_osc), MP_ROM_PTR(&tulip_install_c_osc_obj) },
     { MP_ROM_QSTR(MP_QSTR_c_process), MP_ROM_PTR(&tulip_c_process_obj) },
+    { MP_ROM_QSTR(MP_QSTR_c_osc), MP_ROM_PTR(&tulip_c_osc_obj) },
     { MP_ROM_QSTR(MP_QSTR_c_process_calls), MP_ROM_PTR(&tulip_c_process_calls_obj) },
     { MP_ROM_QSTR(MP_QSTR_uninstall_c_process), MP_ROM_PTR(&tulip_uninstall_c_process_obj) },
 #endif