github.com/pkoning2.ddcmp
1
0
Fork 0
mirror of https://github.com/pkoning2/ddcmp.git synced 2026-01-11 23:53:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

Bugfixes in firmware, add status report on SYN status change.

Browse Source 
Update documentation.
Add links for OSHPark shared PCB layout and Digikey shared BOM.
This commit is contained in:
Paul Koning 2021-08-23 10:33:29 -04:00
parent 97da597a0b
commit 6b456dc489
6 changed files with 106 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
README.md
View File

@ -17,13 +17,28 @@ To use the framer, connect the micro-USB board to a USB port on the computer tha
There are a number of choices for connecting the synchronous link to whatever device you want to use it with:
1. To use a synchronous modem or modem eliminator, connect it with a straight through DB-25 cable to the male DB-25 (marked "DTE").
1. To use a synchronous modem or modem eliminator, connect it with a straight through DB-25 cable to the male DB-25 (marked "DTE"), and operate the framer in "rs232_dte" mode.
2. To connect to a DDCMP device such as the DMR-11 using an RS-232 connection, connect its male DB-25 connector with a straight through DB-25 cable to the female DB-25 (marked "DCE") on the framer.
2. To connect to a DDCMP device such as the DMR-11 using an RS-232 connection, connect its male DB-25 connector with a straight through DB-25 cable to the female DB-25 (marked "DCE") on the framer, and operate the framer in "rs232_dce" mode. In this mode the framer supplies the bit clocks; you specify the desiredd data rate as one of the start command parameters.
3. If you have a device such as a DMR-11 that has a line card which is meant to connect to a BC55 bulkhead panel via a 40-pin ribbon cable, but you don't have or do not want to use a bulkhead panel, connect the line unit with 40 pin ribbon cable to the 40-pin header J8 (marked "To LU"). You can use either RS-232 (with bit clock generated by the framer) or integral modem operation using this connection.
4. If you want to connect the framer to a BC55 bulkhead panel (RS-232 or integral modem), connect the BC55 with a 40-pin ribbon cable to the 40-pin header J7. Do not install termination resistors on the integral modem panel (BC55A); for details, refer to doc/kicad.md.
4. If you want to connect the framer to a BC55 bulkhead panel (RS-232 or integral modem), connect the BC55 with a 40-pin ribbon cable to the 40-pin header J7. Do not install termination resistors on the integral modem panel (BC55A); for details, refer to `doc/kicad.md`.
5. You can connect integral modem coaxial cables to BNC connectors J2 (incoming data) and J3 (outgoing data). Note that DEC specifies triax cable (two shields) but those connectors are expensive so here we just use BNC connectors, which should be fine so long as you're not operating in an extremely noisy environment. Do not install terminating resistors at the framer end, they are built in to the board.
## Indicator lights
There are three indicator lights on the framer board, as well as an LED on the Raspberry Pico board itself. They are:
1. Pico board LED: "on" indicator. It lights up when the framer is started with a successful start command, and off when the framer is stopped.
2. "SYN" indicator: byte sync status. This lights up when the framer receiver has completed byte synchronization, having received four or more consecutive SYN bytes (hex 96). SYN status remains set unless the DDCMP state machine restarts sync search; it will do so if a header CRC error occurs. If the light does not come on, this may indicate no received signal, or (for integral modem mode) speed mismatch exceeding the 10% receive rate tolerance. If the SYN indicator flashes frequently, this may indicate poor signal quality, or (for integral modem mode) a speed mismatch right at the limit of what the device can handle. Note that the weak signal capability of the integral modem depends on the transformers used; refer to `doc/kicad.md` for details.
3. "RX" indicator: flashes when a frame is received (either successfully or with an error).
4. "TX" indicator: flashes when a frame is transmitted.
The RX and TX LEDs have pulse stretchers, so the light flashes are clearly visible even at low packet rates.
The RX and TX LEDs flash once when a framer start command is successfully executed.

16
doc/api.md
View File

