Update CCS12 peripheral firmware and documentation

Source/Internal/ecan.c

@@ -1,3 +1,12 @@
+/**
+ * @file ecan.c
+ * @brief Инициализация eCAN, передача кадров и обработка CAN-прерываний.
+ *
+ * Настраивает выбранный CAN-контроллер и mailbox, нормализует номер устройства,
+ * отправляет данные и ведёт счётчики приёма, передачи и ошибок. Регистры eCAN
+ * изменяются через shadow-копии согласно требованиям C2000; обработчики должны
+ * подтверждать источник прерывания и не задерживать остальные группы PIE.
+ */
 #include "DSP2833x_Device.h"     // DSP2833x Headerfile Include File
 #include "DSP2833x_SWPrioritizedIsrLevels.h"
 
@@ -30,6 +39,14 @@ int CanTimeOutErrorTR = 0;
 
 int wait=0;
 
+/**
+ * @brief Настраивает eCAN-A и его почтовые ящики для выбранного номера узла.
+ * @param Port Номер интерфейса; текущая аппаратная реализация использует CAN-A.
+ * @param DevNum Номер устройства 1..16, насыщаемый реализацией на границах.
+ * @details Регистры управления изменяются через ECanShadow, чтобы исключить
+ * опасные read-modify-write операции над регистрами с особыми битами.
+ * @post Разрешены приёмные mailbox и прерывания CAN, счётчики ошибок сброшены.
+ */
 void InitCan(int Port, int DevNum)
 {
   struct ECAN_REGS ECanShadow; 
@@ -40,6 +57,7 @@ void InitCan(int Port, int DevNum)
 
 	long id = 0x80BA0000;
 
+	/* Протокольная нумерация начинается с 1, аппаратное поле — с 0. */
 	DevNum--;
 	if(DevNum<0)DevNum=0;
 	if(DevNum>15)DevNum=15;
@@ -66,16 +84,16 @@ void InitCan(int Port, int DevNum)
 //	Required before writing the MSGIDs
     ECanRegs->CANME.all = 0;
 
-//	задаем адрес 0 ащикa на передачу
+//	задаем адрес 0 ащикa на передачу
     ECanMboxes->MBOX0.MSGID.all = id +  0x10 + DevNum; 
 
-//	задаем адрес 1 ащикa на прием
-    ECanMboxes->MBOX1.MSGID.all = id + DevNum; //поменать!!!! 1 и 0!!!
+//	задаем адрес 1 ащикa на прием
+    ECanMboxes->MBOX1.MSGID.all = id + DevNum; //поменать!!!! 1 и 0!!!
 
-//	задаем режимы работы ащикa 0 на передачу, остальные на прием
+//	задаем режимы работы ащикa 0 на передачу, остальные на прием
     ECanRegs->CANMD.all = 0xFFFFFFFE; 
     
-//	выбираем только 2 ащикa дла работы, остальные запрещаем
+//	выбираем только 2 ащикa дла работы, остальные запрещаем
     ECanRegs->CANME.all = 0x00000003;
 
 //	Clear all TAn bits
@@ -100,7 +118,7 @@ void InitCan(int Port, int DevNum)
     ECanRegs->CANMC.all = ECanShadow.CANMC.all;
     while(!ECanRegs->CANES.bit.CCE);	// Wait for CCE bit to be set..
    
-// настриваем скорость CAN
+// настриваем скорость CAN
     ECanShadow.CANBTC.all = ECanRegs->CANBTC.all;
 	ECanShadow.CANBTC.bit.SJWREG=1;
 
@@ -113,7 +131,7 @@ void InitCan(int Port, int DevNum)
     ECanRegs->CANMC.all = ECanShadow.CANMC.all;
     while(ECanRegs->CANES.bit.CCE);	// Wait for CCE bit to be cleared..
 
-//	задаем таймауты дла ожиданиа отправки получениа посылки
+//	задаем таймауты дла ожиданиа отправки получениа посылки
    	ECanMOTORegs->MOTO0 = 550000;
 	ECanMOTORegs->MOTO1 = 550000;
 
@@ -140,7 +158,7 @@ void InitCan(int Port, int DevNum)
 	IER |= M_INT9;	// Enable CPU INT
 	EDIS;
 
-// завершили настройку CAN ащиков
+// завершили настройку CAN ащиков
 
     MessageReceivedCount = 0;
     ErrorCount = 0;
@@ -148,6 +166,14 @@ void InitCan(int Port, int DevNum)
 	MessageTransivedCount=0;
 }
 
+/**
+ * @brief Формирует и запускает передачу одного прикладного CAN-кадра.
+ * @param Port Номер CAN-интерфейса.
+ * @param data Слова полезной нагрузки в формате проекта.
+ * @param Addr Идентификатор/адрес получателя.
+ * @note Перед записью mailbox проверяется завершение предыдущей передачи;
+ * тайм-аут отражается в CanTimeOutErrorTR.
+ */
 void CAN_send(int Port, int data[], int Addr)
 {
   unsigned long hiword,loword;
@@ -177,13 +203,19 @@ void CAN_send(int Port, int data[], int Addr)
 	ECanRegs->CANTSC = 0;		//	clear time-out counter
 	EDIS;
 
-	ECanRegs->CANTRS.all = 1;	//	запустить передачу
+	ECanRegs->CANTRS.all = 1;	//	запустить передачу
 	
 	wait=1;
 	led1_toggle();
 }
 
 
+/**
+ * @brief Разбирает данные сработавшего приёмного mailbox.
+ * @param ECanMboxes Набор mailbox активного CAN-контроллера.
+ * @details Копирует полезную нагрузку в CAN_input_data и обновляет счётчик
+ * принятых сообщений; подтверждение аппаратного флага выполняет вызывающий ISR.
+ */
 void Handlai(volatile struct ECAN_MBOXES * ECanMboxes)
 {
   unsigned int adr;
@@ -215,6 +247,11 @@ void Handlai(volatile struct ECAN_MBOXES * ECanMboxes)
 	led2_toggle();
 }
 
+/**
+ * @brief Основной ISR eCAN-A для приёма кадров и завершения передачи.
+ * @details Определяет источник по CANRMP/CANTA, вызывает Handlai() для входного
+ * mailbox, очищает обслуженные флаги и подтверждает группу PIE9.
+ */
 interrupt void CANa_handler(void)
 {
 	// Set interrupt priority:
@@ -234,6 +271,11 @@ interrupt void CANa_handler(void)
 	PieCtrlRegs.PIEIER9.all = TempPIEIER;
 }
 
+/**
+ * @brief ISR линии ошибок eCAN-A.
+ * @details Сохраняет диагностические счётчики, очищает причину ошибки и
+ * возвращает контроллер к приёму, не меняя прикладную адресацию mailbox.
+ */
 interrupt void CANa_reset_err(void)
 {
 	// Set interrupt priority: