minor add comments

this is just to better understand the flow

Change-Id: I045286836176da729cc8c863866d6f6aa3836592

1 files changed, 28 insertions, 8 deletions

diff --git a/firmware/libcommon/source/mode_cardemu.c b/firmware/libcommon/source/mode_cardemu.c
index 6a8d98f..4886983 100644
--- a/firmware/libcommon/source/mode_cardemu.c
+++ b/firmware/libcommon/source/mode_cardemu.c
@@ -1,7 +1,7 @@
 /* card emulation mode
  *
  * (C) 2015-2017 by Harald Welte <laforge@gnumonks.org>
- * (C) 2018 by sysmocom -s.f.m.c. GmbH, Author: Kevin Redon <kredon@sysmocom.de>
+ * (C) 2018-2019 by sysmocom -s.f.m.c. GmbH, Author: Kevin Redon <kredon@sysmocom.de>
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -194,7 +194,8 @@ int card_emu_uart_tx(uint8_t uart_chan, uint8_t byte)
 }
 
 
-/* FIXME: integrate this with actual irq handler */
+/*! common handler if interrupt was received.
+ *  \param[in] inst_num Instance number, range 0..1 (some boards only '0' permitted) */
 static void usart_irq_rx(uint8_t inst_num)
 {
 	Usart *usart = get_usart_by_chan(inst_num);
@@ -202,32 +203,43 @@ static void usart_irq_rx(uint8_t inst_num)
 	uint32_t csr;
 	uint8_t byte = 0;
 
+	/* get one atomic snapshot of state/flags before they get changed */
 	csr = usart->US_CSR & usart->US_IMR;
 
+	/* check if one byte has been completely received and is now in the holding register */
 	if (csr & US_CSR_RXRDY) {
+		/* read the bye from the holding register */
 		byte = (usart->US_RHR) & 0xFF;
+		/* append it to the buffer */
 		if (rbuf_write(&ci->rb, byte) < 0)
 			TRACE_ERROR("rbuf overrun\r\n");
 	}
 
+	/* check if the transmitter is ready for the next byte */
 	if (csr & US_CSR_TXRDY) {
-		if (card_emu_tx_byte(ci->ch) == 0)
+		/* transmit next byte and check if more bytes are to be transmitted */
+		if (card_emu_tx_byte(ci->ch) == 0) {
+			/* stop the TX ready interrupt of no more bytes to transmit */
 			USART_DisableIt(usart, US_IER_TXRDY);
+		}
 	}
 
-	if (csr & (US_CSR_OVRE|US_CSR_FRAME|US_CSR_PARE|
-		   US_CSR_TIMEOUT|US_CSR_NACK|(1<<10))) {
+	/* check if any error flags are set */
+	if (csr & (US_CSR_OVRE|US_CSR_FRAME|US_CSR_PARE|US_CSR_TIMEOUT|US_CSR_NACK|(1<<10))) {
+		/* clear any error flags */
 		usart->US_CR = US_CR_RSTSTA | US_CR_RSTIT | US_CR_RSTNACK;
-		TRACE_ERROR("%u e 0x%x st: 0x%lx\n", ci->num, byte, csr);
+		TRACE_ERROR("%u USART error on 0x%x status: 0x%lx\n", ci->num, byte, csr);
 	}
 }
 
+/*! ISR called for USART0 */
 void mode_cardemu_usart0_irq(void)
 {
 	/* USART0 == Instance 1 == USIM 2 */
 	usart_irq_rx(1);
 }
 
+/*! ISR called for USART1 */
 void mode_cardemu_usart1_irq(void)
 {
 	/* USART1 == Instance 0 == USIM 1 */
@@ -419,15 +431,21 @@ void mode_cardemu_init(void)
 	INIT_LLIST_HEAD(&cardem_inst[0].usb_out_queue);
 	rbuf_reset(&cardem_inst[0].rb);
 	PIO_Configure(pins_usim1, PIO_LISTSIZE(pins_usim1));
+
+	/* configure USART as ISO-7816 slave (e.g. card) */
 	ISO7816_Init(&cardem_inst[0].usart_info, CLK_SLAVE);
 	NVIC_EnableIRQ(USART1_IRQn);
 	PIO_ConfigureIt(&pin_usim1_rst, usim1_rst_irqhandler);
 	PIO_EnableIt(&pin_usim1_rst);
-	usim1_rst_irqhandler(&pin_usim1_rst); /* obtain current RST state */
+
+	/* obtain current RST state */
+	usim1_rst_irqhandler(&pin_usim1_rst);
 #ifndef DETECT_VCC_BY_ADC
 	PIO_ConfigureIt(&pin_usim1_vcc, usim1_vcc_irqhandler);
 	PIO_EnableIt(&pin_usim1_vcc);
-	usim1_vcc_irqhandler(&pin_usim1_vcc); /* obtain current VCC state */
+
+	/* obtain current VCC state */
+	usim1_vcc_irqhandler(&pin_usim1_vcc);
 #else
 	do {} while (!adc_triggered); /* wait for first ADC reading */
 #endif /* DETECT_VCC_BY_ADC */
@@ -442,6 +460,7 @@ void mode_cardemu_init(void)
 	rbuf_reset(&cardem_inst[1].rb);
 	PIO_Configure(pins_usim2, PIO_LISTSIZE(pins_usim2));
 	ISO7816_Init(&cardem_inst[1].usart_info, CLK_SLAVE);
+	/* TODO enable timeout */
 	NVIC_EnableIRQ(USART0_IRQn);
 	PIO_ConfigureIt(&pin_usim2_rst, usim2_rst_irqhandler);
 	PIO_EnableIt(&pin_usim2_rst);
@@ -458,6 +477,7 @@ void mode_cardemu_init(void)
 					  SIMTRACE_CARDEM_USB_EP_USIM2_INT, cardem_inst[1].vcc_active,
 					  cardem_inst[1].rst_active, cardem_inst[1].vcc_active);
 	sim_switch_use_physical(1, 1);
+	/* TODO check RST and VCC */
 #endif /* CARDEMU_SECOND_UART */
 }