Subversion Repositories svn.mios

Rev

Rev 804 | Blame | Compare with Previous | Last modification | View Log | RSS feed

HEADER 3 MIOS8 C Interface

<H1>MIOS8 C Interface</H1>

<P CLASS=INFO>Programming <A HREF="mios.html">MIOS8</A> applications in C became an alternative solution to assembler, since this highlevel language is easier to understand, less error-prone and better re-usable. Disadvantage of C on a PIC controller is worse performance and larger code size, which means that it won't be possible to program so complex applications like <A HREF="midibox_sid.html">MIDIbox SID</A> or <A HREF="midibox_seq.html">MIDIbox SEQ</A> completely in C, especially due to reduced flash and RAM of the PIC18F452 (which is mostly sufficient - but not high enough for so much features...).<P>

<P CLASS=INFO>PIC derivatives like PIC18F4620 and PIC18F4685 relax the memory limitations a bit, but for complex and resource hungry applications the usage of <A HREF="mios32_c.html">MIOS32</A> and a <A HREF="mbhp_core_stm32.html">MBHP_CORE_STM32</A> module is recommended.</P>

<P CLASS=DESC>However, regardless of this fact, MIOS8 and C is a good combination. Why? Because MIOS8 (the operating system) is programmed in assembly language and has been hand-optimized for speed. It handles a lot of performance critical tasks for which the user doesn't need to take care about. MIOS contains a lot of ready made functions that saves people from reinventing the wheel - it enables the interested programmer to implement a MIDI project successfully without the background knowledge about high performance IO handling and proper MIDI processing.</P>

<P CLASS=DESC>So, the user can just start at the application layer where code optimization mostly doesn't matter. And he can expect that many functions will be processed with the same speed, regardless if they have been programmed in C or assembler - ok, the result heavily depends on the application and the compiler which is used, but it's already possible to realize a lot of nice stuff without much effort, and then more users are starting with the C approach, then more coding examples can be shared in the community which should boost up the development cycle of new applications.</P>

<P CLASS=DESC>Currently I'm not able to estimate when it makes sense to program something in assembler or in C - this is some kind of knowledge which has to be built up in the next months - your feedback is welcome! Keep in mind that mixing C and assembler at application layer is still possible. My current suggestion: especially the user interface (button/LED handling, display output, MIDI IO) can be implemented in C without disadvantages, but routines which have to interact fast (like a peripheral driver, or algorithms which has processes a huge amount of data) should be programmed in separate assembler modules and called from C.</P>

<H2>Technical Realization</H2>

<P CLASS=DESC>For MIOS8 itself it doesn't make a difference if a C or assembler routine is hooked to the USER_* callback routines, because this possibility has been taken into account from the beginning of the design phase. MIOS8 will always branch to the USER_* vectors on events, which are part of the application. And from there the application can branch to the C function if desired.</P>

<P CLASS=DESC>MIOS8 functions (MIOS_*) can mostly be called from a C program without performance loss, so long it has only one input and/our output parameter. Functions with more parameters require some extra code which copies the C parameters (which are pushed into the stack) to MIOS_PARAMETER[123].</P>

<P CLASS=DESC>If this sounds new to you, then please don't feel confused - you don't have to take care about this low-level handling!</P>

<P CLASS=DESC>Instead just use the so called "Wrapper" which contains all the code which is required to link C functions to MIOS8. This wrapper is part of the <A HREF="mios_download.html">MIOS8 base package</A>.</P>

<P CLASS=DESC>The wrapper code heavily depends on the compiler which is used. Currently only <A HREF="http://sdcc.sourceforge.net" TARGET="_blank">SDCC</A> is supported, since this is the only compiler for the PIC18F architecture which is freely available. Also the compiler version is important, since the parameter passing method is not stable yet. Therefore please only use official releases (no snapshots) which have been tested with the wrapper. The current <B>working</B> release is 2.8.0<BR>
Btw.: the appr. module is called "PIC16", which doesn't mean that it is intended for PIC16Fxxx processors, but for the PIC18F family with 16-bit code word size. The module is under development and therefore not well documented - but it already works fine and will be improved from time to time.<P>

<P CLASS=DESC>The MIOS8 base package also contains a skeleton for C applications, it's located under $MIOS_PATH/apps/templates/sdcc_skeleton/<BR>
Once you are able to compile this application, you are ready to start programming your own.
<P CLASS=INFO>Related Wiki links:<UL CLASS=CL>
  <LI><A HREF="http://www.midibox.org/dokuwiki/application_development" TARGET="_blank">Introduction of the toolchain</A></LI>
  <LI><A HREF="http://www.midibox.org/dokuwiki/windows_toolchain_quickstart" TARGET="_blank">Quickstart Guide for Windows users</A></LI>
</UL>
</P>

<P CLASS=DESC><I>Note for advanced users: there is a separate user and IRQ stack defined in the Makefile which can be increased (or decreased) if required for large programs. Please also have a look into the larger SDCC based applications like MIDIbox MM and Stribe which demonstrate how to handle with more complex MIOS8 interactions.</I></P>


<H2>Programming Examples</H2>

<UL CLASS=CL>
 
<TABLE CLASS=BOX WIDTH="100%" ALIGN=CENTER BORDER CELLSPACING=2 CELLPADDING=3 >

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_send_ain.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Sending MIDI events on pot movements</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_send_mapped.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Sending mapped MIDI events on pot movements</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_send_range.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Scaling pot values</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_send_ain_takeover.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Realising a Soft-Takeover function for pots</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_send_din.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Sending MIDI events on button movements</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_set_dout.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Controlling 128 LEDs via MIDI</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_send_enc_rel.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Sending relative MIDI events on rotary encoder movements</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_send_enc_abs7.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Sending 7bit MIDI events on rotary encoder movements</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_send_enc_abs14.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Sending 14bit NRPN events on rotary encoder movements</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_handle_mf.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>A simple handler for motorfaders</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_filter_cc.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Filtering every MIDI Event except Bn 07 xx (Volume Controllers)</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_forward_chn1.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Only forward events of Channel #1</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_cc_to_nrpn.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Converting CC to NRPN</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_nrpn_to_cc.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Converting NRPN to CC</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_pic_pin.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Driving PIC pins via MIDI</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_lcd_out.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Printing values on a LCD</SPAN></TD>
  </TR>

  <TR>
    <TD WIDTH=30><SPAN CLASS=BIG><A HREF="mios_c_lcd_schars.html">CODE</A></SPAN></TD>
    <TD><SPAN CLASS=NORM>Using special characters on a LCD</SPAN></TD>
  </TR>

</TABLE>

FOOTER