How should XC libraries be used with C programs?

Technical questions regarding the xTIMEcomposer, xSOFTip Explorer and Programming with XMOS.
erlingrj
Junior Member
Posts: 7
Joined: Tue Aug 10, 2021 1:21 pm

How should XC libraries be used with C programs?

Post by erlingrj »

According to the latest documentation C/C++ is the preferred language to develop and XC will likely be deprecated at some point. I think that is a shame as it seems to offer very nice abstractions for concurrent programming. I am starting out developing an embedded application on xCore and I am probably gonna write it in C. But so far I find that all the peripheral libraries are written in XC and no examples for how to use them with a C program. I have made a simple example in my fork of lib_uart [1]. under examples/uart_streaming_demo_c you can find a working (with the simulator at least) example of streaming uart TX using C. I have pasted the main.c under here:

Code: Select all

#include <uart.h>
#include <stdio.h>
#include <xcore/parallel.h>
#include <xcore/port.h>
#include <xcore/channel_streaming.h>


// Forward declare uart_rx_streaming from lib_uart as a "job"??
// Change port, and chanend to unsigned int
DECLARE_JOB(uart_tx_streaming, (unsigned int, unsigned int, int));

// Declare also this with changing from XC types to C types
void uart_tx_streaming_write_byte(unsigned int c, uint8_t data);


#define TICKS_PER_BYTE 100

DECLARE_JOB(uart_app, (chanend_t));
void uart_app(chanend_t chan)
{
    printf("Starting uart tx\n");
    uint8_t byte = 0;

    while(1) {
        uart_tx_streaming_write_byte(chan, byte);
        printf("Sucessfully sent byte: 0x%X\n", byte);
        byte += 1;
    }   
}


int main(void) {
    streaming_channel_t chan = s_chan_alloc();
    
    port_t p_uart_rx = XS1_PORT_1A;
    port_enable(p_uart_rx);

    PAR_JOBS(
        PJOB(uart_app, (chan.end_b)),
        PJOB(uart_tx_streaming, ( p_uart_rx, chan.end_a, TICKS_PER_BYTE))
    );

    s_chan_free(chan);
    port_disable(p_uart_rx);

    return 0;
}


Do I really have to forward declare all functions I want to use from the XC libraries and exchange the chanend/timer/port primitives with "unsigned int" as explained her [2]? Wouldn't it make sense to move this kind of highly repetitive and error-prone boilerplate code into the libraries themselces?


[1] https://github.com/erlingrj/lib_uart/tree/c-example
[2] https://www.xmos.ai/documentation/XM-01 ... lling.html


erlingrj
Junior Member
Posts: 7
Joined: Tue Aug 10, 2021 1:21 pm

Post by erlingrj »

Actually, in uart.h of lib_uart all the function prototypes are hidden behind a #ifdef __XC__ directive, the natural solution is to add the C-friendly prototypes befind a #elif __STDC__ directive.
erlingrj
Junior Member
Posts: 7
Joined: Tue Aug 10, 2021 1:21 pm

Post by erlingrj »

No I am looking at lib_spi, this has no #ifdef __XC__ directives and can thus not be included in a C project because it uses all the xC primitives. Is there something I am doing wrong here?
User avatar
CousinItt
XCore Addict
Posts: 253
Joined: Wed May 31, 2017 6:55 pm

Post by CousinItt »

Existing code written in XC
Existing XC source code does not need to be ported to C.

The XC compiler, accessed via the XCC compiler driver, will remain part of the tools release. No date has been set for its removal.

Where a decision is made to port a library to C, users may consider porting only the public API for expediency, rather than the entire library.

The XC compiler itself will be maintained for existing applications and libraries. Feature requests or performance optimisations will not be considered.

For guidance on projects developed within older tools releases, see Migrating existing projects.
Note the apparent conflict on the future of the compiler. Also, for multi-tile applications an xc file is still needed, unless this is a stepping stone which they couldn't resolve quickly enough.

So I think your choices are either to use the libraries you need as they are, possibly with a C-friendly interface/wrapper layer using xccompat.h, or to modify them (their API at least) to allow for C compatibility.

https://www.xmos.ai/documentation/XM-01 ... -tile.html