PDCP for AVR – middle layer interface

overview

This document describes an implementation of the Prosthetic Device Communication Protocol (PDCP) consisting of 2 layers:

1. hll – high level layer
2. hal – hardware abstraction layer

The purpose of this document is to detail the interface between these layers.

synopsis

struct can_msg;
void hal_set_filter(uint8_t filter);
void hal_set_mask(uint8_t mask);
void hal_msg_poll();
struct can_msg* hll_msg_alloc();
void hll_msg_commit(struct can_msg* msg);
struct can_msg* hll_msg_get();
void hll_msg_free(struct can_msg* msg);

description

hal_set_filter shall set the filter configuration of the CAN controller to that specified in filter.

hal_set_mask shall set the mask configuration of the CAN controller. The bits in filter masked by mask must match the corresponding bits in the incoming message's Node Id for it to be received by the CAN controller.

hal_msg_poll shall retry fetching any incoming CAN messages left in the CAN controller by simulating an interrupt from the CAN controller.

hll_msg_alloc shall reserve unused memory in the high level layer for an incoming CAN message. This memory shall contain a can_msg structure, to which a pointer shall be returned to the caller. The caller must initialze the structure and send it back by calling hll_msg_commit.

hll_msg_commit shall pass the CAN message referenced by msg to the high level layer's input queue.

hll_msg_get shall look for an outgoing CAN message, and if found, return the contained can_msg structure. Otherwise, it shall return NULL. The caller must signify when it is finished with the pointed-to memory by calling hll_msg_free.

hll_msg_free shall mark the memory in use by the CAN message containing msg as unused.

failure modes

If no memory for an incoming CAN message is found, hll_msg_alloc shall return NULL.

If no outgoing CAN message is found, hll_msg_get shall return NULL.

These functions shall not fail:

• hll_msg_commit
• hll_msg_free

note

• The hardware abstraction layer may leave CAN messages in the CAN controller in the event of failure of hll_msg_alloc. Therefore, the high level layer must call hal_msg_poll when it expects hll_msg_alloc to become possible.
• Incoming CAN messages may only be lost due to full receive buffers in the CAN controller. Assuming the high level layer calls hal_msg_poll whenever its internal «receive buffer» is no longer full, this situation only arises when the latter buffer is already full, and is still filled faster than emptied.
• Outgoing CAN messages are not lost. The high level layer may be temporarily unable to handle outgoing CAN messages only when its internal «send buffer» is full.
• The high level layer's «send» and «receive» buffers may be implemented as a shared memory pool, with no space reserved for any direction. Thus, the capacity of one buffer may be zero due to the other buffer being full.