[PATCH 0/4] dev/io: Add packet processor

[Chris Johns]

Hi,

There are a few things I do not understand about this addition. I brief review
of the code seems OK but I am struggling to understand the requirements driving
this addition. Can a ticket please be created with the requirements and a real
world use case of how it would be used and what problem(s) it solves?

I also think dev/io.h and dev/iopacket.c are too generic for something thing
that appears to be specific to a specific use case.

Chris

On 15/1/2024 8:45 pm, Sebastian Huber wrote:
> The I/O packet processor provides a simple mechanism to exchange
> reliable and in-order data through transmitting and receiving one
> character at a time.
> 
> The I/O packet processor does not buffer data.  The processor uses a
> stop-and-wait automatic repeat request method. There is at most one packet
> in transmission.  The data transfer is done using a single character input
> and output method.  The protocol uses 12-bit sequence numbers, so a host
> could use a sliding window method to increase throughput.  All integers and
> data are base64url encoded.  A 24-bit CRC is used to ensure the data
> integrity.  The '{' character starts a packet.  The '}' character terminates
> a packet.  The '#' character prefixes a 24-bit CRC value.  The ':' character
> separates fields.  The '+' character prefixes data fields.  The following
> packets are defined:
> 
> * hello: {<12-bit seq><12-bit ack>:H#<24-bit CRC>}
> 
> * acknowledge: {<12-bit seq><12-bit ack>:A#<24-bit CRC>}
> 
> * reject: {<12-bit seq><12-bit ack>
>   :R:<12-bit seq of rejected packet>#<24-bit CRC>}
> 
> * jump: {<12-bit seq><12-bit ack>:J:<64-bit address>#<24-bit CRC>}
> 
> * load: {<12-bit seq><12-bit ack>:L:<64-bit load address>
>   <64-bit load size in bytes>#<24-bit CRC>+<data to load>#<24-bit CRC>}
> 
> * signal: {<12-bit seq><12-bit ack>:S:<64-bit signal number>:
>   <64-bit signal value>#<24-bit CRC>}
> 
> * channel: {<12-bit seq><12-bit ack>:C:<64-bit channel number>
>   <64-bit data size in bytes>#<24-bit CRC>+<channel data>#<24-bit CRC>}
> 
> The intended use case are boot loaders and test runners.  For example, test
> runners may interface with an external test server performing equipment
> handling on request using the I/O packet processor.
> 
> Use _IO_Packet_initialize() to initialize the I/O packet processor.  Use
> _IO_Packet_process() to drive the packet processing.  You can enqueue
> packets for transmission with _IO_Packet_enqueue().  You can reliably send
> signals with _IO_Packet_send().  You can reliably transmit and receive
> channel data with _IO_Packet_channel_push() and
> _IO_Packet_channel_exchange().
> 
> A simple boot loader could be implemented like this:
> 
>   #include <bsp.h>
>   #include <rtems/bspIo.h>
>   #include <rtems/counter.h>
>   #include <rtems/dev/io.h>
> 
>   static void output_char( IO_Packet_control *self, uint8_t ch )
>   {
>     (void) self;
>     rtems_putc( ch );
>   }
> 
>   static IO_Packet_status event_handler(
>     IO_Packet_control       *self,
>     IO_Packet_event_control *ctrl,
>     IO_Packet_event          evt
>   )
>   {
>     (void) ctrl;
> 
>     switch ( evt ) {
>       case IO_PACKET_EVENT_JUMP:
>         _IO_Packet_send_acknowledge( self );
>         bsp_restart( _IO_Packet_get_jump_address( self ) );
>         break;
>       case IO_PACKET_EVENT_LOAD_END:
>         _IO_Packet_send_acknowledge( self );
>         break;
>       case IO_PACKET_EVENT_OUTPUT_END:
>         rtems_putc( '\n' );
>         break;
>       default:
>         break;
>     }
> 
>     return IO_PACKET_SUCCESSFUL;
>   }
> 
>   static uint32_t clock_monotonic( IO_Packet_control *self )
>   {
>     (void) self;
>     return rtems_counter_read();
>   }
> 
>   static void Init( rtems_task_argument arg )
>   {
>     IO_Packet_control self;
>     IO_Packet_event_control event;
> 
>     (void) arg;
>     _IO_Packet_initialize( &self, 0, NULL, output_char, clock_monotonic );
>     _IO_Packet_prepend_event_handler( &self, &event, event_handler );
> 
>     while ( true ) {
>       _IO_Packet_process( &self, getchark() );
>     }
>   }
> 
> Matthew Joyce (1):
>   dev/io: Add base64 decoder
> 
> Sebastian Huber (3):
>   dev/io: Make base64 encoding tables public
>   dev/io: Add a CRC-24Q implementation
>   dev/io: Add packet processor
> 
>  cpukit/dev/iobase64.c                         |  24 +-
>  cpukit/dev/iobase64decode.c                   | 166 +++
>  cpukit/dev/iocrc24q.c                         | 148 +++
>  cpukit/dev/iopacket.c                         | 837 ++++++++++++++++
>  cpukit/include/rtems/dev/io.h                 | 941 ++++++++++++++++++
>  spec/build/cpukit/librtemscpu.yml             |   3 +
>  .../build/testsuites/unit/unit-no-clock-0.yml |   3 +
>  testsuites/unit/tc-io-base64-decode.c         | 180 ++++
>  testsuites/unit/tc-io-packet.c                | 617 ++++++++++++
>  9 files changed, 2912 insertions(+), 7 deletions(-)
>  create mode 100644 cpukit/dev/iobase64decode.c
>  create mode 100644 cpukit/dev/iocrc24q.c
>  create mode 100644 cpukit/dev/iopacket.c
>  create mode 100644 testsuites/unit/tc-io-base64-decode.c
>  create mode 100644 testsuites/unit/tc-io-packet.c
>