@ -2,7 +2,7 @@
The framer appears to the host as an Ethernet interface. The interface hardware address is hardcoded aa-00-03-04-05-06 (an unused address from a range assigned to DEC and then rendered obsolete by IEEE 802 -- see `ether-i.pdf`). The framer itself then appears as another Ethernet node connected to that NIC, with hardcoded address aa-00-03-04-05-07.
Communication with the framer uses raw Ethenet packets with protocol type is 60-06 (DEC protocol type assigned to "Customer use").
Communication with the framer uses raw Ethenet packets with protocol type is 60-06 (DEC protocol type assigned to "Customer use"). Following the protocol type is a payload length field, 2 bytes little endian, following the common pattern of many Digital protocols (like DECnet). This allows the frames to be padded to the minimum Ethernet size; USB does not require this but SIMH does.
The payload of these Ethernet packets is either a DDCMP frame, or a command/status packet. The encoding is slightly different for inbound (received data to host) vs. outbound (transmitted data from host).
@ -10,7 +10,7 @@ Outbound payloads are simply DDCMP frames as encoded on the wire, except that th
Inbound payloads begin with a 2-byte receive status value, followed by the received DDCMP frame exactly as received, including the CRC fields. Note that the framer implements CRC checking; the host normally would not look at the CRC bytes but simply use the status value to learn whether the packet is good or bad.
In either direction, we ignore the minimum frame length of Ethernet; only the needed bytes are sent since the USB emulated Ethernet NIC does not appear to object to undersized frames. But since we limit framer packets to standard Ethernet size, the largest DDCMP data length supported is 1488.
In either direction, we pad frames to the minimum frame length of Ethernet. USB emulated Ethernet NIC does not appear to object to undersized frames, but some applications (like SIMH) assume that the Ethernet minimum should be enforced. Since we limit framer packets to standard Ethernet size, the largest DDCMP data length supported is 1486.
Command/status packets begin with 021 (DC1) which is not a DDCMP frame start value. Outbound they carry commands to the adapter; inbound they carry status and counters. Note that the inbound status packet is preceded by a receive status word, as always; for status packets the receive status is always zero (OK).
@ -57,10 +57,11 @@ Transmit speed (4 bytes):
This is the transmit data rate, if the "split speed" bit is set in `mflags`.
Status packet starts with 021 (after the usual 2 byte receive status field), followed by state and counter data:
Status packet starts with 021 (after the usual 2 byte payload length and receive status fields), followed by state and counter data:
* state (1 byte): flags, bit 0 = on (active), bit 1 = in-sync
* mode and flags (2 bytes): as described above for the Start command
* maximum frame payload: 1486 -- information for the host software
* speed (4 bytes): as described above. Not used for RS-232 DTE mode.
* transmit speed (4 bytes): as described above.
* Counters -- all are 4 bytes and wrap on overflow:
@ -77,6 +78,13 @@ Status packet starts with 021 (after the usual 2 byte receive status field), fol
* measured data rate (4 bytes), in bits per second
* framer firmware version (null-terminated ASCII string)
Status messages are generated:
1. At device powerup.
2. In response to any command.
3. In response to a transmit or raw-transmit request that has invalid parameters.
4. When the in-sync status changes (sync acquired or sync lost).
5. In BIST mode, after every 1000 transmitted frames.
Note that the measured data rate for the integral modem case is an approximation since it operates by measuring the edge timing of the received waveform. The calculation assumes that the received data is half ones and half zeroes, which is the case for an idle line (SYN bytes are half and half). If the line is actively carrying data and that data has a different bit density the measured line rate will be inaccurate; in particular for all zeroes it will be 33% higher than the true value. The intent of this data item is to allow checking the data rate of a connected device whose clock may be off spec or unknown, allowing the framer to be configured with a matching data rate for reliable operation.
Last command status values are:
@ -109,4 +117,4 @@ BIST mode can also requested by setting bit 3 in the mode/flags field of a "Star
The DECnet/Python package, in the `tests` directory, contains a set of framer tests in `test_framer.py`. These can be invoked in the usual way, either the full set or any desired specific tests or test classes. Refer to the Python library manual, "unittest" module, for details. Some of the tests require loopback connectors to be installed, and some that use RS-232 DTE mode also require a clock source such as a modem eliminator to be attached to the DTE connector. If this is not done those tests will fail with messages indicating the reason is a missing loopback connector or clock source.
The full set of framer tests require about TBD minutes to run.
The full set of framer tests require about 3.5 minutes to run.

12
doc/kicad.md
View File

@ -1,11 +1,11 @@
# DDCMP Framer
The `kicad/ddcmp` subdirectory contains the design files for the DDCMP framer circuit board, which you can inspect or modify using the open source KiCAD package.
The `kicad/ddcmp` subdirectory contains the design files for the DDCMP framer circuit board (AK-005 A), which you can inspect or modify using the open source KiCAD package.
## Creating the circuit board
There are three ways to get a circuit board.
1. From the shared designs section of the OSHPark PCB fabricator website, in [this link](https://oshpark.com/shared_projects/TO_BE_SUPPLIED "DDCMP Framer").
1. From the shared designs section of the OSHPark PCB fabricator website, in [this link](https://oshpark.com/shared_projects/buAWT8Hy "DDCMP Framer").
2. From any PCB fabricator that accepts KiCAD board files (such as OSHPark).
3. From any PCB fabricator that doesn't, by generating the standard *Gerber* files.
@ -61,7 +61,7 @@ Here are all the parts in the design, with schematic reference (also on the boar
| U3 | MAX3222 | RS-232 transceiver | Maxim | MAX3222ECPN+-ND |
| U4 | MAX3222 | RS-232 transceiver | Maxim | MAX3222ECPN+-ND |
If you want to use Digikey as your supplier, the saved BOM is available [there](https://www.digikey.com/short/TO_BE_SUPPLIED "Digikey BOM"). Note that TR1 and TR2 are not in that BOM since Digikey does not have these; you can order them directly from Mini-Circuits.
If you want to use Digikey as your supplier, the saved BOM is available [there](https://www.digikey.com/short/h1mqd0dm "Digikey BOM"). Note that TR1 and TR2 are not in that BOM since Digikey does not have these; you can order them directly from Mini-Circuits.
### Optional components
@ -90,7 +90,7 @@ If you have trouble getting this part, several other Mini-Circuits transformers
#### Tested alternatives
1. Mini-Circuits ADT1-6T+ (Digikey 3157-ADT1-6T+CT-ND). This one has a specified lower limit of 30 kHz, which means 56kbps is slightly out of spec. Loopback test over around 70 feet of small size coax with a number of connectors to it shows no errors, but the eye pattern is just barely open enough for that to be true. Higher speeds work fine and have excellent eye patterns. If you intend to use short cables, or high speeds (250 kbps or above), this option is fine.
1. Mini-Circuits ADT1-6T+ (Digikey 3157-ADT1-6T+CT-ND). This one has a specified lower limit of 30 kHz, which means 56kbps is slightly out of spec. Loopback test over around 70 feet of small size coax with a number of connectors shows no errors, but the eye pattern is just barely open enough for that to be true. Higher speeds work fine and have excellent eye patterns. If you intend to use short cables, or high speeds (250 kbps or above), this option is fine.
#### Untested alternatives
@ -109,7 +109,7 @@ If you use the line unit 40-pin connection (J8) with the integral modem, you wil
### Assembly suggestions
I found that this order of installing the components works well:
1. U1 (Raspberry Pico). You can surface-mount this or use pin headers (or even short wires) if you prefer.
1. U1 (Raspberry Pico). You can surface-mount this or use pin headers (or even short wires) if you prefer. There are mounting holes to secure the part to the board, which is probably a good idea if surface mounted so the mechanical integrity doesn't depend on the shear strength of the solder joints. The mounting holes are for M2 (metric 2 millimeter) screws. #2 US screws are a hair too big.
2. TR1, TR2 transformers, if you are using surface mount parts
3. Resistors and capacitors
4. LEDs
@ -121,6 +121,8 @@ Note the correct orientation of D1, D2, D3, J7, J8, U1, U2, U3, and U4. U1 is o
The transformers TR1 and TR2 have an orientation dot on the package. For the ADT2-71T+ orintation is important (see above).
The coax connectors (J2 and J3) are made of zinc alloy (pot metal). This is unfortunately standard practice for PCB mount BNC connectors. Before installing, lightly sand the thick body pins to make the solder stick better. It will take a fair amount of heat to solder these pins; use an adequate soldering iron and beware of burning your fingers on the connector bodies for several minutes afterwards.
## Software load
After the board is built you will need to load the software. See the `software.md` file for instructions.

2
doc/software.md
View File

@ -31,4 +31,4 @@ This will build all the necessary components and produce a loadable binary, `ddc
## Options
There is only one build option: change `#define DEBUG 0` to `#define DEBUG 1` to enable debug output to the UART. Plug in a 3.3 volt UART at J1 (note the orientation: pin 1, black wire, is marked by a dot). The UART is set for 115,200 baud, 8 bits, no parity. Debug messages appear in the source code as DPRINTF statements. You can define DEBUG to be 2, this also enables the detailed debug messages (DDPRINTF), but that is very verbose and will significantly slow down operation of the device.
There is only one significant build option: change `#define DEBUG 0` to `#define DEBUG 1` to enable debug output to the UART. Plug in a 3.3 volt UART at J1 (note the orientation: pin 1, black wire, is marked by a dot). The UART is set for 115,200 baud, 8 bits, no parity. Debug messages appear in the source code as DPRINTF statements. You can define DEBUG to be 2, this also enables the detailed debug messages (DDPRINTF), but that is very verbose and will significantly slow down operation of the device.

85
firmware/ddcmp.c
View File

@ -13,6 +13,12 @@
// off UART use.
#define DEBUG 0
// Define this as 0 to turn off padding of frames going to the host.
// For maximal compatibility with various Ethernet drivers we normally
// pad frames so they are at least 60 bytes (Ethernet minimum, not
// counting CRC).
#define PADRUNT 1
// Define this to 1 (default) for 8 bit transmit FIFO, 0 for 32 bit
// transmit FIFO. For standard speeds, 8 bit FIFO is more than
// adequate.
@ -40,6 +46,12 @@
#define MB asm volatile ("" : : : "memory")
#if PADRUNT
#define MINE(x) ((x) > 60) ? (x) : 60
#else
#define MINE(x) (x)
#endif
#if DEBUG
// Debugging, if enabled, uses the UART at the default pins (pin 1 and
// 2, GPIO 0 and GPIO 1).
@ -88,6 +100,9 @@ volatile int avg_period = 0;
// Receive (and more generally, the device) enabled state.
volatile bool rx_enabled = false;
// Last reported SYN status
bool syn_status = false;
// Selftest mode active
bool bist = false;
@ -153,13 +168,14 @@ const uint8_t opins[] = {
#define DC1 0021 // DC1 - used here for command/status, not DDCMP
#define SYN4 0x96969696U
#define RXLIMIT (1500 - 2) // Max received total frame size to host
#define RXLIMIT (1498 - 2) // Max received total frame size to host
#define RDMAX (RXLIMIT - 8 - 2) // Max receive DDCMP data length
#define TXLIMIT 1500 // Max transmit total frame size from host
#define TXLIMIT 1498 // Max transmit total frame size from host
#define TDMAX (TXLIMIT - 6) // Max transmit DDCMP data length
#define MAXLEN (RDMAX < TDMAX ? RDMAX : TDMAX) // Max DDCMP payload
#define RDATA (MAXLEN + 8 + 2) // Frame space in rings
#define BUF_OFF 16 // Buffer offset to start of DDCMP frame
#define ETH_HDR 14 // Length of Ethernet header
#define RBUF_OFF (ETH_HDR + 4) // Rx buffer offset to start of DDCMP frame
#define SYN_CNT 8 // Count of SYN bytes before tx frame start
#if TX8
#define SYN_CNT_V3 10 // Ditto, but in DMC11-AL V3 compatibility mode
@ -208,8 +224,8 @@ enum ddcmp_status
// DDCMP frame buffer layout (framer to host)
struct ddcmp_rxframe
{
int data_len;
uint8_t bufhdr[BUF_OFF - 2]; // room for "Ethernet" header
uint8_t bufhdr[ETH_HDR]; // room for "Ethernet" header
uint16_t data_len; // DDCMP payload length
volatile uint16_t stat; // Status (ddcmp_status code)
uint8_t data[RDATA]; // DDCMP frame data (header + payload)
};
@ -257,10 +273,11 @@ volatile dma_channel_hw_t *txcsr;
// host. The host interface address is aa-00-03-04-05-06; the framer
// appears as an Ethernet device on that LAN with fixed address
// aa-00-03-04-05-07.
static const uint8_t default_hdr[BUF_OFF] = {
static const uint8_t default_hdr[RBUF_OFF] = {
0xaa, 0x00, 0x03, 0x04, 0x05, 0x06, // Dest: aa-00-03-04-05-06
0xaa, 0x00, 0x03, 0x04, 0x05, 0x07, // Source: aa-00-03-04-05-07
0x60, 0x06, // Prot: 60-06 (customer)
0, 0, // Payload length
BUF_EMPTY, 0x00 // Status
};
@ -292,13 +309,16 @@ enum ddcmp_action
// Status message. This starts like a data message, except that the
// header byte is DC1 (0x11) rather than one of the three DDCMP start
// of header codes.
// Note that things must be kept naturally aligned to avoid padding.
struct status_msg_t
{
uint8_t bufhdr[BUF_OFF - 2]; // room for "Ethernet" header
uint8_t bufhdr[ETH_HDR]; // room for "Ethernet" header
uint16_t data_len; // Length of Ethernet payload
uint16_t stat; // Status (ddcmp_status code)
uint8_t dc1;
uint8_t on; // "on" flags
uint16_t mflags;
uint16_t sdusize; // Max DDCMP frame payload
uint32_t speed;
uint32_t txspeed;
uint32_t rxframes;
@ -1214,6 +1234,7 @@ static void start_ddcmp (uint mflags, uint speed, uint txspeed)
dmc_syn_al = dmc = false;
}
status_msg.on = ON_ACT;
syn_status = false;
status_msg.mflags = mflags;
status_msg.speed = speed;
status_msg.txspeed = txspeed;
@ -1270,7 +1291,7 @@ void handle_rbuf (void)
if (tud_network_can_xmit ())
{
DPRINTF ("requesting status transmit\n");
tud_network_xmit (&status_msg, sizeof (status_msg));
tud_network_xmit (&status_msg, MINE (sizeof (status_msg)));
return;
}
}
@ -1289,7 +1310,7 @@ void handle_rbuf (void)
if (tud_network_can_xmit ())
{
DDPRINTF ("requesting transmit for frame %d\n", rbuf_empty);
tud_network_xmit (df->bufhdr, df->data_len + BUF_OFF);
tud_network_xmit (df->bufhdr, MINE (df->data_len + ETH_HDR + 2));
}
}
}
@ -1503,7 +1524,8 @@ static bool transmit (uint8_t *pkt, uint16_t size)
// Handle frames from host
static bool handle_frame (const uint8_t *src, uint16_t size)
{
int plen = size - 14;
int plen = size - 16;
int plen2;
if (src[12] != 0x60 || src[13] != 0x06)
{
@ -1515,12 +1537,19 @@ static bool handle_frame (const uint8_t *src, uint16_t size)
DPRINTF ("Frame from host too short, %d\n", size);
return true;
}
if (src[14] == DC1)
plen2 = src[14] + (src[15] << 8);
if (plen2 > plen || plen2 < 1)
{
command (src + 14, plen);
DPRINTF ("Length field is invalid, %d vs. %d\n", plen, plen2);
return true;
}
if (src[14] == SOH || src[14] == ENQ || src[14] == DLE)
plen = plen2;
if (src[16] == DC1)
{
command (src + 16, plen);
return true;
}
if (src[16] == SOH || src[16] == ENQ || src[16] == DLE)
{
// Data, send it. But if BIST is active, silently discard all
// transmit requests.
@ -1528,9 +1557,9 @@ static bool handle_frame (const uint8_t *src, uint16_t size)
{
return true;
}
return transmit ((uint8_t *) (src + 14), plen);
return transmit ((uint8_t *) (src + 16), plen);
}
DPRINTF ("Unknown frame code %03o\n", src[14]);
DPRINTF ("Unknown frame code %03o\n", src[16]);
return true;
}
@ -1561,10 +1590,12 @@ uint16_t tud_network_xmit_cb (uint8_t *dst, void *ref, uint16_t arg)
if (gpio_get (SYNLED))
{
status_msg.on = ON_ACT | ON_SYN;
syn_status = true;
}
else
{
status_msg.on = ON_ACT;
syn_status = false;
}
}
@ -1596,18 +1627,20 @@ uint16_t tud_network_xmit_cb (uint8_t *dst, void *ref, uint16_t arg)
}
status_msg.freq = freq;
len = sizeof (status_msg);
len = MINE (sizeof (status_msg));
memcpy (dst, &status_msg, len);
DPRINTF ("Sending status report length %d\n", len);
}
else if (df->stat != BUF_EMPTY)
{
len = df->data_len + BUF_OFF;
df->data_len += 2;
len = df->data_len + ETH_HDR + 2;
DDPRINTF ("Sending to host received frame %d status %d len %d\n",
rbuf_empty, df->stat, df->data_len);
dumpbuf (df->bufhdr, len);
// Give it to USB
len = MINE (len);
memcpy (dst, df->bufhdr, len);
// Mark buffer as handled
df->stat = BUF_EMPTY;
@ -1685,9 +1718,11 @@ static void init_once (void)
DPRINTF ("Initializing status buffer\n");
memcpy (&status_msg, default_hdr, sizeof (default_hdr));
status_msg.data_len = sizeof (status_msg) - RBUF_OFF;
status_msg.dc1 = DC1;
status_msg.stat = DDCMP_OK;
status_msg.on = 0;
status_msg.sdusize = MAXLEN;
strcpy (status_msg.version, VERSION);
// No need to clear the counters since this buffer is static so
@ -1804,6 +1839,22 @@ int main ()
{
send_bist_data ();
}
if (status_msg.on)
{
// Framer is on, see if we need to update host with new
// SYN status.
if (gpio_get (SYNLED))
{
if (!syn_status)
{
send_status = true;
}
}
else if (syn_status)
{
send_status = true;
}
}
tud_task();
handle_rbuf ();
handle_tdone ();

BIN
firmware/ddcmp.uf2
View File

Binary file not shown.